"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>