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.

PlatformAudit 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.

EventDescriptionURI RestrictionsRole/User RestrictionsSuccess or Failure Restrictions
amp-usage
Audits the URI of an amp when it is evaluated.Yes, based on the URI of the ampYesSuccess Only
audit-configuration-change
Audits the success or failure of a change to a auditing configuration. N/AYesYes
audit-shutdown
Audits when the audit system is disabled.N/AYesYes
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/AYesYes
authentication-failure
Audits failed authentication attempts.N/AYesFailure Only
concurrent-request-denial
Audits when a request is denied because the concurrent request limit on the App Server was reached.N/AYesFailure 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/AYesYes
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.YesYesSuccess Only
document-insert
Audits when a new document is created, and includes the document URI in the audit record.YesYesSuccess Only
document-read
Audits when a document is read, and includes the document URI in the audit record.YesYesSuccess Only
document-update
Audits when a document is updated, and includes the document URI in the audit record.YesYesSuccess Only
estimate
Audits when an xdmp:estimate expression is evaluated.N/AYesSuccess Only
eval
Audits when a path expression that accesses the database is evaluated.N/AYesSuccess Only
exists
Audits when an xdmp:exists expression is evaluated.N/AYesSuccess Only
FIPS-Disabled
Audits when FIPS mode is disabled.N/AN/ASuccess Only
FIPS-Enabled
Audits when FIPS mode is enabled.N/AN/ASuccess Only
lexicon-read
Audits when a value lexicon (for example, cts:element-values) call is used. N/AYesSuccess Only
mlcp-copy-export-start
Audits when an mlcp copy or export job is about to startN/AN/ASuccess Only
mlcp-copy-export-finish
Audits when an mlcp copy or export job has completed, successfully or not.N/AN/ANo
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. YesYesFailure Only
no-privilege
Audits when a user has insufficient privileges to perform a particular function.YesYesFailure Only
permissions-change
Audits when permissions on a document are modified.YesYesYes
request-blackout-denial
Audits when a request is denied due to a request blackout period.N/AYesFailure Only (when denied)
role-change-failure
Audits when an attempt to add or remove a role from a user fails.N/AYesFailure Only
search
Audits when a cts:search expression is evaluated.N/AYesSuccess 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/AYesYes
server-restart
Audits when MarkLogic Server is restarted with a clean restart (for example, from the Admin Interface).N/AYesSuccess 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/AYesSuccess Only
server-startup
Audits when MarkLogic Server starts up.N/AN/ASuccess Only
TLS-Failure
Audits when a TLS or SSL request fails, and includes the IP address.N/AN/AFailure Only
user-configuration-change
Audits when anything in a user configuration changes.N/AYesYes
user-role-addition
Audits when a role is added to a user.N/AYesYes
user-role-removal
Audits when a role is removed from a user.N/AYesYes

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 FieldDescriptionExample
TimestampContains the date and time the auditable action occurred.2012-03-26 10:55:53.735
EventThe name of the event that triggered the log entry. The possible auditable events are listed in Auditable Events.event=amp-usage
FunctionThe function that was being executed during the event.function=http://marklogic.com/xdmp/admin:read-config-file
ExpressionThe query expression that triggered this audit event.expr=cts:element-value-query(xs:QName("info:status"), ("active", "unloading"), ("unstemmed","lang=en"), 1)
TypeThe type of task inside the MarkLogic server that generated the specific event. type=node-update
URIThe document URI involved in the event.uri=/queries/5523898374388210414.txt
DatabaseThe database that was accessed during the event.database=Security
OutcomeThis indicates the success or failure of the action that triggered the audit event.success=true
UserThe user that performed the action.user=infostudio-admin
RolesThe 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 obsfucated.

2012-03-26 10:55:53.735 event=amp-usage; 
function=http://marklogic.com/xdmp/admin:read-config-file;
uri=/MarkLogic/admin.xqy; database=filesystem;
success=true; user=admin; roles=admin;

2012-03-23 15:04:32.141 event=security-access; user(admin-xxx); success=true; 
user=admin-xxx; roles=admin;

2012-03-23 15:04:32.176 event=document-read;
uri=http://marklogic.com/xdmp/privileges/7768816571421711260;
database=Security; success=true; user=admin-xxx; roles=admin;

2012-03-23 15:05:26.957 event=lexicon-read;
expr=cts:element-value-query(xs:QName("info:status"),
("active", "unloading"), ("unstemmed","lang=en"), 1);
database=App-Services; success=true; user=infostudio-admin;
roles=cpf-restart,infostudio-user;

2012-03-23 15:07:05.164 event=document-update; type=node-update;
uri=/workspaces/14061174091930893017.xml; database=App-Services;
success=true; user=admin-xxx; roles=admin;

2012-03-23 15:07:05.674 event=document-insert; type=insert;
uri=/queries/5523898374388210414.txt; database=App-Services;
success=true; user=admin-xxx; roles=admin;

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 »
Powered by MarkLogic Server 7.0-4.1 and rundmc | Terms of Use | Privacy Policy