NAME

elsfile - ELS log message definition file

DESCRIPTION

A message definition file is a file containing definitions of log messages that are to be used in an application. This documentation is describes the use of description files together with Agents created using the Agent SDK, and restrictions may therefore apply compared to the original ELS message definition source file format.

If an ELS server is to accept and understand the log messages, the information in the log specification file must be read into the server.

Encoding

The file can be encoded as plain seven-bit ASCII, UCS-2 (two-byte UNICODE, any byte order) or utf-8. In the last case, the first characters in the file must be ``#UTF''.

Lines can be terminated by CR_LF or LF.

Syntax

Blank lines are ignored. A hash character (#) as the first character of a line indicates a comment. The comment continues to the end of the line.

The first non-comment line should be the Language Descriptor (LD).

The message definition file contains the following fields:

Language Descriptor, LD
  Language = <Language code>;

The ELS file containing the LD ``en_US'' should always be used.

Facility Designator, FD
  Facility = <facility-name>,<facility-numeric>;

ltfacility-namegt
This is the acronym for the facility. Less than 10 characters, no whitespace, case sensitive, and always US English.

ltfacility-numericgt
This is the numeric designator for the facility. Positive integer in the range 0-4095.

This sets the FD for all FMDs read until the next FD is encountered.

Facility Message Descriptor, FMD
This is a line containing fields that describe the message. The fields are specified as a comma-separated list.

  <msgname>,<msgnum>,<severity>,"<short-message-text>"

msgname
This is the message acronym, which must be in US English.

msgnum
This is the message number. This number is used together with the facility number and severity to create a unique message id.

severity
This is the message severity. It can be one on the letters ``I'' (informational), ``W'' (warning), ``E'' (error) or ``F'' (fatal).

short-message-text
This is the text that will be placed in the ELS log. The message is enclosed in double quotes. If the message contains a double quote, this must be escaped by a back slash (``\''). The text can contain placeholders where application data can be inserted. The symbols ``&1'' through ``&2'' are available for the insertion of application data.

Variable Interpolation

The message string can contain sequences of ``&character''. These sequences will be expanded to contain data supplied with the log event. In addition to ``&1'' through ``&9'', which can be used for arbitrary data, the following characters are also supported.

&U
User name.

&L
Login name.

&H
Server host name.

&C
Client host name.

&T
Token serial number.

&G
Group name.

&S
Site name.

&R
Realm name.

&V
Vendor name.

NOTES

The Keon Security Server will understand only definition files encoded in UCS-2.

EXAMPLE

The following is an example of a message definition file.

  #------------------------------------------------------------
  #
  # LD
  #
  Language=en_US;

  #
  # FD
  # 
  Facility=APP1,741;

  #
  # FMDs
  #
  AUTHFAIL,   1004, I, "REJECT &L@&C not permitted to log in as &1";
  AUTHOK,     1005, I, "OK &L@&C granted access";                       
  MAPFAIL,    1006, I, "REJECT &L@&C as &1: no mapping found";  

  #
  # New FD
  #
  Facility=APP2,742;

  #
  # FMDs for the new FD
  #
  MAPOK,      1007, I, "OK &L@&C successful mapping &1 -> &2";
  CEXPIRED,   1008, W, "REJECT &C: Certificate expired";
  CINVALID,   1009, W, "REJECT &C: Certificate invalid";                                

  #------------------------------------------------------------

SEE ALSO

cat, catlog