Manage logs
Rotate and retain logs
Each file-based log has a rotation policy, and a retention policy.
The rotation policy specifies when to rotate a log file based on a time, log file age, or log file size. Rotated logs have a rotation timestamp appended to their name.
The retention policy specifies whether to retain logs based on the number of logs, their size, or how much free space should be left on the disk.
-
List log rotation policies:
$ dsconfig \ list-log-rotation-policies \ --hostname localhost \ --port 4444 \ --bindDN uid=admin \ --bindPassword password \ --usePkcs12TrustStore /path/to/opendj/config/keystore \ --trustStorePassword:file /path/to/opendj/config/keystore.pin \ --no-prompt Log Rotation Policy : Type : file-size-limit : rotation-interval : time-of-day ------------------------------------:------------:-----------------:-------------------:------------ 24 Hours Time Limit Rotation Policy : time-limit : - : 1 d : - 7 Days Time Limit Rotation Policy : time-limit : - : 1 w : - Fixed Time Rotation Policy : fixed-time : - : - : 2359 Size Limit Rotation Policy : size-limit : 100 mb : - : -
bash -
List log retention policies:
$ dsconfig \ list-log-retention-policies \ --hostname localhost \ --port 4444 \ --bindDN uid=admin \ --bindPassword password \ --usePkcs12TrustStore /path/to/opendj/config/keystore \ --trustStorePassword:file /path/to/opendj/config/keystore.pin \ --no-prompt Log Retention Policy : Type : disk-space-used : free-disk-space : number-of-files ---------------------------------:-----------------:-----------------:-----------------:---------------- File Count Retention Policy : file-count : - : - : 10 Free Disk Space Retention Policy : free-disk-space : - : 500 mb : - Size Limit Retention Policy : size-limit : 500 mb : - : -
bash -
View the policies that apply to a given log with the
dsconfig get-log-publisher-prop
command.The following example shows that the server keeps 10 access log files, rotating either each day or when the log size reaches 100 MB:
$ dsconfig \ get-log-publisher-prop \ --hostname localhost \ --port 4444 \ --bindDN uid=admin \ --bindPassword password \ --publisher-name "Json File-Based Access Logger" \ --property retention-policy \ --property rotation-policy \ --usePkcs12TrustStore /path/to/opendj/config/keystore \ --trustStorePassword:file /path/to/opendj/config/keystore.pin \ --no-prompt Property : Value(s) -----------------:------------------------------------------------------------- retention-policy : File Count Retention Policy rotation-policy : 24 Hours Time Limit Rotation Policy, Size Limit Rotation : Policy
bash -
Use the
dsconfig
command to create, update, delete, and assign log rotation and retention policies. Set the policy that applies to a logger with thedsconfig set-log-publisher-prop
command.
When using access logs based on the ForgeRock Common Audit event framework, you can only configure one of each type of retention or rotation policy. This means you can configure only one file count, free disk space, and size limit log retention policy. You can configure only one fixed time, size limit, and time limit log rotation policy. |
Enable an audit log
-
Enable a file-based audit logger:
$ dsconfig \ set-log-publisher-prop \ --hostname localhost \ --port 4444 \ --bindDN uid=admin \ --bindPassword password \ --publisher-name "File-Based Audit Logger" \ --set enabled:true \ --usePkcs12TrustStore /path/to/opendj/config/keystore \ --trustStorePassword:file /path/to/opendj/config/keystore.pin \ --no-prompt
bash -
Wait for, or make a change to directory data.
The following example changes a description:
$ ldapmodify \ --hostname localhost \ --port 1636 \ --useSsl \ --usePkcs12TrustStore /path/to/opendj/config/keystore \ --trustStorePassword:file /path/to/opendj/config/keystore.pin \ --bindDN "uid=bjensen,ou=People,dc=example,dc=com" \ --bindPassword hifalutin << EOF dn: uid=bjensen,ou=People,dc=example,dc=com changetype: modify replace: description description: New description EOF
bashThe audit log records the changes as shown in the following excerpt:
# <datestamp>; conn=<number>; op=<number> dn: cn=File-Based Audit Logger,cn=Loggers,cn=config changetype: modify replace: ds-cfg-enabled ds-cfg-enabled: true - # <datestamp>; conn=<number>; op=<number> dn: uid=bjensen,ou=people,dc=example,dc=com changetype: modify add: description description: New description -
bashAudit logs record changes in LDIF format. This means that when an LDAP entry is deleted, the audit log records only its DN.
Filter out administrative messages
A common development troubleshooting technique consists of sending client requests while tailing the access log:
$ tail -f /path/to/opendj/logs/ldap-access.audit.json
When the dsconfig
command accesses the configuration, the access log records this.
Such messages can prevent you from seeing the messages of interest from client applications.
You can filter access log messages for administrative connections to the administration port:
-
Configure access log filtering criteria:
$ dsconfig \ create-access-log-filtering-criteria \ --hostname localhost \ --port 4444 \ --bindDN uid=admin \ --bindPassword password \ --publisher-name "Json File-Based Access Logger" \ --criteria-name "Exclude LDAPS on 4444" \ --type generic \ --set connection-port-equal-to:4444 \ --set connection-protocol-equal-to:ldaps \ --usePkcs12TrustStore /path/to/opendj/config/keystore \ --trustStorePassword:file /path/to/opendj/config/keystore.pin \ --no-prompt
bash -
Activate filtering to exclude administrative messages:
$ dsconfig \ set-log-publisher-prop \ --hostname localhost \ --port 4444 \ --bindDN uid=admin \ --bindPassword password \ --publisher-name "Json File-Based Access Logger" \ --set filtering-policy:exclusive \ --usePkcs12TrustStore /path/to/opendj/config/keystore \ --trustStorePassword:file /path/to/opendj/config/keystore.pin \ --no-prompt
bashThe publisher filters messages about administrative requests to the administration port.
Audit configuration changes
This example demonstrates how to set up an audit log file to track changes to the server configuration.
Audit log change records have timestamped comments with connection and operation IDs. You can use these to correlate the changes with messages in access logs:
-
Create an audit log publisher:
$ dsconfig \ create-log-publisher \ --hostname localhost \ --port 4444 \ --bindDN uid=admin \ --bindPassword password \ --publisher-name "File-Based Server Configuration Audit Log" \ --type file-based-audit \ --set enabled:true \ --set filtering-policy:inclusive \ --set log-file:logs/config-audit \ --set rotation-policy:"24 Hours Time Limit Rotation Policy" \ --set rotation-policy:"Size Limit Rotation Policy" \ --set retention-policy:"File Count Retention Policy" \ --usePkcs12TrustStore /path/to/opendj/config/keystore \ --trustStorePassword:file /path/to/opendj/config/keystore.pin \ --no-prompt
bash -
Create log filtering criteria for the logger that matches operations targeting
cn=config
:$ dsconfig \ create-access-log-filtering-criteria \ --hostname localhost \ --port 4444 \ --bindDN uid=admin \ --bindPassword password \ --publisher-name "File-Based Server Configuration Audit Log" \ --criteria-name "Record changes to cn=config" \ --set request-target-dn-equal-to:"**,cn=config" \ --set request-target-dn-equal-to:"cn=config" \ --usePkcs12TrustStore /path/to/opendj/config/keystore \ --trustStorePassword:file /path/to/opendj/config/keystore.pin \ --no-prompt
bashThe server now writes to the audit log file,
/path/to/opendj/logs/config-audit
, whenever an administrator changes the server configuration. The following example output shows the resulting LDIF that defines the log filtering criteria:# <datestamp>; conn=<id>; op=<id> dn: cn=Record changes to cn=config,cn=Filtering Criteria,cn=File-Based Server Configuration Audit Log,cn=Loggers,cn=config changetype: add objectClass: top objectClass: ds-cfg-access-log-filtering-criteria cn: Record changes to cn=config ds-cfg-request-target-dn-equal-to: **,cn=config ds-cfg-request-target-dn-equal-to: cn=config createTimestamp: <timestamp> creatorsName: uid=admin entryUUID: <uuid>
ldif
Allow log message fields
-
When an object is passed in a Common Audit event, it might contain information that should not be logged. By default, the Common Audit implementation uses a whitelist to specify which fields of the event appear:
-
For Common Audit HTTP access log publishers, edit the
log-field-whitelist
property.The following fields appear by default, with each field listed by its JSON path. You cannot change the default whitelist.
If a whitelisted field contains an object, then listing the field means the whole object is whitelisted:
-
/_id
-
/timestamp
-
/eventName
-
/transactionId
-
/trackingIds
-
/userId
-
/client
-
/server
-
/http/request/secure
-
/http/request/method
-
/http/request/path
-
/http/request/headers/accept
-
/http/request/headers/accept-api-version
-
/http/request/headers/content-type
-
/http/request/headers/host
-
/http/request/headers/user-agent
-
/http/request/headers/x-forwarded-for
-
/http/request/headers/x-forwarded-host
-
/http/request/headers/x-forwarded-port
-
/http/request/headers/x-forwarded-proto
-
/http/request/headers/x-original-uri
-
/http/request/headers/x-real-ip
-
/http/request/headers/x-request-id
-
/http/request/headers/x-requested-with
-
/http/request/headers/x-scheme
-
/request
-
/response
-
For CSV logs, the values map to the column headers. The terms are separated by dots (
.
) rather than by slashes (/
).-
LDAP access loggers do not support whitelisting.
By default, all fields are whitelisted.
-
Deny log message fields
When an object is passed in a Common Audit event, it might contain information that should not be logged. Loggers allow all fields that are safe to log by default. The whitelist is processed before the blacklist, so blacklist settings overwrite the whitelist defaults:
-
Blacklist individual fields in common audit access logs to prevent the fields from appearing in messages.
The following example prevents all request headers from appearing in JSON HTTP access logs:
$ dsconfig \ set-log-publisher-prop \ --hostname localhost \ --port 4444 \ --bindDN uid=admin \ --bindPassword password \ --publisher-name "Json File-Based HTTP Access Logger" \ --set log-field-blacklist:/http/response/headers \ --usePkcs12TrustStore /path/to/opendj/config/keystore \ --trustStorePassword:file /path/to/opendj/config/keystore.pin \ --no-prompt
bashThe blacklist values are JSON paths to the fields in log messages.
For CSV logs, the blacklist values map to the column headers. The terms are separated by dots (
.
) rather than by slashes (/
).