Recent changes to Usage

Usage modified by Evgeniy Yakushev

Evgeniy Yakushev — Thu, 12 Nov 2015 10:46:26 -0000

--- v9
+++ v10
@@ -4,4 +4,4 @@

 Sarg writes the full path to the current _sarg.conf_ when it is ran with the -x command line option. Use that command line option to find out exactly which _sarg.conf_ is taken into account.

-The options are described in the sample sarg.conf distributed along with the sources.
+The options are described in the sample sarg.conf distributed along with the sources and also in wiki, see [Configuration options] page.

Usage modified by Evgeniy Yakushev

Evgeniy Yakushev — Wed, 11 Nov 2015 08:57:33 -0000

--- v8
+++ v9
@@ -1,6 +1,6 @@
 # Configuration #

-Sarg reads its configuration options from a configuration file whose path is hard coded during the [2.1 Build on Linux] stage. It is usually set to /etc/sarg/sarg.conf (--sysconfdir=/etc/sarg) but the ./configure script puts it in /usr/local/etc/sarg.conf if no --prefix nor --sysconfdir options are provided.
+Sarg reads its configuration options from a configuration file whose path is hard coded during the [Build on Linux] stage. It is usually set to /etc/sarg/sarg.conf (--sysconfdir=/etc/sarg) but the ./configure script puts it in /usr/local/etc/sarg.conf if no --prefix nor --sysconfdir options are provided.

 Sarg writes the full path to the current _sarg.conf_ when it is ran with the -x command line option. Use that command line option to find out exactly which _sarg.conf_ is taken into account.

3. Usage modified by Evgeniy Yakushev

Evgeniy Yakushev — Tue, 10 Nov 2015 11:36:53 -0000

--- v7
+++ v8
@@ -5,106 +5,3 @@
 Sarg writes the full path to the current _sarg.conf_ when it is ran with the -x command line option. Use that command line option to find out exactly which _sarg.conf_ is taken into account.

 The options are described in the sample sarg.conf distributed along with the sources.
-
-
-## Options to reduce report size ##
-
-If you are short on disk space, here are some options you may try to reduce the reports size.
-
-###### graphs no ######
-Don't produce the graphs in the report.
-
-###### anonymous_output_files yes ######
-Every subdirectory and file created by sarg is assigned a unique number. A number is more difficult to relate to a user but it is shorter than a full user name. The gain is small.
-
-###### lastlog 10 ######
-Keep 10 reports, delete supernumerary reports. Adjust the number of reports you want to keep.
-
-###### report_type  ######
-Remove the reports you don't need from the list.
-
-sites_users, users_sites date_time and site_user_time_date take a lot of disk space.
-
-###### long_url no ######
-If set to _yes_ the complete URLs are included in the report. It takes a __lot__ of space. Set it to no.
-
-# Specifying the date range #
-
-A report covers a date range fixed when the report is generated. The dates covered in the report are specified with command line option -d.
-
-To produce a report of date _dd/mm/yyyy_ activity, use:
-
-    sarg -d dd/mm/yyyy
-
-To span several days, including the bounding dates, use
-
-    sarg -d dd/mm/yyyy-dd/mm/yyyy
-
-Now, it is very common to create reports for yesterday. Therefore, Sarg accepts the syntax:
-
-    sarg -d day-1
-
-It produces a report containing yesterday's activity.
-
-Similarly, to get last week's report, use
-
-    sarg -d week-1
-
-And for a report of last month's activity, use
-
-    sarg -d month-1
-
-The number after the day-, week- or month- part can be changed to produce a report at any time in the past. The number is related to the day, week or month accordingly. Therefore, month-2 is the month before the last when week-3 is three weeks ago and day-7 is a single day one week ago.
-
-# Keeping enough log to process #
-
-On Linux, log files are usually rotated away to keep them from growing until they fill the disk. After several rotations, old log files are deleted. _Logrotate_ is the package responsible for the log file rotation. It must be configured to keep enough material to produce the reports you need.
-
-For instance, if you want to produce a monthly report, you must store at least 32 days worth of log files (31 days to produce the report plus one as sarg runs after the last log file is rotated).
-
-_Squid_'s log file rotation is usually configured in a file named /etc/logrotate.d/squid or something equivalent. Here is a sample:
-
-    /var/log/squid/access.log {
-               weekly
-               rotate 5
-               copytruncate
-               compress
-               notifempty
-               missingok
-               }
-
-The above _logrotate_ file rotates /var/log/squid/access.log every week and keeps 5 compressed old log files. /var/log/squid/ will contain the following files:
-
-    access.log
-    access.log.1.gz
-    access.log.2.gz
-    access.log.3.gz
-    access.log.4.gz
-    access.log.5.gz
-
-Sarg can read them all, even the compressed log files, in order to collect the information it needs to produce the report. There are two ways of telling sarg which files to read.
-
-First, in _sarg.conf_, repeat access_log for every log file like this:
-
-    access_log /var/log/squid/access.log
-    access_log /var/log/squid/access.log.1.gz
-    access_log /var/log/squid/access.log.2.gz
-    access_log /var/log/squid/access.log.3.gz
-    access_log /var/log/squid/access.log.4.gz
-    access_log /var/log/squid/access.log.5.gz
-
-The files don't have to reside in the same directory. If the server running sarg is concentrating logs from several proxy, you can list the directories like this:
-
-    access_log /var/log/squid/server1/access.log
-    access_log /var/log/squid/server2/access.log
-    access_log /var/log/squid/server3/access.log
-
-Don't forget to list each server's rotated log files if you need them.
-
-There is one drawback though. Every listed file __must__ exist or sarg will complain and abort.
-
-The second way of telling sarg about the log files to read doesn't have that limitation. You simply list the files to process on the command line:
-
-    sarg -d week-1 /var/log/squid/access.log*
-
-The shell globs the path and calls sarg with every file matching the pattern.

3. Usage modified by Evgeniy Yakushev

Evgeniy Yakushev — Mon, 02 Nov 2015 07:16:06 -0000

--- v6
+++ v7
@@ -1,6 +1,6 @@
 # Configuration #

-Sarg reads its configuration options from a configuration file whose path is hard coded during the [Build] stage. It is usually set to /etc/sarg/sarg.conf (--sysconfdir=/etc/sarg) but the ./configure script puts it in /usr/local/etc/sarg.conf if no --prefix nor --sysconfdir options are provided.
+Sarg reads its configuration options from a configuration file whose path is hard coded during the [2.1 Build on Linux] stage. It is usually set to /etc/sarg/sarg.conf (--sysconfdir=/etc/sarg) but the ./configure script puts it in /usr/local/etc/sarg.conf if no --prefix nor --sysconfdir options are provided.

 Sarg writes the full path to the current _sarg.conf_ when it is ran with the -x command line option. Use that command line option to find out exactly which _sarg.conf_ is taken into account.

3. Usage modified by Evgeniy Yakushev

Evgeniy Yakushev — Mon, 02 Nov 2015 07:12:00 -0000

--- v5
+++ v6
@@ -6,37 +6,6 @@

 The options are described in the sample sarg.conf distributed along with the sources.

-## What report to produce ##
-
-A report can be made of several pages reporting various statistics. What pages are generated is selected by the report_type option.
-
-Possible values are:
-
-Flag | Description
------|------------
-topusers | Users who accessed internet the most.
-topsites | Most visited sites.
-sites_users | Who visited each site.
-users_sites | List of visited sites for each user.
-date_time | Tables with the daily and hourly downloaded amount of data.
-denied | Requests met with a 403/Denied HTTP code.
-auth_failures | Requests met with a 401/Denied or 407/Denied HTTP codes.
-site_user_time_date | A table listing at what date and time a user visited a given web site.
-downloads | Downloaded files (very unreliable).
-
-The list of downloaded files is very unreliable because it relies entirely on the URL processed by the proxy. More precisely, sarg compares the URL end with a list of common extensions for downloaded files. If a match is found, sarg assumes a file was downloaded.
-
-That procedure fails entirely if the name of the downloaded file is embedded deeper inside the URL as is the case when more HTTP arguments are appended after the name of the downloaded file:
-
-    http://server.com?file=file.zip&name=user
-
-In this example, sarg won't see that file.zip is being downloaded.
-
-Moreover, it is common for a URL to end with .com without this being the download of a _.com_ file:
-
-    http://server.org?redirect=server.com
-
-Again, sarg will fail and report this as a download.

 ## Options to reduce report size ##

3. Usage modified by Evgeniy Yakushev

Evgeniy Yakushev — Sun, 01 Nov 2015 19:18:20 -0000

WikiPage Usage modified by Frederic Marchal

Frederic Marchal — Sun, 20 Jan 2013 14:12:42 -0000

--- v3
+++ v4
@@ -71,7 +71,7 @@

     sarg -d dd/mm/yyyy-dd/mm/yyyy

-Now, it is very common to create reports for yesterday. Therefore, Sarg accept the syntax:
+Now, it is very common to create reports for yesterday. Therefore, Sarg accepts the syntax:

     sarg -d day-1

WikiPage Usage modified by Frederic Marchal

Frederic Marchal — Sun, 20 Jan 2013 14:06:49 -0000

--- v2
+++ v3
@@ -2,7 +2,7 @@

 Sarg reads its configuration options from a configuration file whose path is hard coded during the [Build] stage. It is usually set to /etc/sarg/sarg.conf (--sysconfdir=/etc/sarg) but the ./configure script puts it in /usr/local/etc/sarg.conf if no --prefix nor --sysconfdir options are provided.

-Sarg writes the full path to _sarg.conf_ when it is ran with the -x command line option. Use that command line option to find out exactly which _sarg.conf_ is taken into account.
+Sarg writes the full path to the current _sarg.conf_ when it is ran with the -x command line option. Use that command line option to find out exactly which _sarg.conf_ is taken into account.

 The options are described in the sample sarg.conf distributed along with the sources.

WikiPage Usage modified by Frederic Marchal

Frederic Marchal — Sun, 20 Jan 2013 14:05:36 -0000

--- v1
+++ v2
@@ -1,6 +1,6 @@
 # Configuration #

-Sarg reads its configuration options from a configuration file whose path is hard coded during the [Build] stage. It is usually set to /etc/sarg/sarg.conf (--sysconfdir=/etc/sarg) but the ./configure script puts it in /usr/local/etc/sarg.conf if no --prefix or --sysconfdir options are provided.
+Sarg reads its configuration options from a configuration file whose path is hard coded during the [Build] stage. It is usually set to /etc/sarg/sarg.conf (--sysconfdir=/etc/sarg) but the ./configure script puts it in /usr/local/etc/sarg.conf if no --prefix nor --sysconfdir options are provided.

 Sarg writes the full path to _sarg.conf_ when it is ran with the -x command line option. Use that command line option to find out exactly which _sarg.conf_ is taken into account.

@@ -15,7 +15,7 @@
 Flag | Description
 -----|------------
 topusers | Users who accessed internet the most.
-topsites | Most visites sites.
+topsites | Most visited sites.
 sites_users | Who visited each site.
 users_sites | List of visited sites for each user.
 date_time | Tables with the daily and hourly downloaded amount of data.
@@ -24,7 +24,23 @@
 site_user_time_date | A table listing at what date and time a user visited a given web site.
 downloads | Downloaded files (very unreliable).

+The list of downloaded files is very unreliable because it relies entirely on the URL processed by the proxy. More precisely, sarg compares the URL end with a list of common extensions for downloaded files. If a match is found, sarg assumes a file was downloaded.
+
+That procedure fails entirely if the name of the downloaded file is embedded deeper inside the URL as is the case when more HTTP arguments are appended after the name of the downloaded file:
+
+    http://server.com?file=file.zip&name=user
+
+In this example, sarg won't see that file.zip is being downloaded.
+
+Moreover, it is common for a URL to end with .com without this being the download of a _.com_ file:
+
+    http://server.org?redirect=server.com
+
+Again, sarg will fail and report this as a download.
+
 ## Options to reduce report size ##
+
+If you are short on disk space, here are some options you may try to reduce the reports size.

 ###### graphs no ######
 Don't produce the graphs in the report.
@@ -36,7 +52,90 @@
 Keep 10 reports, delete supernumerary reports. Adjust the number of reports you want to keep.

 ###### report_type  ######
-Remove the reports you don't need from the list. sites_users, users_sites date_time and site_user_time_date take a lot of disk space.
+Remove the reports you don't need from the list.
+
+sites_users, users_sites date_time and site_user_time_date take a lot of disk space.

 ###### long_url no ######
-Include the complete URL in the report. It takes a lot of space. Set it to no.
+If set to _yes_ the complete URLs are included in the report. It takes a __lot__ of space. Set it to no.
+
+# Specifying the date range #
+
+A report covers a date range fixed when the report is generated. The dates covered in the report are specified with command line option -d.
+
+To produce a report of date _dd/mm/yyyy_ activity, use:
+
+    sarg -d dd/mm/yyyy
+
+To span several days, including the bounding dates, use
+
+    sarg -d dd/mm/yyyy-dd/mm/yyyy
+
+Now, it is very common to create reports for yesterday. Therefore, Sarg accept the syntax:
+
+    sarg -d day-1
+
+It produces a report containing yesterday's activity.
+
+Similarly, to get last week's report, use
+
+    sarg -d week-1
+
+And for a report of last month's activity, use
+
+    sarg -d month-1
+
+The number after the day-, week- or month- part can be changed to produce a report at any time in the past. The number is related to the day, week or month accordingly. Therefore, month-2 is the month before the last when week-3 is three weeks ago and day-7 is a single day one week ago.
+
+# Keeping enough log to process #
+
+On Linux, log files are usually rotated away to keep them from growing until they fill the disk. After several rotations, old log files are deleted. _Logrotate_ is the package responsible for the log file rotation. It must be configured to keep enough material to produce the reports you need.
+
+For instance, if you want to produce a monthly report, you must store at least 32 days worth of log files (31 days to produce the report plus one as sarg runs after the last log file is rotated).
+
+_Squid_'s log file rotation is usually configured in a file named /etc/logrotate.d/squid or something equivalent. Here is a sample:
+
+    /var/log/squid/access.log {
+               weekly
+               rotate 5
+               copytruncate
+               compress
+               notifempty
+               missingok
+               }
+
+The above _logrotate_ file rotates /var/log/squid/access.log every week and keeps 5 compressed old log files. /var/log/squid/ will contain the following files:
+
+    access.log
+    access.log.1.gz
+    access.log.2.gz
+    access.log.3.gz
+    access.log.4.gz
+    access.log.5.gz
+
+Sarg can read them all, even the compressed log files, in order to collect the information it needs to produce the report. There are two ways of telling sarg which files to read.
+
+First, in _sarg.conf_, repeat access_log for every log file like this:
+
+    access_log /var/log/squid/access.log
+    access_log /var/log/squid/access.log.1.gz
+    access_log /var/log/squid/access.log.2.gz
+    access_log /var/log/squid/access.log.3.gz
+    access_log /var/log/squid/access.log.4.gz
+    access_log /var/log/squid/access.log.5.gz
+
+The files don't have to reside in the same directory. If the server running sarg is concentrating logs from several proxy, you can list the directories like this:
+
+    access_log /var/log/squid/server1/access.log
+    access_log /var/log/squid/server2/access.log
+    access_log /var/log/squid/server3/access.log
+
+Don't forget to list each server's rotated log files if you need them.
+
+There is one drawback though. Every listed file __must__ exist or sarg will complain and abort.
+
+The second way of telling sarg about the log files to read doesn't have that limitation. You simply list the files to process on the command line:
+
+    sarg -d week-1 /var/log/squid/access.log*
+
+The shell globs the path and calls sarg with every file matching the pattern.

WikiPage Usage modified by Frederic Marchal

Frederic Marchal — Sun, 20 Jan 2013 10:42:13 -0000

Configuration

Sarg reads its configuration options from a configuration file whose path is hard coded during the [Build] stage. It is usually set to /etc/sarg/sarg.conf (--sysconfdir=/etc/sarg) but the ./configure script puts it in /usr/local/etc/sarg.conf if no --prefix or --sysconfdir options are provided.

Sarg writes the full path to sarg.conf when it is ran with the -x command line option. Use that command line option to find out exactly which sarg.conf is taken into account.

The options are described in the sample sarg.conf distributed along with the sources.

What report to produce

A report can be made of several pages reporting various statistics. What pages are generated is selected by the report_type option.

Possible values are:

Flag	Description
topusers	Users who accessed internet the most.
topsites	Most visites sites.
sites_users	Who visited each site.
users_sites	List of visited sites for each user.
date_time	Tables with the daily and hourly downloaded amount of data.
denied	Requests met with a 403/Denied HTTP code.
auth_failures	Requests met with a 401/Denied or 407/Denied HTTP codes.
site_user_time_date	A table listing at what date and time a user visited a given web site.
downloads	Downloaded files (very unreliable).

Options to reduce report size

graphs no

Don't produce the graphs in the report.

anonymous_output_files yes

Every subdirectory and file created by sarg is assigned a unique number. A number is more difficult to relate to a user but it is shorter than a full user name. The gain is small.

lastlog 10

Keep 10 reports, delete supernumerary reports. Adjust the number of reports you want to keep.

report_type

Remove the reports you don't need from the list. sites_users, users_sites date_time and site_user_time_date take a lot of disk space.

long_url no

Include the complete URL in the report. It takes a lot of space. Set it to no.