<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook V4.1//EN" 
  [
    <!ENTITY % metaconf SYSTEM "conf.ent">
    %metaconf;
  ]
>

<!--
   This file is a part of the LogWatcher tool.

   Copyright (C) 2002-2009 Artur Robert Czechowski

   The LogWatcher 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 2 of
   the License, or (at your option) any later version.

   The LogWatcher is distributed in the hope that it will be useful,
   but WITHOUT ANY WARRANTY; without even the implied warranty of
   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
   GNU General Public License for more details.

   You should have received a copy of the GNU General Public License
   along with the LogWatcher; see the file COPYING.
   If not, write to the Free Software Foundation, Inc.,
   59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.

   Artur R. Czechowski
   <arturcz@hell.pl>
   http://hell.pl/arturcz/
-->

<refentry>

  <refmeta>
    <refentrytitle>lwatch.conf</refentrytitle>
    <manvolnum>5</manvolnum>
  </refmeta>

  <refnamediv>
    <refdescriptor>lwatch.conf</refdescriptor>
    <refname>lwatch.conf</refname>
    <refpurpose>configuration file for lwatch(1), syntax highlighting for syslog/syslog-ng file</refpurpose>
  </refnamediv>

  <refsect1>
    <title>DESCRIPTION</title>
    <para>Default configuration file for lwatch is &conf; (built-in value), but you can specify another file with <option>-C</option> command line option. Read lwatch(1) for details.</para>
    <!--
    <para>
      <itemizedlist mark="dash" spacing="compact">
        <listitem><para>match&amp;action settings</para></listitem>
      </itemizedlist>
    </para>
    -->

    <refsect2>
      <title>Comments</title>
      <para>Everything from # (hash) to end of line is a comment.</para>
    </refsect2>

    <refsect2>
      <title>General options</title>
      <para><option>cfg_ver</option> - this is obligatory variable and it must be placed as the first option in config file. This variable contains version of configuration file syntax. Current manual describes version 1.</para>
      <para><option>rule_action</option> - after successful matching rule lwatch tries to match next one. You can choose to exit after executing matching rule changing this parameter from <option>continue</option> (that's the default) to <option>exit</option>. You can override this global parameter for each rule. See section Actions and modificators.</para>
      <para><option>use_syslog</option> - if set to yes some messages will be logged through syslog, default is yes</para>
      <para><option>log_level</option> - how verbose log messages should produce lwatch</para>
      <para><option>date_color</option> - default color of date part</para>
      <para><option>host_color</option> - default color of hostname part</para>
      <para><option>serv_color</option> - default color of service part</para>
      <para><option>mesg_color</option> - default color of message part</para>
      <para><option>input_file</option> - where lwatch is reading data from, built-in default is &infile;, could be overwritten with command line option <option>-i</option></para>
      <para><option>output_file</option> - where lwatch output colored data; built-in default is stdout (-), could be overwritten with command line option <option>-o</option></para>
      <para><option>show_unparsed</option> - by default lwatch ignores
      lines which cannot be split into date, host, service and message, set this variable to yes if you would like to see those lines; it is the same as command line option <option>-s</option></para>
    </refsect2>

    <refsect2>
      <title>Available colors</title>
      <para>To specify color you can use following strings: black, red, green, brown, blue, magenta, cyan, lightgray, darkgray, brightred, brightgreen, yellow, brightblue, purple, brightcyan, white.</para>
    </refsect2>

    <refsect2>
      <title>Available log levels</title>
      <para>To specify the lower visible log level you can use following strings: LOG_EMERG, LOG_ALERT, LOG_CRIT, LOG_ERR, LOG_WARNING, LOG_NOTICE, LOG_INFO, LOG_DEBUG. However, lwatch logs some debug data at LOG_DEBUG, some maybe useful messages at LOG_NOTICE and errors at LOG_ERROR. So, technically, meaningful values are:
        <itemizedlist mark="dash" spacing="compact">
          <listitem><para>LOG_DEBUG - log everything</para></listitem>
          <listitem><para>LOG_NOTICE - log maybe useful messages and errors (this is the default)</para></listitem>
          <listitem><para>LOG_ERROR - log only errors (if LOG_NOTICE is too verbose for you this is the next recommended setting)</para></listitem>
          <listitem><para>LOG_CRIT - be quiet</para></listitem>
        </itemizedlist>
      </para>
      <para>Please keep in mind that meaningful values may be a subject of change in future releases.</para>
    </refsect2>

    <refsect2>
      <title>Matching patterns</title>
      <para>There The True Power of Lwatch is hidden. You can match input lines against PCRE (Perl Compatible Regular Expression) and change output depends on matching. You can read more about PCRE in pcrepattern(3) (from libpcre) or in perlre(1) (from perl).</para>
      <para>There are two ways to define matching pattern/action. First one is the simple one. Just pattern and one action:
      <literallayout>
      /regexp/      action
      </literallayout>
      The second one is more complex, but it allows one to specify more than one action or modificator with one pattern:
      <literallayout>
      /regexp/      {
      &tab;action1
      &tab;action2
      &tab;...
      &tab;actionN
      }
      </literallayout>
      </para>
      <para>There is one important thing you should remember. There is no need to quote / (slash) if you use it
      inside regexp pattern. For example:
      <literallayout>
      //USR/SBIN/CRON/        {       # cron's messages are not important
      &tab;color=blue              # display it in blue
      &tab;match_service
      }
      </literallayout>
      </para>
    </refsect2>

    <refsect2>
      <title>Actions and modificators</title>
      <para><option>date_color</option> - set date color</para>
      <para><option>mesg_color</option>, <option>color</option> - set message color</para>
      <para><option>serv_color</option> - set service name color</para>
      <para><option>host_color</option> - set hostname color</para>
      <para><option>ignore</option> - ignore this pattern, do not match next patterns</para>
      <para><option>exit</option> - do not match next patterns when <option>rule_action</option> is set to <option>continue</option>, in other case it is superfluous</para>
      <para><option>continue</option> - continue with next pattern when <option>rule_action</option> is set to <option>exit</option>, in other case it is superfluous; please note, that if <option>ignore></option> is used in the same action it takes a priority - it makes no sense to match other rules for string that has been ignored</para>
      <para><option>highlight</option> - highlight matched string with given color (see NOTES)</para>
      <para><option>match_host</option> - match hostname insted message</para>
      <para><option>match_service</option> - match service name instead message</para>
    </refsect2>

  </refsect1>

  <refsect1>
    <title>NOTES</title>

    <para><option>highlight</option> action changes the matched text.
    That's why the following part of configuration won't work:
    <literallayout>
    /root/                         highlight=brown
    /session closed for user root/ ignore
    </literallayout>
    when
    <literallayout>
    (pam_unix) session closed for user root
    </literallayout>
    would appear as an input line.</para>
    <para>First rule changes the text to:
    <literallayout>
    (pam_unix) session closed for user [BROWN]root[NORMAL]
    </literallayout>
    where <option>[BROWN]</option> and <option>[NORMAL]</option> are control
    sequences to change color to brown, then change it back to default color
    of this part. Of course this line does not match the second rule
    and you can see it on the output.</para>

    <para>There are two possible workarounds:
    <itemizedlist mark="dash" spacing="compact">
    <listitem><para>put the ignore pattern before the highlight one</para></listitem>
    <listitem><para>enhance your second rules like:
    <literallayout>
    /session closed for user .*root.*/ ignore
    </literallayout>
    </para></listitem>
    </itemizedlist>
    </para>

    

  </refsect1>

  <refsect1>
    <title>EXAMPLES</title>

    <para>Just look into provided lwatch.conf.</para>
  </refsect1>

  <!--
    <para>Some useful entities: &conf; &infile; &bin;</para>
    <itemizedlist mark="dash" spacing="compact">
    <listitem><para>fifo must exist</para></listitem>
    <listitem><para>proper name must be put in &conf; or given with -i command line option</para></listitem>
    </itemizedlist>
    </para>
    <para>In syslog-ng you can run lwatch directly from syslog, i.e.:
    <literallayout>
    log { source(src); destination(console_all);};
    destination console_all {program("&bin; -i- -o/dev/tty11"); };
    </literallayout>
    </para>
  -->

  <refsect1>
    <title>COPYRIGHT</title>

    <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 2 of the License, or (at your
      option) any later version.
    </para>

    <para>
      Regular expression support is provided by the PCRE library package, which
      is open source software, written by Philip Hazel, and copyright by the
      University of Cambridge, England. This library is available at:
      ftp://ftp.csx.cam.ac.uk/pub/software/programming/pcre/
    </para>

  </refsect1>

  <refsect1>
    <title>SEE ALSO</title>

    <para>lwatch(1), pcrepattern(3), perlre(1)</para>
  </refsect1>

</refentry>

<!-- Keep this comment at the end of the file
Local variables:
mode: sgml
sgml-omittag:t
sgml-shorttag:t
sgml-minimize-attributes:nil
sgml-always-quote-attributes:t
sgml-indent-step:2
sgml-indent-data:t
sgml-parent-document:nil
sgml-default-dtd-file:nil
sgml-exposed-tags:nil
sgml-local-catalogs:nil
sgml-local-ecat-files:nil
End:
-->