]>
Commit | Line | Data |
---|---|---|
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> | |
debeace1 | 12 | <date>27 May 2012</date> |
2c7e8c23 | 13 | |
84a17075 | 14 | <author> |
6fca3ad9 FM |
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> | |
84a17075 | 19 | </author> |
2c7e8c23 | 20 | |
84a17075 FM |
21 | <author> |
22 | <firstname>Billy</firstname> | |
23 | <surname>Newsom</surname> | |
24 | <contrib>Revision of the manual page</contrib> | |
25 | </author> | |
26 | ||
27 | <author> | |
6fca3ad9 FM |
28 | <firstname>Luigi</firstname> |
29 | <surname>Gangitano</surname> | |
30 | <contrib>Author of the first manual page</contrib> | |
31 | <email>gangitano@lugroma3.org</email> | |
84a17075 | 32 | </author> |
2c7e8c23 | 33 | |
84a17075 | 34 | <copyright> |
debeace1 | 35 | <year>2012</year> |
84a17075 FM |
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 | ||
d6f08599 | 85 | <varlistentry><term><option>-h</option> <option>--help</option></term> |
84a17075 FM |
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 | <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> | |
113 | Read <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> | |
121 | Convert a <application>squid</application> log file date/time field to a human-readable format. | |
122 | All 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> | |
130 | Output, on the standard output, the internal css <command>sarg</command> inlines in the reports. You can redirect | |
131 | the 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> | |
135 | Using an external css can reduce the size of the report file. If you are short on disk space, you may consider | |
136 | exporting 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> | |
144 | Use <replaceable>date</replaceable> to restrict the report to some date range during log file processing. | |
145 | Format for <replaceable>date</replaceable> is <userinput>dd/mm/yyyy-dd/mm/yyyy</userinput> | |
2c7e8c23 | 146 | or a single date <userinput>dd/mm/yyyy</userinput>. Date ranges can also be specified as |
84a17075 FM |
147 | <parameter>day-<constant>n</constant></parameter>, <parameter>week-<constant>n</constant></parameter>, |
148 | or <parameter>month-<constant>n</constant></parameter> where <constant>n</constant> | |
149 | is 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> | |
157 | Sends 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> | |
165 | Reads 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> | |
173 | Sets 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> | |
185 | Generates reports by user and ip address. | |
186 | </para> | |
187 | <note> | |
188 | <simpara> | |
189 | This requires the <replaceable>report_type</replaceable> | |
190 | option in config file to contain "users_sites". | |
191 | </simpara> | |
192 | </note> | |
193 | </listitem> | |
194 | </varlistentry> | |
195 | ||
c995d358 FM |
196 | <varlistentry><term><option>--keeplogs</option></term> |
197 | <listitem> | |
198 | <para> | |
199 | Don't delete any old report. It is equivalent to setting <option>--lastlog 0</option> but is | |
200 | provided for convenience. | |
201 | </para> | |
202 | </listitem> | |
203 | </varlistentry> | |
204 | ||
84a17075 FM |
205 | <varlistentry><term><option>-l <replaceable>filename</replaceable></option></term> |
206 | <listitem> | |
207 | <para> | |
208 | Uses <replaceable>filename</replaceable> as the input log. This option can be repeated up to 255 times to read | |
209 | multiple files. If the files end with the extension <filename>.gz</filename>, <filename>.bz2</filename> or | |
210 | <filename>.Z</filename> they are decompressed. If the file name is just | |
211 | <replaceable>-</replaceable>, the log file is read from standard input. In that case, it cannot be compressed. | |
212 | </para> | |
213 | <para> | |
214 | This option is kept for compatibility with older versions of sarg but, starting with <application>sarg 2.3</application>, | |
215 | the log files may be named on the command line without the <option>-l</option> | |
216 | option. It allows the use of wildcards on the command line. Make sure you don't exceed the limit of 255 files. | |
217 | </para> | |
218 | </listitem> | |
219 | </varlistentry> | |
220 | ||
c995d358 FM |
221 | <varlistentry><term><option>--lastlog <replaceable>n</replaceable></option></term> |
222 | <listitem> | |
223 | <para> | |
224 | Limit the number of logs kept in the output directory to <replaceable>n</replaceable>. Any supernumerary report | |
225 | is deleted starting with the oldest report. The value of <replaceable>n</replaceable> must be positive or zero. | |
226 | A value of zero means no report should be deleted. | |
227 | </para> | |
228 | </listitem> | |
229 | </varlistentry> | |
230 | ||
84a17075 FM |
231 | <varlistentry><term><option>-L <replaceable>filename</replaceable></option></term> |
232 | <listitem> | |
233 | <para> | |
234 | Reads a proxy redirector log file such as one created by <application>squidGuard</application> or <application>Rejik</application>. | |
235 | If you use this option, you may want to configure <replaceable>redirector_log_format</replaceable> | |
236 | in <filename>sarg.conf</filename> to match the output format of your web content filtering program. | |
237 | This option can be repeated up to 64 times to read multiple files. | |
238 | </para> | |
239 | </listitem> | |
240 | </varlistentry> | |
241 | ||
d6f08599 FM |
242 | <varlistentry><term><option>-m</option></term> |
243 | <listitem> | |
244 | <para> | |
245 | Enable advanced processing debug messages. This option produces an enourmous amount of output. | |
246 | </para> | |
247 | </listitem> | |
248 | </varlistentry> | |
249 | ||
84a17075 FM |
250 | <varlistentry><term><option>-n</option></term> |
251 | <listitem> | |
252 | <para> | |
253 | Enables ip address resolution. | |
254 | </para> | |
255 | </listitem> | |
256 | </varlistentry> | |
257 | ||
258 | <varlistentry><term><option>-o <replaceable>dir</replaceable></option></term> | |
259 | <listitem> | |
260 | <para> | |
261 | Writes report in <replaceable>dir</replaceable>. | |
262 | </para> | |
263 | </listitem> | |
264 | </varlistentry> | |
265 | ||
266 | <varlistentry><term><option>-p</option></term> | |
267 | <listitem> | |
268 | <para> | |
269 | Generates reports using ip address instead of userid. | |
270 | </para> | |
271 | </listitem> | |
272 | </varlistentry> | |
273 | ||
2c7e8c23 FM |
274 | <varlistentry><term><option>-P <replaceable>prefix</replaceable></option> <option>--splitprefix <replaceable>prefix</replaceable></option></term> |
275 | <listitem> | |
276 | <para> | |
277 | This option must be used with <option>--split</option>. If it is provided, the input log is split among | |
278 | several files each containing one day. The name of the output files is made of the <replaceable>prefix</replaceable> | |
279 | and the date formated as <literal>-YYYY-MM-DD</literal>. | |
280 | </para> | |
281 | <para> | |
282 | The output files are written in the output directory | |
283 | specified with <option>-o</option> or in the current directory. | |
284 | </para> | |
285 | </listitem> | |
286 | </varlistentry> | |
287 | ||
d6f08599 FM |
288 | <varlistentry><term><option>-r</option></term> |
289 | <listitem> | |
290 | <para> | |
291 | Output the realtime report on the standard output and exit. | |
292 | </para> | |
293 | </listitem> | |
294 | </varlistentry> | |
295 | ||
84a17075 FM |
296 | <varlistentry><term><option>-s <replaceable>string</replaceable></option></term> |
297 | <listitem> | |
298 | <para> | |
299 | Limits report to the site specified by <replaceable>string</replaceable> | |
300 | [eg. www.debian.org] | |
301 | </para> | |
302 | </listitem> | |
303 | </varlistentry> | |
304 | ||
305 | <varlistentry><term><option>--split</option></term> | |
306 | <listitem> | |
307 | <para> | |
308 | Split the squid log file and output it as text on the standard output omitting the dates outside of the | |
309 | range specified by the <option>-d</option> parameter. | |
310 | If it is combined with <option>--convert</option> | |
311 | the dates are also converted to a human-readable format. | |
312 | </para> | |
2c7e8c23 FM |
313 | <para> |
314 | Combined with <option>-P</option>, the log is written in several files each containing one day of the | |
315 | original log. | |
316 | </para> | |
84a17075 FM |
317 | </listitem> |
318 | </varlistentry> | |
319 | ||
320 | <varlistentry><term><option>-t <replaceable>string</replaceable></option></term> | |
321 | <listitem> | |
322 | <para> | |
323 | Limits the records included in the report based on time-of-day. Format for | |
324 | <replaceable>string</replaceable> is <userinput>HH:MM</userinput> or <userinput>HH:MM-HH:MM</userinput>. | |
325 | The former reports only the requested time. The latter reports any entry falling within the requested | |
326 | range. This limit complement the limit imposed by option <option>-d</option>. | |
327 | </para> | |
328 | </listitem> | |
329 | </varlistentry> | |
330 | ||
331 | <varlistentry><term><option>-u <replaceable>user</replaceable></option></term> | |
332 | <listitem> | |
333 | <para> | |
334 | Limits reports to <replaceable>user</replaceable> activities. | |
335 | </para> | |
336 | </listitem> | |
337 | </varlistentry> | |
338 | ||
d6f08599 FM |
339 | <varlistentry><term><option>-v</option></term> |
340 | <listitem> | |
341 | <para> | |
342 | Write sarg version and exit. | |
343 | </para> | |
344 | </listitem> | |
345 | </varlistentry> | |
346 | ||
84a17075 FM |
347 | <varlistentry><term><option>-w <replaceable>dir</replaceable></option></term> |
348 | <listitem> | |
349 | <para> | |
350 | Store temporary files in <replaceable>dir</replaceable>. In fact, <command>sarg</command> stores its temporary files in | |
351 | the <filename class="directory">sarg</filename> subdirectory of <replaceable>dir</replaceable>. Be sure to set the HTML | |
352 | output directory to a place outside of the temporary directory or sarg may fail or delete the report when it completes its task. | |
353 | </para> | |
354 | </listitem> | |
355 | </varlistentry> | |
356 | ||
357 | <varlistentry><term><option>-x</option></term> | |
358 | <listitem> | |
359 | <para> | |
360 | Writes debug messages to <filename class="devicefile">stdout</filename> | |
361 | </para> | |
362 | </listitem> | |
363 | </varlistentry> | |
364 | ||
365 | <varlistentry><term><option>-z</option></term> | |
366 | <listitem> | |
367 | <para> | |
368 | Writes process messages to <filename class="devicefile">stdout</filename>. | |
369 | </para> | |
370 | </listitem> | |
371 | </varlistentry> | |
372 | ||
373 | </variablelist> | |
374 | </refsect1> | |
375 | ||
376 | <refsect1 id="ExcludeHostFile"><title>Host exclusion file</title> | |
377 | <para>Sarg can be told to exclude visited hosts from the report by providing it | |
378 | with a file containing one host to exclude per line. The "host" may be one of the following: | |
379 | </para> | |
380 | <itemizedlist> | |
381 | <listitem><para>a full host name,</para></listitem> | |
382 | <listitem><para>a host name starting with a wildcard (*) to match any prefix,</para></listitem> | |
383 | <listitem><para>a single ip address,</para></listitem> | |
384 | <listitem><para>a subnet noted a.b.c.d/e.</para></listitem> | |
385 | </itemizedlist> | |
386 | <example><title>Example of a hosts exclusion file</title> | |
387 | <simplelist> | |
388 | <member>*.google.com</member> | |
389 | <member>10.0.0.0/8</member> | |
390 | </simplelist> | |
391 | </example> | |
392 | ||
393 | <para> | |
394 | Sarg cannot exclude IPv6 addresses at the moment. | |
395 | </para> | |
396 | ||
397 | </refsect1> | |
398 | ||
399 | <refsect1><title>See also</title> | |
400 | <para> | |
401 | squid(8) | |
402 | </para> | |
403 | </refsect1> | |
404 | ||
405 | <refsect1><title>Authors</title> | |
406 | <para> | |
407 | This manual page was written by <personname><firstname>Luigi</firstname> <surname>Gangitano</surname></personname> | |
408 | <email>gangitano@lugroma3.org</email>, | |
409 | for the <systemitem class="osname">Debian GNU/Linux</systemitem> system (but may be used by others). Revised | |
410 | by <personname><firstname>Billy</firstname> <surname>Newsom</surname></personname>. | |
411 | </para> | |
412 | <para> | |
413 | Currently maintained by <personname><firstname>Frédéric</firstname> <surname>Marchal</surname></personname> | |
414 | <email>fmarchal@users.sourceforge.net</email>. | |
415 | </para> | |
416 | </refsect1> | |
417 | ||
418 | </refentry> | |
419 | ||
420 | </article> |