|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.
|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.|
cache_directory= STRING Full path to directory where free-sa should temporarily keep its cache files used for reports generation.
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.
index_sort= STRING Sort field(s) and order for index report:
B Bytes (desc.), generation date (desc.) b Bytes (asc.), generation date (desc.) D Generation date (desc.) d Generation date (asc.) N Configuration (desc.), generation date (desc.) n Configuration (asc.), generation date (desc.) U Users (desc.), generation date (desc.) u Users (asc.), generation date (desc.) 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: its 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.
log_format= INTEGER Log file format:
0 Squid 2.x native log format 1 CERN/NCSA Common Log Format (CLF) 2 CERN/NCSA Combined Log Format 3 Postfix 2.x over syslog log format 4 Qmail over syslog log format 5 Communigate pro 5.x native log 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.
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.
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.
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 recipients e-mail address may appear in different cases thus not allowing to collate these e-mail addresses as one and unique recipient.
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 456789 789123456 k kbytes 0k 446k 770628k K kbytes 0.12k 446.08k 770628.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
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.
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:
0 Not remove 1 Remove all reports with period equal to period of newly generated reports (period is checked with precision of 1 day) 2 Remove all reports with period within period of newly generated reports (period is checked with precision of 1 seconds) Note: removal is performed AFTER new reports were generated.
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.
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.
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.
server_efficiency_bytes_divisor= BOOL Apply bytes divisor for server efficiency report (SER).
server_efficiency_report= BOOL Generate server efficiency report (SER).
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.
top_sites_limit= INTEGER Limit number of sites in top sites report (TSR). 0 means no limit.
top_sites_report= BOOL Generate top sites report (TSR).
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.
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.
username_unescape= BOOL Unescape user names, tested only with UTF8 locales (check locale option to set it to some UTF8).
Note: its useful for squid with NTLM auth module configuration, when usernames contain coded (i.e. not US-ASCII) characters.
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%.
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.
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).
users_show_ips= BOOL Show all IP addresses used by user in users report (UR).
users_show_local_filters= BOOL Show users statistics in users report (UR) for every local filter with links to user entry in local filter report (LFR).
The global, users and local filters purpose is including OR excluding records from processing by free-sa. Global filter affects all data processed by free-sa. Users filter affects data processed to all user related reports and top sites report. Local filter affects only data processed to local filter report.
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):
A Policy for IP addresses (0-7). a Entry of IP addresses list. B Policy for bytes (0-1). b Only one entry allowed here - upper bytes limit. C Policy for codes (0-1). c Entry of codes list. I Policy for internal names (0-7). i Entry of internal names list. l Limit number of URLs per one user in local filter report.
0 means no limit. Default: 50.
M Policy for methods (0-1). m Entry of methods list. n Local filter name.
Default: full path to filter configuration file.
S Policy for stat codes (0-1). s Entry of stat codes list. U Policy for URLs (0-7). u Entry of URLs list. w Enable or disable bytes column in local filter report (0-1).
Default: 1, i.e. enabled.
Allowed policies: 0 Include match (by substring for A, I and U policies). 1 Exclude match (by substring for A, I and U 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. 6 Include match by ending substring. 7 Exclude match by ending substring. Allowed stat codes for s entry: 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).
file should end with empty line.
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 following 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 following local filter file contents:
U 0 u XXXXXXXXXXXX u NNNNNNNNNNNN u cmd.exe
3. If we want to see only URLs of actually downloaded images in gif format at users reports and top sites report, then we can make following users filter file contents:
U 4 u \.(gif|GIF|Gif)$ S 0 s 0
SVG report definition is string of characters allows you to define SVG report view.
String may start with number following characters which enable various SVG report view options.
number Generate report for top number entries only (for top sites and top users SVG reports only). l Show legend (for pie chart only). p Generate pie chart instead of bars. r Generate bars in relative scale (for bars only). s Make pie chart labels font smaller. S Make pie chart labels font even more smaller.
1. If we want to generate top users SVG report for top 10 users only using pie chart having small label font with legend:
2. If we want to generate top sites SVG report for all sites using pie chart having smallest label font:
3. If we want to simply switch users grpaphics report to SVG format we have to supply fake option (this is temporary workaround):
4. If we want to generate server efficiency SVG report using piechar with legend:
The usertab file is used by free-sa to replace visible username or IP by specified string in reports.
The file consists of lines, each line is original name or IP with translated string separated by space symbol.
Note: file should end with empty line. Note: file should be encoded in free-sa locale charset specified by locale option, if its not defined then runtime locale charset will be used.
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 following usertab file contents:
192.168.0.1 Mr. Michael 192.168.0.2 Ms. Catarine
Copyright (C) 1997, 2006-2013 Oleg Sapon <firstname.lastname@example.org>
|Free-SA 2.0.0b6p7||FREE-SA.CONF (5)||17 Jun 2012|