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:

{
  "description": "Successful login to couchbase cluster",
  "id": 8192,
  "name": "login success",
  "real_userid": {
    "domain": "builtin",
    "user": "Administrator"
  },
  "remote": {
    "ip": "10.143.192.1",
    "port": 51410
  },
  "roles": [
    "admin"
  ],
  "sessionid": "483a1e627e0ca710bdb3c6f5e8ac0177",
  "timestamp": "2020-02-04T07:11:09.856-08:00"
}

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

Login Failure

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

{
  "description": "Unsuccessful attempt to login to couchbase cluster",
  "id": 8193,
  "name": "login failure",
  "real_userid": {
    "domain": "rejected",
    "user": "Administrator"
  },
  "remote": {
    "ip": "10.143.192.1",
    "port": 51451
  },
  "timestamp": "2020-02-04T07:15:34.098-08:00"
}

This record indicates that a user named Administrator incurred an Unsuccessful attempt to login to couchbase cluster on 2020-02-04 at 07:15:34.

Bucket Creation

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

{
  "bucket_name": "testBucket",
  "description": "Bucket was created",
  "id": 8201,
  "name": "create bucket",
  "props": {
    "compression_mode": "passive",
    "conflict_resolution_type": "seqno",
    "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.143.192.1",
    "port": 51463
  },
  "sessionid": "90ba9344e7fbf0d39ae85deee00a0274",
  "timestamp": "2020-02-04T07:16:51.804-08:00",
  "type": "membase"
}

This record indicates that a Bucket was created on 2020-02-04 at 07:16:51; 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,
  "name": "modify bucket",
  "props": {
    "compression_mode": "passive",
    "eviction_policy": "value_only",
    "flush_enabled": false,
    "max_ttl": 10000000,
    "num_replicas": 1,
    "num_threads": 3,
    "purge_interval": "undefined",
    "ram_quota": 268435456,
    "storage_mode": "couchstore"
  },
  "real_userid": {
    "domain": "builtin",
    "user": "Administrator"
  },
  "remote": {
    "ip": "10.143.192.1",
    "port": 51498
  },
  "sessionid": "90ba9344e7fbf0d39ae85deee00a0274",
  "timestamp": "2020-02-04T07:18:59.669-08:00",
  "type": "membase"
}

This record indicates that the bucket testBucket was modified on 2020-02-04 at 07:18:59. The max_ttl is now represented as 10000000 seconds.

User Creation

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

{
  "description": "User was added or updated",
  "full_name": "Test User",
  "groups": [],
  "id": 8232,
  "identity": {
    "domain": "local",
    "user": "testUser"
  },
  "name": "set user",
  "real_userid": {
    "domain": "builtin",
    "user": "Administrator"
  },
  "reason": "added",
  "remote": {
    "ip": "10.143.192.1",
    "port": 51514
  },
  "roles": [
    "bucket_admin[testBucket]"
  ],
  "sessionid": "82d1c8837f0f7cbafefe3b5c6722a016",
  "timestamp": "2020-02-04T07:21:01.612-08:00"
}

This record indicates that a user named testUser was created by Administrator on 2020-02-04 at 07:21:01; 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:

{
  "description": "FTS index was created/Updated",
  "id": 24577,
  "index_name": "travelSampleIndex",
  "name": "Create/Update index",
  "real_userid": {
    "domain": "builtin",
    "user": "Administrator"
  },
  "timestamp": "2020-02-04T07:23:48.482-08:00"
}

This record indicates that an FTS index named travelSampleIndex was created or updated on 2020-02-04 at 07:23:48.

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.