sarg.1

   1 .\"                                      Hey, EMACS: -*- nroff -*-
   2 .\" First parameter, NAME, should be all caps
   3 .\" Second parameter, SECTION, should be 1-8, maybe w/ subsection
   4 .\" other parameters are allowed: see man(7), man(1)
   5 .TH SARG 1 "May 9, 2010"
   6 .\" Please adjust this date whenever revising the manpage.
   7 .\"
   8 .\" Some roff macros, for reference:
   9 .\" .nh        disable hyphenation
  10 .\" .hy        enable hyphenation
  11 .\" .ad l      left justify
  12 .\" .ad b      justify to both left and right margins
  13 .\" .nf        disable filling
  14 .\" .fi        enable filling
  15 .\" .br        insert line break
  16 .\" .sp <n>    insert n+1 empty lines
  17 .\" for manpage-specific macros, see man(7)
  18 .SH NAME
  19 sarg \- Squid Analysis Report Generator
  20 .SH SYNOPSIS
  21 .B sarg
  22 .RI [ options ]
  23 .I logfile...
  24 .SH DESCRIPTION
  25 \fBsarg\fP is a logfile parser and analyzer for the \fBSquid Web Proxy Cache\fP,
  26 which can be found at \fBhttp://www.squid-cache.org/\fP.
  27 This manual page documents briefly the
  28 .B sarg
  29 command. More information is available at \fBhttp://sarg.sourceforge.net/\fP.
  30 This manual page was originally written for the Debian distribution
  31 because the author didn't include one in favor of documentation
  32 in the GNU Info format; see below.
  33 .PP
  34 .\" TeX users may be more comfortable with the \fB<whatever>\fP and
  35 .\" \fI<whatever>\fP escape sequences to invode bold face and italics,
  36 .\" respectively.
  37 \fBsarg\fP is a tool that allows you to view "where" your users are going to on
  38 the Internet. \fBsarg\fP generates reports in HTML, with fields such as: users,
  39 IP Addresses, bytes, sites, and times.  These HTML files can appear in your
  40 web server's directory for browsing by users or administrators.  You may also
  41 have \fBsarg\fP email the reports to the Squid Cache administrator.
  42 .PP
  43 \fBsarg\fP can read \fBsquid\fP or \fBMicorosft ISA\fP access logs. Optionally, it can
  44 complement the reports with the log of a Squid filter/redirector such as
  45 \fBsquidGuard (http://www.squidguard.org/)\fP.
  46 .SH OPTIONS
  47 A summary of options is included below.
  48 .TP
  49 .B \-h
  50 Show summary of options.
  51 .TP
  52 .B \-a [hostname|ip address]
  53 Limits report to records containing the specified hostname/ip address
  54 .TP
  55 .B \-b filename
  56 Enables UserAgent log and writes it to
  57 .IR "filename".
  58 .TP
  59 .B \-c filename
  60 Uses
  61 .IR "filename"
  62 as the exclude files to select records that are not counted.
  63 .TP
  64 .B \-\-convert
  65 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.
  66 .TP
  67 .B \-\-css
  68 Output, on the standard output, the internal css inlined in the reports by sarg. You can redirect the output to a file of your
  69 choice and edit it. Then you can override the internal css with
  70 .B external_css_file
  71 in sarg.conf.
  72 .TP
  73 .B \-d date
  74 Uses
  75 .I date
  76 as the time limit during log file processing. Format for
  77 .I date
  78 is
  79 .B dd/mm/yyyy-dd/mm/yyyy
  80 or a single date
  81 .BR "dd/mm/yyyy" ". Date ranges can also be specified as " "day-\fIn\fP" ", " "week-\fIn\fP" ", or " "month-\fIn\fP"
  82 where
  83 .I n
  84 is the number of days, weeks or months to jump backward. Note that there is no spaces around the hyphen.
  85 .TP
  86 .B \-e email
  87 Sends report to
  88 .IR "email"
  89 (stdout for console).
  90 .TP
  91 .B \-f filename
  92 Reads configuration from
  93 .IR "filename".
  94 .TP
  95 .B \-g e|u
  96 Sets date format in generated reports.
  97 .br
  98 \fBe\fP = Europe -> dd/mm/yy
  99 .br
 100 \fBu\fP = USA    -> mm/dd/yy
 101 .TP
 102 .B \-i
 103 Generates reports by user and ip address.
 104 .br
 105 \fBNOTE:\fP This requires the 'report_type'
 106 option in config file to contain "users_sites".
 107 .TP
 108 .B \-l filename
 109 Uses
 110 .IR "filename"
 111 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
 112 .IR ".gz" ", " ".bz2" " or " ".Z"
 113 they are decompressed.
 114 If the file name is just
 115 .I -
 116 , the log file is read from standard input. In that case, it cannot be compressed.
 117
 118 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
 119 line without the
 120 .B \-l
 121 option. It allows the use of wildcards on the command line. Make sure you don't exceed the limit of 255 files.
 122 .TP
 123 .B \-L filename
 124 Reads a proxy redirector log file such as one created by squidGuard or Rejik. If you use this option, you may want to configure
 125 .B redirector_log_format
 126 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.
 127 .TP
 128 .B \-n
 129 Enables ip address resolution.
 130 .TP
 131 .B \-o dir
 132 Writes report in
 133 .IR "dir".
 134 .TP
 135 .B \-p
 136 Generates reports using ip address instead of userid.
 137 .TP
 138 .B \-s string
 139 Limits report to the site specified by
 140 .IR "string
 141 [eg. www.debian.org]
 142 .TP
 143 .B \-\-split
 144 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.
 145 If it is combined with
 146 .B \-\-convert
 147 the dates are also converted to a human-readable format.
 148 .TP
 149 .B \-t string
 150 Limits records counted in statistics based on time-of-day. Format for
 151 \fIstring\fP is \fBHH\fP or \fBHH:MM\fP or \fBHH:MM:SS\fP.
 152 .TP
 153 .B \-u user
 154 Limits reports to \fIuser\fP activities.
 155 .TP
 156 .B \-w dir
 157 Uses \fIdir\fP for temporary files.
 158 .TP
 159 .B \-x
 160 Writes debug messages to \fBSTDOUT\fP
 161 .TP
 162 .B \-z
 163 Writes messages on processes to \fBSTDOUT\fP
 164 .SH FILES
 165 .BR /usr/local/sarg/sarg.conf
 166 .br
 167 .B /var/log/squid/access.log
 168 .br
 169 .B /usr/local/squidGuard/logs/squidGuard.log
 170 .SH SEE ALSO
 171 squid(8)
 172 .SH AUTHOR
 173 This manual page was written by Luigi Gangitano <gangitano@lugroma3.org>,
 174 for the Debian GNU/Linux system (but may be used by others).  Revised
 175 by Billy Newsom.