GSP
Quick Navigator

Search Site

Unix VPS
A - Starter
B - Basic
C - Preferred
D - Commercial
MPS - Dedicated
Previous VPSs
* Sign Up! *

Support
Contact Us
Online Help
Handbooks
Domain Status
Man Pages

FAQ
Virtual Servers
Pricing
Billing
Technical

Network
Facilities
Connectivity
Topology Map

Miscellaneous
Server Agreement
Year 2038
Credits
 

USA Flag

 

 

Man Pages


Manual Reference Pages  -  FREE-SA.CONF (5)

NAME

free-sa.conf - Configuration file for free-sa statistic analyzer

CONTENTS

Description
Options
Author

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/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:
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 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:
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.

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

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

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.

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

SVG report definition is string of characters allows you to define SVG report 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 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 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>
Search for    or go to Top of page |  Section 5 |  Main Index


Free-SA 2.0.0b6p7 FREE-SA.CONF (5) 17 Jun 2012

Powered by GSP Visit the GSP FreeBSD Man Page Interface.
Output converted with manServer 1.07.