Index: ossp-pkg/fsl/fsl.pod RCS File: /v/ossp/cvs/ossp-pkg/fsl/fsl.pod,v rcsdiff -q -kk '-r1.10' '-r1.11' -u '/v/ossp/cvs/ossp-pkg/fsl/fsl.pod,v' 2>/dev/null --- fsl.pod 2002/07/25 10:14:03 1.10 +++ fsl.pod 2002/07/25 13:33:50 1.11 @@ -159,79 +159,171 @@ B ::= single-quoted, double-quoted or unquoted text -Here is a table of available channels that lists their B and -B including the type of each parameter. +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. + +The "buffer" channel buffers messages poured in from upper channels. It +flushes the messages down to the lower channels when the buffered space +exceeds the buffer size, when a given time interval is reached (0 +disables this feature) or when a newly arrived message has a level that +matches the levelflush mask. + + f buffer (INT size o [bytes] =4096 + INT interval o [sec] =0 (disabled) + INT levelflush o [level] =0 (none) + ); + +The "fd" channel passes messages poured in from upper channels to +the open file identified by the given filedescriptor. Note that UNIX +usually alloctes 1 for STDOUT and 2 for STDERR. + + o fd (INT filedescriptor m + ); + +The "file" channel opens a file at the given path and passes messages +poured in from upper channels to this file. If the file at the given +path already exists, additional data is either appended (append=1) or +the existing file is truncated (append=0). The desired permissions of +the file can be set. Note that due to a limitation of the current parser +only decimal numbers are accepted, so have fun doing octal to decimal +conversion. Here're some hints + + rw-rw-rw- \0666 =438 rw-r--r-- \0644 =420 + rw-rw-r-- \0664 =436 rw-r----- \0640 =416 + rw-rw---- \0660 =432 rw------- \0600 =384 + + o file (STR path m + INT append o [0=truncate|1=append] =1 + INT perm o [decimal] =420 + ); + +The "filter" channel filters messages poured in from upper channels. A +regex is used against the incoming message and the normal operation is +that only matching messages are passed down the tree. Setting negate +reverses the matching decision. Comparisons are case sensitive unless +nocase is set. + + f filter (STR regex m [PCRE] + INT negate o [0=normal,1=negate] =0 + INT nocase o [0=case,1=nocase] =0 + ); + +The "irc" channel opens a connection to a given IRC channel and passes +messages poured in from upper channels to this IRC channel. If +configured, the message posted to IRC channel contains the progname for +easy identification of the sending host. + + o irc (STR progname o [string] + STR localhost o [hostname|address] =nodename or "localhost" + STR localuser o [string] =name or "uid#"num + STR nickname o [string] =localuser + STR username o [string] =localuser"@"localhost + STR realname o [string] =username + STR channel o [string] ="#l2" + INT join o [01] =1 use JOIN/PART + STR host m [hostname|address] + STR port o [tcpport] =6667 + INT timeout o [sec] =30 + ); + +The "noop" channel can be used to divert incoming messages to multiple +pathes down the tree. Otherwise is does not do anything put passing the +messages along. It has no configuration parameters. + + f noop () + +The "null" channel discards any incoming messages and creates no output +at all. It has no configuration parameters. + + o null () + +The "pipe" channel executes a given command and pipes messages poured in +from upper channels to the commands stdin. The command can be executed +directly or run by "/bin/sh -c". The lifetime of the connection can be +adjusted by setting runtime to either "cont" for a continuous +pipethrough with command restart after termination or "one" for oneshot +where the connection is broken when the command terminates. + + o pipe (STR execmode m [direct|shell] + STR runtime m [cont|one] + STR path m [dir/file] + ); + +The "prefix" channel prefixes messages poured in from upper channels. +The format string may contain variables prefixed with a '%'. These are +expanded using the internal formatters + + L loglevel + N nodename + P pid + +then expansion continues to use application specific formatters where +FSL offers + + D dump + S string + m errno + +and finally remaining variables are expaned by strftime(3). + + f prefix (STR prefix m [string] + STR timezone o [local|utc] =local + ); + +The "smtp" channel forwards messages poured in from upper channels to +remote hosts using the Simple Mail Transfer Protocol. It is possible to +specify the local address to bind to which is useful for multihomed +hosts. + + o smtp (STR progname o [string] + STR localhost o [hostname|address] =nodename or "localhost" + STR localuser o [string] =name or "uid#"num + STR from o [string] =localuser"@"localhost + STR rcpt m [string] + STR subject o [string] ="[L2] ..." + STR host m [hostname|address] + STR port o [tcpport] ="smtp" + INT timeout o [sec] =30 + ); + +The "socket" channel forwards messages poured in from upper channels to +daemons on remote hosts using raw UDP communication or TCP connections. + + o socket (STR proto o [udp|tcp] =tcp + STR host m [hostname|address] + STR port m [udpport|tcpport] + INT timeout o [sec] =30 + ); + +The "syslog" channel forwards messages poured in from upper channels +either to the local syslog or passes it to a remote syslogd. It is +possible to specify the local address to bind to which is useful for +multihomed hosts. + + o syslog (STR target o [local|remote] =local + STR remotehost o [hostname|address] + INT remoteport o [udpport] =514 + STR localhost o [hostname|address] =nodename or localhost + STR facility o [facility] ="user" + STR ident m [string] + INT logpid o [0=no,1=yes] =1 + ); -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) + EXAMPLE + - for a very simple l2spec writing everything to STDERR (FD#2) fd(filedescriptor=2) - EXAMPLE for a simple l2spec writing to a file + EXAMPLE + - for a simple l2spec writing notices and more important + messages to a file - file(path="/var/log/file") + notice: file(path="/var/log/file") EXAMPLE for a very complex l2spec