A newer version of this documentation is available.

View Latest

Auditing

      +
      Couchbase Server provides event-auditing, sending output to a log-file.

      Introduction to Auditing

      The Couchbase Server auditing facility recognizes specific, server-generated events, which can be logged. The output is written to a log-file, which is periodically rotated.

      Audit Event-Types

      Events generated by Couchbase Server are of two kinds:

      • Admin events, which track administrative and configuration changes to the cluster.

      • Data events, which track attempts to access and change data.

      Note that event-auditing occurs on a per node basis: each node captures its own events only. If a cluster-wide record is needed, the individual per node records must be manually consolidated by the administrator.

      This page explains frequently used audit fields, and gives examples of record-structures. For information on managing auditing, see Manage Auditing. See the reference page Audit Event Reference, for a complete list of events that can be audited.

      Audit Fields

      The table below lists frequently used audit fields, with corresponding descriptions. Note that different event-types generate different field-subsets.

      Field Type Description

      "id"

      Integer

      The unique identifier for the event. For example, 20480, 8192, 28672.

      "name"

      String

      The name of the event. For example, "login success", "User was deleted", "A N1QL UPSERT statement was executed".

      "description"

      String

      A description for the event. For example, "Unsuccessful attempt to login to couchbase cluster", "Node was removed from the cluster", "Bucket was created".

      "filtering_permitted"

      Boolean

      Whether the event is filterable. Can be true or false.

      "mandatory_fields"

      Object

      Contains key-value pairs that are mandatory for all events. These include the "timestamp" for the event (for example, "2020-01-29T08:02:07.476-08:00": see http://www.w3.org/TR/NOTE-datetime), and the "user".

      Saving Audit Records

      When auditing is enabled, logged events are written to a default file, named audit.log. After an administrator-specified period — which must be a minimum of 15 minutes and a maximum of 7 days — this file is closed, and is saved under a modified name that features a timestamp corresponding to the time of saving. A new, empty audit.log file is created and saved when a new audit event is generated. Note that this rotation may happen earlier if the file reaches its maximum size of 20MB. For instructions on configuring the file’s rotation time, see Manage Auditing.

      Login

      An audit record for a successful login might appear as follows:

      {
        "roles": [
          "admin"
        ],
        "real_userid": {
          "domain": "builtin",
          "user": "Administrator"
        },
        "sessionid": "e29001c920944ba46e5b1caa3108726b",
        "remote": {
          "ip": "10.143.190.1",
          "port": 49319
        },
        "timestamp": "2020-01-29T08:02:07.476-08:00",
        "id": 8192,
        "name": "login success",
        "description": "Successful login to couchbase cluster"
      }

      In this example, a user named Administrator has successfully logged into a Couchbase cluster using the domain IP address 10.143.190.1.

      Login Failure

      The following audit-record indicates that a login attempt failed:

      {
        "real_userid": {
          "domain": "rejected",
          "user": "Administrator"
        },
        "remote": {
          "ip": "10.143.190.1",
          "port": 49335
        },
        "timestamp": "2020-01-29T08:02:17.204-08:00",
        "id": 8193,
        "name": "login failure",
        "description": "Unsuccessful attempt to login to couchbase cluster"
      }

      This record indicates that a user named Administrator incurred an Unsuccessful attempt to login to couchbase cluster on 2020-01-29 at 08:02:17.

      Bucket Creation

      The audit-record below corresponds to the creation of a bucket.

      {
        "props": {
          "compression_mode": "passive",
          "max_ttl": 0,
          "storage_mode": "couchstore",
          "conflict_resolution_type": "seqno",
          "eviction_policy": "value_only",
          "num_threads": 3,
          "flush_enabled": false,
          "purge_interval": "undefined",
          "ram_quota": 163577856,
          "replica_index": false,
          "num_replicas": 1
        },
        "type": "membase",
        "bucket_name": "testBucket",
        "real_userid": {
          "domain": "builtin",
          "user": "Administrator"
        },
        "sessionid": "0f9bbbf8e133c7ad232c8870b7ead4da",
        "remote": {
          "ip": "10.143.190.1",
          "port": 49365
        },
        "timestamp": "2020-01-29T08:02:42.234-08:00",
        "id": 8201,
        "name": "create bucket",
        "description": "Bucket was created"
      }

      This record indicates that a Bucket was created on 2020-01-29 at 08:02:42; that the bucket was named testBucket; and that its eviction-policy was defined as value_only. The bucket was created by the user Administrator.

      Bucket TTL Modification

      The audit record below corresponds to the modification of Bucket TTL, for the bucket created immediately above.

      {
        "props": {
          "compression_mode": "passive",
          "max_ttl": 10000000,
          "storage_mode": "couchstore",
          "eviction_policy": "value_only",
          "num_threads": 3,
          "flush_enabled": false,
          "purge_interval": "undefined",
          "ram_quota": 163577856,
          "num_replicas": 1
        },
        "type": "membase",
        "bucket_name": "testBucket",
        "real_userid": {
          "domain": "builtin",
          "user": "Administrator"
        },
        "sessionid": "c91626f95b13962b7374ba795634b381",
        "remote": {
          "ip": "10.143.190.1",
          "port": 49556
        },
        "timestamp": "2020-01-29T08:24:20.205-08:00",
        "id": 8202,
        "name": "modify bucket",
        "description": "Bucket was modified"
      }

      This record indicates that the bucket testBucket was modified on 2020-01-29 at 08:24:20. The max_ttl is now represented as 10000000 seconds.

      User Creation

      The audit-record below corresponds to the creation of a user.

      {
        "full_name": "Test Bucket User",
        "roles": [
          "bucket_admin[testBucket]"
        ],
        "identity": {
          "domain": "local",
          "user": "testBucketUser"
        },
        "real_userid": {
          "domain": "builtin",
          "user": "Administrator"
        },
        "sessionid": "0f9bbbf8e133c7ad232c8870b7ead4da",
        "remote": {
          "ip": "10.143.190.1",
          "port": 49375
        },
        "timestamp": "2020-01-29T08:03:07.637-08:00",
        "id": 8232,
        "name": "set user",
        "description": "User was added or updated"
      }

      This record indicates that a user named testBucketUser was created by Administrator on 2020-01-29 at 08:03:07; and that the user was given the role of bucket_admin for the bucket testBucket.

      Index Creation

      The following audit-record indicates that a Full Text Index was created or updated:

      {
        "timestamp": "2020-01-29T08:03:32.059-08:00",
        "real_userid": {
          "domain": "builtin",
          "user": "Administrator"
        },
        "index_name": "travelSampleIndex",
        "id": 24577,
        "name": "Create/Update index",
        "description": "FTS index was created/Updated"
      }

      This record indicates that an FTS index named travelSampleIndex was created or updated on 2020-01-29 at 08:03:32.

      Filterable and Non-Filterable Events

      Eventing for each cluster-node is disabled by default; and can be explicitly enabled. When enablement has occurred, a default subset of Couchbase Server-events is audited, with records duly concatenated to the end of the audit.log file. The events in this default subset are non-filterable; meaning that while auditing is enabled for the node, all the events in the subset are always recorded, and cannot be selectively disabled.

      An additional event-subset, of filterable events, is provided. These events relate to the same modules as the non-filterable events: however, filterable events can be individually disabled or enabled; and, optionally, all filterable events can be ignored, for specified users.

      For information on how to filter events, see Manage Auditing.

      Event Tables

      See the reference page Audit Event Reference, for a complete list of events that can be audited.