sarg.1

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