]> git.ipfire.org Git - thirdparty/sarg.git/blame - sarg_manpage.xml
Generate the manpage from a docbook document
[thirdparty/sarg.git] / sarg_manpage.xml
CommitLineData
84a17075
FM
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>27 Nov 2010</date>
13
14 <author>
15 <firstname>Luigi</firstname>
16 <surname>Gangitano</surname>
17 <contrib>Author of the first manual page</contrib>
18 <email>gangitano@lugroma3.org</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>Frédéric</firstname>
29 <surname>Marchal</surname>
30 <contrib>Docbook version of the manual page</contrib>
31 <email>fmarchal@users.sourceforge.net</email>
32 </author>
33
34 <copyright>
35 <year>2010</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>.
62It allows you to view "where" your users are going to on
63the Internet.
64</para>
65<para>
66<command>sarg</command> generates reports in HTML with fields such as: users,
67IP Addresses, bytes, sites, and times. These HTML files can appear in your
68web server's directory for browsing by users or administrators. You may also
69have <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.
73Optionally, 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>
80A summary of options is included below.
81</para>
82
83<variablelist>
84
85<varlistentry><term><option>-h</option></term>
86<listitem>
87<para>
88Show summary of options.
89</para>
90</listitem>
91</varlistentry>
92
93<varlistentry><term><option>-a hostname|ip address</option></term>
94<listitem>
95<para>
96Limits 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>
104Enables UserAgent log and writes it to <replaceable>filename</replaceable>.
105</para>
106<warning><para>This option is currently unused.</para></warning>
107</listitem>
108</varlistentry>
109
110<varlistentry><term><option>-c <replaceable>filename</replaceable></option></term>
111<listitem>
112<para>
113Read <replaceable>filename</replaceable> for a list of the web hosts to exclude from the report. See <xref linkend="ExcludeHostFile"/>.
114</para>
115</listitem>
116</varlistentry>
117
118<varlistentry><term><option>--convert</option></term>
119<listitem>
120<para>
121Convert a <application>squid</application> log file date/time field to a human-readable format.
122All the log files are read and output as one text on the standard output.
123</para>
124</listitem>
125</varlistentry>
126
127<varlistentry><term><option>--css</option></term>
128<listitem>
129<para>
130Output, on the standard output, the internal css <command>sarg</command> inlines in the reports. You can redirect
131the output to a file of your choice and edit it. Then you can override the internal css with
132<parameter>external_css_file</parameter> in <filename>sarg.conf</filename>.
133</para>
134<para>
135Using an external css can reduce the size of the report file. If you are short on disk space, you may consider
136exporting the css as explained above.
137</para>
138</listitem>
139</varlistentry>
140
141<varlistentry><term><option>-d <replaceable>date</replaceable></option></term>
142<listitem>
143<para>
144Use <replaceable>date</replaceable> to restrict the report to some date range during log file processing.
145Format for <replaceable>date</replaceable> is <userinput>dd/mm/yyyy-dd/mm/yyyy</userinput>
146or a single date <userinput>dd/mm/yyyy</userinput>. Date ranges can also be specified as
147<parameter>day-<constant>n</constant></parameter>, <parameter>week-<constant>n</constant></parameter>,
148or <parameter>month-<constant>n</constant></parameter> where <constant>n</constant>
149is the number of days, weeks or months to jump backward. Note that there is no spaces around the hyphen.
150</para>
151</listitem>
152</varlistentry>
153
154<varlistentry><term><option>-e <replaceable>email</replaceable></option></term>
155<listitem>
156<para>
157Sends report to <replaceable>email</replaceable> (stdout for console).
158</para>
159</listitem>
160</varlistentry>
161
162<varlistentry><term><option>-f <replaceable>filename</replaceable></option></term>
163<listitem>
164<para>
165Reads configuration from <replaceable>filename</replaceable>.
166</para>
167</listitem>
168</varlistentry>
169
170<varlistentry><term><option>-g e|u</option></term>
171<listitem>
172<para>
173Sets date format in generated reports.
174<simplelist>
175<member>e = Europe -> dd/mm/yy</member>
176<member>u = USA -> mm/dd/yy</member>
177</simplelist>
178</para>
179</listitem>
180</varlistentry>
181
182<varlistentry><term><option>-i</option></term>
183<listitem>
184<para>
185Generates reports by user and ip address.
186</para>
187<note>
188<simpara>
189This requires the <replaceable>report_type</replaceable>
190option in config file to contain "users_sites".
191</simpara>
192</note>
193</listitem>
194</varlistentry>
195
196<varlistentry><term><option>-l <replaceable>filename</replaceable></option></term>
197<listitem>
198<para>
199Uses <replaceable>filename</replaceable> as the input log. This option can be repeated up to 255 times to read
200multiple files. If the files end with the extension <filename>.gz</filename>, <filename>.bz2</filename> or
201<filename>.Z</filename> they are decompressed. If the file name is just
202<replaceable>-</replaceable>, the log file is read from standard input. In that case, it cannot be compressed.
203</para>
204<para>
205This option is kept for compatibility with older versions of sarg but, starting with <application>sarg 2.3</application>,
206the log files may be named on the command line without the <option>-l</option>
207option. It allows the use of wildcards on the command line. Make sure you don't exceed the limit of 255 files.
208</para>
209</listitem>
210</varlistentry>
211
212<varlistentry><term><option>-L <replaceable>filename</replaceable></option></term>
213<listitem>
214<para>
215Reads a proxy redirector log file such as one created by <application>squidGuard</application> or <application>Rejik</application>.
216If you use this option, you may want to configure <replaceable>redirector_log_format</replaceable>
217in <filename>sarg.conf</filename> to match the output format of your web content filtering program.
218This option can be repeated up to 64 times to read multiple files.
219</para>
220</listitem>
221</varlistentry>
222
223<varlistentry><term><option>-n</option></term>
224<listitem>
225<para>
226Enables ip address resolution.
227</para>
228</listitem>
229</varlistentry>
230
231<varlistentry><term><option>-o <replaceable>dir</replaceable></option></term>
232<listitem>
233<para>
234Writes report in <replaceable>dir</replaceable>.
235</para>
236</listitem>
237</varlistentry>
238
239<varlistentry><term><option>-p</option></term>
240<listitem>
241<para>
242Generates reports using ip address instead of userid.
243</para>
244</listitem>
245</varlistentry>
246
247<varlistentry><term><option>-s <replaceable>string</replaceable></option></term>
248<listitem>
249<para>
250Limits report to the site specified by <replaceable>string</replaceable>
251[eg. www.debian.org]
252</para>
253</listitem>
254</varlistentry>
255
256<varlistentry><term><option>--split</option></term>
257<listitem>
258<para>
259Split the squid log file and output it as text on the standard output omitting the dates outside of the
260range specified by the <option>-d</option> parameter.
261If it is combined with <option>--convert</option>
262the dates are also converted to a human-readable format.
263</para>
264</listitem>
265</varlistentry>
266
267<varlistentry><term><option>-t <replaceable>string</replaceable></option></term>
268<listitem>
269<para>
270Limits the records included in the report based on time-of-day. Format for
271<replaceable>string</replaceable> is <userinput>HH:MM</userinput> or <userinput>HH:MM-HH:MM</userinput>.
272The former reports only the requested time. The latter reports any entry falling within the requested
273range. This limit complement the limit imposed by option <option>-d</option>.
274</para>
275</listitem>
276</varlistentry>
277
278<varlistentry><term><option>-u <replaceable>user</replaceable></option></term>
279<listitem>
280<para>
281Limits reports to <replaceable>user</replaceable> activities.
282</para>
283</listitem>
284</varlistentry>
285
286<varlistentry><term><option>-w <replaceable>dir</replaceable></option></term>
287<listitem>
288<para>
289Store temporary files in <replaceable>dir</replaceable>. In fact, <command>sarg</command> stores its temporary files in
290the <filename class="directory">sarg</filename> subdirectory of <replaceable>dir</replaceable>. Be sure to set the HTML
291output directory to a place outside of the temporary directory or sarg may fail or delete the report when it completes its task.
292</para>
293</listitem>
294</varlistentry>
295
296<varlistentry><term><option>-x</option></term>
297<listitem>
298<para>
299Writes debug messages to <filename class="devicefile">stdout</filename>
300</para>
301</listitem>
302</varlistentry>
303
304<varlistentry><term><option>-z</option></term>
305<listitem>
306<para>
307Writes process messages to <filename class="devicefile">stdout</filename>.
308</para>
309</listitem>
310</varlistentry>
311
312</variablelist>
313</refsect1>
314
315<refsect1 id="ExcludeHostFile"><title>Host exclusion file</title>
316<para>Sarg can be told to exclude visited hosts from the report by providing it
317with a file containing one host to exclude per line. The "host" may be one of the following:
318</para>
319<itemizedlist>
320<listitem><para>a full host name,</para></listitem>
321<listitem><para>a host name starting with a wildcard (*) to match any prefix,</para></listitem>
322<listitem><para>a single ip address,</para></listitem>
323<listitem><para>a subnet noted a.b.c.d/e.</para></listitem>
324</itemizedlist>
325<example><title>Example of a hosts exclusion file</title>
326<simplelist>
327<member>*.google.com</member>
328<member>10.0.0.0/8</member>
329</simplelist>
330</example>
331
332<para>
333Sarg cannot exclude IPv6 addresses at the moment.
334</para>
335
336</refsect1>
337
338<refsect1><title>See also</title>
339<para>
340squid(8)
341</para>
342</refsect1>
343
344<refsect1><title>Authors</title>
345<para>
346This manual page was written by <personname><firstname>Luigi</firstname> <surname>Gangitano</surname></personname>
347<email>gangitano@lugroma3.org</email>,
348for the <systemitem class="osname">Debian GNU/Linux</systemitem> system (but may be used by others). Revised
349by <personname><firstname>Billy</firstname> <surname>Newsom</surname></personname>.
350</para>
351<para>
352Currently maintained by <personname><firstname>Frédéric</firstname> <surname>Marchal</surname></personname>
353<email>fmarchal@users.sourceforge.net</email>.
354</para>
355</refsect1>
356
357</refentry>
358
359</article>