Log LDAP access to files
JSON format
When you install DS using procedures from Installation,
the primary JSON-based LDAP access log file is logs/ldap-access.audit.json.
The name of the access log publisher in the configuration is Json File-Based Access Logger.
The sample DS Docker image logs to standard output instead of files.
This makes it easy to read log messages with the docker logs command,
and is a pattern you should follow when creating your own DS Docker images.
The name of the LDAP access log publisher configuration in the sample image is Console LDAP Access Logger.
Primary access logs 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 \ --trustStorePassword:file /path/to/opendj/config/keystore.pin \ --no-prompt -
Edit the default access log publisher as necessary.
The following example applies the default settings for DS installed locally, not in a Docker image:
$ 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 \ --trustStorePassword:file /path/to/opendj/config/keystore.pin \ --no-prompt
Filtered JSON format
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 \ --trustStorePassword:file /path/to/opendj/config/keystore.pin \ --no-prompt -
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 \ --trustStorePassword:file /path/to/opendj/config/keystore.pin \ --no-prompt log-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 \ --trustStorePassword:file /path/to/opendj/config/keystore.pin \ --no-prompt log-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 \ --trustStorePassword:file /path/to/opendj/config/keystore.pin \ --no-prompt log-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 \ --trustStorePassword:file /path/to/opendj/config/keystore.pin \ --no-prompt log-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 \ --trustStorePassword:file /path/to/opendj/config/keystore.pin \ --no-prompt log-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 \ --trustStorePassword:file /path/to/opendj/config/keystore.pin \ --no-prompt log-record-type : search search-response-is-indexed : falseFor details about the LDAP result codes listed in the criteria, refer to LDAP result codes.
For details about how filtering works, refer to Access log filtering.
CSV format
A CSV handler sends messages to a comma-separated variable (CSV) file.
|
The interface stability of this feature is Deprecated. 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 \ --trustStorePassword:file /path/to/opendj/config/keystore.pin \ --no-prompt -
Create 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 \ --trustStorePassword:file /path/to/opendj/config/keystore.pin \ --no-prompt -
For tamper-evident logs, follow these steps.
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, refer to 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 \ --trustStorePassword:file /path/to/opendj/config/keystore.pin \ --no-promptIn this example,
AUDIT_KEYSTORE_PINis an environment variable containing the PIN.
-
Backwards-compatible format
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 \ --trustStorePassword:file /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.