Directory Services 7.2.5

Log to a service

The Common Audit framework supports logging access events to an external service:

JDBC

A JDBC handler sends messages to an appropriately configured relational database table.

Before you enable the JDBC handler, create the necessary schema and tables in the target database. See the following example files:

  • /path/to/opendj/config/audit-handlers/mysql_tables-example.sql

  • /path/to/opendj/config/audit-handlers/oracle_tables-example.sql

  • /path/to/opendj/config/audit-handlers/postgres_tables-example.sql

The JDBC handler depends on the JDBC driver for the database, and on HirakiCP. Copy the JDBC driver .jar file for your database, the HirakiCP .jar file for your Java version, and any other dependent libraries required to the opendj/extlib/ directory.

To enable the JDBC handler, see Configure a custom access log. The JSON configuration file for the JDBC handler has the following format:

{
    "class": "org.forgerock.audit.handlers.jdbc.JdbcAuditEventHandler",
    "config": {
        "name": string,                    // Handler name, such as "jdbc".
        "topics": array,                   // LDAP: "ldap-access"; HTTP: "http-access".
        "databaseType": string,            // Supported by default: "h2", "mysql",
                                           // "oracle", "postgres".
        "enabled": boolean,                // Is the handler enabled?
        "buffering": {                     // (Optional) Default: write each message separately,
                                           // no buffering.
            "enabled": boolean,            // Buffer messages to be sent? Default: false.
            "writeInterval": duration,     // Duration; must be > 0 if buffering is enabled.
            "autoFlush": boolean,          // Flush messages automatically? Default: true.
            "maxBatchedEvents": number,    // Maximum messages in prepared statement. Default: 100.
            "maxSize": number,             // Maximum number of buffered messages. Default: 5000.
            "writerThreads": number        // Threads to write buffered messages: Default: 1.
        },
        "connectionPool": {
            "dataSourceClassName": string, // Either set this to the class name of the data source...
            "jdbcUrl": string,             // ...or set this to the JDBC URL to
                                           // connect to the database.
            "username": string,            // Username to connect to the database.
            "password": string,            // Password to connect to the database.
            "autoCommit": boolean,         // (Optional) Commit transactions automatically?
                                           // Default: true.
            "connectionTimeout": number,   // (Optional) Milliseconds to wait before timing out.
                                           // Default: 30,000.
            "idleTimeout": number,         // (Optional) Milliseconds to wait before timing out.
                                           // Default: 600,000.
            "maxLifetime": number,         // (Optional) Milliseconds thread remains in pool.
                                           // Default: 1,800,000.
            "minIdle": number,             // (Optional) Minimum connections in pool.
                                           // Default: 10.
            "maxPoolSize": number,         // (Optional) Maximum number of connections in pool.
                                           // Default: 10.
            "poolName": string,            // (Optional) Name of connection pool.
                                           // Default: audit.
            "driverClassName": string      // (Optional) Class name of database driver.
                                           // Default: null.
        },
        "tableMappings": [                 // Correspondence of message fields to database columns.
            {
                "event": string,           // LDAP: "ldap-access"; HTTP: "http-access".
                "table": string,           // LDAP: "ldapaccess"; HTTP: "httpaccess".
                "fieldToColumn": {         // Map of field names to database column names.
                    "event-field": "database-column" // Event-field takes JSON pointer.
                }
            }
        ]
    }
}

For a sample configuration, see opendj/config/audit-handlers/jdbc-config.json-example.

The writeInterval takes a duration, which is a lapse of time expressed in English, such as 23 hours 59 minutes and 59 seconds. Durations are not case sensitive. Negative durations are not supported. Durations use these units:

  • indefinite, infinity, undefined, unlimited: unlimited duration

  • zero, disabled: zero-length duration

  • days, day, d: days

  • hours, hour, h: hours

  • minutes, minute, min, m: minutes

  • seconds, second, sec, s: seconds

  • milliseconds, millisecond, millisec, millis, milli, ms: milliseconds

  • microseconds, microsecond, microsec, micros, micro, us: microseconds

  • nanoseconds, nanosecond, nanosec, nanos, nano, ns: nanoseconds

JMS

A JMS handler is a JMS producer that publishes messages to an appropriately configured Java Message Service.

To enable the JMS handler, see Configure a custom access log. The JSON configuration file for the JMS handler has the following format:

{
    "class": "org.forgerock.audit.handlers.jms.JmsAuditEventHandler",
    "config": {
        "name": string,                    // Handler name, such as "jms".
        "enabled": boolean,                // Is the handler enabled?
        "topics": array,                   // LDAP: "ldap-access"; HTTP: "http-access".
        "deliveryMode": string,            // One of "NON_PERSISTENT", "PERSISTENT".
        "sessionMode": string,             // One of "AUTO", "CLIENT", "DUPS_OK".
        "batch": {                         // (Optional) Default: Use default settings.
            "capacity": number,            // Maximum capacity of publishing queue. Default: 1.
            "maxBatchedEvents": number,    // Maximum events to deliver in single publishing call.
                                           // Default: 1.
            "writeInterval": string        // Interval between transmissions to JMS.
                                           // Default: "10 millis".
        },
        "jndi": {                          // (Optional) Default: Use default settings.
            "connectionFactoryName": string, // JNDI name for JMS connection factory.
                                           // Default: "ConnectionFactory".
            "topicName": string            // (Optional) Match the value in the context.
                                           // Default: "audit".
            "contextProperties": {         // JNDI InitialContext properties.
                // These depend on the JNDI provider. See the provider documentation for details.
            }
        }
    }
}

For a sample configuration, see opendj/config/audit-handlers/jms-config.json-example.

Syslog

A Syslog handler sends messages to the UNIX system log as governed by RFC 5424, The Syslog Protocol.

The implementation currently only supports writing access messages, not error messages. As a result, this feature is of limited use in most deployments.

To enable a Syslog handler, see Configure a custom access log. The JSON configuration file for the Syslog handler has the following format:

{
    "class": "org.forgerock.audit.handlers.syslog.SyslogAuditEventHandler",
    "config": {
        "name": string,            // Handler name, such as "syslog".
        "enabled": boolean,        // Default: false.
        "topics": array,           // LDAP: "ldap-access"; HTTP: "http-access".
        "protocol": string,        // "TCP" or "UDP".
        "host": string,            // Syslog daemon host, such as localhost;
                                   // must resolve to IP address.
        "port": number,            // Syslog daemon port number, such as 514; range: 0 to 65535.
        "connectTimeout": number,  // If using TCP, milliseconds to wait before timing out.
        "facility": string,        // Syslog facility to use for event messages.
        "buffering": {             // (Optional) Default: write each message separately, no buffering.
            "enabled": boolean,    // Buffer messages to be sent? Default: false.
            "maxSize": number      // Maximum number of buffered messages. Default: 5000.
        }
    }
}

For a sample configuration, see opendj/config/audit-handlers/syslog-config.json-example.

For additional details, see Syslog facility values.

Syslog Facility Values
Value Description

kern

Kernel messages.

user

User-level messages.

mail

Mail system.

daemon

System daemons.

auth

Security/authorization messages.

syslog

Messages generated internally by syslogd.

lpr

Line printer subsystem.

news

Network news subsystem.

uucp

UUCP subsystem.

cron

Clock daemon.

authpriv

Security/authorization messages.

ftp

FTP daemon.

ntp

NTP subsystem.

logaudit

Log audit.

logalert

Log alert.

clockd

Clock daemon.

local0

Local use 0.

local1

Local use 1.

local2

Local use 2.

local3

Local use 3.

local4

Local use 4.

local5

Local use 5.

local6

Local use 6.

local7

Local use 7.