Please use the form below to provide your feedback. Because your feedback is valuable to us, the information you submit in this form is recorded in our issue tracking system (JIRA), which is publicly available. You can track the status of your feedback using the ticket number displayed in the dialog once you submit the form.

cbcat

  • reference
  • Couchbase Server 8.0
The cbcat tool decrypts and displays the contents of encrypted logs and archive files.

Syntax

The basic syntax is:

cbcat [options] file(s)

where file(s) is a file or multiple files to decrypt and view. You can use any method supported by the shell to specify multiple files, including wildcards.

Description

When encryption at rest is active, Couchbase Server encrypts sensitive data stored on disk. This includes logs, configuration files, audit files, and other files generated by Couchbase Server and the services running in the cluster. The cbcat tool enables you to decrypt and view the contents of these encrypted files.

Depending upon your platform, this tool is at the following locations:

Operating system Location

Linux

/opt/couchbase/bin/

Windows

C:\Program Files\Couchbase\Server\bin\

Mac OS X

/Applications/CouchbaseServer.app/Contents/Resources/couchbase-core/bin/

Options

--with-dump-keys <filename>

The name and location of the dump-keys binary. This binary connects to the keystore and gets the encryption keys. If not specified, the default is /opt/couchbase/bin/dump-keys.

You do not usually need to use this option if you installed Couchbase Server in the default location.

--with-gosecrets <filename>

The name and location of the gosecrets.cfg configuration file. This file contains information about the location of encryption keys, and other encryption-at-rest settings. If not specified, the default is /opt/couchbase/var/lib/couchbase/config/gosecrets.cfg.

You do not usually need to use this option if you installed Couchbase Server in the default location.

--password <password>

The master password to use for decryption. Use - to prompt for a password or to read from standard input.

This option and the --with-keystore option are mutually exclusive. You can only use one of these options.

--with-keystore <json>

A JSON representation of a keystore containing the keys that were used to encrypt the files you want to decrypt and view. Use - to read from standard input.

This option and the --password option are mutually exclusive. You can only use one of these options.

--print-header

Prints a header with the file name before the content of the file.

--dump-encryption-header

Prints information from the encryption header, if the file is encrypted.

--version

Displays the program version.

--help

Displays help text.

Schema

The --with-keystore option expects a JSON value with the following schema.

One of …​ Schema

An object which contains a key definition.

Key Definition

or

An array of objects, each of which contains a key definition.

Key Definition array

Key Definition

Property Schema

cipher
required

The encryption algorithm used for the data encryption key. Currently, only one encryption algorithm is supported.

Value: AES-256-GCM

String

id
required

The ID of the data encryption key that was used to encrypt the file you want to view.

This is not the same as the user-friendly name that you can specify when you create a key, or the integer that the Encryption-at-Rest API assigns to a key.

String (UUID)

key
required

The value of the data encryption key that was used to encrypt the file you want to view.

String

To decrypt and view a single file, the keystore only needs to contain a single key definition, which must be the key used to encrypt that file. To decrypt and view multiple files, the keystore must contain the definitions of the keys that were used to encrypt each file.

To get the ID of the key that was used to encrypt a file, you can use cbcat with the --dump-encryption-header option. See Example 5. Alternatively, if the keystore contains at least one valid key definition, but does not contain the correct key for the file you want to decrypt, cbcat tells you the ID of the key that’s required.

To get the value of a key given its ID, use the dump-keys binary. See Example 6.

Output

The tool outputs the contents of the specified input files. If any input files were encrypted, the output is decrypted.

Examples

In the following examples, $MASTER is the master password used to encrypt the logs and configuration files.

Example 1. Decrypt and view a single file
Command
cbcat --password $MASTER eventing.log
Example 2. Prompt for the master password
Command
cbcat --password - eventing.log
Output
Password:
Example 3. Decrypt and view multiple files
Command
cbcat --password $MASTER eventing.log ns_couchdb.log
Example 4. Decrypt and view files with file names

The following command decrypts and views all files whose names begin with memcached.

Command
cbcat --password $MASTER --print-header memcached*
Output
File: memcached.json
======================================================================
<file content ...>
File: memcached.rbac
======================================================================
<file content ...>
Example 5. Decrypt and view file with encryption header
Command
cbcat --password $MASTER --dump-encryption-header memcached.rbac
Output
File: memcached.rbac
  Encrypted:
    Key ID: 3f64f34c-a0bd-4248-a1da-5769e5bc15ef
    Key Derivation: KeyBased
    Compression: None
======================================================================
<file content ...>
Example 6. Decrypt and view file using its encryption key

The following command finds the value of a data encryption key, using the key ID returned by Example 5.

Command
dump-keys -p $MASTER -k 3f64f34c-a0bd-4248-a1da-5769e5bc15ef
Output
{
  "3f64f34c-a0bd-4248-a1da-5769e5bc15ef": {
    "result": "raw-aes-gcm",
    "response": {
      "kind": "configDek",
      "name": "3f64f34c-a0bd-4248-a1da-5769e5bc15ef",
      "key": "5YHAbvomWQuMZSnwQcSWhh4c+XpiildvYlOpbg7VLLE=",
      "encryptionKeyId": "encryptionService",
      "creationTime": "2026-06-30T11:32:03Z",
      "imported": false
    }
  }
}

The following command uses a JSON keystore to decrypt and view a file. In the JSON keystore, the id property is the key ID, and the key property is the same as the key property returned by the previous command.

Command
cbcat --with-keystore '{
  "cipher": "AES-256-GCM",
  "id": "3f64f34c-a0bd-4248-a1da-5769e5bc15ef",
  "key": "5YHAbvomWQuMZSnwQcSWhh4c+XpiildvYlOpbg7VLLE="
}' memcached.rbac

Environment Variables

CB_DUMP_KEYS_DEBUG

If this environment variable is set to true, cbcat prints out the command line and options that it uses to invoke the dump-keys program.

See Also