sarg.1

   1 '\" t
   2 .\"     Title: sarg
   3 .\"    Author: Luigi Gangitano <gangitano@lugroma3.org>
   4 .\" Generator: DocBook XSL Stylesheets v1.75.2 <http://docbook.sf.net/>
   5 .\"      Date: 27 Nov 2010
   6 .\"    Manual: SARG
   7 .\"    Source: sarg
   8 .\"  Language: English
   9 .\"
  10 .TH "SARG" "1" "27 Nov 2010" "sarg" "SARG"
  11 .\" -----------------------------------------------------------------
  12 .\" * set default formatting
  13 .\" -----------------------------------------------------------------
  14 .\" disable hyphenation
  15 .nh
  16 .\" disable justification (adjust text to left margin only)
  17 .ad l
  18 .\" -----------------------------------------------------------------
  19 .\" * MAIN CONTENT STARTS HERE *
  20 .\" -----------------------------------------------------------------
  21 .SH "NAME"
  22 sarg \- Squid Analysis Report Generator
  23 .SH "SYNOPSIS"
  24 .HP \w'\fBsarg\fR\ 'u
  25 \fBsarg\fR [options] [logfile...]
  26 .SH "DESCRIPTION"
  27 .PP
  28
  29 \fBsarg\fR
  30 is a log file parser and analyzer for the
  31 \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\&.
  32 .PP
  33
  34 \fBsarg\fR
  35 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
  36 \fBsarg\fR
  37 email the reports to the Squid Cache administrator\&.
  38 .PP
  39
  40 \fBsarg\fR
  41 can read
  42 squid
  43 or
  44 Microsoft ISA
  45 access logs\&. Optionally, it can complement the reports with the log of a Squid filter/redirector such as
  46 \m[blue]\fBsquidGuard\fR\m[]\&\s-2\u[2]\d\s+2\&.
  47 .SH "OPTIONS"
  48 .PP
  49 A summary of options is included below\&.
  50 .PP
  51 \fB\-h\fR
  52 .RS 4
  53 Show summary of options\&.
  54 .RE
  55 .PP
  56 \fB\-a hostname|ip address\fR
  57 .RS 4
  58 Limits report to records containing the specified hostname/ip address
  59 .RE
  60 .PP
  61 \fB\-b \fR\fB\fIfilename\fR\fR
  62 .RS 4
  63 Enables UserAgent log and writes it to
  64 \fIfilename\fR\&.
  65 .if n \{\
  66 .sp
  67 .\}
  68 .RS 4
  69 .it 1 an-trap
  70 .nr an-no-space-flag 1
  71 .nr an-break-flag 1
  72 .br
  73 .ps +1
  74 \fBWarning\fR
  75 .ps -1
  76 .br
  77 This option is currently unused\&.
  78 .sp .5v
  79 .RE
  80 .RE
  81 .PP
  82 \fB\-c \fR\fB\fIfilename\fR\fR
  83 .RS 4
  84 Read
  85 \fIfilename\fR
  86 for a list of the web hosts to exclude from the report\&. See
  87 the section called \(lqHOST EXCLUSION FILE\(rq\&.
  88 .RE
  89 .PP
  90 \fB\-\-convert\fR
  91 .RS 4
  92 Convert a
  93 squid
  94 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\&.
  95 .RE
  96 .PP
  97 \fB\-\-css\fR
  98 .RS 4
  99 Output, on the standard output, the internal css
 100 \fBsarg\fR
 101 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
 102 \fIexternal_css_file\fR
 103 in
 104 sarg\&.conf\&.
 105 .sp
 106 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\&.
 107 .RE
 108 .PP
 109 \fB\-d \fR\fB\fIdate\fR\fR
 110 .RS 4
 111 Use
 112 \fIdate\fR
 113 to restrict the report to some date range during log file processing\&. Format for
 114 \fIdate\fR
 115 is
 116 \fBdd/mm/yyyy\-dd/mm/yyyy\fR
 117 or a single date
 118 \fBdd/mm/yyyy\fR\&. Date ranges can also be specified as
 119 \fIday\-\fR\fI\fBn\fR\fR,
 120 \fIweek\-\fR\fI\fBn\fR\fR, or
 121 \fImonth\-\fR\fI\fBn\fR\fR
 122 where
 123 \fBn\fR
 124 is the number of days, weeks or months to jump backward\&. Note that there is no spaces around the hyphen\&.
 125 .RE
 126 .PP
 127 \fB\-e \fR\fB\fIemail\fR\fR
 128 .RS 4
 129 Sends report to
 130 \fIemail\fR
 131 (stdout for console)\&.
 132 .RE
 133 .PP
 134 \fB\-f \fR\fB\fIfilename\fR\fR
 135 .RS 4
 136 Reads configuration from
 137 \fIfilename\fR\&.
 138 .RE
 139 .PP
 140 \fB\-g e|u\fR
 141 .RS 4
 142 Sets date format in generated reports\&.
 143 .RS 4
 144 e = Europe \-> dd/mm/yy
 145 .RE
 146 .RS 4
 147 u = USA    \-> mm/dd/yy
 148 .RE
 149 .RE
 150 .PP
 151 \fB\-i\fR
 152 .RS 4
 153 Generates reports by user and ip address\&.
 154 .if n \{\
 155 .sp
 156 .\}
 157 .RS 4
 158 .it 1 an-trap
 159 .nr an-no-space-flag 1
 160 .nr an-break-flag 1
 161 .br
 162 .ps +1
 163 \fBNote\fR
 164 .ps -1
 165 .br
 166 This requires the
 167 \fIreport_type\fR
 168 option in config file to contain "users_sites"\&.
 169 .sp .5v
 170 .RE
 171 .RE
 172 .PP
 173 \fB\-\-keeplogs\fR
 174 .RS 4
 175 Don\'t delete any old report\&. It is equivalent to setting
 176 \fB\-\-lastlog 0\fR
 177 but is provided for convenience\&.
 178 .RE
 179 .PP
 180 \fB\-l \fR\fB\fIfilename\fR\fR
 181 .RS 4
 182 Uses
 183 \fIfilename\fR
 184 as the input log\&. This option can be repeated up to 255 times to read multiple files\&. If the files end with the extension
 185 \&.gz,
 186 \&.bz2
 187 or
 188 \&.Z
 189 they are decompressed\&. If the file name is just
 190 \fI\-\fR, the log file is read from standard input\&. In that case, it cannot be compressed\&.
 191 .sp
 192 This option is kept for compatibility with older versions of sarg but, starting with
 193 sarg 2\&.3, the log files may be named on the command line without the
 194 \fB\-l\fR
 195 option\&. It allows the use of wildcards on the command line\&. Make sure you don\'t exceed the limit of 255 files\&.
 196 .RE
 197 .PP
 198 \fB\-\-lastlog \fR\fB\fIn\fR\fR
 199 .RS 4
 200 Limit the number of logs kept in the output directory to
 201 \fIn\fR\&. Any supernumerary report is deleted starting with the oldest report\&. The value of
 202 \fIn\fR
 203 must be positive or zero\&. A value of zero means no report should be deleted\&.
 204 .RE
 205 .PP
 206 \fB\-L \fR\fB\fIfilename\fR\fR
 207 .RS 4
 208 Reads a proxy redirector log file such as one created by
 209 squidGuard
 210 or
 211 Rejik\&. If you use this option, you may want to configure
 212 \fIredirector_log_format\fR
 213 in
 214 sarg\&.conf
 215 to match the output format of your web content filtering program\&. This option can be repeated up to 64 times to read multiple files\&.
 216 .RE
 217 .PP
 218 \fB\-n\fR
 219 .RS 4
 220 Enables ip address resolution\&.
 221 .RE
 222 .PP
 223 \fB\-o \fR\fB\fIdir\fR\fR
 224 .RS 4
 225 Writes report in
 226 \fIdir\fR\&.
 227 .RE
 228 .PP
 229 \fB\-p\fR
 230 .RS 4
 231 Generates reports using ip address instead of userid\&.
 232 .RE
 233 .PP
 234 \fB\-s \fR\fB\fIstring\fR\fR
 235 .RS 4
 236 Limits report to the site specified by
 237 \fIstring\fR
 238 [eg\&. www\&.debian\&.org]
 239 .RE
 240 .PP
 241 \fB\-\-split\fR
 242 .RS 4
 243 Split the squid log file and output it as text on the standard output omitting the dates outside of the range specified by the
 244 \fB\-d\fR
 245 parameter\&. If it is combined with
 246 \fB\-\-convert\fR
 247 the dates are also converted to a human\-readable format\&.
 248 .RE
 249 .PP
 250 \fB\-t \fR\fB\fIstring\fR\fR
 251 .RS 4
 252 Limits the records included in the report based on time\-of\-day\&. Format for
 253 \fIstring\fR
 254 is
 255 \fBHH:MM\fR
 256 or
 257 \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
 258 \fB\-d\fR\&.
 259 .RE
 260 .PP
 261 \fB\-u \fR\fB\fIuser\fR\fR
 262 .RS 4
 263 Limits reports to
 264 \fIuser\fR
 265 activities\&.
 266 .RE
 267 .PP
 268 \fB\-w \fR\fB\fIdir\fR\fR
 269 .RS 4
 270 Store temporary files in
 271 \fIdir\fR\&. In fact,
 272 \fBsarg\fR
 273 stores its temporary files in the
 274 sarg
 275 subdirectory of
 276 \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\&.
 277 .RE
 278 .PP
 279 \fB\-x\fR
 280 .RS 4
 281 Writes debug messages to
 282 stdout
 283 .RE
 284 .PP
 285 \fB\-z\fR
 286 .RS 4
 287 Writes process messages to
 288 stdout\&.
 289 .RE
 290 .SH "HOST EXCLUSION FILE"
 291 .PP
 292 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:
 293 .sp
 294 .RS 4
 295 .ie n \{\
 296 \h'-04'\(bu\h'+03'\c
 297 .\}
 298 .el \{\
 299 .sp -1
 300 .IP \(bu 2.3
 301 .\}
 302 a full host name,
 303 .RE
 304 .sp
 305 .RS 4
 306 .ie n \{\
 307 \h'-04'\(bu\h'+03'\c
 308 .\}
 309 .el \{\
 310 .sp -1
 311 .IP \(bu 2.3
 312 .\}
 313 a host name starting with a wildcard (*) to match any prefix,
 314 .RE
 315 .sp
 316 .RS 4
 317 .ie n \{\
 318 \h'-04'\(bu\h'+03'\c
 319 .\}
 320 .el \{\
 321 .sp -1
 322 .IP \(bu 2.3
 323 .\}
 324 a single ip address,
 325 .RE
 326 .sp
 327 .RS 4
 328 .ie n \{\
 329 \h'-04'\(bu\h'+03'\c
 330 .\}
 331 .el \{\
 332 .sp -1
 333 .IP \(bu 2.3
 334 .\}
 335 a subnet noted a\&.b\&.c\&.d/e\&.
 336 .RE
 337 .PP
 338 \fBExample\ \&1.\ \&Example of a hosts exclusion file\fR
 339 .RS 4
 340 *\&.google\&.com
 341 .RE
 342 .RS 4
 343 10\&.0\&.0\&.0/8
 344 .RE
 345 .PP
 346 Sarg cannot exclude IPv6 addresses at the moment\&.
 347 .SH "SEE ALSO"
 348 .PP
 349 squid(8)
 350 .SH "AUTHORS"
 351 .PP
 352 This manual page was written by
 353 Luigi Gangitano
 354 gangitano@lugroma3\&.org, for the
 355 Debian GNU/Linux
 356 system (but may be used by others)\&. Revised by
 357 Billy Newsom\&.
 358 .PP
 359 Currently maintained by
 360 Frédéric Marchal
 361 fmarchal@users\&.sourceforge\&.net\&.
 362 .SH "AUTHORS"
 363 .PP
 364 \fBLuigi Gangitano\fR <\&gangitano@lugroma3\&.org\&>
 365 .RS 4
 366 Author of the first manual page
 367 .RE
 368 .PP
 369 \fBBilly Newsom\fR
 370 .RS 4
 371 Revision of the manual page
 372 .RE
 373 .PP
 374 \fBFrédéric Marchal\fR <\&fmarchal@users\&.sourceforge\&.net\&>
 375 .RS 4
 376 Docbook version of the manual page
 377 .RE
 378 .SH "COPYRIGHT"
 379 .br
 380 Copyright \(co 2010 Frédéric Marchal
 381 .br
 382 .SH "NOTES"
 383 .IP " 1." 4
 384 Squid Web Proxy Cache
 385 .RS 4
 386 \%http://www.squid-cache.org/
 387 .RE
 388 .IP " 2." 4
 389 squidGuard
 390 .RS 4
 391 \%http://www.squidguard.org/
 392 .RE