view xml/wflogs-daemon.in @ 4:37eace15ef87

allow hourly/daily/weekly triggers for output generation, append to temp wflogs input files so daemon restart won't drop as much data
author Carl Byington <carl@five-ten-sg.com>
date Fri, 17 May 2013 12:03:21 -0700
parents 400b1de6e1c6
children
line wrap: on
line source

<reference>
    <title>@PACKAGE@ - Version @VERSION@</title>
    <partintro>
        <title>Packages</title>

        <para>The various source and binary packages are available at <ulink
        url="http://www.five-ten-sg.com/@PACKAGE@/packages/">http://www.five-ten-sg.com/@PACKAGE@/packages/</ulink>
        The most recent documentation is available at <ulink
        url="http://www.five-ten-sg.com/@PACKAGE@/">http://www.five-ten-sg.com/@PACKAGE@/</ulink>
        </para>

        <para>A <ulink
        url="http://www.selenic.com/mercurial/wiki/">Mercurial</ulink> source
        code repository for this project is available at <ulink
        url="http://hg.five-ten-sg.com/@PACKAGE@/">http://hg.five-ten-sg.com/@PACKAGE@/</ulink>.
        </para>

    </partintro>

    <refentry id="@PACKAGE@.1">
        <refentryinfo>
            <date>2013-05-17</date>
        </refentryinfo>

        <refmeta>
            <refentrytitle>@PACKAGE@</refentrytitle>
            <manvolnum>1</manvolnum>
            <refmiscinfo>@PACKAGE@ @VERSION@</refmiscinfo>
        </refmeta>

        <refnamediv id='name.1'>
            <refname>@PACKAGE@</refname>
            <refpurpose>daemon to periodically call wflogs</refpurpose>
        </refnamediv>

        <refsynopsisdiv id='synopsis.1'>
            <title>Synopsis</title>
            <cmdsynopsis>
                <command>@PACKAGE@</command>
                <arg><option>-c</option></arg>
                <arg><option>-d <replaceable class="parameter">n</replaceable></option></arg>
            </cmdsynopsis>
        </refsynopsisdiv>

        <refsect1 id='description.1'>
            <title>Description</title>

            <para><command>@PACKAGE@</command> is a simple daemon to periodically
            call wflogs to convert firewall logs to html.</para>

            <para>The <citerefentry> <refentrytitle>@PACKAGE@.conf</refentrytitle>
            <manvolnum>5</manvolnum> </citerefentry> file specifies the syslog files
            to be monitored, and the regular expressions (<citerefentry>
            <refentrytitle>regex</refentrytitle> <manvolnum>7</manvolnum>
            </citerefentry>) to be applied to new lines in those files.  Each matching
            line is written to a temp file used as input by wflogs.</para>

            <para>Considering syslog files in particular, these are normally rotated
            via logrotate.  <command>@PACKAGE@</command> properly detects and
            handles this case by closing the old file, and reopening the newly
            created file.</para>
        </refsect1>

        <refsect1 id='options.1'>
            <title>Options</title>
            <variablelist>
                <varlistentry>
                    <term>-c</term>
                    <listitem>
                        <para>
                            Load the configuration file, print a cannonical form
                            of the configuration on stdout, and exit.
                       </para>
                   </listitem>
                </varlistentry>
                <varlistentry>
                    <term>-d <replaceable class="parameter">n</replaceable></term>
                    <listitem>
                        <para>
                            Set the debug level to <replaceable class="parameter">n</replaceable>.
                        </para>
                    </listitem>
                </varlistentry>
            </variablelist>
        </refsect1>

        <refsect1 id='usage.1'>
            <title>Usage</title>
            <para><command>@PACKAGE@</command> -d 2</para>
        </refsect1>

        <refsect1 id='configuration.1'>
            <title>Configuration</title>
            <para>
                The configuration file is documented in <citerefentry>
                <refentrytitle>@PACKAGE@.conf</refentrytitle> <manvolnum>5</manvolnum>
                </citerefentry>.  Any change to the config file will cause it to be
                reloaded within three minutes.
            </para>
        </refsect1>

        <refsect1 id='copyright.1'>
            <title>Copyright</title>
            <para>
                Copyright (C) 2013 by 510 Software Group &lt;carl@five-ten-sg.com&gt;
            </para>
            <para>
                This program is free software; you can redistribute it and/or modify it
                under the terms of the GNU General Public License as published by the
                Free Software Foundation; either version 3, or (at your option) any
                later version.
            </para>
            <para>
                You should have received a copy of the GNU General Public License along
                with this program; see the file COPYING.  If not, please write to the
                Free Software Foundation, 675 Mass Ave, Cambridge, MA 02139, USA.
            </para>
        </refsect1>

        <refsect1 id='version.1'>
            <title>Version</title>
            <para>
                @VERSION@
            </para>
        </refsect1>
    </refentry>


    <refentry id="@PACKAGE@.conf.5">
        <refentryinfo>
            <date>2013-05-17</date>
        </refentryinfo>

        <refmeta>
            <refentrytitle>@PACKAGE@.conf</refentrytitle>
            <manvolnum>5</manvolnum>
            <refmiscinfo>@PACKAGE@ @VERSION@</refmiscinfo>
        </refmeta>

        <refnamediv id='name.5'>
            <refname>@PACKAGE@.conf</refname>
            <refpurpose>configuration file for @PACKAGE@</refpurpose>
        </refnamediv>

        <refsynopsisdiv id='synopsis.5'>
            <title>Synopsis</title>
            <cmdsynopsis>
                <command>@PACKAGE@.conf</command>
            </cmdsynopsis>
        </refsynopsisdiv>

        <refsect1 id='description.5'>
            <title>Description</title>
            <para>The <command>@PACKAGE@.conf</command> configuration file is
            specified by this partial bnf description. The entire config file
            is case sensitive. All the keywords are lower case.
            </para>

            <literallayout class="monospaced"><![CDATA[
CONFIG     = {CONTEXT ";"}+
CONTEXT    = "context" NAME "{" {STATEMENT}+ "}"
STATEMENT := (PERIOD | VERSIONS | TRIGGER | OUTPUT | TEMPIN | WFLOGS | FILE | PATTERN) ";"
PERIOD    := "period" INTEGER-VALUE-SECONDS
VERSIONS  := "versions" INTEGER-VALUE
TRIGGER   := "trigger" ("hourly" | "daily" | "weekly")
OUTPUT    := "output" OUTPUT-FILE-PATTERN
TEMPIN    := "tempin" TEMP-FILE-NAME
WFLOGS    := "wflogs" WFLOGS-COMMAND-PATTERN
FILE      := "file" FILENAME "{" PATTERN+ "}"
PATTERN   := "pattern" REGULAR-EXPRESSION]]></literallayout>
        </refsect1>

        <refsect1 id='sample.5'>
            <title>Sample</title>
            <literallayout class="monospaced"><![CDATA[
context fast-response {
    period   120;
    versions 20;
    output   "/var/www/html/firewall.0fast.%d.html";
    tempin   "/var/lib/wflogs-daemon/wflogs.fast.input";
    wflogs   "nice wflogs -i all -o html /var/lib/wflogs-daemon/wflogs.fast.input >%s &";
    file     "/var/log/messages";
    pattern  "vyatta kernel";
};

context hourly {
    period   3600;
    versions 4;
    trigger  hourly;
    output   "/var/www/html/firewall.1hourly.%d.html";
    tempin   "/var/lib/wflogs-daemon/wflogs.hourly.input";
    wflogs   "nice wflogs -i all -o html /var/lib/wflogs-daemon/wflogs.hourly.input >%s &";
    file     "/var/log/messages";
    pattern  "vyatta kernel";
};

context daily {
    period   86400;
    versions 7;
    trigger  daily;
    output   "/var/www/html/firewall.2daily.%d.html";
    tempin   "/var/lib/wflogs-daemon/wflogs.daily.input";
    wflogs   "nice wflogs -i all -o html /var/lib/wflogs-daemon/wflogs.daily.input >%s &";
    file     "/var/log/messages";
    pattern  "vyatta kernel";
};

context weekly {
    period   604800;
    versions 4;
    trigger  weekly;
    output   "/var/www/html/firewall.3weekly.%d.html";
    tempin   "/var/lib/wflogs-daemon/wflogs.weekly.input";
    wflogs   "nice wflogs -i all -o html /var/lib/wflogs-daemon/wflogs.weekly.input >%s &";
    file     "/var/log/messages";
    pattern  "vyatta kernel";
};]]></literallayout>
        </refsect1>

        <refsect1 id='version.5'>
            <title>Version</title>
            <para>
                @VERSION@
            </para>
        </refsect1>

    </refentry>
</reference>