Command line options

Command line options

If no command line options are provided, sarg reads its configuration file (/etc/sarg/sarg.conf by default) and generates a report with the specified options. Options provided on the command line override configuration file options.

Example

You have these parameters in your config file:

access_log /var/log/squid/access.log
output_dir /var/www/html/squid-reports

The command sarg called without any option will process file /var/log/squid/access.log and output the result in the /var/www/html/squid-reports directory.

A command sarg /var/log/squid/access.log*.gz -o /var/www/html/squid-reports/daily will execute sarg with default config file, but with replaced access_log and output_dir options.

If you wish to have different types of reports you can run sarg with different options or you can prepare various config files and run sarg with -f option and a path to the required config file.

-a ( HOST | IP )

Using this option, you can make report for specified host. Example:

sarg -a 10.1.2.34

-b FILE

If you need useragent report, you can pass -b option and the path to useragent log file in command line interface. Several files can be passed, each one must be prefixed with -b. Wildcards are NOT supported.

-c FILE

Use sarg -c /etc/sarg/excluded_host to exclude hosts in excluded_host file from reports.

--css

Print internal CSS to a shell. Using CSS file allows you to customize the look of report webpages: font size, position and colors of webpage elements and so on. You can put this file in report folder and set external_css_file option to use this file. Changing parameters in this file will affect the look of all pages simultaneously.

--convert

With this option sarg will list the access.log file (which is specified in access_log option in a config file) with a human readable dates instead of timestamps.The date format is %m/%d/%Y %X.
You can specify non-default access log file (see -l option). Gzipped files are not supported.

-d DATE

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.

-e ( E-MAIL | stdout )

Use sarg -e admin@mycompany.com to send reports to a mailbox. If you pass stdout instead of e-mail address, the report will be displayed in console:

Squid User Access Report
Sort: bytes, reverse
Period: 2015 Nov 13

NUM     USERID               CONNECT   BYTES           %BYTES  ELAPSED TIME MILLISEC   %TIME
------- -------------------- -------- --------------- ------- ---------- ---------- -------
...
     6            10.1.2.72     8261         440.43M   0.51%  132:21:04  476464299 0.51%
     7            10.1.1.89    28987         293.67M   0.34%  104:58:39  377919711 0.40%
     8            10.1.3.96     9470         189.88M   0.22%  133:22:23  480143049 0.51%
     9           10.1.1.234     3566         123.87M   0.14%   22:25:31   80731115 0.09%
... 
------- -------------------- -------- --------------- ------- ---------- ---------- -------
TOTAL                       2608078          86.53G          26020:26:53 93673613063
AVERAGE                        2637          87.49M           26:18:35   94715483

Fri Nov 13 15:06:15 2015

If you pass a valid e-mail, you will receive a mail with the same structure report.

-f FILE

You can have several configuration files for different types of reports. To specify a non-default configiration file, use:

sarg -f /etc/sarg/sarg-test.conf

-h or --help

Help on command line options usage.

-i

Normally, when sarg makes report by users, it ignores the IP address of a computer, where user was logged on. With this option you can get a detailed information from which computer a user had an access to Internet. See example:

--keeplogs

Keep every previously generated report

-L FILE

If you need redirector report, you can pass -L option and the path to squidGuard log file in command line interface. Several files can be passed, each one must be prefixed with -L. Compressed files in bz, gz and xz formats are supported. Wildcards are NOT supported.

-l FILE

By default, sarg analyzes /usr/local/squid/var/logs/access.log file. Option -l allows to specify another file or several files. These files can be compressed with gzip. You can specify more than one file, for example:

sarg -l var/log/squid/access.log-20151001.gz -l var/log/squid/access.log-20150930.gz

Option -l can be omitted, in this case all unknown options will be assumed to be input log files. Example:

sarg var/log/squid/access.log-20151001.gz var/log/squid/access.log-20150930.gz

Compressed files in bz, gz and xz formats are supported. Wildcards are also supported. For example, the following command will process every input log file beginning with "access.log-201510" and ending with ".gz":

sarg /var/log/squid/access.log-201510*.gz

Note that the above command won't work if the file name is preceded with -l and sarg was compiled without file globbing support (i.e. glob.h wasn't found at compile time or --without-glob was passed to the configure script). In that case, simply drop the -l from the command line and let the shell do the file globbing.

--lastlog=NUMBER

Set the number of previous reports to keep.

Eg.: sarg -o /var/www/html/squidreports/weekly --lastlog=52
This command will put the report to a weekly directory and remove those that are older rhan a year.

-n

Resolve IP addresses using RDNS.

-o PATH

The default output directory is /var/www/html/squid-reports. You might want to use different directories for different types of reports: daily, weekly, departments and so on. To change a default directory, use

sarg -o /var/www/html/squid-reports/weekly -d day-1

-p

Use IP address instead of userid even though log files contain authentication information.
See the page squid native log format to get more information about structure of squid log file.

-s SITENAME

Limiting report by a site. Eg. sarg -s www.microsoft.com.

--split
--splitprefix PREFIX or -P PREFIX

Split the log file by date in -d parameter.
Squid access logs may be rotated when reached specific size. Then one day log may consist of several log files. In one log file there can be the end of one day and the start of another. Or on the other hand, log may be rotated very rarely (say, monthly) or when reached huge size.
This option allows you to select records written in a specified day from one or several log files.

Example 1:

sarg --split /var/log/squid/access.log* -d 03/11/2015 --splitprefix acl -o /var/squidlogs

This command will create a new file /var/squidlogs/acl-2015-11-03, which contains records made on Nov 3 2015.

Example 2:

sarg --split /var/log/squid/access.log* -d 03/11/2015-05/11/2015 --splitprefix acl -o /var/squidlogs

This command will create three new files in a /var/squidlogs directory:
acl-2015-11-03 acl-2015-11-04 acl-2015-11-05

They will contains records made on Nov 3 2015, Nov 4 2015, Nov 5 2015 respectively.

If --splitprefix is not specified, then records will be sent to stdout.

Gzipped files are supported.

--statistics

Add this parameter to see sarg execution statistics. The output will be like this:

SARG: Total execution time: 129 seconds
SARG: Lines read: 575760 lines in 40 seconds (14394 lines/s)
SARG: Processed records: 575758 records in 89 seconds (6469 records/s)
SARG: Users: 268 users in 89 seconds (3 users/s)

-t TIME

TIME format is HH:MM or HH:MM-HH:MM. You might want to take into account only traffic generated in a particular period of time, for example, working time. To achieve this, use:

sarg -t 09:00-18:00 -d day-1

The above example produces a report containing every access made between 09:00 inclusive and 18:00 exclusive (i.e. until 17:59:59.999).

If you want to setup more complex time ranges, use weekdays and hours options in sarg.conf.

If you pass a specific time then only traffic of a specific minute will be included.
E.g. Option -t 09:00 limits time from 09:00:00 to 09:00:59.999.

-u USER

You might want to make a report only for specified user. Use -u option:

sarg -u johnsmith

Only one user can be specified by this option. If you wish to make report by some set of users (department, branch, etc.) you may use include_users parameter in sarg.conf.

Note: if you use no authentication on you proxy server and even though resolve_ip option in sarg.conf is set to yes or exec, you should pass an IP address instead of domain name or NetBIOS name or whatever name, since squid writes in access.log the IP addresses, not the domain names.

-w PATH

Use -w to specify non-default directory for temp files.
Eg.: sarg -w /mnt/hdb2/sarg

-x

Displays sarg debug messages.

-z

Displays sarg process messages.

-

This option (single minus sign) on the end of command instructs sarg to read log from stdin. It's useful when you want to filter or modify log records on the fly and pass it to sarg without need to modify access.log file or creating a transformed one.

Example:

zcat /var/log/squid/access.log-20151113.gz | grep -v 'peter' | sarg -

It is going to act like exclude_user peter option in configuration file.