GSP
Quick Navigator

Search Site

Unix VPS
A - Starter
B - Basic
C - Preferred
D - Commercial
MPS - Dedicated
Previous VPSs
* Sign Up! *

Support
Contact Us
Online Help
Handbooks
Domain Status
Man Pages

FAQ
Virtual Servers
Pricing
Billing
Technical

Network
Facilities
Connectivity
Topology Map

Miscellaneous
Server Agreement
Year 2038
Credits
 

USA Flag

 

 

Man Pages


Manual Reference Pages  -  L2 (3)

NAME

OSSP l2 - Flexible Logging

CONTENTS

VERSION

OSSP l2 0.9.13 (08-Jun-2007)

SYNOPSIS

...

DESCRIPTION

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 channels, stacked together in a top-down data flow tree structure with filtering channels in internal nodes and output channels on the leave nodes.

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 extended 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-implemented 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 configuration. 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 definition language. Applying the API allows fine grained control of the channel tree. Additionally, the API allows for a more interactive channel definition. However, using the channel definition language to define the channel tree is more convenient, and takes less coding effort. The channel definition language is almost always sufficient for an application using OSSP l2.

LOGGING LEVELS

PANIC fatal error -> immediate abort (SIGBUS, SIGSEGV) CRITICAL temporary failure -> sleep, retry possible (malloc == NULL) ERROR functionality 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

CHANNEL TREE SPECIFICATION

An OSSP l2 channel tree can be descriped by a textual specification according 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,
                 remotehost=syslog.example.com,
                 target=remote);
   panic: smtp(host=mail.example.com,
               rcpt=foo@example.com);
 }



FUNCTIONS

The following functions are provided by the OSSP l2 API:

AVAILABLE CHANNEL HANDLERS

Syslog Output Channel Handler (l2_handler_syslog)

The Syslog output channel handler l2_handler_syslog sends the incoming message either via syslog(3) to a local syslogd(8) or via BSD Syslog 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 parameters 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, security, 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 library 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_channel_open() may be called again on the same pipe channel pointer previously 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 command process, the l2_channel_write() operation may be called on it with a non-NULL message parameter, and 0 as the buffsize parameter. The return 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 l2_channel_configure().

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 remote mail service. It conforms to RFC 2821 (Simple Mail Transfer Protocol; 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 uname(3) or localhost.
localuser (optional, char *) Username corresponding to the UID of the underlying process. Default 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 exists, user has to provide value.
port (optional, char *) Port name or number of the remote SMTP service. Default is smtp (25).
timeout (optional, int) Timeout in seconds for all I/O operations. Default is 30.

Search for    or go to Top of page |  Section 3 |  Main Index


08-Jun-2007 L2 (3) L2 0.9.13

Powered by GSP Visit the GSP FreeBSD Man Page Interface.
Output converted with manServer 1.07.