sarg.1

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