Skip to content
logo
Percona Server for MongoDB 4.2
Auditing
Initializing search
    percona/psmdb-docs
    percona/psmdb-docs
    • Home
    • Percona Server for MongoDB feature comparison
      • Overview
      • Install Percona Server for MongoDB on Debian and Ubuntu
      • Install Percona Server for MongoDB on Red Hat Enterprise Linux and derivatives
      • Install Percona Server for MongoDB from binary tarball
      • Run Percona Server for MongoDB in a Docker container
        • Percona Memory Engine
        • Hot Backup
        • $backupCursor and $backupCursorExtend aggregation stages
        • Authentication
        • Enable authentication
        • Set up LDAP authentication with SASL
        • Set up x.509 authentication and LDAP authorization
        • Setting up Kerberos authentication
        • LDAP authorization
        • Set up LDAP authentication and authorization using NativeLDAP
        • Data at rest encryption
        • HashiCorp Vault integration
        • Using the Key Management Interoperability Protocol (KMIP)
        • Local key management using a keyfile
        • Migrate from key file encryption to HashiCorp Vault encryption
      • Auditing
        • Audit options
        • Audit message syntax
        • Audit filter examples
          • Standard query selectors
          • Regular expressions
          • Read and write operations
        • Enabling auditing of authorization success
      • Profiling rate limit
      • Log redaction
      • Additional text search algorithm - ngram
      • Tune parameters
        • Upgrade from 4.0 to 4.2
        • Upgrade Percona Server for MongoDB
      • Uninstall Percona Server for MongoDB
      • Release notes index
      • Percona Server for MongoDB 4.2.24-24 (2023-03-09)
      • Percona Server for MongoDB 4.2.23-23 (2022-11-08)
      • Percona Server for MongoDB 4.2.22-22 (2022-09-06)
      • Percona Server for MongoDB 4.2.21-21 (2022-06-29)
      • Percona Server for MongoDB 4.2.20-20 (2022-05-23)
      • Percona Server for MongoDB 4.2.19-19 (2022-03-29)
      • Percona Server for MongoDB 4.2.18-18 (2022-01-19)
      • Percona Server for MongoDB 4.2.17-17 (2021-10-11)
      • Percona Server for MongoDB 4.2.15-16 (2021-07-26)
      • Percona Server for MongoDB 4.2.14-15 (2021-05-13)
      • Percona Server for MongoDB 4.2.13-14 (2021-04-01)
      • Percona Server for MongoDB 4.2.12-13 (2021-02-03)
      • Percona Server for MongoDB 4.2.11-12 (2020-12-07)
      • Percona Server for MongoDB 4.2.10-11 (2020-11-02)
      • Percona Server for MongoDB 4.2.9-10 (2020-10-09)
      • Percona Server for MongoDB 4.2.9-9 (2020-09-03)
      • Percona Server for MongoDB 4.2.8-8 (2020-07-07)
      • Percona Server for MongoDB 4.2.7-7 (2020-06-04)
      • Percona Server for MongoDB 4.2.6-6 (2020-05-07)
      • Percona Server for MongoDB 4.2.5-5 (2020-04-02)
      • Percona Server for MongoDB 4.2.3-4 (2020-02-20)
      • Percona Server for MongoDB 4.2.2-3 (2019-12-24)
      • Percona Server for MongoDB 4.2.1-1 (2019-11-13)
      • Percona Server for MongoDB 4.2.0-1 (2019-09-09)
    • Glossary
      • Copyright and Licensing Information
      • Trademark Policy

    • Audit options
    • Audit message syntax
    • Audit filter examples
      • Standard query selectors
      • Regular expressions
      • Read and write operations
    • Enabling auditing of authorization success

    Auditing¶

    Auditing allows administrators to track and log user activity on a MongoDB server. With auditing enabled, the server will generate an audit log file. This file contains information about different user events including authentication, authorization failures, and so on.

    To enable audit logging, specify where to send audit events using the --auditDestination option on the command line or the auditLog.destination variable in the configuration file.

    If you want to output events to a file, also specify the format of the file using the --auditFormat option or the auditLog.format variable, and the path to the file using the --auditPath option or the auditLog.path variable.

    To filter recorded events, use the --auditFilter option or the auditLog.filter variable.

    For example, to log only events from a user named tim and write them to a JSON file /var/log/psmdb/audit.json, start the server with the following parameters:

    $ mongod \
     --dbpath data/db
     --auditDestination file \
     --auditFormat JSON \
     --auditPath /var/log/psmdb/audit.json \
     --auditFilter '{ "users.user" : "tim" }'
    

    The options in the previous example can be used as variables in the MongoDB configuration file:

    storage:
      dbPath: data/db
    auditLog:
      destination: file
      format: JSON
      path: /var/log/psmdb/audit.json
      filter: '{ "users.user" : "tim" }'
    

    This example shows how to send audit events to the syslog. Specify the following parameters:

    mongod \
    --dbpath data/db
    --auditDestination syslog \
    

    Alternatively, you can edit the MongoDB configuration file:

    storage:
     dbPath: data/db
    auditLog:
     destination: syslog
    

    Note

    If you start the server with auditing enabled, you cannot disable auditing dynamically during runtime.

    Audit options¶

    The following options control audit logging:

    Command line Configuration file Type Description
    --auditDestination() auditLog.destination string Enables auditing and specifies where to send audit events:
    - console: Output audit events to stdout.
    - file: Output audit events to a file specified by the --auditPath option in a format specified by the --auditFormat option.
    - syslog: Output audit events to syslog
    --auditFilter() auditLog.filter string Specifies a filter to apply to incoming audit events, enabling the administrator to only capture a subset of them. The value must be interpreted as a query object with the following syntax:

    { <field1>: <expression1>, ... }

    Audit log events that match this query will be logged. Events that do not match this query will be ignored.
    For more information, see Audit filter examples
    --auditFormat() auditLog.format string Specifies the format of the audit log file, if you set the --auditDestination option to file.
    The default value is JSON. Alternatively, you can set it to BSON
    --auditPath() auditLog.path string Specifies the fully qualified path to the file where audit log events are written, if you set the --auditDestination option to file.
    If this option is not specified, then the auditLog.json file is created in the server’s configured log path. If log path is not configured on the server, then the auditLog.json file is created in the current directory (from which mongod was started).

    NOTE: This file will rotate in the same manner as the system log path, either on server reboot or using the logRotate command. The time of rotation will be added to the old file’s name.

    Audit message syntax¶

    Audit logging writes messages in JSON format with the following syntax:

    {
      atype: <String>,
      ts : { "$date": <timestamp> },
      local: { ip: <String>, port: <int> },
      remote: { ip: <String>, port: <int> },
      users : [ { user: <String>, db: <String> }, ... ],
      roles: [ { role: <String>, db: <String> }, ... ],
      param: <document>,
      result: <int>
    }
    
    Parameter Description
    atype Event type
    ts Date and UTC time of the event
    local Local IP address and port number of the instance
    remote Remote IP address and port number of the incoming connection associated with the event
    users Users associated with the event
    roles Roles granted to the user
    param Details of the event associated with the specific type
    result Exit code (0 for success)

    Audit filter examples¶

    The following examples demonstrate the flexibility of audit log filters.

    auditLog:
       destination: file
          filter: '{atype: {$in: [
             "authenticate", "authCheck",
             "renameCollection", "dropCollection", "dropDatabase",
             "createUser", "dropUser", "dropAllUsersFromDatabase", "updateuser",
             "grantRolesToUser", "revokeRolesFromUser", "createRole", "updateRole",
             "dropRole", "dropAllRolesFromDatabase", "grantRolesToRole", "revokeRolesFromRole",
             "grantPrivilegesToRole", "revokePrivilegesFromRole",
             "replSetReconfig",
             "enableSharding", "shardCollection", "addShard", "removeShard",
             "shutdown",
             "applicationMessage"
          ]}}'
    

    Standard query selectors¶

    You can use query selectors, such as $eq, $in, $gt, $lt, $ne, and others to log multiple event types.

    For example, to log only the dropCollection and dropDatabase events:

    --auditDestination file --auditFilter '{ atype: { $in: [ "dropCollection", "dropDatabase" ] } }'
    
    auditLog:
      destination: file
      filter: '{ atype: { $in: [ "dropCollection", "dropDatabase" ] } }'
    

    Regular expressions¶

    Another way to specify multiple event types is using regular expressions.

    For example, to filter all drop operations:

    --auditDestination file --auditFilter '{ "atype" : /^drop.*/ }'
    
    auditLog:
      destination: file
      filter: '{ "atype" : /^drop.*/ }'
    

    Read and write operations¶

    By default, operations with successful authorization are not logged, so for this filter to work, enable auditAuthorizationSuccess parameter, as described in Enabling auditing of authorization success.

    For example, to filter read and write operations on all the collections in the test database:

    Note

    The dot (.) after the database name in the regular expression must be escaped with two backslashes (\\\\).

    --setParameter auditAuthorizationSuccess=true --auditDestination file --auditFilter '{ atype: "authCheck", "param.command": { $in: [ "find", "insert", "delete", "update", "findandmodify" ] }, "param.ns": /^test\\./ } }'
    
    auditLog:
      destination: file
      filter: '{ atype: "authCheck", "param.command": { $in: [ "find", "insert", "delete", "update", "findandmodify" ] }, "param.ns": /^test\\./ } }'
    
    setParameter: { auditAuthorizationSuccess: true }
    

    Enabling auditing of authorization success¶

    By default, only authorization failures for the authCheck action are logged by the audit system. authCheck is for authorization by role-based access control, it does not concern authentication at logins.

    To enable logging of authorization successes, set the auditAuthorizationSuccess parameter to true. Audit events will then be triggered by every command, including CRUD ones.

    Warning

    Enabling the auditAuthorizationSuccess parameter heavily impacts the performance compared to logging only authorization failures.

    You can enable it on a running server using the following command:

    db.adminCommand( { setParameter: 1, auditAuthorizationSuccess: true } )
    

    To enable it on the command line, use the following option when running mongod or mongos process:

    --setParameter auditAuthorizationSuccess=true
    

    You can also add it to the configuration file as follows:

    setParameter:
      auditAuthorizationSuccess: true
    

    Contact Us

    For free technical help, visit the Percona Community Forum.

    To report bugs or submit feature requests, open a JIRA ticket.

    For paid support and managed or consulting services , contact Percona Sales.


    Last update: December 8, 2022
    Created: December 8, 2022
    Percona LLC and/or its affiliates, © 2023
    Made with Material for MkDocs

    Cookie consent

    We use cookies to recognize your repeated visits and preferences, as well as to measure the effectiveness of our documentation and whether users find what they're searching for. With your consent, you're helping us to make our documentation better.