head 1.34; access; symbols FSL_1_7_0:1.34 FSL_1_6_1:1.34 FSL_1_6_0:1.33 FSL_1_6b2:1.33 FSL_1_6b1:1.33 FSL_1_5_0:1.33 FSL_1_5a3:1.33 FSL_1_5a2:1.33 FSL_1_5a1:1.33 FSL_1_4_0:1.33 FSL_1_4b1:1.33 FSL_1_4a1:1.32 FSL_1_3_0:1.32 FSL_1_3b1:1.32 FSL_1_2_1:1.31 FSL_1_2_0:1.31 FSL_1_1_0:1.29 FSL_1_1b1:1.28 FSL_1_0_8:1.27 FSL_1_0_7:1.27 FSL_1_0_6:1.26 FSL_1_0_5:1.26 FSL_1_0_4:1.26 FSL_1_0_3:1.25 FSL_1_0_2:1.25 FSL_1_0_1:1.25 FSL_1_0_0:1.23 FSL_0_9_0:1.23 FSL_0_1_12:1.16 FSL_0_1_11:1.14 FSL_0_1_10:1.13 FSL_0_1_9:1.13 FSL_0_1_8:1.11 FSL_0_1_7:1.11 FSL_0_1_6:1.11 FSL_0_1_5:1.10 FSL_0_1_1:1.5; locks; strict; comment @# @; 1.34 date 2005.10.03.09.28.53; author rse; state Exp; branches; next 1.33; 1.33 date 2004.01.09.10.48.27; author thl; state Exp; branches; next 1.32; 1.32 date 2003.09.25.13.57.23; author thl; state Exp; branches; next 1.31; 1.31 date 2003.06.30.12.54.05; author thl; state Exp; branches; next 1.30; 1.30 date 2003.06.30.11.13.08; author thl; state Exp; branches; next 1.29; 1.29 date 2003.05.22.14.01.55; author thl; state Exp; branches; next 1.28; 1.28 date 2003.05.22.12.30.35; author thl; state Exp; branches; next 1.27; 1.27 date 2003.01.06.16.41.21; author rse; state Exp; branches; next 1.26; 1.26 date 2002.10.02.08.34.04; author thl; state Exp; branches; next 1.25; 1.25 date 2002.08.02.11.17.42; author rse; state Exp; branches; next 1.24; 1.24 date 2002.08.02.11.06.04; author rse; state Exp; branches; next 1.23; 1.23 date 2002.08.01.11.41.05; author rse; state Exp; branches; next 1.22; 1.22 date 2002.08.01.10.18.06; author rse; state Exp; branches; next 1.21; 1.21 date 2002.08.01.09.48.55; author ms; state Exp; branches; next 1.20; 1.20 date 2002.08.01.09.38.44; author rse; state Exp; branches; next 1.19; 1.19 date 2002.08.01.08.05.50; author thl; state Exp; branches; next 1.18; 1.18 date 2002.07.31.07.39.20; author thl; state Exp; branches; next 1.17; 1.17 date 2002.07.30.18.50.36; author rse; state Exp; branches; next 1.16; 1.16 date 2002.07.30.11.50.00; author thl; state Exp; branches; next 1.15; 1.15 date 2002.07.30.07.10.54; author thl; state Exp; branches; next 1.14; 1.14 date 2002.07.29.17.43.44; author rse; state Exp; branches; next 1.13; 1.13 date 2002.07.27.18.13.32; author rse; state Exp; branches; next 1.12; 1.12 date 2002.07.27.15.37.21; author rse; state Exp; branches; next 1.11; 1.11 date 2002.07.25.13.33.50; author thl; state Exp; branches; next 1.10; 1.10 date 2002.07.25.10.14.03; author rse; state Exp; branches; next 1.9; 1.9 date 2002.07.25.09.42.44; author thl; state Exp; branches; next 1.8; 1.8 date 2002.07.24.19.12.36; author rse; state Exp; branches; next 1.7; 1.7 date 2002.07.24.13.11.37; author thl; state Exp; branches; next 1.6; 1.6 date 2002.07.24.07.57.04; author thl; state Exp; branches; next 1.5; 1.5 date 2002.07.23.09.40.38; author thl; state Exp; branches; next 1.4; 1.4 date 2002.07.22.15.16.32; author thl; state Exp; branches; next 1.3; 1.3 date 2002.07.17.09.57.44; author thl; state Exp; branches; next 1.2; 1.2 date 2002.07.16.13.20.33; author thl; state Exp; branches; next 1.1; 1.1 date 2002.07.09.09.42.09; author rse; state Exp; branches; next ; desc @@ 1.34 log @Adjust copyright messages to include new year 2005. @ text @## ## OSSP fsl - Faking/Flexible Syslog Library ## Copyright (c) 2002-2005 Ralf S. Engelschall ## Copyright (c) 2002-2005 The OSSP Project ## Copyright (c) 2002-2005 Cable & Wireless ## ## 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 - Faking/Flexible Syslog Library =head1 VERSION OSSP fsl FSL_VERSION_STR =head1 SYNOPSIS LDFLAGS=`B` LIBS=`B` ./configure [...] =head1 DESCRIPTION B offers the syslog(3) API otherwise provided by the Standard C Library (F). Instead of writing to the syslogd(8) process, it uses the powerful B logging capabilities. It is a drop-in link-time replacement which enables any syslog(3) consumer to take advantage of B by just linking this library in before F. The program is intended to apply B 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) and a logging facility (I) along. B reads all configuration files matching "ICIC<*>" and parses them using B. Sections are identified by "CICIC<;>" 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. An B channel tree specification is defined by the following context-free grammar: B ::= B B ::= I | B | B '->' B | B '->' '{' B '}' B ::= B | B ';' B B ::= B '/' B ':' B | B ':' B | B B ::= B | '(' B ')' B ::= B | B '|' B B ::= 'panic' | 'critical' | 'error' | 'warning' | 'notice' | 'info' | 'trace' | 'debug' B ::= B B B ::= 'buffer' | 'fd' | 'file' | 'filter' | 'irc' | 'noop' | 'null' | 'pipe' | 'prefix' | 'smtp' | 'socket' | 'syslog' | ... B ::= I | '(' ')' | '(' B ')' B ::= B | B ',' B B ::= B '=' B B ::= m/[a-zA-Z][a-zA-Z0-9_-]*/ B ::= single-quoted, double-quoted or unquoted text =head1 OSSP L2: AVAILABLE CHANNELS 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 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 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. 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 filedescriptor passed through I. Note that Unix usually allocates C<1> for F and C<2> for F. o fd (INT fd 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=0>) or the existing file is truncated (I=1>). The desired permissions of the logfile can be set through I. If I 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 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 and I. 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 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 ) =head2 No Operation Filtering Channel (noop) The B 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 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 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 B 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 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 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] 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 is a syslog(3) redirector it must not use the I=C feature of B. It would point back to itself and end up in a infinite run-time loop! However, it's safe to use I=C with I being set to the local host. =head1 OSSP L2: EXAMPLES =head2 Example 1: simple stderr logging A very simple I just writing everything to F (filedescriptor 2): fd(fd=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 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 "IC<*>" (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 reads configuration sections located in these files. =back =head1 SEE ALSO =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 =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 was implemented in July 2002 by I and I under contract with I . It was originally intended for use in the B project as a replacement for its old B library. It was prompted by the necessity to log to multiple files in the B F package and to write messages of particular log levels to different files in the B F package. The resulting work was generously contributed as Open Source Software to the B project by I for further development and maintainance. =head1 AUTHORS =over 4 =item Thomas Lotterer =item Ralf S. Engelschall =back =cut @ 1.33 log @Adjust copyright messages to include new year 2004 @ text @d3 3 a5 3 ## Copyright (c) 2002-2004 Ralf S. Engelschall ## Copyright (c) 2002-2004 The OSSP Project ## Copyright (c) 2002-2004 Cable & Wireless Deutschland @ 1.32 log @document changes in jitter and new monitor option in file channel @ text @d3 3 a5 3 ## Copyright (c) 2002-2003 Ralf S. Engelschall ## Copyright (c) 2002-2003 The OSSP Project ## Copyright (c) 2002-2003 Cable & Wireless Deutschland @ 1.31 log @add jitter option to file channel @ text @d205 15 a219 5 (I=1 or I=0>) or the existing file is truncated (I=0 or I=1>). If I is set the logfile will be opened and closed for every write operation. This makes log file rotation easy at the price of performance. The desired permissions of the logfile can be set through I. d221 2 a222 5 Note that both append and trunc work equally well but append is obsolete and might be removed in the future. Both options can be specified together as long as they are set different. L2 versions which know the trunc option default to append mode while previous versions limited to support only the append option defaulted to truncate mode. d227 2 a228 1 INT jitter o [0=no|1=yes] =0 @ 1.30 log @introduce "trunc=" option for file channel; change default to append; keep support for obsolete "append" option @ text @d206 10 a215 6 (I=0 or I=1>). The desired permissions of the file can be set. Both append and trunc work equally well but append is obsolete and might be removed in the future. Both options can be specified together as long as they are set different. L2 versions which know the trunc option default to append mode while previous versions only having the append option defaulted to truncate mode. d220 1 @ 1.29 log @whitespaces @ text @d205 7 a211 2 (I=1) or the existing file is truncated (I=0). The desired permissions of the file can be set. d214 2 a215 1 INT append o [0=truncate|1=append] =1 a457 1 append=1, a461 1 append=1, a465 1 append=1, a479 1 append=1, @ 1.28 log @for details see attached ChangeLog @ text @d109 1 a109 1 d149 1 a149 1 | 'smtp' d160 1 a160 1 d206 1 a206 1 desired permissions of the file can be set. d240 1 a240 1 INT join o [01] =1 use JOIN/PART d378 1 a378 1 ) d385 1 a385 1 ) d389 1 a389 1 ) d395 1 a395 1 ) -> d403 1 a403 1 negate=1, d405 1 a405 1 ) d411 1 a411 1 nocase=1, d413 1 a413 1 ) d439 1 a439 1 d446 1 a446 1 prefix="%b %d %H:%M:%S %N $1[%P]: ", d448 1 a448 1 ) d452 1 a452 1 append=1, d457 1 a457 1 append=1, d462 1 a462 1 append=1, d467 1 a467 1 d470 1 a470 1 debug: d472 1 a472 1 prefix="%b %d %H:%M:%S <%L> $1[%P]: ", d474 1 a474 1 ) -> d476 2 a477 2 path="@@l_prefix@@/var/fsl/default.log", append=1, d556 1 a556 1 B reads configuration sections located in these files. d613 1 a613 1 the B F package. @ 1.27 log @Adjust copyright messages to include new year 2003 @ text @d482 1 a482 1 =head1 ENVIRONMENT d484 1 a484 1 The following environment variables affect the execution of B: d488 1 a488 1 =item C d490 2 a491 4 This variable overrides the default value (hard-coded in B under built-time via C<--with-fsl-cfgdir=>I) under run-time. The value has to point to an existing directory where configuration files named "IC<*>" (see below) exist. The default value is d494 1 a494 1 =item C a495 2 This variable overrides the default value (hard-coded in B under built-time via C<--with-fsl-prefix=>I) under run-time. d499 7 a505 1 =item C d507 35 a541 7 This variable overrides the default value (hard-coded in B under built-time via C<--with-fsl-debug=>I) under run-time. The value has to be a valid B channel tree specification. An empty value (either hard-coded or overridden) disables B debugging via B (but still logs errors to F). A value of "C" instead disables debugging at all by discarding all messages. d544 5 @ 1.26 log @rewrite infinite loop description and offer workaround @ text @d3 3 a5 3 ## Copyright (c) 2002 Ralf S. Engelschall ## Copyright (c) 2002 The OSSP Project ## Copyright (c) 2002 Cable & Wireless Deutschland @ 1.25 log @give C&W DE proper credit @ text @d346 4 a349 3 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. @ 1.24 log @Fixed various typos in fsl.pod @ text @d568 14 a581 6 B was implemented in July 2002 by Thomas Lotterer for use in the B project as a replacement for its old B library. It was prompted by the necessity to log to multiple files in the B F package and to write messages of particular log levels to different files in the B F package. @ 1.23 log @add support for FSL_PREFIX and FSL_DEBUG variables. @ text @d175 2 a176 2 indicating the paramter is optional or mandatory. Also, the default value for each paramter is listed, if there is one. d249 1 a249 1 pathes down the tree. Otherwise is does not do anything put passing the d294 1 a294 1 and finally remaining variables are expaned by strftime(3). d429 1 a429 1 # - OSSP l2 has no corresponding level for syslog(3) emerg d570 1 a570 1 for its old B library. It was prompted by the necessarity @ 1.22 log @cleanups @ text @d62 1 a62 1 configuration files matching "IC" and parses them using a356 1 ident .* d487 15 d518 1 a518 1 =item F d520 1 a520 4 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. @ 1.21 log @I think you mean 'at risk' and not 'on risk'. Nice joke. PR: Submitted by: Reviewed by: Approved by: Obtained from: @ text @d81 1 a81 1 =head1 OSSP L2 CHANNEL TREE SPECIFICATION d168 1 a168 1 =head1 AVAILABLE OSSP L2 CHANNELS d350 1 a350 1 =head1 EXAMPLES d371 2 a372 1 A very complex I logging example where... FIXME... d425 74 @ 1.20 log @joking @ text @d420 1 a420 1 subject="Attention: Company on risk!" @ 1.19 log @remove developer internals from example and take mandatories into account @ text @d419 2 a420 1 rcpt=ceo@@example.com @ 1.18 log @renamed L2 fd() channel argument "filedescriptor" to "fd" @ text @d379 2 a380 1 remotehost="localhost" d387 1 a387 1 size=1024 d396 2 a397 1 path="b" d406 2 a407 1 host=irc.dev.de.cw.net d414 2 a415 1 host=sv1.dev.de.cw.net d418 2 a419 1 host=sv1.dev.de.cw.net @ 1.17 log @cleanup @ text @d194 1 a194 1 open file identified by the given I. Note that Unix d197 1 a197 1 o fd (INT filedescriptor m d358 1 a358 1 fd(filedescriptor=2) @ 1.16 log @reduce readfileorallfiles() to readallfiles() only @ text @d54 3 a56 1 The source code of the program remains unchanged. @ 1.15 log @be fussy, "not readable" is implemented being a error condition @ text @d59 6 a64 10 (I) and a logging facility (I) along. B tries to read the file "ICI". If the file does not exist, 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. @ 1.14 log @octal integers are now possible @ text @d60 2 a61 2 tries to read the file "ICI". If the file is not readable, all files matching "IC" are read. @ 1.13 log @overhauling, cleanups and enhancements to the manual page @ text @d212 1 a212 1 INT perm o [decimal] =420 a213 8 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 @ 1.12 log @add Flexible to the official name @ text @d43 3 a45 3 LDFLAGS="`fsl-config --all --ldflags`" \ LIBS="`fsl-config --all --libs`" \ ./configure [...] d59 47 a105 42 (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. d107 4 a110 1 B ::= B d170 9 a178 7 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. d180 3 a182 1 The "buffer" channel buffers messages poured in from upper channels. It d184 1 a184 1 exceeds the buffer size, when a given time interval is reached (0 d186 1 a186 1 matches the levelflush mask. d188 67 a254 4 f buffer (INT size o [bytes] =4096 INT interval o [sec] =0 (disabled) INT levelflush o [level] =0 (none) ); d256 1 a256 3 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. d258 3 a260 2 o fd (INT filedescriptor m ); d262 1 a262 49 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. d264 1 a264 1 f noop () d266 1 a266 1 The "null" channel discards any incoming messages and creates no output d269 1 a269 1 o null () d271 1 a271 11 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] ); d273 23 a295 7 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 d298 1 a298 1 FSL offers d300 3 a302 3 D dump S string m errno d306 10 a315 3 f prefix (STR prefix m [string] STR timezone o [local|utc] =local ); d317 10 a326 4 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. d328 1 a328 10 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 ); d330 1 a330 1 The "socket" channel forwards messages poured in from upper channels to d333 13 a345 10 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. d356 72 a427 2 EXAMPLE - for a very simple l2spec writing everything to STDERR (FD#2) d429 1 a429 1 fd(filedescriptor=2) d431 1 a431 61 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) }; d433 1 a433 1 =head1 FILES d435 3 a437 3 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 d440 11 a450 1 F<@@sysconfdir@@/fsl.*> d452 2 a453 1 =head1 OPENPKG d455 1 a455 2 OpenPKG RPM packages must require the package "fsl" in both C and C and force the packaged application to link against F. d457 12 a468 1 =head1 SEE ALSO d470 1 a470 4 syslog(3), B http://www.ossp.org/pkg/lib/l2/, B http://www.ossp.org/pkg/lib/cfg/, B http://www.openpkg.org/. d474 9 a482 3 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/ d493 7 a499 1 =head1 AUTHOR d501 1 a501 1 Thomas Lotterer @ 1.11 log @description of all available channels @ text @d2 1 a2 1 ## OSSP fsl - Faking Syslog Library d35 1 a35 1 B - Faking Syslog Library @ 1.10 log @Fix a big security hole: the l2_spec() is a varargs function which gets a format string and variable arguments. In case only a fixed string is used we have to use "%s" as the format string or else "%x" in the string is treated like a formatter (and hence cause a segfault or whatever else if it tries to fetch args from the stack). This especially also no longer requires the formatters to be written %%X... @ text @d162 154 a315 2 Here is a table of available channels that lists their B and B including the type of each parameter. d317 2 a318 64 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) d322 3 a324 1 EXAMPLE for a simple l2spec writing to a file d326 1 a326 1 file(path="/var/log/file") @ 1.9 log @new l2 feature: allow empty stream (aka null channel) @ text @d287 1 a287 1 prefix(prefix="%%b %%d %%H:%%M:%%S <%%L> $1 [%%P]: ", d289 1 a289 1 -> file(path="sendmail.debug.log", append=0,perm=432) @ 1.8 log @some additional documentation points @ text @d104 2 a105 1 B ::= B @ 1.7 log @BNF; table of available channels; example @ text @d43 2 a44 2 LDFLAGS=`fsl-config --ldflags` \ LIBS="-lfsl" \ a55 7 =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. d291 8 d302 2 a303 2 OpenPKG RPM packages must require the package "l2" in both C and C and force the packaged application to link against F. d307 19 a325 1 syslog(3). d329 1 a329 1 Thomas Lotterer d332 1 @ 1.6 log @change prefix from l2. to fsl. @ text @d109 48 a156 1 FIXME T_ID, channel_cons, try to remove the word "streams" d158 6 a163 1 B ::= B d165 123 a287 47 B ::= | B | B => stream | B => '{' streams '}' B ::= | stream | stream ';' streams B ::= | B '/' B ':' B | B ':' B | B B ::= | T_ID | '(' B ')' B ::= | T_ID | T_ID '|' B B::= I | '(' ')' | '(' B ')' B ::= | B | B ',' B B ::= | paramter '=' value Here is a table of available channels that lists their names and parameters including the type of each parameter. 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); 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); @ 1.5 log @talk about l2spec @ text @d67 2 a68 2 tries to read the file "CCI". If the file is not readable, all files matching IC are read. @ 1.4 log @flush pending work regarding l2spec documentation @ text @d89 71 a159 55 l2_ch_buffer.c: size, INT, &cfg->bufsize); l2_ch_buffer.c: interval, INT, &cfg->bufinterval); l2_ch_buffer.c: levelflush, INT, &cfg->levelflush); l2_ch_fd.c: filedescriptor, INT, &cfg->fd); l2_ch_file.c: path, STR, &cfg->path); l2_ch_file.c: append, INT, &cfg->append); l2_ch_file.c: perm, INT, &cfg->perm); l2_ch_filter.c: regex, STR, &cfg->szRegex); l2_ch_filter.c: negate, INT, &cfg->bNegate); l2_ch_filter.c: nocase, INT, &cfg->bNoCase); l2_ch_irc.c: progname, STR, &cfg->cpLocalProg); l2_ch_irc.c: localhost, STR, &cfg->cpLocalHost); l2_ch_irc.c: localuser, STR, &cfg->cpLocalUser); l2_ch_irc.c: nickname, STR, &cfg->cpNickname); l2_ch_irc.c: username, STR, &cfg->cpUsername); l2_ch_irc.c: realname, STR, &cfg->cpRealname); l2_ch_irc.c: channel, STR, &cfg->cpChannel); l2_ch_irc.c: join, INT, &cfg->bJoin); l2_ch_irc.c: host, STR, &cfg->cpHost); l2_ch_irc.c: port, STR, &cfg->cpPort); l2_ch_irc.c: timeout, INT, &cfg->nTimeout); l2_ch_pipe.c: execmode, STR, &szMode); /* mode direct or shell */ l2_ch_pipe.c: runtime, STR, &szRel); /* continuous or oneshot */ l2_ch_pipe.c: path, STR, &cfg->szCmdpath); /* path of cmd */ l2_ch_prefix.c: prefix, STR, &cfg->prefix); l2_ch_prefix.c: timezone, STR, &cfg->timezone); l2_ch_smtp.c: progname, STR, &cfg->cpLocalProg); l2_ch_smtp.c: localhost, STR, &cfg->cpLocalHost); l2_ch_smtp.c: localuser, STR, &cfg->cpLocalUser); l2_ch_smtp.c: from, STR, &cfg->cpFrom); l2_ch_smtp.c: rcpt, STR, &cfg->cpRcpt); l2_ch_smtp.c: subject, STR, &cfg->cpSubject); l2_ch_smtp.c: host, STR, &cfg->cpHost); l2_ch_smtp.c: port, STR, &cfg->cpPort); l2_ch_smtp.c: timeout, INT, &cfg->nTimeout); l2_ch_socket.c: proto, STR, &cfg->szProto); l2_ch_socket.c: host, STR, &cfg->szHost); l2_ch_socket.c: port, STR, &cfg->szPort); l2_ch_socket.c: timeout, INT, &cfg->nTimeout); l2_ch_syslog.c: target, STR, &cfg->szTarget); l2_ch_syslog.c: remotehost, STR, &cfg->szRemoteHost); l2_ch_syslog.c: remoteport, INT, &cfg->nRemotePort); l2_ch_syslog.c: localhost, STR, &cfg->szLocalHost); l2_ch_syslog.c: facility, STR, &cfg->szFacility); l2_ch_syslog.c: ident, STR, &cfg->szIdent); l2_ch_syslog.c: logpid, INT, &cfg->bLogPid); @ 1.3 log @substituting the $0 ... $9 variables @ text @d87 58 @ 1.2 log @integration of lib_cfg including tree dump through traverse() @ text @d78 3 a80 2 specification may contain $1, $2, ... variables which are filled in from the I regex parts enclosed in round brackets. @ 1.1 log @First cut for new-born OSSP fsl, a faking syslog(3) API library. It is internally based (and contains) OSSP l2 and OSSP cfg. @ text @d77 1 a77 2 in curly brackets where the closing bracket must be placed on the beginning of a line and terminated with a semicolon. The B @