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 |
|---|---|---|
|
Integer |
The unique identifier for the event.
For example, |
|
String |
The name of the event.
For example, |
|
String |
A description for the event.
For example, |
|
Object |
Contains key-value pairs for |
|
Object |
Contains key-value pairs for |
|
Object |
Contains key-value pairs for |
|
UTC timestamp |
The UTC timestamp for the event’s generation (for example, |
Saving and Pruning 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.
By default, Couchbase Server does not automatically delete rotated audit log files.
Over time, these log files can consume disk space on your nodes.
You can choose to have Couchbase Server remove rotated audit logs after a period of time by using the Configure Auditing REST-API’s pruneAge parameter.
You can also use an external tool or script to periodically remove audit files directly from the log directory.
Sample Audit Records
A number of sample audit records are presented 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.
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.
Some of 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.
Other events, including ones that are initially disabled, are filterable; meaning that while auditing is enabled for the node, each can be individually enabled or disabled by the administrator. Note also that optionally, 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.