Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages


home | help
l2(3)			       Flexible	Logging				 l2(3)

       OSSP l2 - Flexible Logging

       OSSP l2 0.9.13 (08-Jun-2007)


       OSSP l2 is a C library providing	a very flexible	and sophisticated Unix
       logging facility. It is based on	the model of arbitrary number of chan-
       nels, stacked together in a top-down data flow tree structure with fil-
       tering channels in internal nodes and output channels on	the leave

       Channel trees can be either constructed manually	through	lower-level
       API functions or	all at once with a single API function controlled by a
       compact syntactical description of the channel tree. For	generating log
       messages	a printf-style formatting engine is provided which can be ex-
       tended through callback functions. The data flow	inside the channel
       tree is controlled by (eight fixed and nine custom) logging message
       severity	levels which are assigned to each individual channel.

       Channels	are implemented	by channel handlers which can be even customer
       supplied	for creating own channels which	seamlessly integrate into the
       framework. For convenience reasons, OSSP	l2 already ships with pre-im-
       plemented filtering (noop, filter, prefix, buffer) and output (null,
       fd, file, pipe, socket, syslog, smtp) channels which already cover
       mostly all use cases of logging.

       A language is provided to allow for channel specification and configu-
       ration.	Thus, the channel tree can be constructed either by the	API
       and its ANSI C bindings or through the use of this OSSP l2 channel def-
       inition language. Applying the API allows fine grained control of the
       channel tree. Additionally, the API allows for a	more interactive chan-
       nel definition. However,	using the channel definition language to de-
       fine the	channel	tree is	more convenient, and takes less	coding effort.
       The channel definition language is almost always	sufficient for an ap-
       plication using OSSP l2.

       PANIC	fatal error -> immediate abort (SIGBUS,	SIGSEGV) CRITICAL tem-
       porary failure -> sleep,	retry possible (malloc == NULL)	ERROR	 func-
       tionality error WARNING	functionality successful NOTICE	  operation,
       statistics, start/stop --- border line production/testing --- INFO
       step-by-step TRACE    I/O tracing --- border line end-user/developer
       DEBUG	debugging messages

       An OSSP l2 channel tree can be descriped	by a textual specification ac-
       cording to the following	Backus-Naur-Form (BNF):

	tree		   ::= stream
	stream		   ::= channel
			     | channel "->" stream
			     | channel "->" "{"	streams	"}"
	streams		   ::= stream
			     | stream ";" streams
	channel		   ::= channel_level "/" channel_level ":" channel_cons
			     | channel_level ":" channel_cons
			     | channel_cons
	channel_level	   ::= IDENTIFIER
			     | "(" channel_level_mask ")"
	channel_level_mask ::= IDENTIFIER
			     | IDENTIFIER "|" channel_level_mask
	channel_cons	   ::= IDENTIFIER channel_params
	channel_params	   ::= EMPTY
			     | "(" channel_param_list ")"
	channel_param_list ::= EMPTY
			     | channel_param
			     | channel_param "," channel_param_list
	channel_param	   ::= IDENTIFIER "=" PARAMETER

       An example of such a channel tree specification is:

	noop ->	{
	  debug: prefix(prefix="[%d-%m-%Y/%H:%M:%S] ")
	     ->	buffer(size=16384)
		-> file(path=foo.log, trunc=0);
	  error: syslog(ident=foo, facility=user,,
	  panic: smtp(,;

       The following functions are provided by the OSSP	l2 API:

       Syslog Output Channel Handler (l2_handler_syslog)

       The Syslog output channel handler "l2_handler_syslog" sends the incom-
       ing message either via syslog(3)	to a local syslogd(8) or via BSD Sys-
       log protocol to a remote	Syslog service.	It conforms to RFC 3164	(The
       BSD syslog Protocol; C. Lonvick;	August 2001).

       It provides the following channel parameters:

       target (optional, "char *")
	   Sets	the location of	the target Syslog service. Possible values are
	   "local" (the	default) or "remote". If "remote" is used, the parame-
	   ters	"remotehost" has to be set, too.

       remotehost (optional, "char *")
	   Host	name or	IP address of the remote Syslog	service.  No default
	   exists, user	has to provide value.

       remoteport (optional, "int")
	   Port	number of the remote SMTP service.  Default is 514.

       localhost (optional, "char *")
	   The name of the local host, without any domain appended.

       facility	(optional, "char *")
	   The Syslog facility used for	all messages. It has to	be one of the
	   following: "kern", "user", "mail", "daemon",	"auth",	"syslog",
	   "lpr", "news", "uucp", "cron", "authpriv", "ftp", "ntp", "secu-
	   rity", "console", "clock", "local0",	"local1", "local2", "local3",
	   "local4", "local5", "local6", "local7".

       ident (mandatory, "char *")
	   Arbitrary string identifying	the program.  There is no default,
	   user	has to provide value.

       logpid (optional, "int")
	   Boolean flag	whether	to add the Process ID (pid) to the ident tag
	   in messages.	Default	is 0.

       Pipe Output Channel Handler (l2_handler_pipe)

       The Pipe	output channel handler "l2_handler_pipe" sends the incoming
       message to the standard input of	a chosen command, passed to the	l2 li-
       brary as	a parameter when calling l2_configure.

       Any command that	operates on the	standard input (c language descriptor
       stdin) can be used, but attention is advised due	to the wide variety of
       commands	and their particular exit behaviours.

       Attention! Commands that	exit on	their own and with a success return
       value will not be restarted, however those returning with non-zero exit
       codes will be restarted.	OSSP l2	reopens	closed pipe channels due to
       faulted command processes in this way. Should such a reconnection be
       required	after a	command's successful self-termination, l2_chan-
       nel_open() may be called	again on the same pipe channel pointer previ-
       ously used. Stream logging will then write to the pipe channel handler,
       which will forward the log messages to the given	command	as always. To
       find out	if a pipe channel has closed due to the	behaviour of its com-
       mand process, the l2_channel_write() operation may be called on it with
       a non-NULL message parameter, and 0 as the buffsize parameter. The re-
       turn result will	be L2_OK if the	channel	is open. Using the C language,
       such a check might look like:

       TODO NOTE FROM MICHAEL: This info will change once the pipe channel
       handler is redesigned to	allow for proper process termination, signal
       handling	of such	processes, and subsequent channel closing!!!!!!!!!!!

	   if (l2_channel_write(pPipechannel, L2_LEVEL_NOTICE, "", 0) != L2_OK)
	       if (l2_channel_open(pPipechannel) != L2_OK)
		   exit(1); /* failure */

       The command passed to the pipe channel handler may also be stopped
       while still using a OSSP	l2 stream log. If a command process is stopped
       no action is taken until	further	logging	occurs.	As soon	as the pipe
       channel handler receives	a message due to a l2_stream_log operation, it
       will attempt to restart the stopped command process and write to	its
       standard	input. If the effort to	restart	the command process fails then
       the command process is considered dead, and OSSP	l2 will	terminate the
       process and close the channel. A	l2_channel_open() will then reopen the
       pipe channel using configuration	information previously entered with

       It provides the following channel parameters:

       command (optional, "char	*")
	   OSSP	l2 will	execute	the command at this user-provided path,	and
	   pipe	messages to its	standard input when l2_stream_log operations
	   are called.

       SMTP Output Channel Handler (l2_handler_smtp)

       The SMTP	output channel handler "l2_handler_smtp" sends the incoming
       message via Simple Mail Transfer	Protocol (SMTP)	as an Email to a re-
       mote mail service. It conforms to RFC 2821 (Simple Mail Transfer	Proto-
       col; J.	Klensin; April 2001) and RFC 2822 (Internet Message Format; P.
       Resnick;	April 2001).

       It provides the following channel parameters:

       progname	(optional, "char *")
	   Arbitrary string identifying	the program using OSSP l2.  Default is
	   "NULL" which	means no program identification.

       localhost (optional, "char *")
	   Hostname of the underlying machine.	Default	is set through un-
	   ame(3) or "localhost".

       localuser (optional, "char *")
	   Username corresponding to the UID of	the underlying process.	 De-
	   fault is set	through	resolving getuid(2) or "uid#N".

       from (optional, "char *")
	   Sender Email	address	for outgoing mails.  Default is	set through
	   localuser and localhost.

       rcpt (mandatory,	"char *")
	   Recipient Email address for outgoing	mails.	No default exists,
	   user	has to provide value.

       subject (optional, "char	*")
	   Arbitrary string identifying	the generated Email message.  Default
	   is "[L2] log	channel	output on {localhost}".

       host (mandatory,	"char *")
	   Host	name or	IP address of the remote SMTP service.	No default ex-
	   ists, user has to provide value.

       port (optional, "char *")
	   Port	name or	number of the remote SMTP service.  Default is "smtp"

       timeout (optional, "int")
	   Timeout in seconds for all I/O operations.  Default is 30.

08-Jun-2007			   L2 0.9.13				 l2(3)


Want to link to this manual page? Use this URL:

home | help