Audit Events
- Capella Operational
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 clusters with an Enterprise Support 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:
-
The Audit Event Reference for Couchbase Enterprise Server Version 7.2.
-
The Audit Event Reference for Couchbase Enterprise Server Version 7.6.
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, |
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
orin 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.