catlog - event logging interface
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.
-
A number of labels (associated with a format string and an ELS code) must
be defined (using catlog_mklabel() or
catlog_loadspecfile()).
-
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.
-
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.
-
It should now be possible to log events with catlog_event(), resulting in entries that resemble the following:
-
The format and/or code for the label is retrieved and given to the
formatting function of the dispatcher, together with any positional
parameters and relevant values.
-
The format function normally feeds the formatted message synchronously to
the final destination or queues the data in a spool file for processing at
a later time.
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.
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.
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.
- 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.
cat
catels_loginit, catlog_event, catlog_freedispatcher,
catlog_get, catlog_loadspecfile, catlog_mklabel,
catlog_set, catlog_setdispatcher, catlog_vevent
elsfile