Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages


home | help
free-sa.conf(5)		      Statistic	Analyzer	       free-sa.conf(5)

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

       free-sa.conf configures the free-sa statistic analyzer, free-sa(1).

       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

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

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

	      Default: /var/cache/free-sa.

	      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.

	      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

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

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

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

	      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.

	      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 to	switch to after	command	line options parsing.

	      Note:  you should	specify	command	line options arguments in run-
	      time locale format, not this one.

	      Note: it's useful	when you schedule free-sa run via crontab, be-
	      cause usually crond sets C or POSIX locale.

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

	      Full  path  to  local filter file. You may define	multiple local
	      filters using multiple 'local_filter' options. Local filters de-
	      fined  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.

	      Full  path  to  log  file. Log file should be in one of the sup-
	      ported log file formats, check free-sa(1)	 "Supported  log  for-
	      mats" and	'logformat' option below. You may overwrite this value
	      via '-l' command line option.

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

	      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 stan-
	      dard log analysis, i.e. not for cropping log or showing log  in-
	      formation	or free-sa.cgi.

	      Default: false.

	      Shift time and therefore date by specified amount	of seconds. It
	      is useful	when proxy and users are  located  in  different  time

	      Note:  this option affect	all Free-SA internal functions includ-
	      ing remove records from log file and show	log  file  information

	      Default: 0, i.e. no time shift.

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

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

	      Default: 5000, i.e. 5 seconds.

	      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 ad-
	      dresses as one and unique	recipient.

	      Default: false.

	      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 dec-
	      imal delimiter value. The	upper case letter  means  number  with
	      two  digits after	decimal	delimiter value. All divisors in divi-
	      sions 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
	      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.

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

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

	      Default: true.

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

	      Default: undefined, i.e. no logo.

	      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
	      2	     Remove all	reports	with period  within  period  of	 newly
		     generated	reports	(period	is checked with	precision of 1

	      Note: removal is performed AFTER new reports were	generated.

	      Default: 0.

	      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.

	      Word which is  used  to  replace	usernames  when	 'reports_pri-
	      vacy_mode' is enabled.

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

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

	      Show information about free-sa at	pages bottom.

	      Default: true.

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

	      Default: undefined, i.e. no prefix.

	      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.

	      Limit  number  of	 characters  in	visible	part of	URL in all re-
	      ports. 0 means no	limit.

	      Default: 50.

	      Apply bytes divisor for server efficiency	report (SER).

	      Default: false.

	      Generate server efficiency report	(SER).

	      Default: true.

	      Generate server efficiency SVG report by bytes. Check  "SVG  RE-
	      PORT DEFINITION" section below.

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

	      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.

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

	      Default: 0.

	      Generate top sites report	(TSR).

	      Default: true.

	      Generate	top sites SVG report by	bytes. Check "SVG REPORT DEFI-
	      NITION" section below.

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

	      Generate top users SVG report by bytes. Check "SVG REPORT	 DEFI-
	      NITION" section below.

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

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

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

	      Use user names, provided by log as unique	internal name,	other-
	      wise 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 authen-
	      tication schemes enabled in Squid	and you	see exactly same user-
	      names 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.

	      Resolve  IP  addresses  using  DNS  and  use them	as visual user

	      Default: false.

	      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.

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

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

	      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.

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

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

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

	      Default: true.

	      Split user report	with full URLs (UFR) by	site. If true then re-
	      port  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.

	      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.

	      Generate users report (UR).

	      Default: true.

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

	      Default: false.

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

	      Default: false.

       The global, users and local filters purpose is including	 OR  excluding
       records from processing by free-sa. Global filter affects all data pro-
       cessed by free-sa. Users	filter affects data processed to all user  re-
       lated reports and top sites report. Local filter	affects	only data pro-
       cessed 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
       '', '' IPs, and see their accesses to all sites
       except  '',  then  we can make following	global
       filter file contents:

       I 2
       U 1
       u tp://

       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 lo-
       cal filter file contents:

       U 0
       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 follow-
       ing 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 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:


       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.

   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  ''	 IP  with  'Mr.	 Michael'  and
       '' IP	with 'Ms. Catarine' then we can	make following usertab
       file contents: Mr. Michael Ms. Catarine

       free-sa(1), squid(8),

       Copyright (C) 1997, 2006-2013 Oleg Sapon	<>

Free-SA	2.0.0b6p7		  17 Jun 2012		       free-sa.conf(5)


Want to link to this manual page? Use this URL:

home | help