DragonFly On-Line 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/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

DragonFly On-Line Manual Pages

NAME

DESCRIPTION

FILE FORMAT

OPTIONS

FILTER FILES

SVG REPORT DEFINITION

USERTAB FILE

SEE ALSO

AUTHOR