3 .\" Author: Frédéric Marchal <fmarchal@users.sourceforge.net>
4 .\" Generator: DocBook XSL Stylesheets v1.75.2 <http://docbook.sf.net/>
10 .TH "SARG" "1" "27 May 2012" "sarg" "SARG"
11 .\" -----------------------------------------------------------------
12 .\" * Define some portability stuff
13 .\" -----------------------------------------------------------------
14 .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
15 .\" http://bugs.debian.org/507673
16 .\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
17 .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
20 .\" -----------------------------------------------------------------
21 .\" * set default formatting
22 .\" -----------------------------------------------------------------
23 .\" disable hyphenation
25 .\" disable justification (adjust text to left margin only)
27 .\" -----------------------------------------------------------------
28 .\" * MAIN CONTENT STARTS HERE *
29 .\" -----------------------------------------------------------------
31 sarg \- Squid Analysis Report Generator
34 \fBsarg\fR [options] [logfile...]
39 is a log file parser and analyzer for the
40 \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\&.
44 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
46 email the reports to the Squid Cache administrator\&.
54 access logs\&. Optionally, it can complement the reports with the log of a Squid filter/redirector such as
55 \m[blue]\fBsquidGuard\fR\m[]\&\s-2\u[2]\d\s+2\&.
58 A summary of options is included below\&.
60 \fB\-h\fR \fB\-\-help\fR
62 Show summary of options\&.
65 \fB\-a hostname|ip address\fR
67 Limits report to records containing the specified hostname/ip address
70 \fB\-b \fR\fB\fIfilename\fR\fR
72 Enables UserAgent log and writes it to
79 .nr an-no-space-flag 1
86 This option is currently unused\&.
91 \fB\-c \fR\fB\fIfilename\fR\fR
95 for a list of the web hosts to exclude from the report\&. See
96 the section called \(lqHOST EXCLUSION FILE\(rq\&.
103 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\&.
108 Output, on the standard output, the internal css
110 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
111 \fIexternal_css_file\fR
115 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\&.
118 \fB\-d \fR\fB\fIdate\fR\fR
122 to restrict the report to some date range during log file processing\&. Format for
125 \fBdd/mm/yyyy\-dd/mm/yyyy\fR
127 \fBdd/mm/yyyy\fR\&. Date ranges can also be specified as
128 \fIday\-\fR\fI\fBn\fR\fR,
129 \fIweek\-\fR\fI\fBn\fR\fR, or
130 \fImonth\-\fR\fI\fBn\fR\fR
133 is the number of days, weeks or months to jump backward\&. Note that there is no spaces around the hyphen\&.
136 \fB\-e \fR\fB\fIemail\fR\fR
140 (stdout for console)\&.
143 \fB\-f \fR\fB\fIfilename\fR\fR
145 Reads configuration from
151 Sets date format in generated reports\&.
153 e = Europe \-> dd/mm/yy
162 Generates reports by user and ip address\&.
168 .nr an-no-space-flag 1
177 option in config file to contain "users_sites"\&.
184 Don\*(Aqt delete any old report\&. It is equivalent to setting
186 but is provided for convenience\&.
189 \fB\-l \fR\fB\fIfilename\fR\fR
193 as the input log\&. This option can be repeated up to 255 times to read multiple files\&. If the files end with the extension
198 they are decompressed\&. If the file name is just
199 \fI\-\fR, the log file is read from standard input\&. In that case, it cannot be compressed\&.
201 This option is kept for compatibility with older versions of sarg but, starting with
202 sarg 2\&.3, the log files may be named on the command line without the
204 option\&. It allows the use of wildcards on the command line\&. Make sure you don\*(Aqt exceed the limit of 255 files\&.
207 \fB\-\-lastlog \fR\fB\fIn\fR\fR
209 Limit the number of logs kept in the output directory to
210 \fIn\fR\&. Any supernumerary report is deleted starting with the oldest report\&. The value of
212 must be positive or zero\&. A value of zero means no report should be deleted\&.
215 \fB\-L \fR\fB\fIfilename\fR\fR
217 Reads a proxy redirector log file such as one created by
220 Rejik\&. If you use this option, you may want to configure
221 \fIredirector_log_format\fR
224 to match the output format of your web content filtering program\&. This option can be repeated up to 64 times to read multiple files\&.
229 Enable advanced processing debug messages\&. This option produces an enourmous amount of output\&.
234 Enables ip address resolution\&.
237 \fB\-o \fR\fB\fIdir\fR\fR
245 Generates reports using ip address instead of userid\&.
248 \fB\-P \fR\fB\fIprefix\fR\fR \fB\-\-splitprefix \fR\fB\fIprefix\fR\fR
250 This option must be used with
251 \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
253 and the date formated as
256 The output files are written in the output directory specified with
258 or in the current directory\&.
263 Output the realtime report on the standard output and exit\&.
266 \fB\-s \fR\fB\fIstring\fR\fR
268 Limits report to the site specified by
270 [eg\&. www\&.debian\&.org]
275 Split the squid log file and output it as text on the standard output omitting the dates outside of the range specified by the
277 parameter\&. If it is combined with
279 the dates are also converted to a human\-readable format\&.
282 \fB\-P\fR, the log is written in several files each containing one day of the original log\&.
287 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\&.
290 \fB\-t \fR\fB\fIstring\fR\fR
292 Limits the records included in the report based on time\-of\-day\&. Format for
297 \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
301 \fB\-u \fR\fB\fIuser\fR\fR
310 Write sarg version and exit\&.
313 \fB\-w \fR\fB\fIdir\fR\fR
315 Store temporary files in
316 \fIdir\fR\&. In fact,
318 stores its temporary files in the
321 \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\&.
326 Writes debug messages to
332 Writes process messages to
335 .SH "HOST EXCLUSION FILE"
337 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:
358 a host name starting with a wildcard (*) to match any prefix,
380 a subnet noted a\&.b\&.c\&.d/e\&.
383 \fBExample\ \&1.\ \&Example of a hosts exclusion file\fR
391 Sarg cannot exclude IPv6 addresses at the moment\&.
397 This manual page was written by
399 gangitano@lugroma3\&.org, for the
401 system (but may be used by others)\&. Revised by
404 Currently maintained by
406 fmarchal@users\&.sourceforge\&.net\&.
409 \fBFrédéric Marchal\fR <\&fmarchal@users\&.sourceforge\&.net\&>
411 Docbook version of the manual page
416 Revision of the manual page
419 \fBLuigi Gangitano\fR <\&gangitano@lugroma3\&.org\&>
421 Author of the first manual page
425 Copyright \(co 2012 Frédéric Marchal
429 Squid Web Proxy Cache
431 \%http://www.squid-cache.org/
436 \%http://www.squidguard.org/