##
##  OSSP fsl - Faking 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 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>         ::= 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 table of available channels that lists their B<channel_name> and
B<param_names> including the type of each parameter.

FIXME mandatories, defaults, output vs. filterchannels

    buffer (INT size,
            INT interval,
            INT levelflush);

    fd     (INT filedescriptor);

    file   (STR path,
            INT append,
            INT perm);

    filter (STR regex,
            INT negate,
            INT nocase);

    irc    (STR progname,
            STR localhost,
            STR localuser,
            STR nickname,
            STR username,
            STR realname,
            STR channel,
            INT join,
            STR host,
            STR port,
            INT timeout);

    noop   ()

    null   ()

    pipe   (STR execmode,
            STR runtime,
            STR path);

    prefix (STR prefix,
            STR timezone);

    smtp   (STR progname,
            STR localhost,
            STR localuser,
            STR from,
            STR rcpt,
            STR subject,
            STR host,
            STR port,
            INT timeout);

    socket (STR proto,
            STR host,
            STR port,
            INT timeout);

    syslog (STR target,
            STR remotehost,
            INT remoteport,
            STR localhost,
            STR facility,
            STR ident,
            INT logpid);


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

    fd(filedescriptor=2)

    EXAMPLE for a simple l2spec writing to a file

    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