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: 25 Jan 2011
   6 .\"    Manual: SARG
   7 .\"    Source: sarg
   8 .\"  Language: English
   9 .\"
  10 .TH "SARG" "1" "25 Jan 2011" "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\-P \fR\fB\fIprefix\fR\fR \fB\-\-splitprefix \fR\fB\fIprefix\fR\fR
 235 .RS 4
 236 This option must be used with
 237 \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
 238 \fIprefix\fR
 239 and the date formated as
 240 \-YYYY\-MM\-DD\&.
 241 .sp
 242 The output files are written in the output directory specified with
 243 \fB\-o\fR
 244 or in the current directory\&.
 245 .RE
 246 .PP
 247 \fB\-s \fR\fB\fIstring\fR\fR
 248 .RS 4
 249 Limits report to the site specified by
 250 \fIstring\fR
 251 [eg\&. www\&.debian\&.org]
 252 .RE
 253 .PP
 254 \fB\-\-split\fR
 255 .RS 4
 256 Split the squid log file and output it as text on the standard output omitting the dates outside of the range specified by the
 257 \fB\-d\fR
 258 parameter\&. If it is combined with
 259 \fB\-\-convert\fR
 260 the dates are also converted to a human\-readable format\&.
 261 .sp
 262 Combined with
 263 \fB\-P\fR, the log is written in several files each containing one day of the original log\&.
 264 .RE
 265 .PP
 266 \fB\-t \fR\fB\fIstring\fR\fR
 267 .RS 4
 268 Limits the records included in the report based on time\-of\-day\&. Format for
 269 \fIstring\fR
 270 is
 271 \fBHH:MM\fR
 272 or
 273 \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
 274 \fB\-d\fR\&.
 275 .RE
 276 .PP
 277 \fB\-u \fR\fB\fIuser\fR\fR
 278 .RS 4
 279 Limits reports to
 280 \fIuser\fR
 281 activities\&.
 282 .RE
 283 .PP
 284 \fB\-w \fR\fB\fIdir\fR\fR
 285 .RS 4
 286 Store temporary files in
 287 \fIdir\fR\&. In fact,
 288 \fBsarg\fR
 289 stores its temporary files in the
 290 sarg
 291 subdirectory of
 292 \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\&.
 293 .RE
 294 .PP
 295 \fB\-x\fR
 296 .RS 4
 297 Writes debug messages to
 298 stdout
 299 .RE
 300 .PP
 301 \fB\-z\fR
 302 .RS 4
 303 Writes process messages to
 304 stdout\&.
 305 .RE
 306 .SH "HOST EXCLUSION FILE"
 307 .PP
 308 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:
 309 .sp
 310 .RS 4
 311 .ie n \{\
 312 \h'-04'\(bu\h'+03'\c
 313 .\}
 314 .el \{\
 315 .sp -1
 316 .IP \(bu 2.3
 317 .\}
 318 a full host name,
 319 .RE
 320 .sp
 321 .RS 4
 322 .ie n \{\
 323 \h'-04'\(bu\h'+03'\c
 324 .\}
 325 .el \{\
 326 .sp -1
 327 .IP \(bu 2.3
 328 .\}
 329 a host name starting with a wildcard (*) to match any prefix,
 330 .RE
 331 .sp
 332 .RS 4
 333 .ie n \{\
 334 \h'-04'\(bu\h'+03'\c
 335 .\}
 336 .el \{\
 337 .sp -1
 338 .IP \(bu 2.3
 339 .\}
 340 a single ip address,
 341 .RE
 342 .sp
 343 .RS 4
 344 .ie n \{\
 345 \h'-04'\(bu\h'+03'\c
 346 .\}
 347 .el \{\
 348 .sp -1
 349 .IP \(bu 2.3
 350 .\}
 351 a subnet noted a\&.b\&.c\&.d/e\&.
 352 .RE
 353 .PP
 354 \fBExample\ \&1.\ \&Example of a hosts exclusion file\fR
 355 .RS 4
 356 *\&.google\&.com
 357 .RE
 358 .RS 4
 359 10\&.0\&.0\&.0/8
 360 .RE
 361 .PP
 362 Sarg cannot exclude IPv6 addresses at the moment\&.
 363 .SH "SEE ALSO"
 364 .PP
 365 squid(8)
 366 .SH "AUTHORS"
 367 .PP
 368 This manual page was written by
 369 Luigi Gangitano
 370 gangitano@lugroma3\&.org, for the
 371 Debian GNU/Linux
 372 system (but may be used by others)\&. Revised by
 373 Billy Newsom\&.
 374 .PP
 375 Currently maintained by
 376 Frédéric Marchal
 377 fmarchal@users\&.sourceforge\&.net\&.
 378 .SH "AUTHORS"
 379 .PP
 380 \fBFrédéric Marchal\fR <\&fmarchal@users\&.sourceforge\&.net\&>
 381 .RS 4
 382 Docbook version of the manual page
 383 .RE
 384 .PP
 385 \fBBilly Newsom\fR
 386 .RS 4
 387 Revision of the manual page
 388 .RE
 389 .PP
 390 \fBLuigi Gangitano\fR <\&gangitano@lugroma3\&.org\&>
 391 .RS 4
 392 Author of the first manual page
 393 .RE
 394 .SH "COPYRIGHT"
 395 .br
 396 Copyright \(co 2011 Frédéric Marchal
 397 .br
 398 .SH "NOTES"
 399 .IP " 1." 4
 400 Squid Web Proxy Cache
 401 .RS 4
 402 \%http://www.squid-cache.org/
 403 .RE
 404 .IP " 2." 4
 405 squidGuard
 406 .RS 4
 407 \%http://www.squidguard.org/
 408 .RE