OSSP CVS Repository

ossp - ossp-pkg/l2/l2.pod 1.7
Not logged in
[Honeypot]  [Browse]  [Directory]  [Home]  [Login
[Reports]  [Search]  [Ticket]  [Timeline
  [Raw

ossp-pkg/l2/l2.pod 1.7
##
##  L2 - OSSP Logging Library
##  Copyright (c) 2001 The OSSP Project (http://www.ossp.org/)
##  Copyright (c) 2001 Cable & Wireless Deutschland (http://www.cw.com/de/)
##
##  This file is part of OSSP L2, a flexible logging library which
##  can be found at http://www.ossp.org/pkg/l2/.
##
##  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.
##  
##  l2.pod: Unix manual page for C API
##

=pod

=head1 NAME

B<L2> - Logging Library

=head1 VERSION

L2 L2_VERSION_STR

=head1 SYNOPSIS

...

=head1 DESCRIPTION

The B<L2> library is...

=head1 FUNCTIONS

The following functions are provided by the B<L2> API:

=head1 AVAILABLE CHANNEL HANDLERS

=head2 Syslog Output Channel Handler (l2_handler_syslog)

The Syslog output channel handler C<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:

=over 4

=item B<target> (optional, C<char *>)

Sets the location of the target Syslog service. Possible values
are C<local> (the default) or C<remote>. If C<remote> is used, the
parameters C<remotehost> has to be set, too.

=item B<remotehost> (optional, C<char *>)

Host name or IP address of the remote Syslog service.
No default exists, user has to provide value.

=item B<remoteport> (optional, C<int>)     

Port number of the remote SMTP service.
Default is C<514>.

=item B<localhost> (optional, C<char *>)     

The name of the local host, I<without> any domain appended.

=item B<facility> (optional, C<char *>)     

The Syslog facility used for all messages. It has to be one of the
following: C<kern>, C<user>, C<mail>, C<daemon>, C<auth>, C<syslog>,
C<lpr>, C<news>, C<uucp>, C<cron>, C<authpriv>, C<ftp>, C<ntp>,
C<security>, C<console>, C<clock>, C<local0>, C<local1>, C<local2>,
C<local3>, C<local4>, C<local5>, C<local6>, C<local7>.

=item B<ident> (I<mandatory>, C<char *>)     

Arbitrary string identifying the program.
There is no default, user has to provide value.

=item B<logpid> (optional, C<int>)     

Boolean flag whether to add the Process ID (pid)
to the B<ident> tag in messages. Default is C<0>.

=back

=head2 Pipe Output Channel Handler (l2_handler_pipe)

The Pipe output channel handler C<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. 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 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 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:

=over 4

=item B<command> (optional, C<char *>)

L2 will execute the command at this user-provided path, and pipe messages to
its standard input when l2_stream_log operations are called.

=back

=head2 SMTP Output Channel Handler (l2_handler_smtp)

The SMTP output channel handler C<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:

=over 4

=item B<progname> (optional, C<char *>)

Arbitrary string identifying the program using B<OSSP L2>.
Default is C<NULL> which means no program identification.

=item B<localhost> (optional, C<char *>)

Hostname of the underlying machine.
Default is set through uname(3) or C<localhost>.

=item B<localuser> (optional, C<char *>)

Username corresponding to the UID of the underlying process.
Default is set through resolving getuid(2) or C<uid#N>.

=item B<from> (optional, C<char *>)

Sender Email address for outgoing mails.
Default is set through B<localuser> and B<localhost>.

=item B<rcpt> (I<mandatory>, C<char *>)

Recipient Email address for outgoing mails.
No default exists, user has to provide value.

=item B<subject> (optional, C<char *>)

Arbitrary string identifying the generated Email message.
Default is C<[L2] log channel output on {localhost}>.

=item B<host> (I<mandatory>, C<char *>)

Host name or IP address of the remote SMTP service.
No default exists, user has to provide value.

=item B<port> (optional, C<char *>)     

Port name or number of the remote SMTP service.
Default is C<smtp> (25).

=item B<timeout> (optional, C<int>)

Timeout in seconds for all I/O operations.
Default is C<30>.

=back

=cut


CVSTrac 2.0.1