##
##  OSSP fsl - Faking/Flexible Syslog Library
##  Copyright (c) 2002 Ralf S. Engelschall <rse@engelschall.com>
##  Copyright (c) 2002 The OSSP Project <http://www.ossp.org/>
##  Copyright (c) 2002 Cable & Wireless Deutschland <http://www.cw.com/de/>
##
##  This file is part of OSSP fsl, a syslog(3) API faking library which
##  can be found at http://www.ossp.org/pkg/lib/fsl/.
##
##  Permission to use, copy, modify, and distribute this software for
##  any purpose with or without fee is hereby granted, provided that
##  the above copyright notice and this permission notice appear in all
##  copies.
##
##  THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESSED OR IMPLIED
##  WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
##  MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
##  IN NO EVENT SHALL THE AUTHORS AND COPYRIGHT HOLDERS AND THEIR
##  CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
##  SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
##  LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF
##  USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
##  ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
##  OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
##  OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
##  SUCH DAMAGE.
##
##  fsl.pod: OSSP fsl manual page
##

=pod

=head1 NAME

B<OSSP fsl> - Faking/Flexible Syslog Library

=head1 VERSION

OSSP fsl FSL_VERSION_STR

=head1 SYNOPSIS

 LDFLAGS="`fsl-config --all --ldflags`" \
 LIBS="`fsl-config --all --libs`" \
 ./configure [...]

=head1 DESCRIPTION

B<OSSP fsl> offers the syslog(3) API otherwise provided by the Standard
C Library (F<libc>). Instead of writing to the syslogd(8) process, it
uses the powerful B<OSSP l2> logging capabilities. It is a drop-in
link-time replacement which enables any syslog(3) consumer to take
advantage of B<OSSP l2> by just linking this library in before F<libc>.
The source code of the program remains unchanged.

=head1 OPERATION

If an application calls openlog(3) it passes an identification string
(I<ident>) and a logging facility (I<facility>) along. B<OSSP l2syslog>
tries to read the file "C<cfgdir>C</fsl.>I<ident>". If the file is not
readable, all files matching I<cfgdir>C</fsl.*> are read.

In both cases, all data that has been read in is then parsed for
configuration sections. These are identified by "C<ident >I<match>"
at the beginning of a line. The I<match> argument is a PCRE (Perl
Compatible Regular Expression) that is matched against a string
concatenated from "I<ident>/I<facility>" given to the openlog(3) call.

The configuration section contains an B<OSSP l2> specification enclosed
in curly brackets and terminated with a semicolon. The B<OSSP l2>
specification may contain $1 ... $9 variables which are filled in from
the I<match> regex parts enclosed in round brackets. The $0 variable
captures the wholly match and $$ diverts to a single escaped $.

An B<OSSP l2> channel tree is build from each matching section and all
found trees are merged together with a "null" channel to form a single
tree. Further calls to syslog(3) will then inject log messages into this
channel tree.

=head1 L2SPEC

The "logging library" (L2) builds its working configuration using a
global environment object and channels which are interconnected to form
a tree.  The environment object holds general internal information and
maintains the registration of formatters.  The channels are used to
process the logging message and use formatters to transform it.  The
root channel of the tree and each intermediate channel might have one or
more children below it, passing the processed message down the tree. The
leafs of the tree are constructed by channels specifically designed for
outputting the message.  Every logging message is injected into a
channel, most likely the uppermost one, and traverses down the tree
where channels with multiple children duplicate the message.  L2 allows
a developer to build this tree programmatically.  In addition, L2 also
supports building up the channel tree using a text based specification
called the l2spec. The l2spec offers maximum flexibility as a program
can read a l2spec created by a system administrator and pass it to L2
verbatim without even knowing anything about existing channels.  When
this approach is used, a newly designed channel can be used by an
existing program by just linking in the latest lib_l2. The main program
remains unmodified.

B<tree>           ::= B<stream>
                 
B<stream>         ::= I<empty>
                 | B<channel>
                 | B<channel> '->' B<stream>
                 | B<channel> '->' '{' B<streams> '}'

B<streams>        ::= B<stream>
                 | B<stream> ';' B<streams>

B<channel>        ::= B<channel_level> '/'
                   B<channel_level> ':' B<channel_cons>
                 | B<channel_level> ':' B<channel_cons>
                 | B<channel_cons>

B<channel_level>  ::= B<level_name>
                 | '(' B<channel_mask> ')'

B<channel_mask>   ::= B<level_name>
                 | B<level_name> '|' B<channel_mask>

B<level_name>     ::= 'panic'
                 | 'critical'
                 | 'error'
                 | 'warning'
                 | 'notice'
                 | 'info'
                 | 'trace'
                 | 'debug'

B<channel_cons>   ::= B<channel_name> B<channel_params>

B<channel_name>   ::= 'buffer'
                 | 'fd'
                 | 'file'
                 | 'filter'
                 | 'irc'
                 | 'noop'
                 | 'null'
                 | 'pipe'
                 | 'prefix'
                 | 'smtp' 
                 | 'socket'
                 | 'syslog'
                 | ...

B<channel_params> ::= I<empty>
                 | '(' ')'
                 | '(' B<channel_plist> ')'

B<channel_plist>  ::= B<channel_param>
                 | B<channel_param> ',' B<channel_plist>
        
B<channel_param>  ::= B<param_name> '=' B<param_value>

B<param_name>     ::= m/[a-zA-Z][a-zA-Z0-9_-]*/

B<param_value>    ::= single-quoted, double-quoted
                   or unquoted text

Here is a description of all available channels. The table lists their
B<channel_name> prefixed with an 'o' or a 'f' indicating it's operating
as an output or a filter channel. All parameters are B<param_names>
listed, including the type of each parameter which is either a string
(STR) or integer (INT) and an 'm' or 'o' indicating the paramter is
optional or mandatory. Also, the default value for each paramter is
listed, if there is one.

The "buffer" channel buffers messages poured in from upper channels.  It
flushes the messages down to the lower channels when the buffered space
exceeds the buffer size, when a given time interval is reached (0
disables this feature) or when a newly arrived message has a level that
matches the levelflush mask.

  f buffer (INT size            o [bytes] =4096
            INT interval        o [sec]   =0 (disabled)
            INT levelflush      o [level] =0 (none)
            );

The "fd" channel passes messages poured in from upper channels to
the open file identified by the given filedescriptor. Note that UNIX
usually alloctes 1 for STDOUT and 2 for STDERR.

  o fd     (INT filedescriptor  m
            );

The "file" channel opens a file at the given path and passes messages
poured in from upper channels to this file. If the file at the given
path already exists, additional data is either appended (append=1) or
the existing file is truncated (append=0). The desired permissions of
the file can be set. Note that due to a limitation of the current parser
only decimal numbers are accepted, so have fun doing octal to decimal
conversion. Here're some hints

    rw-rw-rw- \0666 =438    rw-r--r-- \0644 =420
    rw-rw-r-- \0664 =436    rw-r----- \0640 =416
    rw-rw---- \0660 =432    rw------- \0600 =384

  o file   (STR path            m
            INT append          o [0=truncate|1=append] =1
            INT perm            o [decimal]             =420
            );

The "filter" channel filters messages poured in from upper channels. A
regex is used against the incoming message and the normal operation is
that only matching messages are passed down the tree. Setting negate
reverses the matching decision. Comparisons are case sensitive unless
nocase is set.

  f filter (STR regex           m [PCRE]
            INT negate          o [0=normal,1=negate] =0
            INT nocase          o [0=case,1=nocase]   =0
            );

The "irc" channel opens a connection to a given IRC channel and passes
messages poured in from upper channels to this IRC channel. If
configured, the message posted to IRC channel contains the progname for
easy identification of the sending host.

  o irc    (STR progname        o [string]
            STR localhost       o [hostname|address] =nodename or "localhost"
            STR localuser       o [string]           =name or "uid#"num
            STR nickname        o [string]           =localuser
            STR username        o [string]           =localuser"@"localhost
            STR realname        o [string]           =username
            STR channel         o [string]           ="#l2"
            INT join            o [01]               =1 use JOIN/PART 
            STR host            m [hostname|address]
            STR port            o [tcpport]          =6667
            INT timeout         o [sec]              =30
            );

The "noop" channel can be used to divert incoming messages to multiple
pathes down the tree. Otherwise is does not do anything put passing the
messages along. It has no configuration parameters.

  f noop   ()

The "null" channel discards any incoming messages and creates no output
at all. It has no configuration parameters.

  o null   ()

The "pipe" channel executes a given command and pipes messages poured in
from upper channels to the commands stdin. The command can be executed
directly or run by "/bin/sh -c". The lifetime of the connection can be
adjusted by setting runtime to either "cont" for a continuous
pipethrough with command restart after termination or "one" for oneshot
where the connection is broken when the command terminates.

  o pipe   (STR execmode        m [direct|shell]
            STR runtime         m [cont|one]
            STR path            m [dir/file]
            );

The "prefix" channel prefixes messages poured in from upper channels.
The format string may contain variables prefixed with a '%'. These are
expanded using the internal formatters

    L loglevel
    N nodename
    P pid

then expansion continues to use application specific formatters where
FSL offers

    D dump
    S string
    m errno

and finally remaining variables are expaned by strftime(3).

  f prefix (STR prefix          m [string]
            STR timezone        o [local|utc] =local
            );

The "smtp" channel forwards messages poured in from upper channels to
remote hosts using the Simple Mail Transfer Protocol. It is possible to
specify the local address to bind to which is useful for multihomed
hosts.

  o smtp   (STR progname        o [string]
            STR localhost       o [hostname|address] =nodename or "localhost"
            STR localuser       o [string]           =name or "uid#"num
            STR from            o [string]           =localuser"@"localhost
            STR rcpt            m [string]
            STR subject         o [string]           ="[L2] ..."
            STR host            m [hostname|address]
            STR port            o [tcpport]          ="smtp"
            INT timeout         o [sec]              =30
            );

The "socket" channel forwards messages poured in from upper channels to
daemons on remote hosts using raw UDP communication or TCP connections.

  o socket (STR proto           o [udp|tcp] =tcp
            STR host            m [hostname|address]
            STR port            m [udpport|tcpport]
            INT timeout         o [sec] =30
            );

The "syslog" channel forwards messages poured in from upper channels
either to the local syslog or passes it to a remote syslogd.  It is
possible to specify the local address to bind to which is useful for
multihomed hosts.

  o syslog (STR target          o [local|remote]     =local
            STR remotehost      o [hostname|address]
            INT remoteport      o [udpport]          =514
            STR localhost       o [hostname|address] =nodename or localhost
            STR facility        o [facility]         ="user"
            STR ident           m [string]
            INT logpid          o [0=no,1=yes]       =1
            );

    EXAMPLE
    - for a very simple l2spec writing everything to STDERR (FD#2)

    fd(filedescriptor=2)

    EXAMPLE
    - for a simple l2spec writing notices and more important
    messages to a file

    notice: file(path="/var/log/file")

    EXAMPLE for a very complex l2spec

    noop
    -> {
        (info): filter(
            regex="foo"
        ) 
        -> syslog(
            remotehost="localhost"
        );
        info: prefix(
        ) 
        -> {
            debug/error: buffer(
                size=1024
            ) 
            -> file(
                path="a"
            );
            (trace|debug)/(trace): buffer(
                size=65536
            ) -> 
            file(
                path="b"
            )
        };
        prefix() -> {
            warning: filter(
                negate=1, 
                regex="foo"
            ) 
            -> irc(
                host=irc.dev.de.cw.net
            );
            error: filter(
                nocase=1, 
                regex="foo"
            ) 
            -> smtp(
                host=sv1.dev.de.cw.net
            );
            panic: smtp(
                host=sv1.dev.de.cw.net
            )
        }
    };

=head1 EXAMPLE

 ident sendmail/.* {
   debug:
     prefix(prefix="%b %d %H:%M:%S <%L> $1 [%P]: ",
            timezone=local)
     -> file(path="sendmail.debug.log", append=0, perm=432)
 };

=head1 FILES

The B<OSSP l2syslog> library reads configuration sections located in
one or more files. The path to the directory containing these file(s)
is specified at compile time and is given to the configure script via
C<--with-cfgdir=>I<cfgdir>.

F<@sysconfdir@/fsl.*>

=head1 OPENPKG

OpenPKG RPM packages must require the package "fsl" in both C<BuildPreReq> and
C<PreReq> and force the packaged application to link against F<libfsl.a>.

=head1 SEE ALSO

syslog(3), 
B<OSSP l2> http://www.ossp.org/pkg/lib/l2/, 
B<OSSP cfg> http://www.ossp.org/pkg/lib/cfg/, 
B<OpenPKG> http://www.openpkg.org/.

=head1 ONLINE RESOURCES

 Project Homepage:  http://www.ossp.org/pkg/lib/fsl/
 Source Repository: http://cvs.ossp.org/pkg/lib/fsl/
 Distribution Files: ftp://ftp.ossp.org/pkg/lib/fsl/

=head1 HISTORY

B<OSSP fsl> was implemented in July 2002 by Thomas Lotterer
<thomas@lotterer.net> for use in the B<OpenPKG> project as a replacement
for its old B<fakesyslog> library. It was prompted by the necessarity
to log to multiple files in the B<OpenPKG> F<inn> package and to write
messages of particular log levels to different files in the B<OpenPKG>
F<postfix> package.

=head1 AUTHOR

Thomas Lotterer <thomas@lotterer.net>

=cut