'\" t
.\"     Title: sarg
.\"    Author: Frédéric Marchal <fmarchal@users.sourceforge.net>
.\" Generator: DocBook XSL Stylesheets v1.78.1 <http://docbook.sf.net/>
.\"      Date: 12 Nov 2015
.\"    Manual: SARG
.\"    Source: sarg
.\"  Language: English
.\"
.TH "SARG" "1" "12 Nov 2015" "sarg" "SARG"
.\" -----------------------------------------------------------------
.\" * Define some portability stuff
.\" -----------------------------------------------------------------
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.\" http://bugs.debian.org/507673
.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\" -----------------------------------------------------------------
.\" * set default formatting
.\" -----------------------------------------------------------------
.\" disable hyphenation
.nh
.\" disable justification (adjust text to left margin only)
.ad l
.\" -----------------------------------------------------------------
.\" * MAIN CONTENT STARTS HERE *
.\" -----------------------------------------------------------------
.SH "NAME"
sarg \- Squid Analysis Report Generator
.SH "SYNOPSIS"
.HP \w'\fBsarg\fR\ 'u
\fBsarg\fR [options] [logfile...]
.SH "DESCRIPTION"
.PP
\fBsarg\fR
is a log file parser and analyzer for the
\m[blue]\fBSquid Web Proxy Cache\fR\m[]\&\s-2\u[1]\d\s+2\&. It allows you to view "where" your users are going to on the Internet\&.
.PP
\fBsarg\fR
generates reports in HTML with fields such as: users, IP Addresses, bytes, sites, and times\&. These HTML files can appear in your web server\*(Aqs directory for browsing by users or administrators\&. You may also have
\fBsarg\fR
email the reports to the Squid Cache administrator\&.
.PP
\fBsarg\fR
can read
squid
or
Microsoft ISA
access logs\&. Optionally, it can complement the reports with the log of a Squid filter/redirector such as
\m[blue]\fBsquidGuard\fR\m[]\&\s-2\u[2]\d\s+2\&.
.SH "OPTIONS"
.PP
A summary of options is included below\&.
.PP
\fB\-h\fR \fB\-\-help\fR
.RS 4
Show summary of options\&.
.RE
.PP
\fB\-a hostname|ip address\fR
.RS 4
Limits report to records containing the specified hostname/ip address
.RE
.PP
\fB\-b \fR\fB\fIfilename\fR\fR
.RS 4
Enables UserAgent log and writes it to
\fIfilename\fR\&.
.RE
.PP
\fB\-c \fR\fB\fIfilename\fR\fR
.RS 4
Read
\fIfilename\fR
for a list of the web hosts to exclude from the report\&. See
the section called \(lqHOST EXCLUSION FILE\(rq\&.
.RE
.PP
\fB\-\-convert\fR
.RS 4
Convert a
squid
log file date/time field to a human\-readable format\&. All the log files are read and output as one text on the standard output\&.
.RE
.PP
\fB\-\-css\fR
.RS 4
Output, on the standard output, the internal css
\fBsarg\fR
inlines in the reports\&. You can redirect the output to a file of your choice and edit it\&. Then you can override the internal css with
\fIexternal_css_file\fR
in
sarg\&.conf\&.
.sp
Using an external css can reduce the size of the report file\&. If you are short on disk space, you may consider exporting the css as explained above\&.
.RE
.PP
\fB\-d \fR\fB\fIdate\fR\fR
.RS 4
Use
\fIdate\fR
to restrict the report to some date range during log file processing\&. Format for
\fIdate\fR
is
\fBdd/mm/yyyy\-dd/mm/yyyy\fR
or a single date
\fBdd/mm/yyyy\fR\&. Date ranges can also be specified as
\fIday\-\fR\fI\fBn\fR\fR,
\fIweek\-\fR\fI\fBn\fR\fR, or
\fImonth\-\fR\fI\fBn\fR\fR
where
\fBn\fR
is the number of days, weeks or months to jump backward\&. Note that there is no spaces around the hyphen\&.
.RE
.PP
\fB\-e \fR\fB\fIemail\fR\fR
.RS 4
Sends report to
\fIemail\fR
(stdout for console)\&.
.RE
.PP
\fB\-f \fR\fB\fIfilename\fR\fR
.RS 4
Reads configuration from
\fIfilename\fR\&.
.RE
.PP
\fB\-g e|u\fR
.RS 4
Sets date format in generated reports\&.
.RS 4
e = Europe \-> dd/mm/yy
.RE
.RS 4
u = USA    \-> mm/dd/yy
.RE
.RE
.PP
\fB\-i\fR
.RS 4
Generates reports by user and ip address\&.
.if n \{\
.sp
.\}
.RS 4
.it 1 an-trap
.nr an-no-space-flag 1
.nr an-break-flag 1
.br
.ps +1
\fBNote\fR
.ps -1
.br
This requires the
\fIreport_type\fR
option in config file to contain "users_sites"\&.
.sp .5v
.RE
.RE
.PP
\fB\-\-keeplogs\fR
.RS 4
Don\*(Aqt delete any old report\&. It is equivalent to setting
\fB\-\-lastlog 0\fR
but is provided for convenience\&.
.RE
.PP
\fB\-l \fR\fB\fIfilename\fR\fR
.RS 4
Uses
\fIfilename\fR
as the input log\&. This option can be repeated up to 255 times to read multiple files\&. If the files end with the extension
\&.gz,
\&.bz2
or
\&.Z
they are decompressed\&. If the file name is just
\fI\-\fR, the log file is read from standard input\&. In that case, it cannot be compressed\&.
.sp
This option is kept for compatibility with older versions of sarg but, starting with
sarg 2\&.3, the log files may be named on the command line without the
\fB\-l\fR
option\&. It allows the use of wildcards on the command line\&. Make sure you don\*(Aqt exceed the limit of 255 files\&.
.RE
.PP
\fB\-\-lastlog \fR\fB\fIn\fR\fR
.RS 4
Limit the number of logs kept in the output directory to
\fIn\fR\&. Any supernumerary report is deleted starting with the oldest report\&. The value of
\fIn\fR
must be positive or zero\&. A value of zero means no report should be deleted\&.
.RE
.PP
\fB\-L \fR\fB\fIfilename\fR\fR
.RS 4
Reads a proxy redirector log file such as one created by
squidGuard
or
Rejik\&. If you use this option, you may want to configure
\fIredirector_log_format\fR
in
sarg\&.conf
to match the output format of your web content filtering program\&. This option can be repeated up to 64 times to read multiple files\&.
.RE
.PP
\fB\-n\fR
.RS 4
Enables ip address resolution\&.
.RE
.PP
\fB\-o \fR\fB\fIdir\fR\fR
.RS 4
Writes report in
\fIdir\fR\&.
.RE
.PP
\fB\-p\fR
.RS 4
Generates reports using ip address instead of userid\&.
.RE
.PP
\fB\-P \fR\fB\fIprefix\fR\fR \fB\-\-splitprefix \fR\fB\fIprefix\fR\fR
.RS 4
This option must be used with
\fB\-\-split\fR\&. If it is provided, the input log is split among several files each containing one day\&. The name of the output files is made of the
\fIprefix\fR
and the date formated as
\-YYYY\-MM\-DD\&.
.sp
The output files are written in the output directory specified with
\fB\-o\fR
or in the current directory\&.
.RE
.PP
\fB\-r\fR
.RS 4
Output the realtime report on the standard output and exit\&.
.RE
.PP
\fB\-s \fR\fB\fIstring\fR\fR
.RS 4
Limits report to the site specified by
\fIstring\fR
[eg\&. www\&.debian\&.org]
.RE
.PP
\fB\-\-split\fR
.RS 4
Split the squid log file and output it as text on the standard output omitting the dates outside of the range specified by the
\fB\-d\fR
parameter\&. If it is combined with
\fB\-\-convert\fR
the dates are also converted to a human\-readable format\&.
.sp
Combined with
\fB\-P\fR, the log is written in several files each containing one day of the original log\&.
.RE
.PP
\fB\-\-statistics\fR
.RS 4
Writes some statistics about the execution time\&. The statistics include the total execution time; the number of records read in the input log files and the time it took to read them; the number of records and users processed and the time it took to process them\&.
.RE
.PP
\fB\-t \fR\fB\fIstring\fR\fR
.RS 4
Limits the records included in the report based on time\-of\-day\&. Format for
\fIstring\fR
is
\fBHH:MM\fR
or
\fBHH:MM\-HH:MM\fR\&. The former reports only the requested time\&. The latter reports any entry falling within the requested range\&. This limit complement the limit imposed by option
\fB\-d\fR\&.
.RE
.PP
\fB\-u \fR\fB\fIuser\fR\fR
.RS 4
Limits reports to
\fIuser\fR
activities\&.
.RE
.PP
\fB\-v\fR
.RS 4
Write sarg version and exit\&.
.RE
.PP
\fB\-w \fR\fB\fIdir\fR\fR
.RS 4
Store temporary files in
\fIdir\fR\&. In fact,
\fBsarg\fR
stores its temporary files in the
sarg
subdirectory of
\fIdir\fR\&. Be sure to set the HTML output directory to a place outside of the temporary directory or sarg may fail or delete the report when it completes its task\&.
.RE
.PP
\fB\-x\fR
.RS 4
Writes debug messages to
stdout
.RE
.PP
\fB\-z\fR
.RS 4
Writes process messages to
stdout\&.
.RE
.SH "HOST EXCLUSION FILE"
.PP
Sarg can be told to exclude visited hosts from the report by providing it with a file containing one host to exclude per line\&. The "host" may be one of the following:
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
a full host name,
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
a host name starting with a wildcard (*) to match any prefix,
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
a single ip address,
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
a subnet noted a\&.b\&.c\&.d/e\&.
.RE
.PP
\fBExample\ \&1.\ \&Example of a hosts exclusion file\fR
.RS 4
*\&.google\&.com
.RE
.RS 4
10\&.0\&.0\&.0/8
.RE
.PP
Sarg cannot exclude IPv6 addresses at the moment\&.
.SH "SEE ALSO"
.PP
squid(8)
.SH "AUTHORS"
.PP
This manual page was written by
Luigi Gangitano<gangitano@lugroma3\&.org>, for the
Debian GNU/Linux
system (but may be used by others)\&. Revised by
Billy Newsom\&.
.PP
Currently maintained by
Frédéric Marchal<fmarchal@users\&.sourceforge\&.net>\&.
.SH "AUTHORS"
.PP
\fBFrédéric Marchal\fR <\&fmarchal@users\&.sourceforge\&.net\&>
.RS 4
Docbook version of the manual page
.RE
.PP
\fBBilly Newsom\fR
.RS 4
Revision of the manual page
.RE
.PP
\fBLuigi Gangitano\fR <\&gangitano@lugroma3\&.org\&>
.RS 4
Author of the first manual page
.RE
.SH "COPYRIGHT"
.br
Copyright \(co 2012 Frédéric Marchal
.br
.SH "NOTES"
.IP " 1." 4
Squid Web Proxy Cache
.RS 4
\%http://www.squid-cache.org/
.RE
.IP " 2." 4
squidGuard
.RS 4
\%http://www.squidguard.org/
.RE