NAME

DESCRIPTION

FILE FORMAT

The arguments are of the following types:

STRING Set of characters.

BOOL Boolean value: 'true' or 'false'.

INTEGER Signed integer.

free-sa.conf file sample is included in distribution, check it at /usr/local/etc/free-sa/free-sa.conf.sample.

Note:

file should end with empty line.

Note:

you may use 'true'/'false', 'yes'/'no', 'enable'/'disable', '1'/'0' in any case as boolean value and only first symbol is significant for boolean value, i.e. for example, you may use just 'T' instead of 'true'.

OPTIONS

cache_directory="STRING"

Full path to directory where free-sa should temporarily keep its cache files used for reports generation.

Default: /var/cache/free-sa.

configuration_name="STRING"

Configuration name, will be showed in list report (LR) and index report (IR).

Default: undefined, in this case full path to configuration file will be used as configuration name.

email_address="STRING"

Generate top users report in text format and send it to e-mail specified by STRING. If STRING is '-' then report will be showed on stdout. You may overwrite this value via '-e' command line option.

Default: undefined, i.e. report is disabled and nothing will be sent.

global_filter="STRING"

Full path to global filter file. Check "FILTER FILES" section below.

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

index_show_calendar="BOOL"

Show calendar menu with search box at index report (IR). This menu simplifies navigation across reports dated by various months and years and allows to search on-the-fly by report name.

Default: true.

index_sort="STRING"

Sort field(s) and order for index report:

Default: D, i.e. generation date (desc.)

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 free-sa run via crontab, because usually crond sets C or POSIX locale.

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

local_filter="STRING"

Full path to local filter file. You may define multiple local filters using multiple 'local_filter' options. Local filters defined within first 8 'local_filter' lines counted from top of free-sa configuration file will have indicators while the rest 8 will not. Check "FILTER FILES" section below.

Default: undefined, i.e. all local filters are disabled.

log_file="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" and 'logformat' option below. You may overwrite this value via '-l' command line option.

Default: /var/log/squid/access.log.

log_format="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.

log_skip_errors="BOOL" (EXPERIMENTAL)

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

Note: this option is EXPERIMENTAL and implemented only for standard log analysis, i.e. not for cropping log or showing log information or free-sa.cgi.

Default: false.

log_time_zone_shift="INTEGER"

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.

real_time_home="STRING"

Absolute or relative path to the root of Free-SA directory used in real time report (RTR). This option allows easy relocation of the free-sa.cgi binary to any directory on a web server side.

Default: ..

real_time_timeout="INTEGER"

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

Default: 5000, i.e. 5 seconds.

recipient_tolower="BOOL"

Convert recipient name (URL) to lower case. It should be useful for mail logs where recipient's e-mail address may appear in different cases thus not allowing to collate these e-mail addresses as one and unique recipient.

Default: false.

reports_bytes_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.

reports_indicators="BOOL"

Show coloured indicators in most reports at right of the table, indicating presence of record (user, URL, etc) in local filter reports.

Note: indicators are showed only for first 8 local filters.

Default: true.

reports_logo="STRING"

Logo image URL showed at pages top. You may use relative URLs like '../image.jpg'.

Default: undefined, i.e. no logo.

reports_overwrite="INTEGER"

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

Note: removal is performed AFTER new reports were generated.

Default: 0.

reports_privacy_mode="INTEGER"

Use one of available privacy modes:

0   No privacy, i.e. show usernames.
1   Replace all usernames with value of 'reports_privacy_username' option.
2   In addition to mode 1, 'privacy_table.txt' file is generated at reports directory
    with usernames conversation table. Some countries allows this.
    

Default: 0.

reports_privacy_username="STRING"

Word which is used to replace usernames when 'reports_privacy_mode' is enabled.

Default: undefined, i.e. use localised verion of 'User' word.

reports_rotate="INTEGER|STRING"

Remove reports older than specified time in seconds via INTEGER value or 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.

reports_show_info="BOOL"

Show information about free-sa at pages bottom.

Default: true.

reports_site_name="STRING"

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

Default: undefined, i.e. no prefix.

reports_svg_width="INTEGER"

Optimize SVG graphics reports to specified screen width. Set this option to something that is around 5-10% less than your screen width.

Default: 960, i.e. optimize for 1024x768.

reports_url_limit="INTEGER"

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

Default: 50.

server_efficiency_bytes_divisor="BOOL"

Apply bytes divisor for server efficiency report (SER).

Default: false.

server_efficiency_report="BOOL"

Generate server efficiency report (SER).

Default: true.

server_efficiency_svg="STRING"

Generate server efficiency SVG report by bytes. Check "SVG REPORT DEFINITION" section below.

Default: undefined, i.e. this report is disabled.

target_directory="STRING"

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

Default: /usr/local/www/free-sa.

top_sites_limit="INTEGER"

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

Default: 0.

top_sites_report="BOOL"

Generate top sites report (TSR).

Default: true.

top_sites_svg="STRING"

Generate top sites SVG report by bytes. Check "SVG REPORT DEFINITION" section below.

Default: undefined, i.e. this report is disabled.

top_users_svg="STRING"

Generate top users SVG report by bytes. Check "SVG REPORT DEFINITION" section below.

Default: undefined, i.e. this report is disabled.

username_file="STRING"

Full path to usernames table file used for names translation. Check "USERTAB FILE" section below.

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

username_is_preferred="BOOL"

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

Default: true.

username_remove="STRING" (EXPERIMENTAL)

Remove specified STRING from beginning or ending of username. For example, this could be useful when you have multiple authentication schemes enabled in Squid and you see exactly same usernames with and without domain prefix/suffix in reports. When this option is enabled domain prefix/suffix will be removed thus all user stats will appear under one username.

Note: string removal is performed after unescape and internal conversation to lower case with removal of special characters are applied.

Note: do not use this option if STRING may appear in the middle of username because in such case username will be truncated starting from first entrance of STRING pattern in username. Due to this limitation option is marked as EXPERIMENTAL.

Default: undefined, i.e. no string removal is applied.

username_resolve_ip="BOOL"

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

Default: false.

username_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.

users_excess="STRING"

Full path to file where users excess report (UER) should be placed.

Default: undefined, i.e. users excess report is disabled.

users_excess_limit="INTEGER"

Limit list of users reported in users excess report to ones who has exceeded specified amount of bytes.

Default: 0, i.e. all users are reported in users excess report.

users_filter="STRING"

Full path to users filter file. Check "FILTER FILES" section below.

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

users_fullurl_report="BOOL"

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

Default: true.

users_fullurl_split="BOOL"

Split user report with full URLs (UFR) by site. If true then report for every site visited by user is placed to the separate file. This option is useful when number of unique sites and therefore URLs per one user is big.

Default: false.

users_graphics_svg="STRING"

Generate users graphics report (UGR) in SVG format. Check "SVG REPORT DEFINITION" section below.

Default: undefined, i.e. users graphics report is generated in HTML format.

users_report="BOOL"

Generate users report (UR).

Default: true.

users_show_ips="BOOL"

Show all IP addresses used by user in users report (UR).

Default: false.

users_show_local_filters="BOOL"

Show user's statistics in users report (UR) for every local filter with links to user entry in local filter report (LFR).

Default: false.

FILTER FILES

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

U 0
u XXXXXXXXXXXX
u NNNNNNNNNNNN
u cmd.exe

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

SVG REPORT DEFINITION

USERTAB FILE

192.168.0.1 Mr. Michael
192.168.0.2 Ms. Catarine

SEE ALSO

AUTHOR