Message Format

All syslog messages follow a specific format. Below is an example of a message as well as an explanation of its parts.

Oct 12 14:58:35 example_host BG: 1234:01:01:site=access.example.com;who=John Smith(jsmith);who_ip=192.168.1.1; event=login;target=web/login;status=success

The example above represents one message on one line. Messages can be broken down into two parts: a header followed by a payload of fields and values.

The header is made up of the date, time, hostname, and the characters BG:, which designate that this message is a BeyondTrust-specific syslog message. The remaining header information is made up of a unique 4-digit site ID, a segment number, and the total number of segments. If your B Series Appliance has only one site installed, all messages will have the same site ID. All three of these data are followed by colons. So from the example above, the entire header is:

Following the header is the payload. The format of the payload is field1=value1;field2=value2;…

This format is better suited to provide an order-independent set of data than a comma-separated format would provide, since some of the messages may contain upwards of 70 fields of data.

Note the escaping of "=", ";", and "\" characters. If any payload values include any of these characters, those characters will be prefixed with a backslash character ("\") to indicate that the next character is part of the value data, not a delimiter. For example, if a username were changed to user;s=name\id in the web interface, then the payload field/value pair in the syslog message would read ...new _ username=user\;s\=name\\id;.

Message segmentation

As mentioned above, certain syslog messages can be much larger than others. As a result, the syslog service will segment any messages that are larger than 1KB into multiple messages. In this guide, these messages will be referred to as segments.

Since the message example above is less than 1024 bytes, the header shows a value of 01:01:, indicating that this is the first segment and that there is only one segment in this message. A larger example message which does show segmentation is used in the Old/New Nomenclature section of this guide.

Payload format

Examination of the payload shows that there are several standard data fields in every message. Messages will also contain non-standard data fields that provide more information about the syslog message. Here, we discuss the standard data fields.

Again, each of these fields will be present somewhere within the payload, but the order is not specifically set. Of these four fields, the most significant is the event field. The value associated with the event field indicates what actually occurred.

Oct 12 14:58:35 example_host BG: 1234:01:01:site=access.example.com;who=John Smith(jsmith);who_ip=192.168.1.1;event=login;target=web/login;status=success

From the example, it can be determined that this particular message was generated by a login attempt. The remaining payload provides information about that event. In this case, the login attempt was for the /login administrative interface (target=web/login), and it was a successful attempt (status=success).

Syslog messages stack in order of occurrence. In the example below, a user attempts to log in but is required to change their password. The user tries to use an invalid password before setting one that matches the site's security policy and then log in successfully. Where the string ...<data truncated>... occurs, extraneous data was removed to make the example messages more readable.

Oct 12 14:53:24 example_host BG: 1234:01:01:site=access.example.com;…<data truncated>…event=login;status=failure;reason=change_password
Oct 12 14:53:43 example_host BG: 1234:01:01:site=access.example.com;…<data truncated>…event=change_password;status=failure;reason=invalid password
Oct 12 14:54:02 example_host BG: 1234:01:01:site=access.example.com;…<data truncated>…event=change_password;status=success
Oct 12 14:54:03 example_host BG: 1234:01:01:site=access.example.com;…<data truncated>…event=login;status=success

Integrated login

If a user attempts to log in via integrated login, such as LDAP, RADIUS, or Kerberos, and is unsuccessful, a login failure message will be generated even if that user can subsequently log in using local credentials.

The message below would be generated if the user could not be obtained because the failure happened too early in the integrated process or if the exchange succeeded but the security provider configuration denied the user access. In the example below, <method> will be either password for LDAP or RADIUS or gssapi for Kerberos.

Oct 12 14:53:24 example_host BG: 1234:01:01:site=access.example.com;…<data truncated>…who=unknown () using <method>; event=login;status=failure;reason=failed

Such a scenario could cause the following sequence to occur. A user attempts integrated authentication, fails because of a technical reason, such as being unable to supply a proper service ticket for Kerberos, and as a result, no username is available. However, the user then logs in using a local account or an account on another security provider.

Oct 12 14:53:24 example_host BG: 1234:01:01:site=access.example.com;…<data truncated>…who=unknown () using gssapi; event=login;status=failure;reason=failed
Oct 12 14:53:28 example_host BG: 1234:01:01:site=access.example.com;…<data truncated>…who=John Smith(jsmith); event=login;status=success

An alternate scenario could occur if a security provider is not configured with a proper default policy or group lookup for an integrated login, or if it explicitly denies that user.

Oct 12 14:53:24 example_host BG: 1234:01:01:site=access.example.com;…<data truncated>…who=John Smith([email protected]);event=login;status=failure;reason=failed
Oct 12 14:53:28 example_host BG: 1234:01:01:site=access.example.com ;…<data truncated>…who=John Smith(jsmith); event=login;status=success

Old/new nomenclature

One important note should be made concerning a common nomenclature that is frequently used within syslog messages. When a change is made to an existing setting, the change is often notated by prefixing the original setting with old _ and the new setting with new _ . The example below demonstrates a display name change. Note that this example message is split into two segments because the amount of data exceeds 1KB.

Oct 12 14:53:24 example_host BG: 1234:01:02:site=access.example.com;…<data truncated>…event=user_changed;old_username=jsmith;old_display_name=John Smith;old_permissions:suppor
Oct 12 14:53:24 example_host BG: 1234:02:02:t=1;old_permissions:support:canned_scripts=1;…<data truncated>…new_display_name=John D. Smith

This event shows that the display name was changed. The syslog process takes a snapshot of the user's current settings and prefixes those settings with old _ . It then takes a snapshot of only the changes that are about to take effect and prefixes those settings with new _ . Because, in this example, only the display _ name setting has been changed, only that setting will have both an old _ entry and a new _ entry. However, all of the other unchanged settings will also be listed, prefixed with old _ .

Localized strings

Another note concerns fields that refer to text in a specific language. When an event containing one of these fields is triggered, the resulting value is a localized string. When a localized string field is returned, the field name will change to include the value's language.

For example, the subject field of an access invite event returns a localized string. If an access invite's subject is changed, the resulting message would appear in the following format:

Oct 12 14:53:24 example_host BG: 1234:01:01:site=access.example.com;…<data truncated>…event=customizable_text_changed;public_site:id=1;old_user:invite:email:subject:en-us=Access Session Invitation from %USER_NAME%;old_user:invite:email:subject:it=Invito alla sessione di accesso da %USER_NAME%;new_ user:invite:email:subject:en-us=Join %USER_NAME%'s Session;new_ user:invite:email:subject:it=Partecipa a Sessione di %USER_NAME%

Note that even if your B Series Appliance does not have multiple languages installed, all applicable messages will be formatted as localized strings.