Audit Events

      +
      Capella provides event auditing, whereby events are logged. Log files can be downloaded for inspection.

      Introduction to Auditing

      The Capella auditing facility recognizes specific, server-generated events, which can be logged. Output is written to log files, each of which is periodically rotated.

      Auditing occurs on a per node basis: each node captures its own events, and saves the records in its own log file. When inspection is required of events that were audited within a specific time period, the user can request export of the corresponding log files. Capella duly gathers the files, and makes them available within a single compressed file, which can be downloaded by the user.

      Auditing is available to databases with an Enterprise Service Plan.

      Filterable and Non-Filterable Events

      Auditing for Capella is disabled by default; and can be explicitly enabled. When auditing for Capella is disabled, no events are audited.

      After enablement of Capella auditing has occurred, a default subset of events is audited. Most of the events in this default subset are non-filterable; meaning that while auditing is enabled, such events are always recorded, and cannot be selectively disabled.

      Capella also provides filterable events. These are, in most cases, individually disabled by default; and in consequence, remain individually disabled even after auditing for Capella as a whole has been enabled. However, they can be individually enabled. Additionally, they can be configured to be ignored whenever generated by the actions of specified users.

      For information on how to configure the filtering of events, see Audit Management.

      Ignoring Filterable Events By User

      In some cases, it may be unnecessary to log filterable events incurred by particular users. Filterable events created by such users can be specified to be ignored, even when these filterable events have been explicitly enabled.

      For a user’s events to be ignored, the username and the domain of the user must be specified: the domain always being local.

      The following Couchbase internal users may also be specified:

      @eventing

      @cbq-engine

      @ns_server

      @index

      @projector

      @goxdcr

      @fts

      @cbas

      For any internal or external user specified in the field, all filterable events will be ignored. Non-filterable events, however, will continue to be audited.

      Event Tables

      For a complete list of audit events, see:

      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, or 28672.

      "name"

      String

      The name of the event. For example, "login success", "User was deleted", or "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", or "Bucket was created".

      "real_userid"

      Object

      Contains key-value pairs for "domain" (specifying "local"; "external"; "builtin" — for the administrator who set up the cluster; or "rejected" — for a user who has been denied access); and "user" (specifying the id of the user who generated the event).

      "local"

      Object

      Contains key-value pairs for "ip" and incoming "port", for the node on which the event was processed.

      "remote"

      Object

      Contains key-value pairs for "ip" and outgoing "port", for the node on which the event-request was dispatched.

      "timestamp"

      UTC timestamp

      The UTC timestamp for the event’s generation (for example, "2020-01-29T08:02:07.476-08:00": see Date and Time Formats).

      Examples of Audit Event Records

      A number of audit event records are shown below.

      Login

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

      {
        "description": "Successful login to couchbase cluster",
        "id": 8192,
        "local": {
          "ip": "10.144.210.101",
          "port": 8091
        },
        "name": "login success",
        "real_userid": {
          "domain": "local",
          "user": "testUser"
        },
        "remote": {
          "ip": "10.144.210.1",
          "port": 53322
        },
        "roles": [
          "admin"
        ],
        "sessionid": "ba2760cee506d0293a8b4a0bf83687b807329667",
        "timestamp": "2021-02-09T14:44:17.938Z"
      }

      In this example, a user named testUser has successfully logged into a Couchbase cluster-node whose IP address is 10.144.210.101.

      Login Failure

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

      {
        "description": "Unsuccessful attempt to login to couchbase cluster",
        "id": 8193,
        "local": {
          "ip": "10.144.210.101",
          "port": 8091
        },
        "name": "login failure",
        "real_userid": {
          "domain": "rejected",
          "user": "newUser"
        },
        "remote": {
          "ip": "10.144.210.1",
          "port": 53348
        },
        "timestamp": "2021-02-09T14:45:34.934Z"
      }

      This record indicates that a user named newUser incurred an Unsuccessful attempt to login to couchbase cluster.

      Bucket Creation

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

      {
        "bucket_name": "testBucket",
        "description": "Bucket was created",
        "id": 8201,
        "local": {
          "ip": "10.144.231.102",
          "port": 8091
        },
        "name": "create bucket",
        "props": {
          "compression_mode": "passive",
          "conflict_resolution_type": "seqno",
          "durability_min_level": "none",
          "eviction_policy": "value_only",
          "flush_enabled": false,
          "max_ttl": 0,
          "num_replicas": 1,
          "num_threads": 3,
          "purge_interval": "undefined",
          "ram_quota": 268435456,
          "replica_index": false,
          "storage_mode": "couchstore"
        },
        "real_userid": {
          "domain": "builtin",
          "user": "Administrator"
        },
        "remote": {
          "ip": "10.144.231.1",
          "port": 53837
        },
        "sessionid": "3f8472056c30014d32f19aca0bb22b10d5cefbee",
        "timestamp": "2022-08-23T10:05:34.489Z",
        "type": "membase"
      }

      This record indicates that a Bucket was created; 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.

      {
        "bucket_name": "testBucket",
        "description": "Bucket was modified",
        "id": 8202,
        "local": {
          "ip": "10.144.210.101",
          "port": 8091
        },
        "name": "modify bucket",
        "props": {
          "compression_mode": "passive",
          "durability_min_level": "none",
          "eviction_policy": "value_only",
          "flush_enabled": false,
          "max_ttl": 100000,
          "num_replicas": 1,
          "num_threads": 3,
          "purge_interval": "undefined",
          "ram_quota": 268435456,
          "storage_mode": "couchstore"
        },
        "real_userid": {
          "domain": "builtin",
          "user": "Administrator"
        },
        "remote": {
          "ip": "10.144.210.1",
          "port": 53397
        },
        "sessionid": "eb1411eaa5eb041ea07fb86ffe93a94a59f8e8e2",
        "timestamp": "2021-02-09T14:48:14.653Z",
        "type": "membase"
      }

      This record indicates that the bucket testBucket was modified. The max_ttl is now represented as 100000 seconds.

      User Creation

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

      {
        "description": "User was added or updated",
        "full_name": "",
        "groups": [],
        "id": 8232,
        "identity": {
          "domain": "local",
          "user": "clusterUser"
        },
        "local": {
          "ip": "10.144.210.101",
          "port": 8091
        },
        "name": "set user",
        "real_userid": {
          "domain": "builtin",
          "user": "Administrator"
        },
        "reason": "added",
        "remote": {
          "ip": "10.144.210.1",
          "port": 53444
        },
        "roles": [
          "cluster_admin"
        ],
        "sessionid": "eb1411eaa5eb041ea07fb86ffe93a94a59f8e8e2",
        "timestamp": "2021-02-09T14:50:38.256Z"
      }

      This record indicates that a user named clusterUser was created by Administrator; and that the user was given the role of cluster_admin.

      Index Creation

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

      {
        "description": "FTS index was created/Updated",
        "id": 24577,
        "index_name": "testIndex",
        "local": {
          "ip": "127.0.0.1",
          "port": "8094"
        },
        "name": "Create/Update index",
        "real_userid": {
          "domain": "builtin",
          "user": "Administrator"
        },
        "remote": {
          "ip": "127.0.0.1",
          "port": "39575"
        },
        "timestamp": "2021-02-09T15:20:49.953Z"
      }

      This record indicates that an FTS index named testIndex was created or updated.

      Export Request Lifecycle

      To obtain a record of events audited during a specified time-period, the user creates an audit log request: in response, Capella gathers records for the specified time-period, and makes all corresponding log files available for user-download, as a single compressed file. Details of the required, individual calls are provided in Audit Management.

      The lifecycle of an audit log request — extending from the point at which the request is made by the user, to the point at which the compressed file is available for user-download — is explained below.

      Request Status and Processing Duration

      After a request has been made, its progress can be tracked by means of its status attribute. At a given time, this can be any one of the following:

      • queued. The request has been received, and is awaiting processing.

      • in progress. The request is being processed. This status is typically reached soon after the request has been initially queued. The duration of processing typically depends on the length and calendar-placement of the user-specified time-period. If the time-period is within the last 24 hours, processing is likely to be fast, since the corresponding files are at hand. Alternatively, if the time-period extends to a point earlier than the last 24 hours, processing is likely to take longer, since corresponding files have in some cases been archived, and so require additional steps for retrieval.

      • ready. The request has been successfully processed. A download URL is now available, whereby the resulting compressed file can be downloaded, and its content examined. The URL will be available until approximately 72 hours after export-completion. The compressed file will contains a single log file for each node that existed on the cluster during the specified time-period.

      • failed. The request failed, and no export has occurred. The user should open a support ticket, so that the problem can be investigated and appropriately resolved.

      • no audit log files exist within the requested time frame. No log files exist for the time-period that was specified: therefore, no export has occurred. This problem may be a consequence of auditing not having been enabled during the requested time-period. It is also possible that there was no auditable activity on the cluster during the requested time-period.

      Limitations on Export Requests

      The following limitations exist on export requests:

      • Only one export request may be running at any given time. A running export request is one whose status is either queued or in progress.

      • No more than three historical export requests are permitted in a 24 hour period. A historical export request is one whose start time is earlier than the point that is 24 hours before the making of the request.

        Note, however, that any number of export requests can be made whose start time is no earlier than 24 hours of the making of the request.

      • No export request can be made whose start time is earlier than 30 days prior to the making of the request.

      • No export request can be made whose start time is later than 15 minutes prior to the making of the request.

      • No export request can be made whose absolute time-range is less than 15 minutes.

      Note also that returned files may contain subsets of records that were made outside the user-specified time-period.