Log LDAP Access to Files
The primary JSON-based LDAP access log file is logs/ldap-access.audit.json. Primary access log files include messages for each LDAP operation. They can grow quickly, but are particularly useful for analyzing overall client behavior:
Decide whether to trust transaction IDs sent by client applications, used to correlate requests as they traverse multiple servers.
Client applications using the ForgeRock Common Audit event framework send transaction IDs with their requests. The transaction IDs correlate audit events, tracing the request through multiple applications.
Transaction IDs are sent over LDAP using an internal DS request control. They are sent over HTTP in an HTTP header.
By default, DS servers do not trust transaction IDs sent with client application requests.
When a server trusts transaction IDs from client application requests, outgoing requests reuse the incoming ID. For each outgoing request in the transaction, the request's transaction ID has the form
original-transaction-id/sequence-number, where sequence-number reflects the position of the request in the series of requests for this transaction. For example, if the original-transaction-id isabc123, the first outgoing request has the transaction IDabc123/0, the secondabc123/1, the thirdabc123/2, and so on. This lets you distinguish specific requests within a transaction when correlating audit events from multiple services.To trust transactions, set the advanced global server property,
trust-transaction-ids:true:$
dsconfig \ set-global-configuration-prop \ --advanced \ --hostname localhost \ --port 4444 \ --bindDN uid=admin \ --bindPassword password \ --set trust-transaction-ids:true \ --usePkcs12TrustStore /path/to/opendj/config/keystore \ --trustStorePasswordFile /path/to/opendj/config/keystore.pin \ --no-promptEdit the default access log publisher as necessary.
The following example applies the default settings:
$
dsconfig \ set-log-publisher-prop \ --hostname localhost \ --port 4444 \ --bindDN uid=admin \ --bindPassword password \ --publisher-name "Json File-Based Access Logger" \ --set enabled:true \ --add "rotation-policy:24 Hours Time Limit Rotation Policy" \ --add "rotation-policy:Size Limit Rotation Policy" \ --set "retention-policy:File Count Retention Policy" \ --usePkcs12TrustStore /path/to/opendj/config/keystore \ --trustStorePasswordFile /path/to/opendj/config/keystore.pin \ --no-prompt
DS servers write messages to a filtered access log file, logs/filtered-ldap-access.audit.json. This log grows more slowly than the primary access log. It includes only messages about the following:
Administrative requests related to backing up and restoring data, scheduling tasks, and reading and writing configuration settings
Authentication failures
Requests from client applications that are misbehaving
Requests that take longer than one second for the server to process
Search requests that return more than 1000 entries
Unindexed searches
Follow these steps to change the configuration:
Edit the filtered access log publisher as necessary.
The following example updates the configuration to include control OIDs in log records:
$
dsconfig \ set-log-publisher-prop \ --hostname localhost \ --port 4444 \ --bindDN uid=admin \ --bindPassword password \ --publisher-name "Filtered Json File-Based Access Logger" \ --set log-control-oids:true \ --usePkcs12TrustStore /path/to/opendj/config/keystore \ --trustStorePasswordFile /path/to/opendj/config/keystore.pin \ --no-prompt(Optional) Edit the filtering criteria as necessary.
The following commands list the relevant default filtering criteria settings for the filtered access log:
$
dsconfig \ get-access-log-filtering-criteria-prop \ --hostname localhost \ --port 4444 \ --bindDN uid=admin \ --bindPassword password \ --publisher-name "Filtered Json File-Based Access Logger" \ --criteria-name "Administrative Requests" \ --usePkcs12TrustStore /path/to/opendj/config/keystore \ --trustStorePasswordFile /path/to/opendj/config/keystore.pin \ --no-promptlog-record-type : add, bind, compare, delete, extended, : modify, rename, search request-target-dn-equal-to : "**,cn=config", "**,cn=tasks", : cn=config, cn=tasks$dsconfig \ get-access-log-filtering-criteria-prop \ --hostname localhost \ --port 4444 \ --bindDN uid=admin \ --bindPassword password \ --publisher-name "Filtered Json File-Based Access Logger" \ --criteria-name "Auth Failures" \ --usePkcs12TrustStore /path/to/opendj/config/keystore \ --trustStorePasswordFile /path/to/opendj/config/keystore.pin \ --no-promptlog-record-type : add, bind, compare, delete, extended, : modify, rename, search response-result-code-equal-to : 7, 8, 13, 48, 49, 50, 123$dsconfig \ get-access-log-filtering-criteria-prop \ --hostname localhost \ --port 4444 \ --bindDN uid=admin \ --bindPassword password \ --publisher-name "Filtered Json File-Based Access Logger" \ --criteria-name "Long Requests" \ --usePkcs12TrustStore /path/to/opendj/config/keystore \ --trustStorePasswordFile /path/to/opendj/config/keystore.pin \ --no-promptlog-record-type : add, bind, compare, delete, extended, : modify, rename, search response-etime-greater-than : 1000$dsconfig \ get-access-log-filtering-criteria-prop \ --hostname localhost \ --port 4444 \ --bindDN uid=admin \ --bindPassword password \ --publisher-name "Filtered Json File-Based Access Logger" \ --criteria-name "Misbehaving Clients" \ --usePkcs12TrustStore /path/to/opendj/config/keystore \ --trustStorePasswordFile /path/to/opendj/config/keystore.pin \ --no-promptlog-record-type : add, bind, compare, delete, extended, : modify, rename, search response-result-code-equal-to : 1, 2, 17, 18, 19, 21, 34, 60, 61, 64, : 65, 66, 67, 69$dsconfig \ get-access-log-filtering-criteria-prop \ --hostname localhost \ --port 4444 \ --bindDN uid=admin \ --bindPassword password \ --publisher-name "Filtered Json File-Based Access Logger" \ --criteria-name "Searches Returning 1000+ Entries" \ --usePkcs12TrustStore /path/to/opendj/config/keystore \ --trustStorePasswordFile /path/to/opendj/config/keystore.pin \ --no-promptlog-record-type : search search-response-nentries-greater-than : 1000$dsconfig \ get-access-log-filtering-criteria-prop \ --hostname localhost \ --port 4444 \ --bindDN uid=admin \ --bindPassword password \ --publisher-name "Filtered Json File-Based Access Logger" \ --criteria-name "Unindexed Searches" \ --usePkcs12TrustStore /path/to/opendj/config/keystore \ --trustStorePasswordFile /path/to/opendj/config/keystore.pin \ --no-promptlog-record-type : search search-response-is-indexed : falseFor details about the LDAP result codes listed in the criteria, see LDAP Result Codes.
For details about how filtering works, see "Access Log Filtering".
A CSV handler sends messages to a comma-separated variable (CSV) file.
Important
The CSV handler does not sanitize messages when writing to CSV log files.
Do not open CSV logs in spreadsheets and other applications that treat data as code.
The default CSV LDAP access log file is logs/ldap-access.csv:
Decide whether to trust transaction IDs sent by client applications, used to correlate requests as they traverse multiple servers.
Client applications using the ForgeRock Common Audit event framework send transaction IDs with their requests. The transaction IDs correlate audit events, tracing the request through multiple applications.
Transaction IDs are sent over LDAP using an internal DS request control. They are sent over HTTP in an HTTP header.
By default, DS servers do not trust transaction IDs sent with client application requests.
When a server trusts transaction IDs from client application requests, outgoing requests reuse the incoming ID. For each outgoing request in the transaction, the request's transaction ID has the form
original-transaction-id/sequence-number, where sequence-number reflects the position of the request in the series of requests for this transaction. For example, if the original-transaction-id isabc123, the first outgoing request has the transaction IDabc123/0, the secondabc123/1, the thirdabc123/2, and so on. This lets you distinguish specific requests within a transaction when correlating audit events from multiple services.To trust transactions, set the advanced global server property,
trust-transaction-ids:true:$
dsconfig \ set-global-configuration-prop \ --advanced \ --hostname localhost \ --port 4444 \ --bindDN uid=admin \ --bindPassword password \ --set trust-transaction-ids:true \ --usePkcs12TrustStore /path/to/opendj/config/keystore \ --trustStorePasswordFile /path/to/opendj/config/keystore.pin \ --no-promptCreate an enabled CSV file access logger with optional rotation and retention policies:
$
dsconfig \ create-log-publisher \ --hostname localhost \ --port 4444 \ --bindDN uid=admin \ --bindPassword password \ --publisher-name "Common Audit Csv File Access Logger" \ --type csv-file-access \ --set enabled:true \ --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 \ --trustStorePasswordFile /path/to/opendj/config/keystore.pin \ --no-prompt(Optional) For tamper-evident logs, follow these steps.
Important
Tamper-evident logging relies on digital signatures and regularly flushing messages to the log system. In high-volume directory deployments with heavy access patterns, signing log messages has a severe negative impact on server performance, reducing throughput by orders of magnitude.
Be certain to test the performance impact with realistic access patterns for your deployment before enabling the feature in production.
Prepare a keystore.
For details, see "Make Tampering Evident".
Enable the tamper-evident capability:
$
dsconfig \ set-log-publisher-prop \ --hostname localhost \ --port 4444 \ --bindDN uid=admin \ --bindPassword password \ --publisher-name "Common Audit Csv File Access Logger" \ --set tamper-evident:true \ --set key-store-file:config/audit-keystore \ --set key-store-pin:"&{audit.keystore.pin}" \ --usePkcs12TrustStore /path/to/opendj/config/keystore \ --trustStorePasswordFile /path/to/opendj/config/keystore.pin \ --no-promptIn this example,
AUDIT_KEYSTORE_PINis an environment variable containing the PIN.
This access log format was the default for older DS servers. Use this log format if you already have software configured to consume that format. The default log file is logs/access:
Enable the LDAP access logger:
$
dsconfig \ set-log-publisher-prop \ --hostname localhost \ --port 4444 \ --bindDN uid=admin \ --bindPassword password \ --publisher-name "File-Based Access Logger" \ --set enabled:true \ --usePkcs12TrustStore /path/to/opendj/config/keystore \ --trustStorePasswordFile /path/to/opendj/config/keystore.pin \ --no-promptBy default, this access log contains a message for each request, and a message for each response. It also includes messages for connection and disconnection.
Write messages only on responses by setting the
log-format:combinedproperty. The setting is useful when filtering messages based on response criteria. It causes the server to log one message per operation, rather than one for each request and response.