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

<!--
   This file is 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/

   $Id: lwatch.sgml,v 1.23 2009/03/23 21:00:59 arturcz Exp $
   $Source: /cvsroot/lwatch/files/doc/lwatch.sgml,v $
-->

<refentry>

  <refmeta>
    <refentrytitle>lwatch</refentrytitle>
    <manvolnum>1</manvolnum>
  </refmeta>

  <refnamediv>
    <refdescriptor>lwatch</refdescriptor>
    <refname>lwatch</refname>
    <refpurpose>syntax highlighting for syslog/syslog-ng file</refpurpose>
  </refnamediv>

  <refsynopsisdiv>
    <cmdsynopsis>
      <command>lwatch</command>
      <arg>-C <replaceable>filename</replaceable></arg>
      <arg>--config <replaceable>filename</replaceable></arg>
      <arg>-i <replaceable>filename</replaceable></arg>
      <arg>--input <replaceable>filename</replaceable></arg>
      <arg>-o <replaceable>filename</replaceable></arg>
      <arg>--output <replaceable>filename</replaceable></arg>
      <arg>-sOhv</arg>
      <arg>--show-unparsed</arg>
      <arg>--omit-rc</arg>
      <arg>--help</arg>
    </cmdsynopsis>
  </refsynopsisdiv>

  <refsect1>
    <title>DESCRIPTION</title>

    <para>Lwatch is a log colorizer. It reads syslog/syslog-ng data
      from named fifo or from stdin and displays colored logs into
    stdout.</para>

    <para>Lwatch is highly user-customizable. It reads configuration
      data from the file &conf; or (if given) from the file provided with option
    <option>-C</option></para>

    <para>The way it works is simple. It reads a line from input (build-in default is &infile;), splits it
      into four parts: date, hostname, service name (with PID, if available)
      and real message. Each part has its own default color. You can redefine
      them in configuration file. Default colors as the same as in loco(1)
      [see: http://www.zjuul.net/~jules/loco/]. But lwatch is not only a static log
      colorizer. It is something more. It can colorize your logs any way
      you wish. You are able to set a new color for any part (date, host,
      service, message) using regexp based patterns.</para>
  </refsect1>

  <!-- Piszemy lwatch.conf(5)
  <refsect1>
    <title>CONFIGURATION FILE</title>
    <para>There is no documentation for configuration file as for now. Look at
    provided file, there are a lot of comments there.</para>
    <para>I am going to make some changes in configuration file before
    1.0-stable release. I will also provide docs about how to configure lwatch
    in this release.</para>
  </refsect1>
  -->

  <refsect1>
    <title>COMMAND LINE OPTIONS</title>
    <para>
      Lwatch accepts some command line options. Command line options have precedence over values from configuration file.
      <variablelist>
        <varlistentry>
	  <term><option>-C <replaceable>filename</replaceable></option></term>
	  <term><option>--config <replaceable>filename</replaceable></option></term>
	  <listitem>
	    <para>read config from filename instead of &conf;</para>
	  </listitem>
        </varlistentry>
        <varlistentry>
	  <term><option>-i <replaceable>filename</replaceable></option></term>
	  <term><option>--input <replaceable>filename</replaceable></option></term>
	  <listitem>
	    <para>read data from named fifo filename instead of &infile;</para>
	  </listitem>
        </varlistentry>
        <varlistentry>
	  <term><option>-o <replaceable>filename</replaceable></option></term>
	  <term><option>--output <replaceable>filename</replaceable></option></term>
	  <listitem>
	    <para>write colored logs to filename instead stdout</para>
	  </listitem>
        </varlistentry>
        <varlistentry>
	  <term><option>-s</option></term>
	  <term><option>--show-unparsed</option></term>
	  <listitem>
	    <para>show unparsed lines like `last message repeated 5 times' or `--- MARK ---'</para>
	  </listitem>
        </varlistentry>
        <varlistentry>
	  <term><option>-O</option></term>
	  <term><option>--omit-rc</option></term>
	  <listitem>
	    <para>do not read values from config file</para>
	  </listitem>
        </varlistentry>
        <varlistentry>
	  <term><option>-h</option></term>
	  <term><option>--help</option></term>
	  <listitem>
	    <para>show help about runtime option</para>
	  </listitem>
        </varlistentry>
        <varlistentry>
	  <term><option>-v</option></term>
	  <term><option>--version</option></term>
	  <listitem>
	    <para>show version and copyright notices</para>
	  </listitem>
        </varlistentry>
      </variablelist>
    </para>
  </refsect1>

  <!-- <refsect1>
    <title>Environment</title>

    <para>The lwatch does not use any <envvar>VARIABLES</envvar></para>

  </refsect1> -->

  <refsect1>
    <title>RUNNING</title>
    <para>Preferred way to run lwatch is to read syslog messages from named fifo or from standard input.</para>
    <para>If you use syslog you really want to read messages from named fifo.
    To do it, put a line:
    <literallayout>
    *.*                                 |&infile;
    </literallayout>
    in your syslog.conf. Create appropriate fifo and restart syslog, then run
    lwatch. You can also run lwatch before starting syslog.
    If you don't know how to create named fifo see mknod(1) for details.
    </para>

    <para>
    Remember:
    <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 comand 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>

    <para>
    Lwatch does not support reading from regular files. If you really need this functionality use following command:
    <literallayout>tail -f /path/to/filename | &bin; -i-</literallayout>
    It could be subject to change in the future.
    </para>
  </refsect1>

  <refsect1>
    <title>RESOURCES</title>
    <itemizedlist mark="dash" spacing="compact">
    <listitem><para>http://sf.net/projects/lwatch</para></listitem>
    <listitem><para>http://freshmeat.net/projects/lwatch/</para></listitem>
    </itemizedlist>
  </refsect1>

  <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>NOTE FROM AUTHOR</title>
    <para>I have written this tool for my own needs because perl tools, however flexible, eated a lot of memory and CPU.
    I have found it useful and I share it with the Open Source
    Community. But still, developing of this software is driven
    by my own needs. So, you could expect next release in a year or two ;)</para>
    <para>It would be really nice if you could find some time and spare
    it for rating this project on FreshMeat (see RESOURCES). Comments
    are welcome too. I cannot promise that I will add new features to
    lwatch immediately but any positive feedback will raise my motivation level up.</para>
    <para>Thank you in advance for your time.</para>
  </refsect1>

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

    <para>lwatch.conf(5)</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:
-->