"Fossies" - the Fresh Open Source Software Archive 
Member "sarg-2.4.0/sarg_manpage.xml" (30 Jan 2017, 13327 Bytes) of package /linux/privat/sarg-2.4.0.tar.gz:
As a special service "Fossies" has tried to format the requested source page into HTML format using (guessed) XML source code syntax highlighting (style:
standard) with prefixed line numbers.
Alternatively you can here
view or
download the uninterpreted source code file.
See also the latest
Fossies "Diffs" side-by-side code changes report for "sarg_manpage.xml":
2.3.11_vs_2.4.0.
1 <?xml version="1.0" encoding="utf-8"?>
2 <!DOCTYPE article PUBLIC '-//OASIS//DTD DocBook XML V4.5//EN'
3 'http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd'>
4
5 <article lang="en">
6 <title>SARG</title>
7
8 <refentry id="sarg">
9
10 <refentryinfo>
11 <productname>sarg</productname>
12 <date>12 Nov 2015</date>
13
14 <author>
15 <firstname>Frédéric</firstname>
16 <surname>Marchal</surname>
17 <contrib>Docbook version of the manual page</contrib>
18 <email>fmarchal@users.sourceforge.net</email>
19 </author>
20
21 <author>
22 <firstname>Billy</firstname>
23 <surname>Newsom</surname>
24 <contrib>Revision of the manual page</contrib>
25 </author>
26
27 <author>
28 <firstname>Luigi</firstname>
29 <surname>Gangitano</surname>
30 <contrib>Author of the first manual page</contrib>
31 <email>gangitano@lugroma3.org</email>
32 </author>
33
34 <copyright>
35 <year>2012</year>
36 <holder>Frédéric Marchal</holder>
37 </copyright>
38 </refentryinfo>
39
40 <refmeta>
41 <refentrytitle>sarg</refentrytitle>
42 <manvolnum>1</manvolnum>
43 </refmeta>
44
45 <refnamediv>
46 <refname>sarg</refname>
47 <refpurpose>Squid Analysis Report Generator</refpurpose>
48 <!--<refclass>UNIX/Linux</refclass>-->
49 </refnamediv>
50
51 <refsynopsisdiv>
52 <cmdsynopsis>
53 <command>sarg</command>
54 <arg choice="opt">options</arg>
55 <arg choice="opt" rep="repeat">logfile</arg>
56 </cmdsynopsis>
57 </refsynopsisdiv>
58
59 <refsect1><title>Description</title>
60 <para>
61 <command>sarg</command> is a log file parser and analyzer for the <ulink url="http://www.squid-cache.org/">Squid Web Proxy Cache</ulink>.
62 It allows you to view "where" your users are going to on
63 the Internet.
64 </para>
65 <para>
66 <command>sarg</command> generates reports in HTML with fields such as: users,
67 IP Addresses, bytes, sites, and times. These HTML files can appear in your
68 web server's directory for browsing by users or administrators. You may also
69 have <command>sarg</command> email the reports to the Squid Cache administrator.
70 </para>
71 <para>
72 <command>sarg</command> can read <application>squid</application> or <application>Microsoft ISA</application> access logs.
73 Optionally, it can complement the reports with the log of a Squid filter/redirector such as
74 <ulink url="http://www.squidguard.org/">squidGuard</ulink>.
75 </para>
76 </refsect1>
77
78 <refsect1><title>Options</title>
79 <para>
80 A summary of options is included below.
81 </para>
82
83 <variablelist>
84
85 <varlistentry><term><option>-h</option> <option>--help</option></term>
86 <listitem>
87 <para>
88 Show summary of options.
89 </para>
90 </listitem>
91 </varlistentry>
92
93 <varlistentry><term><option>-a hostname|ip address</option></term>
94 <listitem>
95 <para>
96 Limits report to records containing the specified hostname/ip address
97 </para>
98 </listitem>
99 </varlistentry>
100
101 <varlistentry><term><option>-b <replaceable>filename</replaceable></option></term>
102 <listitem>
103 <para>
104 Enables UserAgent log and writes it to <replaceable>filename</replaceable>.
105 </para>
106 </listitem>
107 </varlistentry>
108
109 <varlistentry><term><option>-c <replaceable>filename</replaceable></option></term>
110 <listitem>
111 <para>
112 Read <replaceable>filename</replaceable> for a list of the web hosts to exclude from the report. See <xref linkend="ExcludeHostFile"/>.
113 </para>
114 </listitem>
115 </varlistentry>
116
117 <varlistentry><term><option>--convert</option></term>
118 <listitem>
119 <para>
120 Convert a <application>squid</application> log file date/time field to a human-readable format.
121 All the log files are read and output as one text on the standard output.
122 </para>
123 </listitem>
124 </varlistentry>
125
126 <varlistentry><term><option>--css</option></term>
127 <listitem>
128 <para>
129 Output, on the standard output, the internal css <command>sarg</command> inlines in the reports. You can redirect
130 the output to a file of your choice and edit it. Then you can override the internal css with
131 <parameter>external_css_file</parameter> in <filename>sarg.conf</filename>.
132 </para>
133 <para>
134 Using an external css can reduce the size of the report file. If you are short on disk space, you may consider
135 exporting the css as explained above.
136 </para>
137 </listitem>
138 </varlistentry>
139
140 <varlistentry><term><option>-d <replaceable>date</replaceable></option></term>
141 <listitem>
142 <para>
143 Use <replaceable>date</replaceable> to restrict the report to some date range during log file processing.
144 Format for <replaceable>date</replaceable> is <userinput>dd/mm/yyyy-dd/mm/yyyy</userinput>
145 or a single date <userinput>dd/mm/yyyy</userinput>. Date ranges can also be specified as
146 <parameter>day-<constant>n</constant></parameter>, <parameter>week-<constant>n</constant></parameter>,
147 or <parameter>month-<constant>n</constant></parameter> where <constant>n</constant>
148 is the number of days, weeks or months to jump backward. Note that there is no spaces around the hyphen.
149 </para>
150 </listitem>
151 </varlistentry>
152
153 <varlistentry><term><option>-e <replaceable>email</replaceable></option></term>
154 <listitem>
155 <para>
156 Sends report to <replaceable>email</replaceable> (stdout for console).
157 </para>
158 </listitem>
159 </varlistentry>
160
161 <varlistentry><term><option>-f <replaceable>filename</replaceable></option></term>
162 <listitem>
163 <para>
164 Reads configuration from <replaceable>filename</replaceable>.
165 </para>
166 </listitem>
167 </varlistentry>
168
169 <varlistentry><term><option>-g e|u</option></term>
170 <listitem>
171 <para>
172 Sets date format in generated reports.
173 <simplelist>
174 <member>e = Europe -> dd/mm/yy</member>
175 <member>u = USA -> mm/dd/yy</member>
176 </simplelist>
177 </para>
178 </listitem>
179 </varlistentry>
180
181 <varlistentry><term><option>-i</option></term>
182 <listitem>
183 <para>
184 Generates reports by user and ip address.
185 </para>
186 <note>
187 <simpara>
188 This requires the <replaceable>report_type</replaceable>
189 option in config file to contain "users_sites".
190 </simpara>
191 </note>
192 </listitem>
193 </varlistentry>
194
195 <varlistentry><term><option>--keeplogs</option></term>
196 <listitem>
197 <para>
198 Don't delete any old report. It is equivalent to setting <option>--lastlog 0</option> but is
199 provided for convenience.
200 </para>
201 </listitem>
202 </varlistentry>
203
204 <varlistentry><term><option>-l <replaceable>filename</replaceable></option></term>
205 <listitem>
206 <para>
207 Uses <replaceable>filename</replaceable> as the input log. This option can be repeated up to 255 times to read
208 multiple files. If the files end with the extension <filename>.gz</filename>, <filename>.bz2</filename> or
209 <filename>.Z</filename> they are decompressed. If the file name is just
210 <replaceable>-</replaceable>, the log file is read from standard input. In that case, it cannot be compressed.
211 </para>
212 <para>
213 This option is kept for compatibility with older versions of sarg but, starting with <application>sarg 2.3</application>,
214 the log files may be named on the command line without the <option>-l</option>
215 option. It allows the use of wildcards on the command line. Make sure you don't exceed the limit of 255 files.
216 </para>
217 </listitem>
218 </varlistentry>
219
220 <varlistentry><term><option>--lastlog <replaceable>n</replaceable></option></term>
221 <listitem>
222 <para>
223 Limit the number of logs kept in the output directory to <replaceable>n</replaceable>. Any supernumerary report
224 is deleted starting with the oldest report. The value of <replaceable>n</replaceable> must be positive or zero.
225 A value of zero means no report should be deleted.
226 </para>
227 </listitem>
228 </varlistentry>
229
230 <varlistentry><term><option>-L <replaceable>filename</replaceable></option></term>
231 <listitem>
232 <para>
233 Reads a proxy redirector log file such as one created by <application>squidGuard</application> or <application>Rejik</application>.
234 If you use this option, you may want to configure <replaceable>redirector_log_format</replaceable>
235 in <filename>sarg.conf</filename> to match the output format of your web content filtering program.
236 This option can be repeated up to 64 times to read multiple files.
237 </para>
238 </listitem>
239 </varlistentry>
240
241 <varlistentry><term><option>-n</option></term>
242 <listitem>
243 <para>
244 Enables ip address resolution.
245 </para>
246 </listitem>
247 </varlistentry>
248
249 <varlistentry><term><option>-o <replaceable>dir</replaceable></option></term>
250 <listitem>
251 <para>
252 Writes report in <replaceable>dir</replaceable>.
253 </para>
254 </listitem>
255 </varlistentry>
256
257 <varlistentry><term><option>-p</option></term>
258 <listitem>
259 <para>
260 Generates reports using ip address instead of userid.
261 </para>
262 </listitem>
263 </varlistentry>
264
265 <varlistentry><term><option>-P <replaceable>prefix</replaceable></option> <option>--splitprefix <replaceable>prefix</replaceable></option></term>
266 <listitem>
267 <para>
268 This option must be used with <option>--split</option>. If it is provided, the input log is split among
269 several files each containing one day. The name of the output files is made of the <replaceable>prefix</replaceable>
270 and the date formated as <literal>-YYYY-MM-DD</literal>.
271 </para>
272 <para>
273 The output files are written in the output directory
274 specified with <option>-o</option> or in the current directory.
275 </para>
276 </listitem>
277 </varlistentry>
278
279 <varlistentry><term><option>-r</option></term>
280 <listitem>
281 <para>
282 Output the realtime report on the standard output and exit.
283 </para>
284 </listitem>
285 </varlistentry>
286
287 <varlistentry><term><option>-s <replaceable>string</replaceable></option></term>
288 <listitem>
289 <para>
290 Limits report to the site specified by <replaceable>string</replaceable>
291 [eg. www.debian.org]
292 </para>
293 </listitem>
294 </varlistentry>
295
296 <varlistentry><term><option>--split</option></term>
297 <listitem>
298 <para>
299 Split the squid log file and output it as text on the standard output omitting the dates outside of the
300 range specified by the <option>-d</option> parameter.
301 If it is combined with <option>--convert</option>
302 the dates are also converted to a human-readable format.
303 </para>
304 <para>
305 Combined with <option>-P</option>, the log is written in several files each containing one day of the
306 original log.
307 </para>
308 </listitem>
309 </varlistentry>
310
311 <varlistentry><term><option>--statistics</option></term>
312 <listitem>
313 <para>
314 Writes some statistics about the execution time. The statistics include the
315 total execution time; the number of records read in the input log files and the
316 time it took to read them; the number of records and users processed and the
317 time it took to process them.
318 </para>
319 </listitem>
320 </varlistentry>
321
322 <varlistentry><term><option>-t <replaceable>string</replaceable></option></term>
323 <listitem>
324 <para>
325 Limits the records included in the report based on time-of-day. Format for
326 <replaceable>string</replaceable> is <userinput>HH:MM</userinput> or <userinput>HH:MM-HH:MM</userinput>.
327 The former reports only the requested time. The latter reports any entry falling within the requested
328 range. This limit complement the limit imposed by option <option>-d</option>.
329 </para>
330 </listitem>
331 </varlistentry>
332
333 <varlistentry><term><option>-u <replaceable>user</replaceable></option></term>
334 <listitem>
335 <para>
336 Limits reports to <replaceable>user</replaceable> activities.
337 </para>
338 </listitem>
339 </varlistentry>
340
341 <varlistentry><term><option>-v</option></term>
342 <listitem>
343 <para>
344 Write sarg version and exit.
345 </para>
346 </listitem>
347 </varlistentry>
348
349 <varlistentry><term><option>-w <replaceable>dir</replaceable></option></term>
350 <listitem>
351 <para>
352 Store temporary files in <replaceable>dir</replaceable>. In fact, <command>sarg</command> stores its temporary files in
353 the <filename class="directory">sarg</filename> subdirectory of <replaceable>dir</replaceable>. Be sure to set the HTML
354 output directory to a place outside of the temporary directory or sarg may fail or delete the report when it completes its task.
355 </para>
356 </listitem>
357 </varlistentry>
358
359 <varlistentry><term><option>-x</option></term>
360 <listitem>
361 <para>
362 Writes debug messages to <filename class="devicefile">stdout</filename>
363 </para>
364 </listitem>
365 </varlistentry>
366
367 <varlistentry><term><option>-z</option></term>
368 <listitem>
369 <para>
370 Writes process messages to <filename class="devicefile">stdout</filename>.
371 </para>
372 </listitem>
373 </varlistentry>
374
375 </variablelist>
376 </refsect1>
377
378 <refsect1 id="ExcludeHostFile"><title>Host exclusion file</title>
379 <para>Sarg can be told to exclude visited hosts from the report by providing it
380 with a file containing one host to exclude per line. The "host" may be one of the following:
381 </para>
382 <itemizedlist>
383 <listitem><para>a full host name,</para></listitem>
384 <listitem><para>a host name starting with a wildcard (*) to match any prefix,</para></listitem>
385 <listitem><para>a single ip address,</para></listitem>
386 <listitem><para>a subnet noted a.b.c.d/e.</para></listitem>
387 </itemizedlist>
388 <example><title>Example of a hosts exclusion file</title>
389 <simplelist>
390 <member>*.google.com</member>
391 <member>10.0.0.0/8</member>
392 </simplelist>
393 </example>
394
395 <para>
396 Sarg cannot exclude IPv6 addresses at the moment.
397 </para>
398
399 </refsect1>
400
401 <refsect1><title>See also</title>
402 <para>
403 squid(8)
404 </para>
405 </refsect1>
406
407 <refsect1><title>Authors</title>
408 <para>
409 This manual page was written by <personname><firstname>Luigi</firstname> <surname>Gangitano</surname></personname>
410 <email>gangitano@lugroma3.org</email>,
411 for the <systemitem class="osname">Debian GNU/Linux</systemitem> system (but may be used by others). Revised
412 by <personname><firstname>Billy</firstname> <surname>Newsom</surname></personname>.
413 </para>
414 <para>
415 Currently maintained by <personname><firstname>Frédéric</firstname> <surname>Marchal</surname></personname>
416 <email>fmarchal@users.sourceforge.net</email>.
417 </para>
418 </refsect1>
419
420 </refentry>
421
422 </article>