- Security >
- Security Tutorials >
- Configure System Events Auditing
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:
storage:
dbPath: data/db
auditLog:
destination: 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:
storage:
dbPath: data/db
auditLog:
destination: 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:
storage:
dbPath: data/db
auditLog:
destination: file
format: JSON
path: 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:
storage:
dbPath: data/db
auditLog:
destination: file
format: BSON
path: 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 as detailed in Audit Event Actions, Details, and Results. The audit feature has an --auditFilter option to determine which events to record.
The --auditFilter option takes a string representation of a query document of the form:
{ <field1>: <expression1>, ... }
- The <field> can be any field in the audit message, including fields returned in the param document.
- The <expression> is a query condition expression.
To specify an audit filter, enclose the filter document in single quotes to pass the document as a string.
To specify the audit filter in a configuration file, you must use the YAML format of the configuration file.
Filter for Multiple Operation Types¶
The following example uses the filter { atype: { $in: [ "createCollection", "dropCollection" ] } } to audit only the createCollection and dropCollection actions.
To specify an audit filter, 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
To specify the audit filter in a configuration file, you must use the YAML format of the configuration file.
storage:
dbPath: data/db
auditLog:
destination: file
format: JSON
path: data/db/auditLog.json
filter: '{ atype: { $in: [ "createCollection", "dropCollection" ] } }'
Filter on Authentication Operations on a Single Database¶
The <field> can include any field in the audit message. For authentication operations, the audit messages include a db field in the param document.
The following example uses the filter { atype: "authenticate", "param.db": "test" } to audit only the authenticate operations that occur against the test database.
To specify an audit filter, 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 specify the audit filter in a configuration file, you must use the YAML format of the configuration file.
storage:
dbPath: data/db
security:
authorization: enabled
auditLog:
destination: file
format: JSON
path: data/db/auditLog.json
filter: '{ atype: "authenticate", "param.db": "test" }'
To filter on all authenticate operations across databases, use the filter { atype: "authenticate" }.
Filter by Authorization Role¶
The following example uses the filter { roles: { role: "readWrite", db: "test" } } to only audit operations for users with readWrite role on the test database. This includes users with roles that inherit from readWrite.
To specify an audit filter, enclose the filter document in single quotes to pass the document as a string.
mongod --dbpath data/db --auth --auditDestination file --auditFilter '{ roles: { role: "readWrite", db: "test" } }' --auditFormat JSON --auditPath data/db/auditLog.json
To specify the audit filter in a configuration file, you must use the YAML format of the configuration file.
storage:
dbPath: data/db
security:
authorization: enabled
auditLog:
destination: file
format: JSON
path: data/db/auditLog.json
filter: '{ roles: { role: "readWrite", db: "test" } }'
Filter by insert and remove Operations¶
To capture read and write operations in the audit, you must also enable the audit system to log authorization successes using the auditAuthorizationSuccess parameter. [1]
Note
Enabling auditAuthorizationSuccess degrades performance more than logging only the authorization failures.
To specify an audit filter, enclose the filter document in single quotes to pass the document as a string.
mongod --dbpath data/db --auth --setParameter auditAuthorizationSuccess=true --auditDestination file --auditFilter '{ atype: "authCheck", "param.command": { $in: [ "insert", "delete" ] } }' --auditFormat JSON --auditPath data/db/auditLog.json
To specify the audit filter in a configuration file, you must use the YAML format of the configuration file.
storage:
dbPath: data/db
security:
authorization: enabled
auditLog:
destination: file
format: JSON
path: data/db/auditLog.json
filter: '{ atype: "authCheck", "param.command": { $in: [ "insert", "delete" ] } }'
setParameter: { auditAuthorizationSuccess: true }
| [1] | You can enable auditAuthorizationSuccess parameter without enabling --auth; however, all operations will return success for authorization checks. |