NAME

catlog - event logging interface

DESCRIPTION

The catlog module is a collection of functions used to log events.

Event log messages can be sent to different locations. Internally, each log event message is identified by a ``facility.label'' pair. The facility part can be omitted, and is associated with enough redundant information to enable the log functions to produce event logs for different purposes, such as BoKS, ELS, or a local file.

The basic information for a log event message is the same as that used in an ELS input file (see elsfile for the file format). In event logging, however, all information is handled as strings rather than compiled into static codes.

Overview of the catlog subsystem

  1. A number of labels (associated with a format string and an ELS code) must be defined (using catlog_mklabel() or catlog_loadspecfile()).

  2. One or more dispatchers must be set up using such functions as catels_loginit() or catboks_loginit(). The resulting dispatchers must then be inserted into the log system with catlog_setdispatcher(), either globally or for each session.

  3. Values to be used as log parameters are defined with catlog_set(), globally or for each session. For example, a default facility can be set to avoid having to specify it with all labels.

  4. It should now be possible to log events with catlog_event(), resulting in entries that resemble the following:

ELS codes

An ELS code is a unique identifier for a specific log message. The code is a 32-bit unsigned integer with the following fields:

bits 31 - 20
The facility code.

bits 19 - 16
The severity.

bits 15 - 0
The message number.

Facility code is a ``family name'' for the logs from a specific entity. The facility code must be registered at the ELS server.

The severity of a log message can be one of the following:

INFORMATIONAL (0)
WARNING (1)
ERROR (2)
FATAL (3)
The message number is the identifier for a specific message from a specific facility.

Description strings

The description string is the textual log message. It can contain embedded format characters with the format &character, which are expanded to strings. Each format character has a corresponding symbol that represents a string set by catlog_set(). The following is an example of a description string:

  "REJECT &C: Certificate expired"

The ``&C'' in the above string will be expanded to the value of CATLOG_CLIENTNAME, as set with catlog_set().

The format characters are as follows:

&U
The user name. Corresponding symbol: CATLOG_USERNAME

&L
Login name. Corresponding symbol: CATLOG_LOGINNAME

&H
Server host name. Corresponding symbol: CATLOG_HOSTNAME

&C
Client host name. Corresponding symbol: CATLOG_CLIENTNAME

&T
Token serial number. Corresponding symbol: CATLOG_TOKENSN

&G
Group name. Corresponding symbol: CATLOG_GROUPNAME

&S
Site name. Corresponding symbol: CATLOG_SITENAME

&R
Realm name. Corresponding symbol: CATLOG_REALMNAME

&V
Vendor name. Corresponding symbol: CATLOG_VENDORNAME

The description strings can also include arbitrary parameters, which are also expanded. These parameters are called &<[1-9]>. Obviously, a description string is limited to nine parameters. These positional arguments are substituted for the strings supplied to catlog_event() or catlog_vevent(), for example:

  "OK &L@&C successful mapping &1 -> &2"

The above string has two fields that will be expanded to the CATLOG_LOGINNAME and CATLOG_CLIENTNAME respectively, and two parameters that will be substituted with arbitrary strings supplied by the caller.

ELS Message Specification File

The messages used for logging are specified in a separate file. This file is used for logging in both the Keon Security Server 5.0 (ELS) and the Keon Security Server 4.5 environment. See elsfile for more details.

FUNCTION OVERVIEW

catels_loginit
Allocate and initialize a dispatcher that sends data to the ELS.

catlog_event
Log an event in the context of a session or in the global context.

catlog_freedispatcher
Free a log dispatcher.

catlog_get
Retrieve information for a predefined parameter as previously set using catlog_set().

catlog_loadspecfile
Load the log definitions from the specified file.

catlog_mklabel
Register a log label and facility label with an ELS code and a description string. The facility label can be NULL.

catlog_set
Register a value to a predefined parameter. Some parameters (if they are defined) are used automatically by the log system, for example, Agent Host Name.

catlog_setdispatcher
Install a log dispatcher for a session or globally.

catlog_vevent
Log an event. This function is similar to catlog_event() but takes a variable number of arguments for the positional parameters of the log message.

SEE ALSO

cat

catels_loginit, catlog_event, catlog_freedispatcher, catlog_get, catlog_loadspecfile, catlog_mklabel, catlog_set, catlog_setdispatcher, catlog_vevent

elsfile