How do I configure DS (All versions) to use the Syslog audit event handler?

Last updated Jan 12, 2023

The purpose of this article is to provide information on configuring DS to use the Syslog audit event handler; it covers both an external and a local configuration. This article assumes you already have a working Syslog server configured.

Overview

You can configure the Syslog audit event handler as either an external or local configuration as detailed in the following sections:

Using an external Syslog audit event handler
Using a local Syslog audit event handler

Note

You must ensure Syslog is correctly set up before configuring DS to use the Syslog audit event handler. See RSyslog Documentation for further information, ensuring that you restart the Syslog server after making any changes to the Syslog configuration.

Example configuration files can be found in the /path/to/ds/config/audit-handlers directory; they have an -example suffix and can be used as the basis of your configuration files.

You should be aware of the following limitation noted in Syslog:

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

Using an external Syslog audit event handler

You can configure DS to use an external Syslog audit event handler as follows:

Create a JSON configuration file for the Syslog audit event handler in the /path/to/ds/config/audit-handlers directory. For example, your configuration file may look similar to this: { "class": "org.forgerock.audit.handlers.syslog.SyslogAuditEventHandler", "config": { "name": "External Syslog Event Handler", "enabled" : true, "topics": [ "ldap-access" ], "protocol": "UDP", "host": "syslogd.forgerock.com", "port": 514, "connectTimeout": 60, "facility": "SYSLOG", "buffering": { "enabled": false } } }
Configure DS to use the external Syslog audit handler using the dsconfig command, for example:
- DS 7.1 and later: $ ./dsconfig create-log-publisher --port 4444 --hostname ds.example.com --bindDN uid=admin --bindPassword password --publisher-name "External Syslog Publisher Access" --type external-access --set enabled:true --set config-file:/path/to/ds/config/audit-handlers/syslog-handler.json --usePkcs12TrustStore /path/to/ds/config/keystore --trustStorePassword:file /path/to/ds/config/keystore.pin --no-prompt
- DS 7: $ ./dsconfig create-log-publisher --port 4444 --hostname ds.example.com --bindDN uid=admin --bindPassword password --publisher-name "External Syslog Publisher Access" --type external-access --set enabled:true --set config-file:/path/to/ds/config/audit-handlers/syslog-handler.json --usePkcs12TrustStore /path/to/ds/config/keystore --trustStorePasswordFile /path/to/ds/config/keystore.pin --no-prompt
- DS 6.x: $ ./dsconfig create-log-publisher --port 4444 --hostname ds.example.com --bindDN "cn=Directory Manager" --bindPassword password --publisher-name "External Syslog Publisher Access" --type external-access --set enabled:true --set config-file:/path/to/ds/config/audit-handlers/syslog-handler.json --trustAll --no-prompt
Restart the DS server.

The audit logs should now be written to the /var/log/msgs directory on the remote syslogd server.

Using a local Syslog audit event handler

You can configure DS to use a local Syslog audit event handler as follows:

Create a JSON configuration file for the Syslog audit event handler in the /path/to/ds/config/audit-handlers directory. For example, your configuration file may look similar to this (observe the host is now set to localhost): { "class": "org.forgerock.audit.handlers.syslog.SyslogAuditEventHandler", "config": { "name": "Local Syslog Event Handler", "enabled" : true, "topics": [ "ldap-access" ], "protocol": "UDP", "host": "localhost", "port": 514, "connectTimeout": 60, "facility": "SYSLOG", "buffering": { "enabled": false } } }
Configure DS to use the local Syslog audit handler using the dsconfig command, for example:
- DS 7.1 and later: $ ./dsconfig create-log-publisher --port 4444 --hostname ds.example.com --bindDN uid=admin --bindPassword password --publisher-name "Local Syslog Publisher Access" --type external-access --set enabled:true --set config-file:/path/to/ds/config/audit-handlers/local-syslog-handler.json --usePkcs12TrustStore /path/to/ds/config/keystore --trustStorePassword:file /path/to/ds/config/keystore.pin --no-prompt
- DS 7: $ ./dsconfig create-log-publisher --port 4444 --hostname ds.example.com --bindDN uid=admin --bindPassword password --publisher-name "Local Syslog Publisher Access" --type external-access --set enabled:true --set config-file:/path/to/ds/config/audit-handlers/local-syslog-handler.json --usePkcs12TrustStore /path/to/ds/config/keystore --trustStorePasswordFile /path/to/ds/config/keystore.pin --no-prompt
- DS 6.x: $ ./dsconfig create-log-publisher --port 4444 --hostname ds.example.com --bindDN "cn=Directory Manager" --bindPassword password --publisher-name "Local Syslog Publisher Access" --type external-access --set enabled:true --set config-file:/path/to/ds/config/audit-handlers/local-syslog-handler.json --trustAll --no-prompt
Restart the DS server.

The audit logs should now be written to the /var/log/messages directory on the local server where DS is running.

Related Training

N/A

Related Issue Tracker IDs

N/A