Files options:

downloads="STRING"

Full path to downloads extensions file (required for downloads report).

Default: undefined, i.e. no downloads file.

global_filter="STRING"

Full path to global filter file.

Default: undefined, i.e. global filter disabled.

local_filter="STRING"

Full path to local filter file.

Default: undefined, i.e. local filter disabled.

log="STRING"

Full path to log file. Log file should be in one of the supported log file formats, check free-sa(1) "Supported log formats". You may overwrite this value via '-l' command line option.

Default: /usr/src/tmp/free-sa-buildroot/var/log/squid/access.log.

usertab="STRING"

Full path to usertab file for names translation.

Default: undefined, i.e. no usertab file.

Directories options:

targetdir="STRING"

Full path to directory, from where free-sa should put index report (IR). You may overwrite this value via '-o' command line option.

Default: /usr/src/tmp/free-sa-buildroot/var/www/html/free-sa.

tmpdir="STRING"

Full path to directory, where free-sa should put temporary files.

Default: /usr/src/tmp/free-sa-buildroot/var/cache/free-sa.

Reports selection options:

ts="BOOL"

Generate top sites report (TSR).

Default: true.

paf="BOOL"

Generate proxy authentication faulures report (TTR), i.e. for 407 code.

Default: true.

saf="BOOL"

Generate sites authentication faulures report (TTR), i.e. for 401 code.

Default: true.

pdn="BOOL"

Generate proxy denied report (TTR).

Default: true.

sdn="BOOL"

Generate sites denied report (TTR), i.e. for 403 code.

Default: true.

cct="BOOL"

Generate CONNECT method report (TTR).

Default: true.

pst="BOOL"

Generate PUT/POST method report (TTR).

Default: true.

dld="BOOL"

Generate downloads report (TTR). If true, then set downloads file via 'downloads' option.

Default: false.

users="BOOL"

Generate users report (UR).

Default: true.

fullurl="BOOL"

Generate additional user report with full URLs (UFR). If true, then report generation time increases by ~130%.

Default: true.

ufr_split="BOOL"

Split user report with full URLs (UFR) by site. If true, then report for every visited site by user is placed to separate file.

Default: false.

email="STRING"

Generate top user report in text format and send it to e-mail specified by STRING. You may overwrite this value via '-e' command line option.

Default: undefined, i.e. no send is done.

Reports limits options:

paf_limit="INTEGER"

saf_limit="INTEGER"

pdn_limit="INTEGER"

sdn_limit="INTEGER"

cct_limit="INTEGER"

pst_limit="INTEGER"

dld_limit="INTEGER"

lcf_limit="INTEGER"

Limit number of URLs per one user for typical reports (TTR, where lcf is local filter report). 0 means no limit.

Default: 50.

url_limit="INTEGER"

Limit number of characters in visible part of URL for all reports. 0 means no limit.

Default: 50.

ts_limit="INTEGER"

Limit number of sites in top sites report (TSR). 0 means no limit.

Default: 0.

dld_min="INTEGER"

Add downloads indicator to links (and therefore add those links to downloads report) only if link have size higher than defined by this option. 0 means no limit.

Default: 0.

rtr_timeout="INTEGER"

Update interval for real time report (RTR) page in milliseconds.

Default: 5000, i.e. 5 seconds.

Other options:

name="STRING"

Configuration name, will be showed in reports list report (LR).

Default: undefined, i.e. use full path to configuration file instead.

logformat="INTEGER"

Log file format:

Note: support for NetCache and Blue Coat proxies is EXPERIMENTAL and implemented only via Squid 2.x native log format. For these log formats you probably should enable 'skip_errors' option.

Default: 0.

skip_errors="BOOL" (EXPERIMENTAL)

Try to skip erroneous records presented on log and continue log analysis from next record.

Note: this option is implemented only for standard log analysis, i.e. not for removing records from log file or showing log file information or free-sa.cgi.

Default: false.

fulltraffic="BOOL"

Generate user reports assuming full trafic, i.e. show cached, denied and other local only traffic.

Default: false.

inameuser="BOOL"

Use user names, provided by log as unique internal name, otherwise use IP.

Default: true.

indicators="BOOL"

Show coloured indicators in most reports at right of the table, indicating presence of user or URL (depending on report type) in 7 typical reports categories (TTR).

Default: true.

overwrite="INTEGER"

Remove all reports when new one is generated according to rule selected by INTEGER:

Note: removing is done AFTER generating new reports.

Default: 0.

resolveip="BOOL"

Resolve IP addresses using DNS and use them as visual user names.

Note: resolving may greately increase report generation time.

Default: false.

showinfo="BOOL"

Show information about report generator at pages bottom.

Default: true.

site="STRING"

For specific log formats only: use this string as prefix to site address.

Default: undefined, i.e. no prefix.

logo="STRING"

Logo image URL showed at pages top.

Default: undefined, i.e. no logo.

locale="STRING"

Locale to switch to after command line options parsing.

Note: you should specify command line options arguments in runtime locale format, not this one.

Note: it's useful when you schedule run of free-sa from crontab, because crond sets C or POSIX locale.

Default: undefined, i.e. use current locale.

rotate="INTEGER|STRING"

Remove reports older than specified time in seconds via INTEGER value or in word via STRING value (starting from free-sa run time).

Conversion table of some useful rotate option values:

 INTEGER     STRING
      60               1 minute
     600              10 minutes
    3600       hour    1 hour
   28800               8 hours
   36000              10 hours
   86400        day    1 day      or    24 hours
  604800       week    1 week     or     7 days
 2592000      month    1 month    or    30 days
 7776000    quarter    3 months   or    90 days
15552000               6 months   or   180 days
31536000       year    1 year     or   365 days

Default: undefined, i.e. no reports rotatation.

tz_shift="INTEGER" (EXPERIMENTAL)

Shift time and therefore date by specified amount of seconds. It is useful when proxy and users are located in different time zones.

Note: this option affect all Free-SA internal functions including remove records from log file and show log file information actions.

Default: 0, i.e. no time shift.

divisor="STRING"

Select bytes field represence in all reports except server efficiency. Actually divisor option value is letter, which is lowest meaning digits order (except 'v'/'V' values). The lower case letter means number rounded to integer without digits after decimal delimiter value. The upper case letter means number with two digits after decimal delimiter value. All divisors in divisions is 2 in the power of interpreted option value (i.e. 1 kbyte = 1024 bytes).

Allowed option values and their effect on bytes field in reports is showed below using example for 123, 456768 and 789123456 bytes field values. Locale is assumed with ' symbol as thousands separator:

b or B   bytes        123   456'789   789'123'456
k        kbytes        0k      446k      770'628k
K        kbytes     0.12k   446.08k   770'628.37k
m        Mbytes        0M        0M          753M
M        Mbytes     0.00M     0.43M       752.56M
g        Gbytes        0G        0G            1G
G        Gbytes     0.00G     0.00G        0.734G
t        Tbytes        0T        0T            0T
T        Tbytes     0.00T     0.00T         0.00T
p        Pbytes        0P        0P            0P
P        Pbytes     0.00P     0.00P         0.00P
v or V   Varbytes     123      446k          753M

Default: b.

user_unescape="BOOL"

Unescape user names, tested only with UTF8 locales (check locale option to set it to some UTF8).

Note: it's useful for squid with NTLM auth module configuration, when usernames contain coded (i.e. not US-ASCII) characters.

Default: false.

File format

The file consists of options with arguments, comments and empty lines. Each line that starts with a hash (#) symbol is a comment. Options and arguments are case sensitive and of the form: Option Argument. Each policy option is unique, it may appear only once.

Allowed options (allowed policy ranges is specified at brackets for each policy option):

U Policy for URLs (0-5).

u Entry of URLs list.

I Policy for internal names (0-5).

i Entry of internal names list.

C Policy for codes (0-1).

c Entry of codes list.

M Policy for methods (0-1).

m Entry of methods list.

S Policy for stat codes (0-1).

s Entry of stat codes list.

B Policy for bytes (0-5).

b Only one entry allowed here - upper bytes limit.

Allowed policies:

0 Include match (by substring for U, I policies).

1 Exclude match (by substring for U, I policies).

2 Include match by exact string.

3 Exclude match by exact string.

4 Include match by extended POSIX regular expression.

5 Exclude match by extended POSIX regular expression.

Allowed stat codes:

0 Actual traffic type.

1 Denied traffic type (delivery rejected for mail logs).

2 Cached traffic type.

3 Other local traffic type (ex: authentication errors).

Methods list must be filled with first uppercase letter of method name (P for PUT and POST).

Note:

file should end with empty line.

Filter file examples

1. If we want to see only records related to users with '192.168.0.15', '192.168.0.27' IPs, and see their accesses to all sites except 'www.ourcorporatesite.com', then we can make next global filter file contents:

I 2
i 192.168.0.15
i 192.168.0.27
U 1
u tp://www.ourcorporatesite.com

2. If we want to see records related to Code Red, Code Red 2 and Nimda viruses activity at local filter report, then we can make next local filter file contents:

U 0
u XXXXXXXXXXXX
u NNNNNNNNNNNN
u cmd.exe

3. If we want to see urls of actually downloaded from net only images in gif format at local filter report, then we can make next local filter file contents:

U 4
u \.(gif|GIF|Gif)$
S 0
s 0

File format

The file consists of lines, each line is original name or IP with translated string.

Note:

file should end with empty line.

Note:

file should be encoded in free-sa locale charset specified by 'locale' option, if it's not defined then use runtime locale charset.

Usertab example

If we want to replace '192.168.0.1' IP with 'Mr. Michael' and '192.168.0.2' IP with 'Ms. Catarine' then we can make next usertab file contents:

192.168.0.1 Mr. Michael
192.168.0.2 Ms. Catarine