Manage Auditing
Actions performed on Couchbase Server can be audited. This allows administrators to ensure that system-management tasks are being appropriately performed.
Audit Records and Their Content
The records created by the Couchbase Auditing facililty capture information on who has performed what action, when, and how successfully. The records are created by Couchbase Server-processes, which run asynchronously. Each record is stored as a JSON document, which can be retrieved and inspected.
Auditing can be configured by the Full Admin and Security Admin roles, and read by the Read-Only Admin role.
A conceptual overview of event auditing can be found in Auditing. See the reference page Audit Event Reference, for a complete list of the events that can be audited.
Manage Auditing with the UI
Access Couchbase Web Console, and left-click on the Security tab, in the vertical navigation-bar, at the left-hand side of the Dashboard:
This brings up the Security screen, which appears as follows:
The initial, default view is for Users. To select auditing, left-click on the Audit tab, on the horizontal control-bar, near the top:
This brings up the Audit view:
To enable auditing, check the Audit events & write them to a log checkbox:
This makes the default pathname within the Audit Log Directory text-field editable.
For Linux, the pathname is /opt/couchbase/var/lib/couchbase/logs; for Windows, C:\Program Files\Couchbase\Server\var\lib\couchbase\logs; for MacOS, /Users/couchbase/Library/Application Support/Couchbase/var/lib/couchbase/logs.
If you wish to modify the pathname, enter the appropriate content. Records will be saved to the directory you specify. Note the advisory message now visible beneath the checkbox: as this indicates, electing to audit a wide range of events may significantly impact performance and consume disk-space.
The Log Rotation time interval & size trigger determines at what times stored log files — referred to as targets — are rotated: this means that the current default file, to which records are being written, named audit.log, is saved under a new name, which features an appended timestamp.
For example: usermachinename.local-2017-03-16T15-42-18-audit.log.
Note that rotated log files are never deleted by Couchbase Server: if deletion is appropriate, this must be handled explicitly by the administrator.
The number of time-units is specified by changing the number 1, which appears in the interactive field by default.
The time-unit type is specified by means of the pull-down menu, at the right-hand side of the field:
Note that the value you establish must be from 15 minutes to 7 days.
Log rotation can also be specified by means of a size trigger: this can be edited, in the interactive field to the right of the Log Rotation pane. The default value is 20, and the units are megabytes.
Filterable Events
Events can be filtered for the Data Service, the Query and Index Service, the Eventing Service, and the Analytics Service. Filtering means selective logging.
To view filterable events for the Data Service, first, ensure that logging is generally enabled, by checking the Audit events & write them to a log checkbox. Then, left-click on the right-pointing arrowhead adjacent to Data Service. The Data Service events panel opens, as follows:
This shows that currently, no Data Service events are to be logged. To elect to log all such events, move the enable all toggle to the right:
The panel now appears as follows:
Every checkbox appears selected, indicating that each corresponding event will be logged. To de-select individual events, simply uncheck the appropriate checkboxes.
Ignoring Filterable Events By User
In some cases, it may not be desirable to log events incurred by particular users: for example, those corresponding to the authentication performed by a Full Administrator.
Such users can be specified in the Ignore Filterable Events From These Users field.
As the placeholder indicates, specification should take the form username/external or username/couchbase, according to the domain in which the user is registered.
(See
Authentication, for information on authentication domains.)
On instances of Couchbase Server whose version is no earlier than 6.0.3, the following Couchbase internal users may also be specified in the Ignore Events From These Users field:
@eventing |
@cbq-engine |
@ns_server |
@index |
@projector |
@goxdcr |
@fts |
@cbas |
Each internal user should be specified in the form @internalusername/couchbase.
If multiple internal user-names are specified, these should be separated with a comma, and no space.
For each internal user specified in the field, all filterable events will be ignored: non-filterable events, however, will continue to be audited.
Left-click on the Save button, to save the configuration.
Manage Auditing with the CLI
To manage auditing with the Couchbase CLI, use the setting-audit command, as follows:
/opt/couchbase/bin/couchbase-cli setting-audit \ --cluster 10.143.192.101 \ --username Administrator \ --password password \ --audit-enabled 1 \ --audit-log-path '/opt/couchbase/var/lib/couchbase/logs' \ --audit-log-rotate-interval 86400 \ --audit-log-rotate-size 104857600
This enables auditing for the current node, by specifying a value of 1 for the audit-enabled parameter.
(Specifying 0 would disable auditing for the current node.)
A pathname is specified as the value of audit-log-path, indicating the location for the audit.log file.
An audit-log-rotate-interval of 86400 seconds (24 hours) is specified, as is an audit-log-rotate-size of 104857600 byes (100 MB).
If the call is successful, the following message is displayed:
SUCCESS: Audit settings modified
For more information on configuring audit with the Couchbase command-line interface, see setting-audit.
Manage Auditing with the REST API
The Couchbase REST API provides three endpoints whereby auditing can be managed. Full details are provided in Configure Auditing.
Filterable events are referred to with individual ids, as well as by name, description, and module.
A complete list can be displayed by means of the GET /settings/audit/descriptors http method and URI.
In the following example, output is piped to the jq program, to facilitate readability.
curl -v -X GET -u Administrator:password http://10.143.192.101:8091/settings/audit/descriptors | jq
If successful, the call returns an array of objects, each of which contains identifying information for a filterable event:
[
{
"id": 8243,
"name": "mutate document",
"module": "ns_server",
"description": "Document was mutated via the REST API"
},
{
"id": 8255,
"name": "read document",
"module": "ns_server",
"description": "Document was read via the REST API"
},
{
"id": 8257,
"name": "alert email sent",
"module": "ns_server",
"description": "An alert email was successfully sent"
},
.
.
,
Each element in the array thus features the id, `name, module, and description of a filterable event.
The POST /settings/audit http method and URI can be used to modify the current audit configuration.
For example:
curl -v -X POST -u Administrator:password \ http://10.143.192.101:8091/settings/audit \ -d auditdEnabled=true \ -d disabled=8243,8255,8257,32770,32771,32772,32780,32783,32784,32785,32786,40963 \ -d rotateSize=524288000 \ -d rotateInterval=7200 \ -d logPath='/opt/couchbase/var/lib/couchbase/logs'
Here, auditing for the node is enabled, by specifying a value of true for the auditEnabled parameter.
A comma-separated list of audit-event ids is provided as the value for the disabled parameter; indicating that each corresponding filterable event will be disabled.
The rotateSize is specified in bytes, and the rotateInterval in seconds.
See Configure Auditing, for more detailed information; including use of the GET /settings/audit method and URI to retrieve the current audit configuration.