FreeBSD Manual Pages
free-sa.conf(5) Statistic Analyzer free-sa.conf(5) NAME free-sa.conf - Configuration file for free-sa statistic analyzer DESCRIPTION free-sa.conf configures the free-sa statistic analyzer, free-sa(1). 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". 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/lo- cal/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 re- port (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 spec- ified by STRING. If STRING is '-' then report will be showed on std- out. 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: 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: 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 fil- ters using multiple 'local_filter' options. Local filters defined within first 8 'local_filter' lines counted from top of free-sa con- figuration 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 'log- format' option below. You may overwrite this value via '-l' command line option. Default: /var/log/squid/access.log. 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 for- mats 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 effi- ciency. 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 delim- iter 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, in- dicating presence of record (user, URL, etc) in local filter re- ports. 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 se- lected by INTEGER: 0 Not remove 1 Remove all reports with period equal to period of newly gen- erated reports (period is checked with precision of 1 day) 2 Remove all reports with period within period of newly gener- ated reports (period is checked with precision of 1 seconds) 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 ad- dress. 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 DEFINI- TION" section below. Default: undefined, i.e. this report is disabled. top_users_svg="STRING" Generate top users SVG report by bytes. Check "SVG REPORT DEFINI- TION" 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 con- versation to lower case with removal of special characters are ap- plied. 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 limi- tation 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 op- tion 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 RE- PORT 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 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 re- lated reports and top sites report. Local filter affects only data processed to local filter report. 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): 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). 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.ourcor- poratesite.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 SVG report definition is string of characters allows you to define SVG re- port view. String format 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. SVG report definition string examples (recommended values) 1. If we want to generate top users SVG report for top 10 users only using pie chart having small label font with legend: top_users_svg="10psl" 2. If we want to generate top sites SVG report for all sites using pie chart having smallest label font: top_sites_svg="pS" 3. If we want to simply switch users grpaphics report to SVG format we have to supply fake option (this is temporary workaround): users_graphics_svg="y" 4. If we want to generate server efficiency SVG report using piechar with legend: server_efficiency_svg="pl" USERTAB FILE The usertab file is used by free-sa to replace visible username or IP by specified string in reports. File format The file consists of lines, each line is original name or IP with trans- lated string separated by 'space' symbol. Note: file should end with empty line. Note: file should be encoded in free-sa locale charset specified by 'lo- cale' option, if it's not defined then runtime locale charset will be used. 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 following usertab file contents: 192.168.0.1 Mr. Michael 192.168.0.2 Ms. Catarine SEE ALSO free-sa(1), squid(8), AUTHOR Copyright (C) 1997, 2006-2013 Oleg Sapon <xsov@mail.ru> Free-SA 2.0.0b6p7 17 Jun 2012 free-sa.conf(5)
NAME | DESCRIPTION | FILE FORMAT | OPTIONS | FILTER FILES | SVG REPORT DEFINITION | USERTAB FILE | SEE ALSO | AUTHOR
Want to link to this manual page? Use this URL:
<https://man.freebsd.org/cgi/man.cgi?query=free-sa.conf&sektion=5&manpath=FreeBSD+Ports+15.1.quarterly>