##
##  OSSP fsl - Faking/Flexible Syslog Library
##  Copyright (c) 2002-2005 Ralf S. Engelschall <rse@engelschall.com>
##  Copyright (c) 2002-2005 The OSSP Project <http://www.ossp.org/>
##  Copyright (c) 2002-2005 Cable & Wireless <http://www.cw.com/>
##
##  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=`B<fsl-config --all --ldflags>`
LIBS=`B<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 program is intended to apply B<OSSP l2> functionality to existing
syslog(3) based third-party programs without the requirement to change
the source code of the program.

=head1 OPERATION

If an application calls openlog(3) it passes an identification string
(I<ident>) and a logging facility (I<facility>) along. B<OSSP fsl> reads all
configuration files matching "I<cfgdir>C</>I<prefix>C<*>" and parses them using
B<OSSP cfg>. Sections are identified by "C<ident>I<match>C</>I<l2-spec>C<;>"
directives.  The I<match> argument is an B<OSSP pcre> (Perl-compatible)
regular expression that is matched against a string concatenated from
"I<ident>/I<facility>" given to the openlog(3) call.

The I<l2-spec> (single) argument is an B<OSSP l2> channel tree
specification, usually quoted with B<OSSP cfg> flexible quotes (to make
it a single B<OSSP cfg> argument) like "C<q{...}>". The I<l2-spec>
may contain "C<$1>", ..., "C<$9>" variables which are filled in from
the I<match> regular expression parts enclosed in round brackets. The
"C<$0>" variable captures the wholly match and "C<$$>" diverts to a
single escaped "C<$>".

An B<OSSP l2> channel tree is build from all I<l2-spec> on each matching
"C<ident>" directives and all found trees are merged together with a
top "C<noop>" channel to form a single channel tree. Further calls to
syslog(3) will then inject log messages into this channel tree.

=head1 OSSP L2: CHANNEL TREE SPECIFICATION

B<OSSP l2> builds its working configuration using a global environment
object and channels which are interconnected to form a channel 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. B<OSSP l2> allows a developer
to build this tree programmatically. In addition, B<OSSP l2> also
supports building up the channel tree using a text based "channel tree
specification" language. This declarative language offers maximum
flexibility as a program can read a specification created by a system
administrator and pass it to B<OSSP l2> verbatim without even knowing
anything about existing channels. If this approach is used, a newly
designed channel can be used by an existing program by just linking in
the latest B<OSSP l2> version. The main program remains unmodified.

An B<OSSP l2> channel tree specification is defined by the following
context-free grammar:

B<l2-spec>        ::= 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

=head1 OSSP L2: AVAILABLE CHANNELS

B<OSSP l2> provides various channels. The following lists their
B<channel_name> prefixed with an 'C<o>' or a 'C<f>' indicating whether
it is operating as an output or filter channel. All parameters to
B<param_names> are listed, including the type of each parameter which
is either a string (C<STR>) or integer (C<INT>) and an 'C<m>' or 'C<o>'
indicating the parameter is optional or mandatory. Also, the default
value for each parameter is listed, if there is one.

=head2 Buffering Filter Channel (buffer)

The B<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 I<size>, when a given time I<interval> is reached (0
disables this feature) or when a newly arrived message has a level that
matches the I<levelflush> mask.

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

=head2 Filedescriptor Output Channel (fd)

The B<fd> channel passes messages poured in from upper channels to the
open file identified by the filedescriptor passed through I<fd>. Note that Unix
usually allocates C<1> for F<stdout> and C<2> for F<stderr>.

 o fd     (INT fd              m
           )

=head2 File Output Channel (file)

The B<file> channel opens a file at the given I<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
(I<trunc>=0>) or the existing file is truncated (I<trunc>=1>). The
desired permissions of the logfile can be set through I<perm>. If
I<jitter> is set to a number n other than zero the logfile will be
closed and reopened before every n'th write operation. In other words,
a logfile moved away will receive a maximum of n additional messages,
then a new file using the old name will be opened without truncation. If
I<monitor> is set to n seconds other than zero a timer is set. For every
write operation the time is checked. If n or more seconds have passed by
the timer is reset and it is checked whether the logfile was moved or
disappeard. In such case the logfile will be closed an reopened before
the actual write. In other words, a logfile moved away will receive
messages no longer than the timer is set to, then a new file using the
old name will be opened without truncation. These options make external
log file rotation easy at a controllable price of performance. It is
possible to combine I<jitter> and I<monitor>.

Note that the append option is obsolete and might be removed in the
future. Use the trunc option with inverse logic instead.

 o file   (STR path            m
           INT append          o [0=no|1=yes]          =1
           INT trunc           o [0=no|1=yes]          =0
           INT jitter          o [count]               =0 (disabled)
           INT monitor         o [sec]                 =0 (disabled)
           INT perm            o [octal]               =0644
           )

=head2 Filtering Channel (filter)

The B<filter> channel filters messages poured in from upper channels.
A regular expression is applied against the incoming message and the
normal operation is that only matching messages are passed down the
tree. Setting I<negate> reverses the matching decision. Comparisons are
case sensitive unless I<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
           )

=head2 Internet Relay Chat Output Channel (irc)

The B<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 I<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
           )

=head2 No Operation Filtering Channel (noop)

The B<noop> channel can be used to divert incoming messages to multiple
channel paths down the tree. Otherwise is does not do anything put passing the
messages along. It has no configuration parameters at all.

 f noop   ()

=head2 No Operation Output Channel (null)

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

 o null   ()

=head2 Command Pipe Output Channel (pipe)

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

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

=head2 Prefixing Filtering Channel (prefix)

The B<prefix> channel prefixes messages poured in from upper channels.
The I<prefix> format string may contain formatting variables prefixed
with a 'C<%>'. These are expanded using the internal B<OSSP fsl>
formatters

 L loglevel
 N nodename
 P pid

then expansion continues to use application specific formatters where
B<OSSP l2> offers

 D dump
 S string
 m errno

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

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

=head2 Simple Mail Transfer Protocol Output Channel (smtp)

The B<smtp> channel forwards messages poured in from upper channels
to remote hosts using the Simple Mail Transfer Protocol (SMTP). It is
possible to specify the local address to bind to which is useful for
multi-homed 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
           )

=head2 Raw Socket Output Channel (socket)

The B<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
           )

=head2 Syslog Remote Output Channel (syslog)

The B<syslog> channel forwards messages poured in from upper channels
either to the local syslog(3) library or passes it directly via UDP
communication to a remote (or even local) syslogd(8). It is possible
to specify the local address to bind to which is useful for multi-homed
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
            );

WARNING: Because B<OSSP fsl> is a syslog(3) redirector it must not use
the I<target>=C<local> feature of B<OSSP l2>. It would point back to
itself and end up in a infinite run-time loop! However, it's safe to use
I<target>=C<remote> with I<remotehost> being set to the local host.

=head1 OSSP L2: EXAMPLES

=head2 Example 1: simple stderr logging

A very simple I<l2-spec> just writing everything to F<stderr>
(filedescriptor 2):

 fd(fd=2)

=head2 Example 2: simple logfile writing

A very simple I<l2-spec> just writing notices and more important
messages to a logfile with each message prepended with a classical
timestamp prefix:

 notice: prefix(prefix="[%b %d %H:%M:%S]")
         -> file(path="/var/log/foo")

=head2 Example 3: complex logging

A very complex I<l2-spec> logging example follows.
Figuring out the details is left as an exercise to the reader ;)

 noop
 -> {
     (info): filter(
         regex="foo"
     )
     -> syslog(
         remotehost="localhost",
         ident="l2"
     );
     info: prefix(
         prefix="[%b %d %H:%M:%S] <%L> [%P]"
     )
     -> {
         debug/error: buffer(
             size=65536
         )
         -> file(
             path="a"
         );
         (trace|debug)/(trace): buffer(
             size=65536
         ) ->
         file(
             path="b",
             perm=0660
         )
     };
     prefix() -> {
         warning: filter(
             negate=1,
             regex="foo"
         )
         -> irc(
             host=irc.example.com,
             timeout=3
         );
         error: filter(
             nocase=1,
             regex="foo"
         )
         -> smtp(
             host=mail.example.com,
             rcpt=cfo@example.com
         );
         panic: smtp(
             host=mail.example.com,
             rcpt=ceo@example.com,
             subject="Attention: Company at risk!"
         )
     }
 };

=head1 EXAMPLE

 #   map syslog(3) API priorities to OSSP l2 levels
 #   Notes: - syslog(3) has no corresponding priority for OSSP l2 "trace"
 #          - OSSP l2 has no corresponding level for syslog(3) "emerg"
 map emerg   panic;
 map alert   panic;
 map crit    critical;
 map err     error;
 map warning warning;
 map notice  notice;
 map info    info;
 map debug   debug;

 #   equivalent of the usual INN syslog.conf(5) entries:
 #   news.crit    @l_prefix@/var/inn/log/news.crit
 #   news.err     @l_prefix@/var/inn/log/news.err
 #   news.notice  @l_prefix@/var/inn/log/news.notice
 ident (.+)/news q{
     prefix(
       prefix="%b %d %H:%M:%S %N $1[%P]: ",
       timezone=local
     )
     -> {
         critical: file(
             path="@l_prefix@/var/inn/log/news.crit",
             perm=0644
         );
         error: file(
             path="@l_prefix@/var/inn/log/news.err",
             perm=0644
         );
         notice: file(
             path="@l_prefix@/var/inn/log/news.notice",
             perm=0644
         )
     }
 }

 #   default logging
 default (.+)/.+ q{
     debug:
     prefix(
         prefix="%b %d %H:%M:%S <%L> $1[%P]: ",
         timezone=local
     ) ->
     file(
         path="@l_prefix@/var/fsl/default.log",
         perm=0644
     )
 };

=head1 CONFIGURE

Operation.

=over 4

=item C<--with-fsl-cfgdir>

The value has to point to an existing directory where configuration
files named "I<prefix>C<*>" (see below) exist. The default value is
"C<@FSL_CFGDIR@>".

=item C<--with-fsl-prefix>

The value has to be a valid partial Unix filename. The default value is
"C<@FSL_PREFIX@>".

=back

Deployment.

=over 4

=item C<--with-fsl-debuglogcode>

The value must be empty or something where empty omits and anything else
includes debugging code.  When debugging is not used the whole debugging
code is replaced with a simple no-operation stub function.  The default
value is "C<@FSL_DEBUGLOGCODE@>".

=item C<--with-fsl-debuglogfile>

The value has to point to a file where logging information is being
dumped into. The directory has to exist, the file must be
creatable/writable.  The file is opened, written in append mode and
closed for every debug log message. In case of problems the debug log
messages will be silently discarded.  The default value is
"C<@FSL_DEBUGLOGFILE@>".

=item C<--with-fsl-debuglogmask>

The value has to point to a symlink. The content of this symlink is the
name of a loglevel or a logmask. Possible values are panic, critical,
error, warning, notice, info, trace, debug; A single word is interpreted
as a log level and all messages with that or a more important level will
be logged. If a comma is found in the symlink content a logmask is build
by or'ing together the values behind all words. The same is true when
the entire value is inside round brackets, which makes this part of the
format compatible to l2spec and allows a single word to be a mask rather
than a level. If for any reasons the symlink does not exist, is not
readable, has a syntactically wrong value or any other problems the
debug log messages will be silently discarded.  The default value is
"C<@FSL_DEBUGLOGMASK@>".

=item C<--with-fsl-debuglogstop>

The value is the maximum size of the logfile in bytes.  If this size is
reached or exceeded before the message is written logging stops and
debug log messages will be silently discarded.  The default value is
"C<@FSL_DEBUGLOGSTOP@>".

=back

For convenience reasons, what(1) or a "strings binarywithfsl | grep
'@(#)'" will provide information about debugging code being omitted or
included and, in the latter case, which logfile and logmask are being
used.

=head1 FILES

=over 4

=item F<@FSL_CFGDIR@/@FSL_PREFIX@*>

B<OSSP fsl> reads configuration sections located in these files.

=back

=head1 SEE ALSO

=over 4

=item syslog(2)

The B<POSIX> API which B<OSSP fsl> replaces under link-time.

=item B<OSSP l2>, l2(3), http://www.ossp.org/pkg/lib/l2/

The underlying library providing the flexible logging
functionality (see I<l2-spec> above).

=item B<OSSP cfg>, cfg(3), http://www.ossp.org/pkg/lib/cfg/

The underlying library providing the parsing
of the B<OSSP fsl> configuration files (see F<FSL_CFGDIR/fsl.*> above).

=item B<OSSP pcre>, pcre(3), http://www.ossp.org/pkg/lib/pcre/

The underlying library providing the matching of program identifiers on
B<OSSP fsl> C<indent> configuration directives (see I<match> above).

=item B<OpenPKG>, openpkg(7), http://www.openpkg.org/

The project which prompted the development of B<OSSP fsl>
and which is also the primary application domain of it.

=back

=head1 ONLINE RESOURCES

=over 4

=item http://www.ossp.org/pkg/lib/fsl/

=item http://cvs.ossp.org/pkg/lib/fsl/

=item ftp://ftp.ossp.org/pkg/lib/fsl/

=back

=head1 HISTORY

B<OSSP fsl> was implemented in July 2002 by I<Thomas Lotterer>
<thomas@lotterer.net> and I<Ralf S. Engelschall> <rse@engelschall.com>
under contract with I<Cable & Wireless Deutschland GmbH>
<http://www.cw.com/de>.

It was originally intended for use in the B<OpenPKG> project as a
replacement for its old B<fakesyslog> library. It was prompted by the
necessity 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.

The resulting work was generously contributed as Open Source Software
to the B<OSSP> project by I<Cable & Wireless Deutschland GmbH>
<http://www.cw.com/de> for further development and maintainance.

=head1 AUTHORS

=over 4

=item Thomas Lotterer <thomas@lotterer.net>

=item Ralf S. Engelschall <rse@engelschall.com>

=back

=cut