-.\" Hey, EMACS: -*- nroff -*-
-.\" First parameter, NAME, should be all caps
-.\" Second parameter, SECTION, should be 1-8, maybe w/ subsection
-.\" other parameters are allowed: see man(7), man(1)
-.TH SARG 1 "May 9, 2010"
-.\" Please adjust this date whenever revising the manpage.
+'\" 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
.\"
-.\" Some roff macros, for reference:
-.\" .nh disable hyphenation
-.\" .hy enable hyphenation
-.\" .ad l left justify
-.\" .ad b justify to both left and right margins
-.\" .nf disable filling
-.\" .fi enable filling
-.\" .br insert line break
-.\" .sp <n> insert n+1 empty lines
-.\" for manpage-specific macros, see man(7)
-.SH NAME
+.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
-.B sarg
-.RI [ options ]
-.I logfile...
-.SH DESCRIPTION
-\fBsarg\fP is a logfile parser and analyzer for the \fBSquid Web Proxy Cache\fP,
-which can be found at \fBhttp://www.squid-cache.org/\fP.
-This manual page documents briefly the
-.B sarg
-command. More information is available at \fBhttp://sarg.sourceforge.net/\fP.
-This manual page was originally written for the Debian distribution
-because the author didn't include one in favor of documentation
-in the GNU Info format; see below.
-.PP
-.\" TeX users may be more comfortable with the \fB<whatever>\fP and
-.\" \fI<whatever>\fP escape sequences to invode bold face and italics,
-.\" respectively.
-\fBsarg\fP is a tool that allows you to view "where" your users are going to on
-the Internet. \fBsarg\fP generates reports in HTML, with fields such as: users,
-IP Addresses, bytes, sites, and times. These HTML files can appear in your
-web server's directory for browsing by users or administrators. You may also
-have \fBsarg\fP email the reports to the Squid Cache administrator.
-.PP
-\fBsarg\fP can read \fBsquid\fP or \fBMicorosft ISA\fP access logs. Optionally, it can
-complement the reports with the log of a Squid filter/redirector such as
-\fBsquidGuard (http://www.squidguard.org/)\fP.
-.SH OPTIONS
-A summary of options is included below.
-.TP
-.B \-h
-Show summary of options.
-.TP
-.B \-a [hostname|ip address]
+.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
-.TP
-.B \-b filename
+.RE
+.PP
+\fB\-b \fR\fB\fIfilename\fR\fR
+.RS 4
Enables UserAgent log and writes it to
-.IR "filename".
-.TP
-.B \-c filename
-Uses
-.IR "filename"
-as the exclude files to select records that are not counted.
-.TP
-.B \-\-convert
-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.
-.TP
-.B \-\-css
-Output, on the standard output, the internal css inlined in the reports by sarg. You can redirect the output to a file of your
-choice and edit it. Then you can override the internal css with
-.B external_css_file
-in sarg.conf.
-.TP
-.B \-d date
-Uses
-.I date
-as the time limit during log file processing. Format for
-.I date
+\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
-.B dd/mm/yyyy-dd/mm/yyyy
+\fBdd/mm/yyyy\-dd/mm/yyyy\fR
or a single date
-.BR "dd/mm/yyyy" ". Date ranges can also be specified as " "day-\fIn\fP" ", " "week-\fIn\fP" ", or " "month-\fIn\fP"
+\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
-.I n
-is the number of days, weeks or months to jump backward. Note that there is no spaces around the hyphen.
-.TP
-.B \-e email
+\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
-.IR "email"
-(stdout for console).
-.TP
-.B \-f filename
+\fIemail\fR
+(stdout for console)\&.
+.RE
+.PP
+\fB\-f \fR\fB\fIfilename\fR\fR
+.RS 4
Reads configuration from
-.IR "filename".
-.TP
-.B \-g e|u
-Sets date format in generated reports.
-.br
-\fBe\fP = Europe -> dd/mm/yy
+\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
-\fBu\fP = USA -> mm/dd/yy
-.TP
-.B \-i
-Generates reports by user and ip address.
+.ps +1
+\fBNote\fR
+.ps -1
.br
-\fBNOTE:\fP This requires the 'report_type'
-option in config file to contain "users_sites".
-.TP
-.B \-l filename
+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
-.IR "filename"
-as the input log. This option can be repeated up to 255 times to read multiple files. The files must be listed in chronological order from newest to oldest. If the files end with the extension
-.IR ".gz" ", " ".bz2" " or " ".Z"
-they are decompressed.
-If the file name is just
-.I -
-, the log file is read from standard input. In that case, it cannot be compressed.
-
-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
-.B \-l
-option. It allows the use of wildcards on the command line. Make sure you don't exceed the limit of 255 files.
-.TP
-.B \-L filename
-Reads a proxy redirector log file such as one created by squidGuard or Rejik. If you use this option, you may want to configure
-.B redirector_log_format
-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.
-.TP
-.B \-n
-Enables ip address resolution.
-.TP
-.B \-o dir
+\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
-.IR "dir".
-.TP
-.B \-p
-Generates reports using ip address instead of userid.
-.TP
-.B \-s string
+\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
-.IR "string
-[eg. www.debian.org]
-.TP
-.B \-\-split
-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\fP parameter.
-If it is combined with
-.B \-\-convert
-the dates are also converted to a human-readable format.
-.TP
-.B \-t string
-Limits records counted in statistics based on time-of-day. Format for
-\fIstring\fP is \fBHH\fP or \fBHH:MM\fP or \fBHH:MM:SS\fP.
-.TP
-.B \-u user
-Limits reports to \fIuser\fP activities.
-.TP
-.B \-w dir
-Uses \fIdir\fP for temporary files.
-.TP
-.B \-x
-Writes debug messages to \fBSTDOUT\fP
-.TP
-.B \-z
-Writes messages on processes to \fBSTDOUT\fP
-.SH FILES
-.BR /usr/local/sarg/sarg.conf
+\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
-.B /var/log/squid/access.log
+Copyright \(co 2012 Frédéric Marchal
.br
-.B /usr/local/squidGuard/logs/squidGuard.log
-.SH SEE ALSO
-squid(8)
-.SH AUTHOR
-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.
+.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
projects / thirdparty / sarg.git / blobdiff