OPTIONS

Configure System Events Auditing

New in version 2.6.

MongoDB Enterprise supports auditing of various operations. A complete auditing solution must involve all mongod server and mongos router processes.

The audit facility can write audit events to the console, the syslog (option is unavailable on Windows), a JSON file, or a BSON file. For details on the audited operations and the audit log messages, see System Event Audit Messages.

Enable and Configure Audit Output

Use the --auditDestination option to enable auditing and specify where to output the audit events.

Output to Syslog

To enable auditing and print audit events to the syslog (option is unavailable on Windows) in JSON format, specify syslog for the --auditDestination setting. For example:

mongod --dbpath data/db --auditDestination syslog

Warning

The syslog message limit can result in the truncation of the audit messages. The auditing system will neither detect the truncation nor error upon its occurrence.

You may also specify these options in the configuration file:

dbpath=data/db
auditDestination=syslog

Output to Console

To enable auditing and print the audit events to standard output (i.e. stdout), specify console for the --auditDestination setting. For example:

mongod --dbpath data/db --auditDestination console

You may also specify these options in the configuration file:

dbpath=data/db
auditDestination=console

Output to JSON File

To enable auditing and print audit events to a file in JSON format, specify file for the --auditDestination setting, JSON for the --auditFormat setting, and the output filename for the --auditPath. The --auditPath option accepts either full path name or relative path name. For example, the following enables auditing and records audit events to a file with the relative path name of data/db/auditLog.json:

mongod --dbpath data/db --auditDestination file --auditFormat JSON --auditPath data/db/auditLog.json

The audit file rotates at the same time as the server log file.

You may also specify these options in the configuration file:

dbpath=data/db
auditDestination=file
auditFormat=JSON
auditPath=data/db/auditLog.json

Note

Printing audit events to a file in JSON format degrades server performance more than printing to a file in BSON format.

Output to BSON File

To enable auditing and print audit events to a file in BSON binary format, specify file for the --auditDestination setting, BSON for the --auditFormat setting, and the output filename for the --auditPath. The --auditPath option accepts either full path name or relative path name. For example, the following enables auditing and records audit events to a BSON file with the relative path name of data/db/auditLog.bson:

mongod --dbpath data/db --auditDestination file --auditFormat BSON --auditPath data/db/auditLog.bson

The audit file rotates at the same time as the server log file.

You may also specify these options in the configuration file:

dbpath=data/db
auditDestination=file
auditFormat=BSON
auditPath=data/db/auditLog.bson

To view the contents of the file, pass the file to the MongoDB utility bsondump. For example, the following converts the audit log into a human-readable form and output to the terminal:

bsondump data/db/auditLog.bson

Filter Events

By default, the audit facility records all auditable operations. The audit feature has an --auditFilter option to determine which events to record. The --auditFilter option takes a document of the form:

{ atype: <expression> }

The <expression> is a query condition expression to match on various actions .

Filter for a Single Operation Type

For example, to audit only the createCollection action, use the filter { atype: "createCollection" }:

Tip

To specify the filter as a command-line option, enclose the filter document in single quotes to pass the document as a string.

mongod --dbpath data/db --auditDestination file --auditFilter '{ atype: "createCollection" }' --auditFormat JSON --auditPath data/db/auditLog.json

Filter for Multiple Operation Types

To match on multiple operations, use the $in operator in the <expression> as in the following:

Tip

To specify the filter as a command-line option, enclose the filter document in single quotes to pass the document as a string.

mongod --dbpath data/db --auditDestination file --auditFilter '{ atype: { $in: [ "createCollection", "dropCollection" ] } }' --auditFormat JSON --auditPath data/db/auditLog.json

Filter on Authentication Operations on a Single Database

For authentication operations, you can also specify a specific database with the param.db field:

{ atype: <expression>, "param.db": <database> }

For example, to audit only authenticate operations that occur against the test database, use the filter { atype: "authenticate", "param.db": "test" }:

Tip

To specify the filter as a command-line option, enclose the filter document in single quotes to pass the document as a string.

mongod --dbpath data/db --auth --auditDestination file --auditFilter '{ atype: "authenticate", "param.db": "test" }' --auditFormat JSON --auditPath data/db/auditLog.json

To filter on all authenticate operations across databases, use the filter { atype: "authenticate" }.