Loading TOC...
Administrator's Guide (PDF)

Administrator's Guide — Chapter 11

Auditing Events

MarkLogic Server provides an auditing facility to audit various events such as document read access, server startup, server shutdown, document permission changes, and so on. These audit event records are logged to audit files stored under the MarkLogic Server data directory for each instance of MarkLogic Server. This chapter describes the auditing features and includes the following parts:

Overview of Auditing

Auditing in MarkLogic Server enables you to specify which events should generate an audit event record. You can choose from a large list of events to audit, and can restrict audit events based on various identities (user, role, or document URI). This section describes the logging capabilities of MarkLogic Server and includes the following parts:

Audit Log Files

When auditing is enabled, MarkLogic Server writes audit events to the AuditLog.txt file. Each host in a cluster maintains its own audit log files. Some actions might trigger multiple audit events, and those events might be logged over multiple hosts, as events are audited on the host in which the event occurs. For more information about the audit events, see Auditable Events. Note the following about the audit event log files:

  • Writes messages to AuditLog.txt file for various events.
  • Each event has a timestamp, event type, user, role, and other information relevant to the event (for example, document URI for document-read event). For an example of log entries, see Sample Audit Logs.
  • You can configure how often to rotate the audit files (similar to the log files, as described in Log Files).
  • The Audit log files are stored in the same directory as the Access log files (port_AccessLog.txt) and the Error log files (ErrorLog.txt), which is in the <marklogic-data-dir>/Logs directory. These files are private to the host in which the audit event occurred.
  • You may view the current or any archived file log at any time using standard text file viewing tools. Additionally, you can access the log files from the Log tab on the main page of the Admin Interface.

The following table shows the location of the AuditLog.txt files on the various platforms.

Platform Audit File
Microsoft Windows C:\Program Files\MarkLogic\Data\Logs\AuditLog.txt
Red Hat Linux /var/opt/MarkLogic/Logs/AuditLog.txt
Mac OS X ~Library/Application Support/MARKlogic/Data/Logs/AuditLog.txt

Restricting Audit Events

You can configure auditing to restrict events that are audited based on the following criteria:

  • You can select which events to audit.
  • You can include or exclude events by user name. For included users, only events initiated by the named users are audited. For excluded users, only events initiated by users other that the named users are audited.
  • You can include or exclude events by role. For included roles, only events initiated by users with the included roles are audited. For excluded roles, only events initiated by users who do not have the excluded roles are audited.
  • You can include or exclude events by outcome of event (success/failure/both).
  • You can include or exclude events by document URI. Documents URIs are audited if any fragment from that document is loaded into memory, and that audit event is written to the audit log on the host in which the forest that contains the document resides.

For the procedure to set up auditing, see Configuring Auditing to Audit Certain Events and Set Up Certain Restrictions.

Audit Successful, Unsuccessful, or Both Types of Events

You can choose to audit only unsuccessful, only successful, or both types of events. If you audit many events and/or if you audit both successful and unsuccessful events, then you may end up auditing a lot of events. It is not really a problem to audit many events, but it might make your audit logs get very large very fast. For the procedure to set up auditing, see Configuring Auditing to Audit Certain Events and Set Up Certain Restrictions.

Enabled at the Group Level

You can enable or disable auditing for each group. If auditing is enabled for a group, any configured auditable event for that group is audited. For details on the procedure to enable auditing, see Enabling Auditing for a Group.

Auditable Events

There are many auditable events in MarkLogic Server. When auditing is enabled, any enabled auditable event logs are written to the AuditLog.txt file. In a clustered environment, audit events are written to the audit file on the host in which the event occurs. Some activities might result in audit events that are distributed over multiple hosts, because events are audited on the host in which the event occurs. For example, the document access audit events are audited on the data node where the forest containing the document is hosted, therefore if a query that updates a document is run, it could cause (depending on the audit configuration and the cluster configuration) audit events to occur on the node in which the query is evaluated (the evaluation-node) and on one or more data-nodes where the affected documents are hosted.

The following table lists the auditable events you can enable in MarkLogic Server.

Event Description URI Restrictions Role/User Restrictions Success or Failure Restrictions
amp-usage Audits the URI of an amp when it is evaluated. Yes, based on the URI of the amp Yes Success Only
audit-configuration-change Audits the success or failure of a change to a auditing configuration. N/A Yes Yes
audit-shutdown Audits when the audit system is disabled. N/A Yes Yes
audit-startup Audits when the audit system is enabled. Note that this event does not occur when MarkLogic Server starts up, only when the audit system is enabled. N/A Yes Yes
authentication-failure Audits failed authentication attempts. N/A Yes Failure Only
concurrent-request-denial Audits when a request is denied because the concurrent request limit on the App Server was reached. N/A Yes Failure Only
configuration-change Audits the success or failure of a change to a configuration file, including the path to the configuration file that changed. N/A Yes Yes
document-execute Audits when a document in a database is executed (for example, an XQuery document), and includes the document URI in the audit record. Yes Yes Success Only
document-insert Audits when a new document is created, and includes the document URI in the audit record. Yes Yes Success Only
document-read Audits when a document is read, and includes the document URI in the audit record. Yes Yes Success Only
document-update Audits when a document is updated, and includes the document URI in the audit record. Yes Yes Success Only
document-wipe Audits when a temporal document is wiped (all versions deleted), and includes the document URI in the audit record. Yes Yes Success Only
estimate Audits when an xdmp:estimate expression is evaluated. N/A Yes Success Only
eval Audits when a path expression that accesses the database is evaluated. N/A Yes Success Only
external-authentication-failure Audits when an external authorization attempt fails. N/A Yes Success Only
exists Audits when an xdmp:exists expression is evaluated. N/A Yes Success Only
FIPS-Disabled Audits when FIPS mode is disabled. N/A N/A Success Only
FIPS-Enabled Audits when FIPS mode is enabled. N/A N/A Success Only
lexicon-read Audits when a value lexicon (for example, cts:element-values) call is used. N/A Yes Success Only
mlcp-copy-export-start Audits when an mlcp copy or export job is about to start N/A N/A Success Only
mlcp-copy-export-finish Audits when an mlcp copy or export job has completed, successfully or not. N/A N/A No
no-permission Audits when an operation fails because of a SEC-PERMDENIED exception, which happens when an operation on a document (insert, update, or execute) is attempted without the needed permissions. Yes Yes Failure Only
no-privilege Audits when a user has insufficient privileges to perform a particular function. Yes Yes Failure Only
optic Audits when an optic call completes. N/A Yes Success Only
permissions-change Audits when permissions on a document are modified. Yes Yes Yes
request-blackout-denial Audits when a request is denied due to a request blackout period. N/A Yes Failure Only (when denied)
role-change-failure Audits when an attempt to add or remove a role from a user fails. N/A Yes Failure Only
search Audits when a cts:search expression is evaluated. N/A Yes Success Only
security-access Audits when one of the following security-related functions are called: xdmp:can-grant-roles, xdmp:has-privilege, xdmp:user-roles, xdmp:role-roles, xdmp:privilege-roles, xdmp:amp-roles, xdmp:get-current-role, xdmp:user, xdmp:role, xdmp:amp. N/A Yes Yes
server-restart Audits when MarkLogic Server is restarted with a clean restart (for example, from the Admin Interface). N/A Yes Success Only
server-shutdown Audits when MarkLogic Server is shut down with a clean shutdown (for example, from the shutdown scripts or from the Admin Interface). N/A Yes Success Only
server-startup Audits when MarkLogic Server starts up. N/A N/A Success Only
SPARQL Audits when a SPARQL call completes. N/A Yes Success Only
SQL Audits when a SQL call completes. N/A Yes Success Only
TLS-Failure Audits when a TLS or SSL request fails, and includes the IP address. N/A N/A Failure Only
user-configuration-change Audits when anything in a user configuration changes. N/A Yes Yes
user-role-addition Audits when a role is added to a user. N/A Yes Yes
user-role-removal Audits when a role is removed from a user. N/A Yes Yes
HTTP-client-authentication-failure Audits failed HTTP client authentication attempts. N/A Yes Failure Only
LDAP-client-authentication-failure Audits failed LDAP client authentication attempts. N/A Yes Failure Only
SMTP-client-authentication-failure Audits failed SMTP client authentication attempts. N/A Yes Failure Only

Audit Log Content

The information included in an audit log depends on the type of event. All audit log entries include basic information such as the event type, user, success, and roles assigned to the user. Audit log entries may include the following space-separated fields:

Log Entry Field Description Example
Timestamp Contains the date and time the auditable action occurred. 2012-03-26 10:55:53.735
Event The name of the event that triggered the log entry. The possible auditable events are listed in Auditable Events. event=amp-usage
Function The function that was being executed during the event. function=http://marklogic.com/xdmp/admin:read-config-file
Expression The query expression that triggered this audit event. expr=cts:element-value-query(xs:QName("info:status"), ("active", "unloading"), ("unstemmed","lang=en"), 1)
Type The type of task inside the MarkLogic server that generated the specific event. type=node-update
URI The document URI involved in the event. uri=/queries/5523898374388210414.txt
Database The database that was accessed during the event. database=Security
Outcome This indicates the success or failure of the action that triggered the audit event. success=true
User The user that performed the action. user=infostudio-admin
Roles The roles assigned to the user performing the action. roles=cpf-restart,infostudio-user

Sample Audit Logs

Here are some sample AuditLog.txt entries with user-specific information obfuscated.

2018-12-05 02:23:15.302 event=SMTP-client-authentication-failure; user=daemon; host=smtp.marklogic.com; success=false;
2018-12-05 02:42:11.515 event=HTTP-client-authentication-failure; user=xyz; type=digest; url=http://localhost:2975/qstring.sjs?sname=http-auth-digestbasic-modules-db; success=false;
2018-12-05 02:41:50.036 event=LDAP-client-authentication-failure; url=ldap://dc1.mltest1.local:389; success=false;

Configuring Auditing for a Group

Auditing is configured at the group level using the Auditing page of the Admin Interface. For details on groups, see Groups. This section describes the following audit configuration procedures:

Enabling Auditing for a Group

Perform the following steps to enable auditing for a group:

  1. Access the Admin Interface with a browser.
  2. Open the Audit Configuration screen (Groups > group_name > Auditing).
  3. Select True for the Audit Enabled radio button.
  4. Configure any audit events and/or audit restrictions you want.
  5. Click OK.

Disabling Auditing for a Group

Perform the following steps to disable auditing for a group:

  1. Access the Admin Interface with a browser.
  2. Open the Audit Configuration screen (Groups > group_name > Auditing).
  3. Select False for the Audit Enabled radio button.
  4. Click OK.

This will immediately disable auditing for the group. Any settings you had configured will remain, but will not be in effect until you enable auditing again.

Configuring Auditing to Audit Certain Events and Set Up Certain Restrictions

The following is the general procedure for configuring audit events and audit restrictions. Your procedure will vary depending on what events and restrictions you choose to configure.

  1. Access the Admin Interface with a browser.
  2. Open the Audit Configuration screen (Groups > group_name > Auditing).
  3. Under Audit Events, choose the events you want audited. For a description of each event, see Auditable Events.
  4. Under Audit Restrictions, enter any restrictions you want. For details on audit restrictions, see Restricting Audit Events.
  5. Click OK to save your changes.
« Previous chapter
Next chapter »