-.\" 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 \fBMicrosoft 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. 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