Index: ossp-pkg/fsl/fsl.pod RCS File: /v/ossp/cvs/ossp-pkg/fsl/fsl.pod,v rcsdiff -q -kk '-r1.12' '-r1.13' -u '/v/ossp/cvs/ossp-pkg/fsl/fsl.pod,v' 2>/dev/null --- fsl.pod 2002/07/27 15:37:21 1.12 +++ fsl.pod 2002/07/27 18:13:32 1.13 @@ -40,9 +40,9 @@ =head1 SYNOPSIS - LDFLAGS="`fsl-config --all --ldflags`" \ - LIBS="`fsl-config --all --libs`" \ - ./configure [...] +LDFLAGS=`B` +LIBS=`B` +./configure [...] =head1 DESCRIPTION @@ -56,50 +56,58 @@ =head1 OPERATION If an application calls openlog(3) it passes an identification string -(I) and a logging facility (I) along. B -tries to read the file "CCI". If the file is not -readable, all files matching IC are read. - -In both cases, all data that has been read in is then parsed for -configuration sections. These are identified by "CI" -at the beginning of a line. The I argument is a PCRE (Perl -Compatible Regular Expression) that is matched against a string -concatenated from "I/I" given to the openlog(3) call. - -The configuration section contains an B specification enclosed -in curly brackets and terminated with a semicolon. The B -specification may contain $1 ... $9 variables which are filled in from -the I regex parts enclosed in round brackets. The $0 variable -captures the wholly match and $$ diverts to a single escaped $. - -An B 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. +(I) and a logging facility (I) along. B +tries to read the file "ICI". If the file is not +readable, all files matching "IC" are read. + +In both cases, all data that has been read in is parsed for +configuration sections via B. These are identified by "CIC< >IC<;>" directives. The I argument is an B (Perl-compatible) regular expression that is matched against a +string concatenated from "I/I" given to the openlog(3) +call. + +The I (single) argument is an B channel tree +specification, usually quoted with B flexible quotes (to make +it a single B argument) like "C". The I +may contain "C<$1>", ..., "C<$9>" variables which are filled in from +the I 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 channel tree is build from all I on each matching +"C" directives and all found trees are merged together with a +top "C" 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 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 allows a developer +to build this tree programmatically. In addition, B 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 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 version. The main program remains unmodified. -B ::= B +An B channel tree specification is defined by the following +context-free grammar: + +B ::= B B ::= I | B @@ -159,151 +167,182 @@ B ::= single-quoted, double-quoted or unquoted text -Here is a description of all available channels. The table lists their -B prefixed with an 'o' or a 'f' indicating it's operating -as an output or a filter channel. All parameters are B -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. +=head1 AVAILABLE OSSP L2 CHANNELS -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. +B provides various channels. The following lists their +B prefixed with an 'C' or a 'C' indicating whether +it is operating as an output or filter channel. All parameters to +B are listed, including the type of each parameter which +is either a string (C) or integer (C) and an 'C' or 'C' +indicating the paramter is optional or mandatory. Also, the default +value for each paramter is listed, if there is one. - 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 - ); +=head2 Buffering Filter Channel (buffer) -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 B 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, when a given time I is reached (0 +disables this feature) or when a newly arrived message has a level that +matches the I mask. -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 - ); + 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 channel passes messages poured in from upper channels to the +open file identified by the given I. Note that Unix +usually allocates C<1> for F and C<2> for F. + + o fd (INT filedescriptor m + ) + +=head2 File Output Channel (file) + +The B channel opens a file at the given I 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=1) or the existing file is truncated (I=0). The +desired permissions of the file can be set. + + o file (STR path m + INT append o [0=truncate|1=append] =1 + INT perm o [decimal] =420 + ) + +Notice: 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 + +=head2 Filtering Channel (filter) + +The B 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 reverses the matching decision. Comparisons are +case sensitive unless I 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 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 +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 "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 - ); +=head2 No Operation Filtering Channel (noop) -The "noop" channel can be used to divert incoming messages to multiple +The B 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. +messages along. It has no configuration parameters at all. + + f noop () - f noop () +=head2 No Operation Output Channel (null) -The "null" channel discards any incoming messages and creates no output +The B channel discards any incoming messages and creates no output at all. It has no configuration parameters. - o null () + 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] - ); +=head2 Command Pipe Output Channel (pipe) -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 +The B channel executes a given command and pipes messages poured +in from upper channels to the commands F. The command can be +executed directly or run by "C". The lifetime of the +connection can be adjusted by setting I to either "C" +for a continuous pipe-through with command restart after termination or +"C" 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 channel prefixes messages poured in from upper channels. +The I format string may contain formatting variables prefixed +with a 'C<%>'. These are expanded using the internal B +formatters + + L loglevel + N nodename + P pid then expansion continues to use application specific formatters where -FSL offers +B offers - D dump - S string - m errno + 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 - ); + 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. +=head2 Simple Mail Transfer Protocol Output Channel (smtp) - 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 B 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. -The "socket" channel forwards messages poured in from upper channels to -daemons on remote hosts using raw UDP communication or TCP connections. + 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 + ) - o socket (STR proto o [udp|tcp] =tcp - STR host m [hostname|address] - STR port m [udpport|tcpport] - INT timeout o [sec] =30 - ); +=head2 Raw Socket Output Channel (socket) -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. +The B 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 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] @@ -314,99 +353,133 @@ 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) +NOTICE: Because B implements the syslog(3) library API itself, +use cannot use the I=C feature of B, because it +would lead to a endless run-time loop! Be careful here, please. + +=head1 EXAMPLES + +=head2 Example 1: simple stderr logging + +A very simple I just writing everything to F +(filedescriptor 2): + + ident .* + fd(filedescriptor=2) + +=head2 Example 2: simple logfile writing + +A very simple I 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 logging example where... FIXME... + + noop + -> { + (info): filter( + regex="foo" + ) + -> syslog( + remotehost="localhost" + ); + info: prefix( + prefix="[%b %d %H:%M:%S] <%L> [%P]" + ) + -> { + 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 FILES -The B 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. +=over 4 -F<@sysconfdir@/fsl.*> +=item F -=head1 OPENPKG +B reads configuration sections located in these files. The +path FSL_CFGDIR of the directory containing these file(s) has to be +specified at build-time of B via the F option +C<--with-cfgdir=>I. -OpenPKG RPM packages must require the package "fsl" in both C and -C and force the packaged application to link against F. +=back =head1 SEE ALSO -syslog(3), -B http://www.ossp.org/pkg/lib/l2/, -B http://www.ossp.org/pkg/lib/cfg/, -B http://www.openpkg.org/. +=over 4 + +=item syslog(2) + +The B API which B replaces under link-time. + +=item B, l2(3), http://www.ossp.org/pkg/lib/l2/ + +The underlying library providing the flexible logging +functionality (see I above). + +=item B, cfg(3), http://www.ossp.org/pkg/lib/cfg/ + +The underlying library providing the parsing +of the B configuration files (see F above). + +=item B, pcre(3), http://www.ossp.org/pkg/lib/pcre/ + +The underlying library providing the matching of program identifiers on +B C configuration directives (see I above). + +=item B, openpkg(7), http://www.openpkg.org/ + +The project which prompted the development of B +and which is also the primary application domain of it. + +=back =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/ +=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 @@ -417,9 +490,15 @@ messages of particular log levels to different files in the B F package. -=head1 AUTHOR +=head1 AUTHORS + +=over 4 + +=item Thomas Lotterer + +=item Ralf S. Engelschall -Thomas Lotterer +=back =cut