Console Logging in BBj

Console Logging is available in BBj 19.0 and higher. The purpose of Console Logging is to record anything entered at the BBj SysConsole or TermConsole command line and any changes made to a program line using the console’s command line editor (graphical or character-based) during a BBj session. This information, along with a username, timestamp, and session number, is written to the syslog of a user-specified Linux/UNIX machine that is accessible only to the system administrator with the root password.

BBj Console Logging is dependent on syslog, which is included as part of the operating system on Linux and UNIX systems. Therefore, networks of Windows or Mac computers can implement BBj Console Logging when a suitable Linux or UNIX machine is available to act as the syslog server.

The console logging system helps businesses meet Sarbanes-Oxley auditing requirements. The BBj-generated console logging information stored in the syslog provides an audit trail, showing what changes have been made to an executing BBj session by any user able to access the console ready prompt for entering commands or changing code. For this reason, it is sometimes referred to as “audit logging” or “program auditing”, although those names are a little misleading.

Configuring Console Logging

Console logging must be configured and managed by a trusted administrative user with both the root password and a working knowledge of syslog operations. Ordinary BBj users, constituting the group whose activities will be logged, must not have access to the root password or the syslog configuration, otherwise the integrity of the log for auditing purposes will be compromised. The designated admin user should take the following steps to configure console logging in BBj:

  1. Configure the syslog to listen for messages from BBj. Precisely documenting syslog configuration for all the various platforms and operating systems in use today is beyond the scope of these instructions, but there are three basic steps:

    1. Edit the syslog configuration file.

    2. Restart the syslog service.

    3. Verify the syslog server is listening for messages.

  2. Edit the console logger configuration file. A sample copy called consoleLogger.config is in the <bbjhome>/cfg directory of a BBj installation. Edit this file to reflect various parameters that allow BBj to connect with the machine being used as the syslog server.

    • syslogServerHostName: Use "localhost" if the syslog is running on the same machine that is running BBj, otherwise specify the name of the machine on the network that is running the syslog.

    • syslogServerPort: The default is "514".

    • syslogProtocol: This can be either "TCP" or "UDP", and must match the setting specified in the syslog configuration file from Step 1.

    • syslogMessageSeverity: The default severity level is "INFORMATIONAL", but other choices are "DEBUG", "NOTICE", "WARNING", "ERROR", "CRITICAL", "ALERT", or "EMERGENCY" depending on the attention that console messages from BBj should be given.

    • syslogMessageFormat: The default format is "RFC_3164", but an alternative is "RFC_5424".

    In the example console logger configuration file below, the host name and other parameters have been changed:

    syslogServerHostName=BigKahuna
    syslogServerPort=514
    syslogProtocol=UDP
    syslogMessageSeverity=NOTICE
    syslogMessageFormat=RFC_5424

  3. Rename and move the console logger configuration file to a secure location and change its permissions. Rename the configuration file and move it out of the <bbjhome>/cfg directory to a location on the network accessible to all computers that run BBj. The choice of file name and extension does not matter. Change its file permissions to allow read access for everyone and write access only for root.

  4. Edit the BBj.properties file. Add a new one-line property to the BBj.properties file, which looks something like this:

    consoleLogger.configurationFile=C\:\\BASIS_BBj_Trunk\\cfg\\myLoggerConfig.txt

    The location and name of the console logger configuration file is specified by the consoleLogger.configurationFile property in the BBj.properties file. If the property is not present in the BBj.properties file, or if the specified location is wrong and the configuration file does not exist there, console logging is disabled and a one-time warning message is written to the Debug.log file. This means that organizations which do not require the console logging feature and therefore do not position the configuration file will always see this harmless one-line message.

Failure Cases

The following information details how console logging fails if various configuration items are omitted:

Case 1: The consoleLogger.configurationFile property is not found (or is removed) from the BBj.properties file.

  • This is the situation most commonly encountered by companies and users who do not require console logging to a syslog server, because by default BBj is shipped without the consoleLogger.configurationFile property in the BBj.properties file. Console logging does not take place unless it is deliberately configured by an administrator user.
  • In this case nothing is written to the syslog, regardless of the status of the configuration file or syslog server.
  • A one-time message goes to BBj's Debug.log stating, "CONSOLE LOGGING IS DISABLED: Initialization exception: Missing syslog message protocol". No other warnings or indications are provided.

Case 2: The consoleLogger.configurationFile property is present in the BBj.properties file, but the property points to a non-existent configuration file.

  • In this case nothing is written to the syslog, regardless of the status of the syslog server.
  • A one-time message goes to BBj's Debug.log stating, "CONSOLE LOGGING IS DISABLED: Initialization exception: Missing syslog message protocol". No other warnings or indications are provided.

Case 3: The consoleLogger.configurationFile property is present in the BBj.properties file, but the property points to an existing configuration file with incorrect or missing information.

  • In this case, the success or failure of console logging depends on which specific properties in the configuration file are incorrect or missing. Some cause console logging to fail, others allow logging to proceed using default values.
  • If the syslogProtocol is invalid or missing, a one-time message goes to BBj's Debug.log stating, "CONSOLE LOGGING IS DISABLED: Initialization exception: Invalid/Missing syslog message protocol". Console logging fails, and no other warning or indication is provided.
  • If the syslogServerHostName is missing, a one-time message goes to BBj's Debug.log stating, "CONSOLE LOGGING IS DISABLED: Initialization exception: Missing syslog host name". Console logging fails, and no other warning or indication is provided.
  • If the syslogServerHostName is invalid, the BBj console responds slowly at first, and then continues at normal speed. A one-time message goes to BBj's Debug.log stating, "CONSOLE LOGGING IS DISABLED: Incorrect consolelogging configuration: java.net.UnknownHostException: <incorrect_host_name_here>". Console logging fails, and no other warning or indication is provided.
  • If the syslogServerPort is missing, a default value of "514" is used. BBj performs console logging using that port number. If that default port is not a good match for the syslog server, there may be other exceptions or symptoms of failure.
  • If the syslogServerPort is invalid or unsuited for the syslog server, there may be other exceptions or symptoms of failure.
  • If the syslogMessageSeverity or the syslogMessageFormat are invalid or missing, default values of Severity.INFORMATIONAL and MessageFormat.RFC_3164 are used. BBj performs console logging using those default values. If those defaults are not a good match for the syslog server, there may be other exceptions or symptoms of failure.

Case 4: The consoleLogger.configurationFile property is present in the BBj.properties file, pointing to an existing configuration file with fully correct information, but the specified syslog server is not available (offline, not configured, etc.).

  • The BBj console responds slowly at first, and then continues at normal speed. A one-time message goes to BBj's Debug.log stating, "CONSOLE LOGGING IS DISABLED: Incorrect console logging configuration: java.net.UnknownHostException: <unavailable_host_name_here>". Console logging fails, and no other warning or indication is provided.

Case 5: Console logging is configured entirely correctly, but the user has no BASIS SAM license.

  • License nagging occurs, but console logging proceeds as normal.