diff --git a/modules/ROOT/nav.adoc b/modules/ROOT/nav.adoc
index 8133ad9abe..fe0622674a 100644
--- a/modules/ROOT/nav.adoc
+++ b/modules/ROOT/nav.adoc
@@ -96,6 +96,7 @@ include::third-party:partial$nav.adoc[]
** xref:learn:security/on-the-wire-security.adoc[On-the-Wire Security]
** xref:learn:security/auditing.adoc[Auditing]
** xref:learn:security/encryption-overview.adoc[Encryption]
+ *** xref:learn:security/native-encryption-at-rest-overview.adoc[]
.Manage
* xref:manage:management-overview.adoc[Overview]
@@ -156,6 +157,7 @@ include::third-party:partial$nav.adoc[]
**** xref:manage:manage-security/rotate-server-certificates.adoc[Certificate Rotation]
**** xref:manage:manage-security/handle-certificate-errors.adoc[Certificate Error Handling]
** xref:manage:manage-security/manage-tls.adoc[Manage On-the-Wire Security]
+ ** xref:manage:manage-security/manage-native-encryption-at-rest.adoc[]
** xref:manage:manage-security/manage-auditing.adoc[Manage Auditing]
** xref:manage:manage-security/manage-sessions.adoc[Manage Sessions]
** xref:manage:manage-security/manage-console-access.adoc[Manage Console Access]
@@ -444,6 +446,12 @@ include::cli:partial$cbcli/nav.adoc[]
***** xref:rest-api:rest-regenerate-all-certs.adoc[Regenerate All Certificates]
***** xref:rest-api:deprecated-security-apis/deprecated-certificate-management-apis.adoc[Deprecated Certificate Management APIs]
****** xref:rest-api:deprecated-security-apis/upload-retrieve-root-cert.adoc[Upload and Retrieve the Root Certificate]
+ *** xref:rest-api:security/encryption-at-rest/encryption-at-rest.adoc[]
+ **** xref:rest-api:security/encryption-at-rest/manage-encryption-keys.adoc[]
+ **** xref:rest-api:security/encryption-at-rest/manage-system-encryption-at-rest.adoc[]
+ **** xref:rest-api:security/encryption-at-rest/rotate-encryption-at-rest-key.adoc[]
+ **** xref:rest-api:security/encryption-at-rest/force-encryption-at-rest.adoc[]
+ **** xref:rest-api:security/encryption-at-rest/drop-encryption-deks.adoc[]
*** xref:rest-api:rest-authorization.adoc[Authorization API]
**** xref:rest-api:rbac.adoc[Role-Based Access Control (RBAC)]
diff --git a/modules/introduction/partials/new-features-80.adoc b/modules/introduction/partials/new-features-80.adoc
index d875f9a19f..cf63221f86 100644
--- a/modules/introduction/partials/new-features-80.adoc
+++ b/modules/introduction/partials/new-features-80.adoc
@@ -1,8 +1,6 @@
[#section-new-feature-800-couchbase-cluster]
=== Couchbase Cluster
-
-
https://jira.issues.couchbase.com/browse/MB-61457[MB-61457]::
The following settings have been added to the `/pools/default/buckets` REST APIs.
+
@@ -165,3 +163,10 @@ It is now possible to change the plan used by a repository.
The repository first needs to be paused, and then the plan can be changed,
and the repository resumed, where it will now execute the tasks from its new plan.
+=== Security
+
+https://jira.issues.couchbase.com/browse/MB-16143[MB-16143]::
+Couchbase Server Enterprise now supports native encryption at rest.
+You can encrypt bucket data, audits, and most logging and configuration information.
+You choose which buckets to encrypt and which remain unencrypted.
+See xref:learn:security/native-encryption-at-rest-overview.adoc[] for more information.
diff --git a/modules/learn/assets/images/security/encryption-at-rest-key-hierarchy.drawio b/modules/learn/assets/images/security/encryption-at-rest-key-hierarchy.drawio
new file mode 100644
index 0000000000..d0beb8066d
--- /dev/null
+++ b/modules/learn/assets/images/security/encryption-at-rest-key-hierarchy.drawio
@@ -0,0 +1,192 @@
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
diff --git a/modules/learn/assets/images/security/encryption-at-rest-key-hierarchy.svg b/modules/learn/assets/images/security/encryption-at-rest-key-hierarchy.svg
new file mode 100644
index 0000000000..378d4e92eb
--- /dev/null
+++ b/modules/learn/assets/images/security/encryption-at-rest-key-hierarchy.svg
@@ -0,0 +1,4 @@
+
+
+
+
\ No newline at end of file
diff --git a/modules/learn/pages/security/authentication-domains.adoc b/modules/learn/pages/security/authentication-domains.adoc
index 4ec382aed6..97a9cc0be4 100644
--- a/modules/learn/pages/security/authentication-domains.adoc
+++ b/modules/learn/pages/security/authentication-domains.adoc
@@ -10,16 +10,17 @@
Couchbase Server authenticates each user by means of one of two _authentication domains_.
The domains are:
-* _Local_: Contains users defined locally.
+[#local-domain]
+* Local: Contains users defined locally.
This includes:
- ** The _Full Administrator_ for Couchbase Server.
+ ** The Full Administrator for Couchbase Server.
- ** _Locally Defined Users_, which are explicitly created by a Couchbase Server administrator; and each feature a username and password unique within the Local domain.
+ ** Locally Defined Users, which are explicitly created by a Couchbase Server administrator; and each feature a username and password unique within the Local domain.
- ** _Internal Components_ within Couchbase Server that support core functionality (for example, indexing, searching, and replicating), and run with full administrative privileges.
+ ** Internal Components within Couchbase Server that support core functionality (for example, indexing, searching, and replicating), and run with full administrative privileges.
- ** _Generated Users_, which are created by Couchbase Server as part of the upgrade process from pre-5.0 to 5.0 and post-5.0 versions; each in correspondence with a legacy bucket.
+ ** Generated Users, which are created by Couchbase Server as part of the upgrade process from pre-5.0 to 5.0 and post-5.0 versions; each in correspondence with a legacy bucket.
Each Generated User is assigned a _username_ that is identical to the bucket-name; and either a _password_ that is identical to the bucket's pre-5.0 password, or _no password_, if the bucket did not feature a password.
Generated Users are created to ensure that legacy applications can continue to access legacy buckets after upgrade to 5.0 or post-5.0, with the same username-password combination being used for authentication.
+
diff --git a/modules/learn/pages/security/encryption-overview.adoc b/modules/learn/pages/security/encryption-overview.adoc
index 609cf7f517..9b8242ee72 100644
--- a/modules/learn/pages/security/encryption-overview.adoc
+++ b/modules/learn/pages/security/encryption-overview.adoc
@@ -1,91 +1,91 @@
= Encryption
-:description: pass:q[Couchbase Server uses _encryption_, to protect data.]
+:description: pass:q[Couchbase Server lets you use encryption to protect data.]
+:page-toclevels: 2
[abstract]
{description}
+You can configure network encryption for communications with clients, between nodes in the cluster, and with other clusters when using Cross-Datacenter Replication (XDCR).
+Couchbase Server supports encrypting data stored on disk to limit data exposure.
+You can also have your application store encrypted attributes in documents.
+This topic provides an overview of the encryption features in Couchbase Server.
-[#encryption-in-couchbase-server]
-== Encryption in Couchbase Server
-
-By means of _encryption_, data is encoded such that it is non-readable, other than by authorized parties who possess the appropriate means of _decryption_.
-Prior to decryption, therefore, encrypted data can be securely saved or transmitted.
-This ensures the privacy of user-data, and the integrity of servers and their clients.
-
-Couchbase Server provides extensive support for data encryption and decryption.
-Multiple areas of the system are affected: therefore, essential information is distributed throughout the documentation set.
-
-[#areas-of-encryption]
-== Areas of Encryption
-
-The principal areas of Couchbase Server encryption-support are listed below, along with links to further information.
[#encryption-on-the-wire]
-=== Encryption on the Wire
-
-This allows data to pass in encrypted form between nodes, between clusters, and between a cluster and its clients.
+== Network Encryption
-* *Node-to-Node Encryption*.
-Network traffic between the individual nodes of a Couchbase-Server cluster can be encrypted, in order to optimize cluster-internal security.
-See xref:learn:clusters-and-availability/node-to-node-encryption.adoc[Node-to-Node Encryption].
+You can choose to encrypt client connections, intra-node connections, and cluster-to-cluster connections.
+You configure each connection type separately.
+For example, you can choose to encrypt client connections, but leave connections between nodes in a cluster unencrypted.
-* *On-the-Wire Security Configuration*.
-To support secure communications between nodes, clusters, and clients, Couchbase Server provides interfaces for the configuration of _TLS_ and supportive _cipher-suites_; of cluster-internal encryption-levels; and of secure UI-access.
-See xref:learn:security/on-the-wire-security.adoc[On-the-Wire Security] for a conceptual overview, and xref:manage:manage-security/manage-tls.adoc[Manage On-the-Wire Security] for step-by-step configuration-instructions.
+Couchbase Server supports the following types of network encryption:
-* *Secure Console Access*.
-Administrators can connect securely to Couchbase Web Console.
-Non-secure access can be disabled, for extra security.
-See xref:manage:manage-security/manage-console-access.adoc[Manage Console Access].
+Node to Node::
+You can choose to encrypt all internal traffic between nodes in the cluster.
+This configuration helps limit data leakage from network intrusions.
+See xref:learn:clusters-and-availability/node-to-node-encryption.adoc[].
-* *X.509 Certificates*.
-These support encrypted communications between nodes, between clusters, and between a cluster and its clients.
-** xref:learn:security/certificates.adoc[Certificates] provides an overview of certificates and their management.
+Client Connections::
+You can make encryption optional or required for client connections.
+See xref:manage:manage-security/configure-client-certificates.adoc#enabling-client-security[Securing Client Access with TLS].
-** xref:manage:manage-security/configure-server-certificates.adoc[Configure Server Certificates] explains the practical steps towards configuring certificates for Couchbase Server.
-This page also provides information on working with different versions of SSL/TLS, and on supported _ciphers_.
+Couchbase Server Web Console Access::
+You can configure the Web Console to require secure connections.
+See xref:manage:manage-security/manage-console-access.adoc[].
-** xref:manage:manage-security/configure-client-certificates.adoc[Configure Client Certificates] describes how to create a certificate to allow a client's secure access to Couchbase Server.
+Secure Access to Services::
+You can configure Couchbase Server services to only use secure ports.
+See xref:install:install-ports.adoc[].
-** xref:manage:manage-security/enable-client-certificate-handling.adoc[Enable Client-Certificate Handling] explains how to configure Couchbase Server to accept communications from clients that wish to authenticate and communicate securely by means of certificates.
+Secure XDCR Replication::
+You can encrypt XDCR replication between Couchbase Server clusters.
+See xref:manage:manage-xdcr/enable-full-secure-replication.adoc[].
-** xref:manage:manage-security/rotate-server-certificates.adoc[Certificate Rotation] provides steps whereby server certificates can be _rotated_ periodically, to ensure optimal security.
+Couchbase Server TLS Support::
+Couchbase Server uses Transport Layer Security (TLS) with a selection of cipher-suites for network encryption.
+See the following pages for more information about Couchbase Server's TLS support:
++
+* xref:learn:security/on-the-wire-security.adoc[] provides a conceptual overview of TLS in Couchbase Server.
+* xref:manage:manage-security/manage-tls.adoc[] has step-by-step configuration instructions.
+* xref:manage:manage-security/manage-connections-and-disks.adoc[] has a general overview of network security best practices.
-** xref:manage:manage-security/handle-certificate-errors.adoc[Certificate Error Handling] explains how to handle errors related to certificate-based secure communication.
-** xref:manage:manage-xdcr/enable-full-secure-replication.adoc[Enable Fully Secure Replications] describes how certificates can be used to ensure that data is replicated securely between clusters.
+[#encryption-at-rest]
+== Encryption at Rest
-** xref:rest-api:rest-certificate-management.adoc[Certificate Management API] lists the REST API methods and URIs available for certificate management.
+Encryption at rest encrypts files stored on disk.
+The files you can encrypt include those that store database data, configuration, logs, and audits.
+Encrypting data at rest can help limit the exposure of confidential information from a security breach.
-** The xref:cli:cbcli/couchbase-cli-ssl-manage.adoc[ssl-manage] CLI command supports management of SSL certificates.
+You have several options to encrypt your data at rest:
-* *Secure Ports*.
-Services are available on secure ports.
-See xref:install:install-ports.adoc[Couchbase Server Ports].
+Use the Couchbase Server native encryption at-rest feature::
+Couchbase Server Enterprise has a built-in encryption-at-rest feature where it encrypts data as it saves it to disk.
+Using the built-in encryption lets you fine-tune which data is encrypted and which it not.
+For example, you can choose to encrypt sensitive customer data, while leaving less sensitive data, such as product catalog data, unencrypted.
+By encrypting just the sensitive data in your database, you can limit the overhead of encrypting and decrypting data.
+See xref:learn:security/native-encryption-at-rest-overview.adoc[] for more information.
-* *General Network Security*.
-Best practices for ensuring the security of the network are provided in xref:manage:manage-security/manage-connections-and-disks.adoc[Network Security Recommendations].
+Use third-party tools::
+Third party tools such as https://cpl.thalesgroup.com/encryption/transparent-encryption[Thales CipherTrust^] (formerly known as Vormetric/Gemalto) and https://www.protegrity.com/[Protegrity^] can provide centralized encryption at rest.
-[#encryption-at-rest]
-=== Encryption at Rest
+Use OS-level disk encryption::
+You can use disk encryption such as the LUKS encrypted filesystem which is available on Linux.
+See xref:manage:manage-security/manage-connections-and-disks.adoc#securing-on-disk-data[Securing On-Disk Data].
-Encryption _at Rest_ (meaning, on disk or other storage-device) allows passwords and data in files and directories to be encrypted.
-* *Data in Files and Directories*.
-Programs are available for the encryption of data in files and directories.
-See xref:manage:manage-security/manage-connections-and-disks.adoc#securing-on-disk-data[Securing On-Disk Data].
+== System Secrets
-* *System Secrets*.
-Passwords, certificates, and other items essential to Couchbase-Server security can be written to disk in encrypted format.
+Couchbase Server can write passwords, certificates, and other sensitive information to disk in encrypted format.
See xref:manage:manage-security/manage-system-secrets.adoc[Manage System Secrets].
[#encryption-in-applications]
-=== Encryption in Applications
+== Encryption in Applications
-* *Field Level Encryption*.
-This allows fields within a document to be securely encrypted by the SDK, to support FIPS-140-2 compliance.
-See xref:java-sdk:howtos:encrypting-using-sdk.adoc[Field Level Encryption], for an overview.
+Applications can use the SDK to store fields in encrypted format.
+See the SDK documentation for your development language for more information.
+For example:
-* *Field Level Encryption from the Java SDK*.
-Provides directions for configuring encrypted field-level communication with Couchbase Server.
-See xref:java-sdk:concept-docs:encryption.adoc[Field Level Encryption from the Java SDK].
+* Go SDK: xref:go-sdk:howtos:encrypting-using-sdk.adoc[]
+* Java SDK: xref:java-sdk:howtos:encrypting-using-sdk.adoc[]
+* Python SDK: xref:python-sdk:howtos:encrypting-using-sdk.adoc[]
diff --git a/modules/learn/pages/security/native-encryption-at-rest-overview.adoc b/modules/learn/pages/security/native-encryption-at-rest-overview.adoc
new file mode 100644
index 0000000000..7400cde2f2
--- /dev/null
+++ b/modules/learn/pages/security/native-encryption-at-rest-overview.adoc
@@ -0,0 +1,220 @@
+= Native Encryption at Rest Overview
+:description: Couchbase Server can encrypt data, configuration, logs, and audit information it saves to disk. This encryption can help reduce the chances of or severity of data breaches.
+:page-toclevels: 2
+:page-edition: Enterprise Edition
+
+[abstract]
+{description}
+This feature is transparent to the database's users.
+Couchbase Server automatically decrypts data when reading it from disk and encrypts it when writing it to disk.
+For steps to take when managing this feature, see xref:manage:manage-security/manage-native-encryption-at-rest.adoc[].
+
+[#keys]
+== Encryption-at-Rest Keys
+
+To encrypt data at rest, you must create at least one encryption key.
+Couchbase Server uses the keys you create directly to encrypt Data Encryption Keys (DEKs) which uses to encrypt the information it stores on disk.
+This two-layer system lets Couchbase Server manage the rotation and expiration of the DEKs, even when another system manages the encryption keys.
+
+You have two primary choices to make when creating an encryption key:
+
+* What system you want to manage the key.
+You can have Couchbase Server manage encryption keys or have a third-party Key Management Service (KMS) manage them.
+See <<#kms>> for more information about choosing a KMS.
+
+* What data Couchbase Server can use the encryption key to encrypt.
+You can restrict the key to encrypting one or more types of data:
+
++
+** **Other encryption keys:**
+Enabling a key to encrypt other encryption-at-rest keys makes it a Key Encryption Key (KEK).
+KEKs are useful when you want to use multiple layers of encryption keys.
+For example, you can use a KEK managed by a third-party KMS as a primary encryption key that encrypts keys managed by Couchbase Server.
+** **Buckets:**
+You can enable a key to encrypt all buckets or restrict it to specific buckets.
+** **Configuration:**
+By default, Couchbase Server uses the xref:manage:manage-security/manage-system-secrets.adoc#setting-the-master-password[master password] to encrypt configuration data.
+You can choose to use an encryption-at-rest key instead.
+** **Logs:**
+You can choose to use an encryption-at-rest key to encrypt logs.
+You can also use the master password instead.
+** **Audits:**
+As with configuration and log data, you can choose to use an encryption-at-rest key or the master password to encrypt audit data.
+
+The following sections explain these choices in greater detail.
+
+== Encrypting Bucket Data
+
+When using native encryption at rest to encrypt data in buckets, you choose which buckets to encrypt.
+For example, you can decide to just encrypt buckets containing sensitive data (such as customer information).
+Then you would leave less-sensitive data unencrypted, such as product catalog data.
+Encrypting just sensitive data can help reduce the overhead of encrypting and decrypting data on your cluster.
+
+Each bucket can have its own encryption key.
+This configuration is useful in multi-tenancy configurations where each customer may want to manage their own encryption key.
+
+== Encrypting Audit, Logs, and Configuration Data
+
+In addition to data, you can encrypt audit, logs, and most configuration data.
+You enable the encryption of each of these types of data separately.
+You can use either an encryption-at-rest key or the master password to encrypt data.
+By default, Couchbase Server uses the master password to configuration data.
+Couchbase Server does not set the master password by default.
+You must set it on each node in the cluster.
+See xref:manage:manage-security/manage-system-secrets.adoc#setting-the-master-password[Setting the Master Password] for more information about the master password.
+
+[NOTE]
+====
+Some configuration data cannot be encrypted.
+This includes:
+
+* Bootstrap information
+* Node and internal client certificates
+* Prometheus configuration, metric data, and tokens used to gather metrics
+====
+
+[#when-data-is-encrypted]
+== When Couchbase Server Encrypts Data
+
+When you enable encryption at rest for a bucket or a type of system data, Couchbase Server encrypts all of the data it writes.
+However, it does not encrypt existing data in the bucket or already written system data.
+For example, if you enable encryption at rest for logs, Couchbase Server encrypts new log entries but does not encrypt existing log entries.
+Existing unencrypted data in buckets is encrypted when its mutated or compacted.
+
+You can use the REST API to force Couchbase Server to encrypt existing unencrypted data.
+See xref:rest-api:security/encryption-at-rest/force-encryption-at-rest.adoc[] for more information.
+
+Similarly to enabling encryption, when you turn off encryption at rest, Couchbase Server does not immediately decrypt all encrypted data.
+It stops encrypting the new data it writes but does not decrypt and rewrite the existing encrypted data.
+It still decrypts encrypted data as it reads it.
+It only rewrites data in an unencrypted format when updating data.
+You can use the same REST API call to force Couchbase Server to decrypt and rewrite the all of the data.
+See xref:rest-api:security/encryption-at-rest/force-encryption-at-rest.adoc[] for more information.
+
+[#kms]
+== Encryption Key Management Services
+
+A key management service (KMS) creates, stores, and manages the lifecycle of encryption keys.
+Couchbase Server uses a KMS to manage its encryption-at-rest keys.
+It uses these keys to encrypt and decrypt data encryption keys (DEKs) which are the keys nodes use to encrypt and decrypt the data they store on disk.
+
+When you create an encryption-at-rest key, you choose which KMS you want to manage it.
+Couchbase Server works with several KMSs:
+
+Couchbase Server Secret Management::
+You can have Couchbase Server act as a KMS.
+When you use Couchbase Server as a KMS, it generates, stores, and manages the encryption keys it uses to encrypt DEKs.
+
++
+When Couchbase Server manages the keys, it stores them locally in an encrypted format.
+You can use the master password to encrypt encryption-at-rest keys.
+See xref:manage:manage-security/manage-system-secrets.adoc#setting-the-master-password[Setting the Master Password] for more information about the master password.
+This password is not set by default--you must configure it for each node.
+See xref:manage:manage-security/manage-system-secrets.adoc[] for more information about the master password.
+
++
+You can also use an encryption key managed by another KMS as a key encryption key (KEK) to encrypt the keys that Couchbase Server manages.
+In this configuration, Couchbase Server relies on the remote KMS to decrypt its encryption keys.
+This is the recommended configuration when using an external KMS.
+It limits the number of encryption and decryption requests Couchbase Server has to send to the external KMS.
+After Couchbase Server has the KMS decrypt its own encryption keys, it can use them to encrypt and decrypt DEKs locally.
+
+AWS Key Management Service::
+You can use the https://docs.aws.amazon.com/kms/latest/developerguide/overview.html[AWS Key Management Service] (AWS KMS) to manage keys for you.
+This method enhances security by keeping the encryption keys stored in AWS rather than on the Couchbase Server cluster.
+Couchbase Server sends encryption and decryption requests to the AWS KMS.
+One downside of using the AWS KMS is that the cluster relies on an external source for encryption.
+Disruptions in AWS or the network can result in errors because the Couchbase Server cannot encrypt or decrypt data encrypted using the keys managed by AWS.
+Using AWS KMS can also cause latency issues if Couchbase Server relies on it for many encryption keys.
+See <<#aws-kms-caution>> for more information.
+
+
+KMSs that support Key Management Interoperability Protocol (KMIP)::
+https://en.wikipedia.org/wiki/Key_Management_Interoperability_Protocol[KMIP] is a standards protocol implemented by key management services.
+Couchbase Server can work with any KMS that implements this standard.
+As with AWS KMS, using a KMIP-compliant KMS enhances security by storing the encryption keys remotely instead of locally in the cluster.
+It also has the same downside--Couchbase Server may report errors due to KMS downtime or network issues.
+
+
+[#aws-kms-caution]
+[CAUTION]
+.Remote KMS Best Practice
+====
+Do not assign encryption keys managed by AWS KMS or a KMIP KMS to encrypt Couchbase Server data.
+When you assign an encryption key to encrypt a particular type of data, Couchbase Server uses the key to encrypt the DEKs each node uses to encrypt the data.
+If a DEK is encrypted with a key managed by an external KMS, Couchbase Server has to send a request to the KMS to decrypt the DEK.
+These requests to a remote KMS can take less than a second.
+However, a starting cluster needs to decrypt all of the DEKs on all nodes.
+The volume of these synchronous requests can result in a significant delay in starting the cluster.
+
+To avoid this issue, only use AWS KMS or a KMIP KMS encryption keys to encrypt encryption-at-rest keys managed by Couchbase Server.
+You then assign these Couchbase Server managed keys to encrypt data.
+This method reduces the number of requests to the remote KMS.
+Once Couchbase Server has the KMS decrypt its encryption keys, it can decrypt the DEKs locally.
+
+See <<#kms-and-keys>> for more information about using multiple KMSs and multiple keys.
+====
+
+[#kms-and-keys]
+== Using Multiple KMSs and Multiple Keys
+
+In a basic setup, you may choose to use a single encryption key managed by Couchbase Server to encrypt all data.
+This configuration is easy to manage, but does not offer much flexibility.
+
+Couchbase Server does not limit you to a single KMS.
+You can choose any KMS onfigured for each encryption key.
+For example, you can choose to create one or more encryption keys managed by AWS KMS or a KMIP-compliant KMS.
+Then use these keys as Key Encryption Keys (KEKs) to encrypt keys that Couchbase Server manages.
+This method adds a layer of security to the locally managed encryption keys while reducing the number of key retrievals from the remote KMS.
+
+The following diagram shows a possible configuration using a single primary encryption key hosted by AWS KMS.
+This key encryption key encrypts 5 encryption-at-rest keys managed by Couchbase Server.
+Each of these keys encrypt the DEKs that encrypt the different types of data that's written to disk: audit, configuration, and log data and the data stored in 2 buckets named A and B.
+Each node in the cluster has Data Encryption Keys (DEKs) encrypted by the intermediate encryption keys managed by Couchbase Server.
+For simplicity, the diagram only shows 2 nodes.
+However, this configuration can scale to any size cluster.
+
+
+image::security/encryption-at-rest-key-hierarchy.svg["Diagram showing a single AWS key encrypting 5 Couchbase Server managed KEKs which in turn encrypt DEKs on each node"]
+
+You can have even more complex hierarchies where there are several keys hosted by AWS KMS or a KMIP KMS.
+
+
+[#rotation-expiration]
+== Encryption Key Rotation and Expiration
+
+Key rotation periodically deactivates old keys and generates new encryption keys to replace them.
+Frequent rotations limit the amount of data encrypted with any particular key.
+It helps limit the exposure of data if a data breach compromises an encryption key.
+
+You can choose to have Couchbase Server rotate DEKs automatically.
+You can also have it automatically rotate encryption keys that it manages.
+Rotation of an externally managed encryption key is handled by the KMS that manage it.
+AWS transparently rotates its keys, while keeping the key ID the same.
+So, from Couchbase Server's perspective, the key does not change.
+KMIP compatible KMSs have their own rotation schemes and may require you to manually rotate keys or update the key IDs in Couchbase Server after rotation.
+See your KMS's documentation for more information about how it handles key rotation.
+
+When Couchbase Server rotates a DEK, it generates a new DEK and uses the active encryption key to encrypt it.
+
+By default, Couchbase Server automatically rotates DEKs but not the encryption keys it manages.
+You choose how frequently Couchbase Server rotates DEKs and (if you enable it) the encryption keys it manages.
+
+When Couchbase Server generates a new encryption key or DEK during rotation, it does not immediately delete the deactivated key.
+It keeps deactivated keys so it can decrypt the data encrypted with it.
+It uses the new key to encrypt data as it writes it to disk.
+When rotating DEKs, Couchbase Server does not re-encrypt existing data unless it's mutated.
+
+Couchbase Server only deletes a deactivated DEK when either:
+
+* No data uses the DEK for encryption.
+Once the last piece of data that relies on the deactivated DEK for decryption is either mutated or deleted, Couchbase Server deletes the unused DEK.
+
+* The DEK's lifetime elapses.
+You can set a maximum lifetime for DEKs which limits how long Couchbase Server can keep it after rotation.
+When a DEK's lifetime elapses, Couchbase Server uses the active DEK to re-encrypt data that's still encrypted with the DEK.
+It then deletes the expired DEK.
+
+You can adjust the rotation and lifetime for encryption keys to suit your environment.
+
+See xref:manage:manage-security/manage-native-encryption-at-rest.adoc[] to learn how to manage native encryption at rest.
diff --git a/modules/learn/partials/encryption-key-hierarhy-diagram.adoc b/modules/learn/partials/encryption-key-hierarhy-diagram.adoc
new file mode 100644
index 0000000000..b445238a56
--- /dev/null
+++ b/modules/learn/partials/encryption-key-hierarhy-diagram.adoc
@@ -0,0 +1,80 @@
+// Note: this was redone in Darwio. Probably need to delete this later.
+
+[graphviz,encryption-at-rest-key-diagram,svg]
+....
+
+digraph kms_couchbase_keys {
+ rankdir=TB;
+ ranksep=1.0;
+ nodesep=0.5;
+ node [shape=box, style=filled, fillcolor=white, fontname="Sans"];
+
+ // Top-level CMK
+ CMK [label="AWS KMS\nPrimary Key Encryption Key"];
+
+ subgraph cluster_cbkeys {
+ label = "Couchbase Server Managed Keys";
+ K_Log [label="Encryption Key\nfor Logs"];
+ K_Audit [label="Encryption Key\nfor Audit"];
+ K_Config [label="Encryption Key\nfor Config"];
+ K_BA [label="Encryption Key\nfor Bucket A"];
+ K_BB [label="Encryption Key\nfor Bucket B"];
+
+ { rank = same; K_Log; K_Audit; K_Config; K_BA; K_BB }
+}
+ // CMK to KEKs
+ CMK -> K_Log;
+ CMK -> K_Audit;
+ CMK -> K_Config;
+ CMK -> K_BA;
+ CMK -> K_BB;
+
+ // Node 1 cluster
+ subgraph cluster_node1 {
+ ranksep=0.5;
+ label = "Node 1";
+ DEK_Log1 [label="DEK: Logs"];
+ DEK_Audit1 [label="DEK: Audit"];
+ DEK_Config1 [label="DEK: Config"];
+ DEK_A1 [label="DEK: Bucket A"];
+ DEK_B1 [label="DEK: Bucket B"];
+ }
+
+DEK_Log1 -> DEK_Audit1 [style=invis];
+DEK_Audit1 -> DEK_Config1 [style=invis];
+DEK_Config1 -> DEK_A1 [style=invis];
+DEK_A1 -> DEK_B1 [style=invis];
+
+ // Node 2 cluster
+ subgraph cluster_node2 {
+ label = "Node 2";
+ DEK_Log2 [label="DEK: Logs"];
+ DEK_Audit2 [label="DEK: Audit"];
+ DEK_Config2 [label="DEK: Config"];
+ DEK_A2 [label="DEK: Bucket A"];
+ DEK_B2 [label="DEK: Bucket B"];
+ }
+
+DEK_Log2 -> DEK_Audit2 [style=invis];
+DEK_Audit2 -> DEK_Config2 [style=invis];
+DEK_Config2 -> DEK_A2 [style=invis];
+DEK_A2 -> DEK_B2 [style=invis];
+
+ // Connections to Node 1
+ K_Log -> DEK_Log1;
+ K_Audit -> DEK_Audit1;
+ K_Config -> DEK_Config1;
+ K_BA -> DEK_A1;
+ K_BB -> DEK_B1;
+
+ // Connections to Node 2
+ K_Log -> DEK_Log2;
+ K_Audit -> DEK_Audit2;
+ K_Config -> DEK_Config2;
+ K_BA -> DEK_A2;
+ K_BB -> DEK_B2;
+
+DEK_Log1 -> DEK_Log2 [style=invis]; // Force node 1 to left
+
+}
+....
\ No newline at end of file
diff --git a/modules/manage/assets/images/manage-buckets/addBucketWithMagmaOption.png b/modules/manage/assets/images/manage-buckets/addBucketWithMagmaOption.png
index ea02f57115..4da723e6b8 100644
Binary files a/modules/manage/assets/images/manage-buckets/addBucketWithMagmaOption.png and b/modules/manage/assets/images/manage-buckets/addBucketWithMagmaOption.png differ
diff --git a/modules/manage/assets/images/manage-security/add-encryption-key-dialog.png b/modules/manage/assets/images/manage-security/add-encryption-key-dialog.png
new file mode 100644
index 0000000000..b9fcfc77cb
Binary files /dev/null and b/modules/manage/assets/images/manage-security/add-encryption-key-dialog.png differ
diff --git a/modules/manage/assets/images/manage-security/add-encryption-key-uses.png b/modules/manage/assets/images/manage-security/add-encryption-key-uses.png
new file mode 100644
index 0000000000..fd26b452a5
Binary files /dev/null and b/modules/manage/assets/images/manage-security/add-encryption-key-uses.png differ
diff --git a/modules/manage/assets/images/manage-security/encryption-at-rest-details.png b/modules/manage/assets/images/manage-security/encryption-at-rest-details.png
new file mode 100644
index 0000000000..8cad2a502c
Binary files /dev/null and b/modules/manage/assets/images/manage-security/encryption-at-rest-details.png differ
diff --git a/modules/manage/assets/images/manage-security/encryption-at-rest-page.png b/modules/manage/assets/images/manage-security/encryption-at-rest-page.png
new file mode 100644
index 0000000000..d854d02e81
Binary files /dev/null and b/modules/manage/assets/images/manage-security/encryption-at-rest-page.png differ
diff --git a/modules/manage/pages/manage-buckets/create-bucket.adoc b/modules/manage/pages/manage-buckets/create-bucket.adoc
index 7290327995..2c61fa236b 100644
--- a/modules/manage/pages/manage-buckets/create-bucket.adoc
+++ b/modules/manage/pages/manage-buckets/create-bucket.adoc
@@ -2,6 +2,7 @@
:description: pass:q[_Full_ and _Cluster_ Administrators can use Couchbase Web Console, the CLI, or the REST API to create a bucket.]
:page-aliases: clustersetup:create-bucket
:page-topic-type: guide
+:page-toclevels: 3
[abstract]
{description}
@@ -92,7 +93,12 @@ The available advanced settings for your bucket change based on your selected *B
* <>
[#couchbase-bucket-settings]
-==== Couchbase Bucket Settings
+==== Couchbase Bucket Advanced Settings
+
+The Couchbase Bucket advanced settings let you set options such as replication, compression, and flushing.
+
+[#add-data-bucket-dialog-expanded]
+image::manage-buckets/addBucketWithMagmaOption.png[,400,align=center, alt="An image that displays the Add Data Bucket dialog's Advanced bucket settings with the default selections for a Couchbase bucket."]
To configure advanced settings for a Couchbase bucket:
@@ -141,12 +147,14 @@ include::learn:partial$full-ejection-note.adoc[]
[#bucket-priority, start="6"]
. Choose a *Bucket Priority* for the bucket:
+
+--
* *Default*
* *High*
-
+--
+
Bucket Priority sets the priority of the bucket's background tasks relative to the background tasks of other buckets on the cluster.
++
Background tasks may involve disk I/O, DCP stream-processing, item-paging, and more.
Specifying High might result in faster processing for the current bucket's tasks.
This setting only takes effect when there is more than one bucket defined for the cluster, and you have assigned different Bucket Priority values.
@@ -168,12 +176,14 @@ For more information about durability, see xref:learn:data/durability.adoc[].
+
For more information about how to configure Auto-Compaction, see xref:manage:manage-settings/configure-compact-settings.adoc[].
+. To enable xref:learn:security/native-encryption-at-rest-overview.adoc[native encryption at rest], select the *Enable Encryption at Rest*, then select a key from the *Encryption Key* list.
+For more details about enabling encryption at rest, see xref:manage:manage-security/manage-native-encryption-at-rest.adoc[].
+
. To enable flushing for the bucket, under *Flush*, select the *Enable* checkbox.
+
For more information about flushing, see xref:manage-buckets/flush-bucket.adoc[Flush a Bucket].
-[#add-data-bucket-dialog-expanded]
-image::manage-buckets/addBucketWithMagmaOption.png[,400,align=center, alt="An image that displays the Add Data Bucket dialog, with a Couchbase Bucket Type and CouchStore Storage Backend selected. The Advanced bucket settings are expanded and to show the default selections for a Couchbase and Couchstore bucket."]
+
[#memcached-bucket-settings]
==== Memcached Bucket Settings
diff --git a/modules/manage/pages/manage-security/manage-native-encryption-at-rest.adoc b/modules/manage/pages/manage-security/manage-native-encryption-at-rest.adoc
new file mode 100644
index 0000000000..32e6422d03
--- /dev/null
+++ b/modules/manage/pages/manage-security/manage-native-encryption-at-rest.adoc
@@ -0,0 +1,544 @@
+= Manage Native Encryption at Rest
+:description: pass:q[Couchbase Server's native encryption at rest protects sensitive data by encrypting it when writing it to disk.]
+:tabs:
+:page-topic-type: guide
+:page-toclevels: 3
+:keywords: encryption at rest, security
+:page-edition: Enterprise Edition
+:page-topic-type: reference
+
+[abstract]
+{description}
+This feature is transparent to the database's users.
+Couchbase Server automatically decrypts data when read from disk and encrypts it when writing it to disk.
+
+You can encrypt:
+
+* All data in a non-ephemeral bucket
+* Logs
+* Configuration data
+* Audit data
+
+For an overview of native encryption at rest, see xref:learn:security/native-encryption-at-rest-overview.adoc[].
+
+== Enabling Encryption
+
+Enabling encryption at rest is a two step process:
+
+. Create at least one encryption key.
+You must use an encryption-at-rest key to encrypt bucket data.
+You can choose to use the xref:manage:manage-security/manage-system-secrets.adoc#setting-the-master-password[master password] instead of an encryption-at-rest key to encrypt audit, configuration, and log data.
+However, for the best security, you should use an encryption-at-rest key.
+. Enable encryption for one or more types of data.
+
+The following sections explain these steps in greater detail.
+
+[[create-keys]]
+== Creating Encryption Keys
+
+Couchbase Server only supports encrypting bucket data using an encryption at rest key.
+Therefore, you must create at least one encryption-at-rest key to encrypt bucket data.
+You should also consider creating encryption-at-rest keys when encrypting audit, configuration, and log data.
+
+=== Requirements
+
+For each key you create, you must choose a Key Management Service (KMS) that maintains the key for you.
+You have three options to choose from:
+
+* Amazon's AWS KMS
+* Any KMS that implements the Key Management Interoperability Protocol (KMIP)
+* Couchbase Server
+
+See xref:learn:security/native-encryption-at-rest-overview.adoc#kms[Encryption Key Management Services] for more information.
+
+You must decide what data your encryption key can encrypt.
+You can create an encryption key that can encrypt any data and other encryption keys.
+You can also choose to limit what data the key can be use to encrypt, or configure it to only encrypt other encryption keys.
+See learn:security/native-encryption-at-rest-overview.adoc#keys[Encryption-at-Rest Keys] for more information.
+
+You must have the proper privileges to create encryption keys.
+The role you need depends on what the key you're creating can encrypt:
+
+include::rest-api:partial$encryption-at-rest-key-write-roles.adoc[]
+
+
+=== Create an Encryption Key Using the Couchbase Server Web Console
+
+To create an encryption key using the Couchbase Server Web Console:
+
+. Click menu:Security[] on the main menu.
+. Click menu:Encryption at Rest[].
+The *Encryption at Rest* tab opens.
+
++
+image::manage-security/encryption-at-rest-page.png[]
+
+. Click btn:[Add Encryption Key] to open the *Add Encryption Key* dialog.
+
++
+image::manage-security/add-encryption-key-dialog.png[,400]
+
+
+. Enter a name for your key in the *Name* box.
+. If you want to limit what your key can encrypt, click *Configure* to expand the list of uses.
+Then choose what you want to your key to be able to encrypt.
+
++
+image::manage-security/add-encryption-key-uses.png[,300]
+
++
+If you want your key to only be able encrypt specific buckets, deselect *Data* and then select the buckets.
+
++
+IMPORTANT: If you're creating an encryption key managed by a KMIP KMS or AWS KMS, only leave *Key Encryption Key (KEK)* selected.
+Then use the key to encrypt an encryption key managed by Couchbase Server.
+Do not assign an encryption key managed by a remote KMS to directly encrypt data.
+See xref:learn:security/native-encryption-at-rest-overview.adoc#aws-kms-caution[this caution] for more information.
+
+. Under *Key Type*, choose the KMS you want to manage your key.
+The option you choose changes the fields in the rest of the dialog.
+
+. Depending on the KMS you chose, enter the details to complete creating the encryption key:
++
+[{tabs}]
+====
+AWS::
++
+--
+[start=8]
+. Enter the Amazon Resource Name (ARN) for the encryption key and the AWS Region in which the KMS is located.
+. Choose whether to use the AWS Instance Metadata Service.
+Enable this option if your Couchbase Server cluster runs on AWS EC2 instances to allow it to connect to other AWS services.
+. Enter the paths on your cluster where you have stored the AWS credential, configuration, and profile files.
+. Verify that your settings work by clicking the btn:[Test Encryption Key Settings] button.
+
+--
+
+KMIP::
++
+--
+To use a KMIP-compatible KMS:
+
+[start=8]
+. Enter the host and port number for the KMS server and choose a timeout for network connections.
+. Choose which certificates to use when verifying the identity of the KMS.
+You can choose to not verify the KMS's identity, however this is insecure.
+. Enter the details for the client certificate Couchbase Server uses to authenticate with the KMS.
+This information includes how to encrypt the certificate passphrase.
+. In the *KMIP Encryption/Decryption Approach* field, choose how Couchbase Server interacts with the KMS:
+
++
+* Select *Use KMIP Get & encrypt locally*, if you want Couchbase Server to retrieve the encryption key from the KMS and use it locally to decrypt keys and data.
+* Select *Use KMIP native Encrypt/Decrypt operation* to have Couchbase Server send the encrypted DEKs to the KMS so it can decrypt them.
+This method is more secure, because the encryption key does not leave the KMS.
+--
+
+Auto-Generated::
++
+--
+This option has Couchbase Server manage the key.
+To complete creating the key:
+
+[start=8]
+. Choose whether you want to use the cluster's master password or another encryption key to encrypt your new key.
+If you want to use another encryption key, it must be configured as a Key Encryption Key (KEK).
+. Decide whether you want Couchbase Server to cache the key.
+This setting lets Couchbase Server keep the key unencrypted in memory so it does not have to read and decrypt it for each encryption or decryption.
+Disabling this option increases processor resource use because Couchbase Server has to decrypt the key for each use.
+Disabling it does slightly improve security by reducing the chance of in-memory key exposure attacks.
+. Decide whether you want to have the encryption-at-rest key auto rotate.
+If you choose to rotate it, enter how often to rotate, a date and time for the first rotation.
+See xref:learn:secrutiy/native-encryption-at-rest-overview.adoc#rotation-expiration[Encryption Key Rotation and Expiration] for more information about key rotation.
+--
+
+====
+
+=== Create an Encryption Key Using the REST API
+
+The REST API's `/settings/encryptionKeys` endpoint lets you create and manage encryption keys.
+To create an encryption key, send a POST containing details of the key to this endpoint.
+
+The following example shows how to create an encryption key managed by Couchbase Server using the REST API:
+
+include::rest-api:example$encryption-at-rest/create-auto-generated-key.adoc[]
+
+Some of the parameters set in the example are:
+
+* `name`: the name you want to give the key.
+* `type`: the KMS you want to use to manage the key and the key's encryption algprithm.
+* `usage`: the type of data the key can encrypt.
+
+The `data` object content depends on the KMS you chose.
+For keys managed by Couchbase Server, the `data` object's content mainly set key rotation options.
+The example sets the `rotationIntervalInDays` to `90` and the date of the next rotation to July 1st 2025.
+
+The output of running the previous example looks like this:
+
+include::rest-api:example$encryption-at-rest/create-auto-generated-key-response.adoc[]
+
+See xref:rest-api:security/encryption-at-rest/manage-encryption-keys.adoc#create-key[Create or Update an Encryption-at-Rest Key] for details on how to create keys using the REST API.
+
+== Encrypt Data at Rest
+
+Once you have created an encrytion-at-rest key, you can use it to encrypt bucket data.
+For audit, configuration, and log data, you can choose to use the master password instead of an encryption-at-rest key.
+You must set the master password on each node before using it for encryption at rest.
+By default, the nodes do not have a master password.
+See xref:manage:manage-security/manage-system-secrets.adoc#setting-the-master-password[Setting the Master Password] for more information.
+
+NOTE: Once you enable encryption for a bucket or system data, Couchbase Server begins to encrypt data as it writes it.
+It does not encrypt the data that existed before you enabled encryption.
+See xref:learn:security/native-encryption-at-rest-overview.adoc#when-data-is-encrypted[When Couchbase Server Encrypts Data] for more information when Couchbase Server encrypts and decrypts data.
+
+The following sections explain how to enable encryption for each type of data.
+
+=== Encrypt Bucket Data
+
+To encrypt a bucket, you must have at least one encrytion-at-rest key configured to encrypt all buckets or the specific bucket you want to encrypt.
+See <> for more information about creating encryption-at-rest keys.
+
+Users with xref:learn:security/roles.adoc#bucket-admin[Bucket Admin] or xref:learn:security/roles.adoc#cluster-admin[Cluster Admin] roles can enable encryption for rest for buckets as long as an encryption key exists that's allowed to encrypt the bucket.
+
+NOTE: Once you enable encryption for a bucket, Couchbase Server begins to encrypt data as it writes it.
+It does not encrypt the data that existed in the bucket before you enabled encryption.
+See xref:learn:security/native-encryption-at-rest-overview.adoc#when-data-is-encrypted[When Couchbase Server Encrypts Data] for more information when Couchbase Server encrypts and decrypts data.
+
+==== Encrypt a Bucket Using the Couchbase Server Web Console
+. On the main menu, select menu:Buckets[].
+. You can encrypt a bucket when you create it or you can edit an existing bucket to encrypt it.
++
+--
+For an existing bucket:
+
+a. Click the name of the bucket you want to encrypt.
+a. Click btn:[Edit].
+
+For a new bucket:
+
+a. Click btn:[Add Bucket] to open the *Create Bucket* dialog.
+--
+
+. In the *Edit Bucket Settings* or *Add Data Bucket* dialog, expand the *Advanced bucket settings* section.
+. Select the *Enable Encryption at Rest*.
+. In the *Available Encryption Keys* list, select the encryption key you want to use to encrypt the bucket.
+. Configure the *DEK Rotation Interval* and *DEK Life Time* settings to configure the data encryption key rotation.
+See xref::learn:security/native-encryption-at-rest-overview.adoc#rotation-expiration[Encryption Key Rotation and Expiration] for more information about these settings.
+. Click btn:[Add Bucket] or btn:[Save Changes] to save your changes.
+
+==== Encrypt a Bucket Using the REST API
+When creating a bucket, you can set the `encryptionAtRestKeyId` parameter to the ID of the encryption key you want to use to encrypt the bucket:
+
+include::rest-api:example$encryption-at-rest/bucket-encryption-examples.adoc[tag=create-bucket]
+
+When updating an existing bucket, you can set the `encryptionAtRestKeyId` parameter to the ID of the encryption key you want to use to encrypt the bucket:
+
+include::rest-api:example$encryption-at-rest/bucket-encryption-examples.adoc[tag=alter-bucket]
+
+If the bucket is already encrypted, Couchbase Server re-encrypts the bucket's data encryption keys (DEKs) using the newly-assigned encryption key.
+If the bucket is not encrypted, Couchbase Server begins encrypting its data.
+
+See xref:rest-api:rest-bucket-create.adoc[] for more information about creating and updating buckets using the REST API.
+
+=== Encrypt Audit, Configuration, and Log Data
+
+You can encrypt audit, configuration, and log data using the master password or an encryption-at-rest key.
+By default, Couchbase Server encrypts the configuration data using the master password.
+
+To make changes to the encryption settings for audit, configuration, and log data, you must have the xref:learn:security/roles.adoc#full-admin[Full Admin] or xref:learn:security/roles.adoc#security-admin[Security Admin] roles.
+
+==== Change Audit, Configuration, or Log Encryption Settings via the Web Console
+To change the settings for audit, configuration, and log data via the Couchbase Server Web Console:
+
+. Click menu:Security[] on the main menu.
+. Click menu:Encryption at Rest[].
+. Click btn:[Edit] under *Configuration Encryption*, *Logs Encryption*, or *Audit Encryption* depending on the type of data whose encryption settings you want to change.
+. In the *Encryption at Rest* dialog, change the encryption-at-rest settings:
+
++
+--
+To Disable Encryption::
+Select *Disabled*
+
+To Use the Master Password::
+Select *Master Password*
+
+To Use an Encryption-at-Rest Key::
+a. Select *Encryption Key*.
+
+a. Under *Available Encryption Keys*, select the encryption key you want to use.
+You must have a key that you configured to encrypt the type of data you selected.
+a. Optionally change the *DEK Rotation Interval* and *DEK Life Time* settings to configure the data encryption key rotation.
+See xref::learn:security/native-encryption-at-rest-overview.adoc#rotation-expiration[Encryption Key Rotation and Expiration] for more information about these settings.
+--
+. Click btn:[Save Changes] to save your changes.
+
+
+==== Change Audit, Configuration, or Log Encryption Settings via the REST API
+
+The REST API's `/settings/security/encryptionAtRest` endpoint lets you change the settings for audit, configuration, and log data encryption.
+To change the settings, send a POST request to this endpoint with settings for each type of data you whose encryption you want to change.
+The following example shows how to enabled encryption at rest for audit data using an encryption-at-rest key whose `id` is `0`:
+
+include::rest-api:example$encryption-at-rest/system-encryption-examples.adoc[tag=encrypt-data-with-key]
+
+TIP: You can find the `id` attribute of the encryption-at-rest key you want to use by sending a GET request to the `/settings/encryptionKeys` endpoint.
+See xref:rest-api:security/encryption-at-rest/manage-encryption-keys.adoc#list-keys[List Encryption-at-Rest Keys] for more information about this endpoint.
+
+For more information about managing encryption at rest settings for audit, configuration, and log data, see xref:rest-api:security/encryption-at-rest/manage-system-encryption-at-rest.adoc[].
+
+== Viewing Encryption Status
+
+You can view the status of encryption at rest for a bucket, audit, configuration, and log data using the Couchbase Server Web Console or the REST API.
+
+=== Viewing Encryption Status Using the Couchbase Server Web Console
+
+
+To view the status of encryption at rest for a bucket using the Couchbase Server Web Console:
+
+. Click menu:Buckets[] on the main menu.
+. Click the name of the bucket whose encryption status you want to view.
+. The encryption status appears next to the *Encryption At Rest* label under the bucket's name.
+. For more details, hover over the eye icon next to the *Encryption At Rest* label.
+
++
+image::manage-security/encryption-at-rest-details.png[alt=An image of a popup showing that the buceket is fully encrypted and details of the data encryption keys (DEKS)"]
+
+To view the status of encryption at rest for audit, configuration, and log data using the Couchbase Server Web Console:
+
+. Click menu:Security[] on the main menu.
+. Click the menu:Encryption at Rest[] tab.
+. The encryption status appears next to the *Configuration Encryption*, *Logs Encryption*, and *Audit Encryption* labels.
+. To view details about the encryption status, hover over the eye icon next to the label.
+
+=== Viewing Encryption Status Using the REST API
+
+To view the encryption status of buckets using the REST API, send a GET request to the `/pools/default/buckets` endpoint.
+View the `encryptionAtRestKeyId` field in the response to see the encryption status of each bucket.
+If it's set to `-1`, the bucket is not encrypted.
+If it's set to any other value, the bucket is encrypted and the value is the ID of the encryption key Couchbase Server uses to encrypt it.
+Additional details, such as the encrypted status of the data, are in the `encryptionAtRestInfo` object.
+See xref:rest-api:rest-bucket-summary.adoc[] for more information about the `/pools/default/buckets` endpoint.
+
+The following example shows how to view the encryption status of the bucket bucket named `testBucket`.
+It pipes the REST API result through the `jq` command to format and filter the output to show just the `encryptionAtRestKeyId` and `encryptionAtRestInfo` fields:
+
+[source,bash]
+----
+curl -X GET -u Administrator:password \
+ http://localhost:8091/pools/default/buckets/testBucket \
+ | jq '{encryptionAtRestInfo, encryptionAtRestKeyId}'
+----
+
+The result of running this command looks like this:
+
+[source, json]
+----
+{
+ "encryptionAtRestInfo": {
+ "dataStatus": "encrypted",
+ "dekNumber": 3,
+ "issues": [],
+ "oldestDekCreationDatetime": "2025-05-14T15:57:20Z"
+ },
+ "encryptionAtRestKeyId": 18
+}
+----
+
+To view the encryption status of audit, configuration, and log data using the REST API, send a GET request to the `/settings/security/encryptionAtRest` endpoint.
+See xref:rest-api:security/encryption-at-rest/manage-system-encryption-at-rest.adoc#get-settings[Get Audit, Config, and Log Encryption-at-Rest Settings] for more information.
+
+[#rotate-keys]
+== Manually Rotate Encryption-at-rest Keys
+
+You can have Couchbase Server automatically rotate the encryption-at-rest keys it manages based on a schedule you set when creating the key.
+You can also manually have Couchbase Server rotate a key that it manages.
+To rotate an encryption-at-rest key managed by an external KMS, you must use the KMS's tools to rotate the key, then have Couchbase Server re-encrypt DEKs with the new key.
+
+The following sections explain these processes.
+
+=== Manually Rotate a Couchbase Server-Managed Encryption-At-Rest Key
+
+You can manually rotate encryption-at-rest keys that Couchbase Server manages.
+You may choose to manually rotate a key if you believe it has been compromised or if you your security requirements have changed.
+
+When you rotate an encryption-at-rest key, Couchbase Server creates a new key and uses it to re-encrypt all DEKs that were encrypted with the previous version of the key.
+This process does not re-encrypt data, as the DEKs do not change.
+
+To manually rotate a Couchbase-Managed encryption-at-rest key using the Couchbase Server Web Console:
+
+. Click menu:Security[] on the main menu.
+. Click the menu:Encryption at Rest[] tab.
+. Click the encryption key you want to rotate.
+. Click the btn:[Rotate] button next to the key you want to rotate.
+
+To manually rotate an encryption-at-rest key, send a POST request to the `/controller/rotateEncryptionKey/{KEY_ID}` endpoint, where `{KEY_ID}` is the ID of the key you want to rotate.
+See xref:rest-api:security/encryption-at-rest/rotate-encryption-at-rest-key.adoc[] for more information about manually rotating encryption-at-rest keys using the REST API.
+
+=== Manually Rotate a Encryption-at-rest Key Managed by AWS KMS
+
+To rotate an encryption-at-rest key managed by AWS KMS, you must use AWS's tools to rotate the key.
+See https://docs.aws.amazon.com/kms/latest/developerguide/rotate-keys.html[Rotate AWS KMS keys^] to learn how to rotate keys in AWS KMS.
+Once you have rotated the key in AWS KMS, have Couchbase Server re-encrypt any DEKs encrypted with the previous version of the key.
+
+To re-encrypt the DEKs with the rotated key using the Couchbase Server Web Console:
+
+. Click menu:Security[] on the main menu.
+. Click the menu:Encryption at Rest[] tab.
+. Click the encryption key that you rotated in AWS KMS.
+. Click btn:[Rotate] next to the key you want to rotate.
+
+To re-encrypt the DEKs using the REST API, send a POST request to the `/controller/rotateEncryptionKey/{KEY_ID}` endpoint, where `{KEY_ID}` is the ID of the key that you rotated in AWS KMS.
+See xref:rest-api:security/encryption-at-rest/rotate-encryption-at-rest-key.adoc[] for more information about manually rotating encryption-at-rest keys using the REST API.
+
+=== Manually Rotate an Encryption-at-rest Key Managed by a KMIP KMS
+
+You must use the KMS's tools to rotate the keys it manages.
+Couchbase Server cannot trigger the rotation of a key managed by an external KMS.
+Consult your KMS's documentation to learn how to rotate its keys.
+
+Some KMIP KMSs require you to create a new key with a new ID when rotating a key.
+In this case, when you rotate a key in the KMS, you must update the key ID in Couchbase Server.
+
+To update the key ID in Couchbase Server using the Couchbase Server Web Console:
+
+. Click menu:Security[].
+. Click menu:Encryption at Rest[].
+. Click the KMIP KMS encryption key that you rotated.
+. Click the btn:[Edit].
+. In the *Edit Encryption Key* dialog, change the *KMIP Key ID* to the new key ID and click btn:[Save Encryption Key].
+
+To update the key ID in Couchbase Server using the REST API, use the `/settings/encryptionKeys/{KEY_ID}` endpoint to modify the key. The `KEY_ID` path parameter is the Couchbase Server ID of the key you want to update.
+Update the `activeKey.kmipId` attribute in the `data` object to the new key ID.
+
+The following example updates the KMIP key ID of the encryption-at-rest key with the Couchbase Server `id` of `3` to the a KMIP key ID:
+
+[source,console]
+----
+curl -sS -u Administrator:password \
+ -X PUT http://127.0.0.1:8091/settings/encryptionKeys/3 \
+ --data-binary @- <
+.Edit an Existing Bucket
+----
+POST /pools/default/buckets/{bucketName}
----
[#description]
== Description
-These respectively create a new bucket and edit an existing bucket.
-The bucket can be of any type: Couchbase, Ephemeral, or Memcached.
-(Note, however that Memcached buckets are now _deprecated_.)
+These endpoints create a new bucket and edit an existing bucket.
+You can create buckets of any type: Couchbase, Ephemeral, or Memcached.
+(Memcached buckets are now deprecated.)
-On creation, a bucket must be assigned a name that is unique among buckets defined on the cluster: this name cannot subsequently be changed.
-Names cannot be longer than 100 bytes (which is to say, characters).
+When you create a bucket, you must assign it a name that is unique across all buckets on the cluster. You cannot change the name after creation.
+Bucket names must not exceed 100 bytes (i.e., 100 characters).
-A maximum of 30 buckets can be created on a single cluster.
+A single cluster can contain up to 30 buckets.
-Administrators with either the Full Admin or the Cluster Admin role can create buckets and edit their configurations.
-Bucket configurations can also be edited by administrators with the Bucket Admin role, provided that its privileges have been extended either to all buckets on the cluster, or to the specific bucket whose configuration is to be edited.
-See xref:learn:security/roles.adoc[Roles], for information on roles and privileges.
+Administrators with the Full Admin or Cluster Admin role can create and configure buckets.
+Administrators with the Bucket Admin role can also edit bucket configurations, as long as their privileges apply to all buckets or specifically to the target bucket.
+For details on roles and privileges, see xref:learn:security/roles.adoc[Roles].
NOTE: While migrating a bucket from one storage backend to another, you can only edit the bucket's xref:rest-api:rest-bucket-create.adoc#ramQuota[ramQuota] and xref:rest-api:rest-bucket-create.adoc#storagebackend[storageBackend] parameters. See xref:manage:manage-buckets/migrate-bucket.adoc[] for more information.
@@ -37,8 +41,9 @@ NOTE: While migrating a bucket from one storage backend to another, you can only
[#curl-syntax]
== Curl Syntax
-Note that floats and integers referred to in the following syntax-display are _non-negative_ only.
+The floats and integers fields in the following syntax must be non-negative values.
+[source,bash]
----
curl -X POST -u :
http://:/pools/default/buckets
@@ -66,84 +71,131 @@ curl -X POST -u :
-d historyRetentionCollectionDefault=[ true | false ]
-d historyRetentionBytes=
-d historyRetentionSeconds=
+ -d encryptionAtRestKeyId=
+ -d encryptionAtRestDekRotationInterval=
+ -d encryptionAtRestDekLifetime=
-d autoCompactionDefined=[ true | false ]
- -d parallelDBAndViewCompaction=[ true | false ]
- -d databaseFragmentationThreshold[percentage]=
- -d databaseFragmentationThreshold[size]=
- -d viewFragmentationThreshold[percentage]=
- -d viewFragmentationThreshold[size]=
- -d purgeInterval=[ | ]
- -d allowedTimePeriod[fromHour]=
- -d allowedTimePeriod[fromMinute]=
- -d allowedTimePeriod[toHour]=
- -d allowedTimePeriod[toMinute]=
- -d allowedTimePeriod[abortOutside]=[ true | false ]
+ -d parallelDBAndViewCompaction=[ true | false ]
+ -d databaseFragmentationThreshold[percentage]=
+ -d databaseFragmentationThreshold[size]=
+ -d viewFragmentationThreshold[percentage]=
+ -d viewFragmentationThreshold[size]=
+ -d purgeInterval=[ | ]
+ -d allowedTimePeriod[fromHour]=
+ -d allowedTimePeriod[fromMinute]=
+ -d allowedTimePeriod[toHour]=
+ -d allowedTimePeriod[toMinute]=
+ -d allowedTimePeriod[abortOutside]=[ true | false ]
+
----
All parameters are described in the following subsections.
== Parameter Groups
-Parameters that support the creation and editing of buckets can be considered to form two groups; which are, respectively, _General_ and _Auto-compaction_.
+Parameters that support the creation and editing of buckets can be broken into two groups: Genera and Auto-compaction.
=== General
-Parameters in the _General_ group include:
+This section lists the general parameters for creating a bucket.
-* Parameters that _must_ be specified on bucket creation, these being:
+You must supply a value for the following parameters:
-** xref:rest-api:rest-bucket-create.adoc#ramQuota[ramQuota], which establishes a memory-quota for the bucket, and _can_ be edited following bucket creation.
+* xref:rest-api:rest-bucket-create.adoc#ramQuota[ramQuota]
+* xref:rest-api:rest-bucket-create.adoc#name[name]
-** xref:rest-api:rest-bucket-create.adoc#name[name], which establishes a name for the bucket, and _cannot_ be edited following bucket creation.
+All other parameters are optional and have a default value.
-* Parameters that _can_ be specified on bucket creation, but if not specified, acquire a default value.
-They include:
+The following parameters can be edited after bucket creation:
-** Parameters that _can_ be edited after bucket creation; these being xref:rest-api:rest-bucket-create.adoc#evictionpolicy[evictionPolicy], xref:rest-api:rest-bucket-create.adoc#durabilityminlevel[durabilityMinLevel], xref:rest-api:rest-bucket-create.adoc#threadsnumber[threadsNumber], xref:rest-api:rest-bucket-create.adoc#rank[rank], xref:rest-api:rest-bucket-create.adoc#replicanumber[replicaNumber], xref:rest-api:rest-bucket-create.adoc#compressionmode[compressionMode], xref:rest-api:rest-bucket-create.adoc#maxttl[maxTTL], xref:rest-api:rest-bucket-create.adoc#flushenabled[flushEnabled], xref:rest-api:rest-bucket-create.adoc#magmaseqtreedatablocksize[magmaSeqTreeDataBlockSize],
-xref:rest-api:rest-bucket-create.adoc#historyretentioncollectiondefault[historyRetentionCollectionDefault],
-xref:rest-api:rest-bucket-create.adoc#historyretentionbytes[historyRetentionBytes], xref:rest-api:rest-bucket-create.adoc#storagebackend[storageBackend], and
-xref:rest-api:rest-bucket-create.adoc#historyretentionseconds[historyRetentionSeconds].
+* <>
+* <>
+* <>
+* <>
+* <>
+* <>
+* <>
+* <>
+* <>
+* <>
+* <>
+* <>
+* <>
+* <>
+* <>
+* <>
-** Parameters that _cannot_ be edited after bucket creation; these being xref:rest-api:rest-bucket-create.adoc#buckettype[bucketType], xref:rest-api:rest-bucket-create.adoc#replicaindex[replicaIndex], and xref:rest-api:rest-bucket-create.adoc#conflictresolutiontype[conflictResolutionType].
+You cannot edit these parameters after bucket creation:
-For full details and examples, see xref:rest-api:rest-bucket-create.adoc#general-parameters[General Parameters], below.
+* xref:rest-api:rest-bucket-create.adoc#buckettype[bucketType]
+* xref:rest-api:rest-bucket-create.adoc#replicaindex[replicaIndex]
+* xref:rest-api:rest-bucket-create.adoc#conflictresolutiontype[conflictResolutionType]
+
+For full details and examples, see xref:rest-api:rest-bucket-create.adoc#general-parameters[General Parameters].
=== Auto-Compaction
-_All_ auto-compaction parameters can be edited, following bucket creation.
+You can edit all auto-compaction parameters after bucket creation.
+
+The Auto-compaction parameter group contains the following:
+
+* xref:rest-api:rest-bucket-create.adoc#autocompactiondefined[autoCompactionDefined]
+* xref:rest-api:rest-bucket-create.adoc#paralleldbandviewcompaction[parallelDBAndViewCompaction]
+* xref:rest-api:rest-bucket-create.adoc#databasefragmentationthresholdpercentage[+databaseFragmentationThreshold[percentage]+]
+* xref:rest-api:rest-bucket-create.adoc#databasefragmentationthresholdsize[+databaseFragmentationThreshold[size]+]
+* xref:rest-api:rest-bucket-create.adoc#viewfragmentationthresholdpercentage[+viewFragmentationThreshold[percentage]+]
+* xref:rest-api:rest-bucket-create.adoc#viewfragmentationthresholdsize[+viewFragmentationThreshold[size]+]
+* xref:rest-api:rest-bucket-create.adoc#purgeinterval[purgeInterval]
+* xref:rest-api:rest-bucket-create.adoc#allowedtimeperiodfromhour[+allowedTimePeriod[fromHour]+]
+* xref:rest-api:rest-bucket-create.adoc#allowedtimeperiodfromminute[+allowedTimePeriod[fromMinute]+]
+* xref:rest-api:rest-bucket-create.adoc#allowedtimeperiodtohour[+allowedTimePeriod[toHour]+]
+* xref:rest-api:rest-bucket-create.adoc#allowedtimeperiodtominute[+allowedTimePeriod[toMinute]+]
+* xref:rest-api:rest-bucket-create.adoc#allowedtimeperiodabortoutside[+allowedTimePeriod[abortOutside]+]
-The Auto-compaction parameter group contains the following: xref:rest-api:rest-bucket-create.adoc#autocompactiondefined[autoCompactionDefined], xref:rest-api:rest-bucket-create.adoc#paralleldbandviewcompaction[parallelDBAndViewCompaction], xref:rest-api:rest-bucket-create.adoc#databasefragmentationthresholdpercentage[+databaseFragmentationThreshold[percentage]+], xref:rest-api:rest-bucket-create.adoc#databasefragmentationthresholdsize[+databaseFragmentationThreshold[size]+], xref:rest-api:rest-bucket-create.adoc#viewfragmentationthresholdpercentage[+viewFragmentationThreshold[percentage]+], xref:rest-api:rest-bucket-create.adoc#viewfragmentationthresholdsize[+viewFragmentationThreshold[size]+], xref:rest-api:rest-bucket-create.adoc#purgeinterval[purgeInterval], xref:rest-api:rest-bucket-create.adoc#allowedtimeperiodfromhour[+allowedTimePeriod[fromHour]+], xref:rest-api:rest-bucket-create.adoc#allowedtimeperiodfromminute[+allowedTimePeriod[fromMinute]+], xref:rest-api:rest-bucket-create.adoc#allowedtimeperiodtohour[+allowedTimePeriod[toHour]+], xref:rest-api:rest-bucket-create.adoc#allowedtimeperiodtominute[+allowedTimePeriod[toMinute]+], and xref:rest-api:rest-bucket-create.adoc#allowedtimeperiodabortoutside[+allowedTimePeriod[abortOutside]+].
-Note that _Auto-compaction_ parameters take effect only if both of the following are true:
+[NOTE]
+====
+Auto-compaction parameters take effect only if both of the following are true:
* Auto-compaction is enabled, by means of the xref:rest-api:rest-bucket-create.adoc#autocompactiondefined[autoCompactionDefined] parameter.
* An explicit setting is made to the xref:rest-api:rest-bucket-create.adoc#paralleldbandviewcompaction[parallelDBAndViewCompaction] parameter.
+====
-Note that in Couchbase Server Enterprise Edition, auto-compaction does not apply to memory-optimized index storage, and there are no settings necessary for configuring the auto-compaction of Global Secondary Indexes using standard index storage.
-For information on storage, see xref:learn:buckets-memory-and-storage/storage-engines.adoc[Storage Engines].
+[NOTE]
+====
+In Couchbase Server Enterprise Edition, auto-compaction does not apply to memory-optimized index storage.
+There are no settings necessary for configuring the auto-compaction of Global Secondary Indexes using standard index storage.
+For information about storage, see xref:learn:buckets-memory-and-storage/storage-engines.adoc[Storage Engines].
-For full details and examples, see xref:rest-api:rest-bucket-create.adoc#auto-compaction-parameters[Auto-Compaction Parameters], below.
+For full details and examples, see <>.
+====
[#general-parameters]
== General Parameters
-The parameters listed in the following subsections are all included in the _General_ group, and therefore apply equally to Couchbase Server Enterprise and Community Editions.
+The parameters listed in the following subsections are all included in the General group, and therefore apply equally to Couchbase Server Enterprise and Community Editions.
[#name]
=== name
-A name for a bucket that is to be created.
-The name must be unique among the bucket-names defined for the cluster, and cannot be longer than 100 characters.
-Acceptable characters are `A-Z`, `a-z`, and `0-9`.
-Additionally, the _underscore_, _period_, _dash_, and _percent_ characters can be used.
+Provide a name for the bucket you want to create.
+The name must be unique among the bucket names defined for the cluster and cannot exceed 100 characters.
+Acceptable characters include `A-Z`, `a-z`, `0-9`, `_`, `.`, `-`, and `%`.
-The name parameter _must_ be specified, if a bucket is being created.
-If it is not, or if the intended name is improperly designed, an error-notification is returned.
-For example: : `{"name":"Bucket name needs to be specified"}`.
-Note that a bucket-name _cannot_ be changed after bucket-creation.
-Therefore, if this parameter is specified in an attempt to edit the bucket-configuration, it is ignored.
-To edit the configuration of an existing bucket, the bucket-name must be specified as the `` path-parameter; as indicated above, in xref:rest-api:rest-bucket-create.adoc#http-methods-and-uris[HTTP Methods and URIs].
+You must specify the name parameter when creating a bucket.
+If you do not provide it or if the name is invalid, the system returns an error notification.
+For example:
+
+[source,json]
+----
+{"name":"Bucket name needs to be specified"}
+----
+
+You cannot change the bucket name after creating the bucket.
+If you try to specify this parameter while editing the bucket configuration,Couchbase Server ignores it.
+To edit an existing bucket's configuration, specify the bucket name as the `{bucketName}` path parameter.
+Refer to xref:rest-api:rest-bucket-create.adoc#http-methods-and-uris[HTTP Methods and URIs] for more details.
[#example-name-create]
==== Example: Defining a New Name, When Creating
@@ -151,8 +203,9 @@ To edit the configuration of an existing bucket, the bucket-name must be specifi
In the following example, a bucket named `testBucket` is created, with a RAM-size of `256` MiB.
The bucket name is specified by means of the `name` parameter, with a value of `testBucket`.
+[source,bash]
----
-curl -v -X POST http://10.143.201.101:8091/pools/default/buckets \
+curl -X POST http://127.0.0.1:8091/pools/default/buckets \
-u Administrator:password \
-d name=testBucket \
-d ramQuota=256
@@ -163,10 +216,11 @@ If successful, the call returns a `202 Accepted` notification, with empty conten
[#example-name-edit]
==== Example: Referencing the Existing Name, When Editing
-To _edit_ the bucket, the same endpoint is used, but with the bucket name specified as a concluding path-parameter, as follows:
+To edit the bucket, the same endpoint is used, but with the bucket name specified as a concluding path-parameter, as follows:
+[source,bash]
----
-curl -v -X POST http://10.143.201.101:8091/pools/default/buckets/testBucket \
+curl -v -X POST http://127.0.0.1:8091/pools/default/buckets/testBucket \
-u Administrator:password \
-d ramQuota=512
----
@@ -176,24 +230,25 @@ The value of the `ramQuota` parameter (described below), is hereby increased to
[#buckettype]
=== bucketType
-Specifies the _type_ of the bucket.
+Specifies the type of the bucket.
This can be `couchbase` (which is the default), `ephemeral`, or `memcached`.
For a detailed explanation of bucket types, see xref:learn:buckets-memory-and-storage/buckets.adoc[Buckets].
If an invalid bucket type is specified, the error-notification `{"bucketType":"invalid bucket type"}` is returned.
-This parameter _cannot_ be modified, following bucket-creation.
+This parameter cannot be modified, following bucket-creation.
If an attempt at modification is made, the parameter is ignored.
[#example-buckettype-create]
==== Example: Defining a Bucket Type, When Creating
-A bucket type can _only_ be specified when the bucket is created: the specified type _cannot_ be changed subsequently.
+A bucket type can only be specified when the bucket is created: the specified type cannot be changed subsequently.
-The following example creates a bucket, named `testBucket`, whose type is _ephemeral_:
+The following example creates a bucket, named `testBucket`, whose type is ephemeral:
+[source,bash]
----
-curl -v -X POST http://10.143.201.101:8091/pools/default/buckets \
+curl -v -X POST http://127.0.0.1:8091/pools/default/buckets \
-u Administrator:password \
-d name=testBucket \
-d ramQuota=256 \
@@ -211,7 +266,7 @@ The minimum amount is 100 MiB.
The maximum amount is the total Data Service memory quota configured per node, minus the amount already assigned to other buckets.
For information on per node memory configuration, see the page for xref:manage:manage-settings/general-settings.adoc[General] Settings.
-A value for `ramQuota` _must_ be specified: the value _can_ be modified, following bucket-creation.
+A value for `ramQuota` must be specified: the value can be modified, following bucket-creation.
An incorrect memory-specification returns a notification such as `{"ramQuota":"RAM quota cannot be less than 100 MiB"}`.
@@ -220,8 +275,9 @@ An incorrect memory-specification returns a notification such as `{"ramQuota":"R
The following example creates a Couchbase bucket, named `testBucket` and assigns it `256` MiB of memory.
+[source,bash]
----
-curl -v -X POST http://10.143.201.101:8091/pools/default/buckets \
+curl -v -X POST http://127.0.0.1:8091/pools/default/buckets \
-u Administrator:password \
-d name=testBucket \
-d ramQuota=256
@@ -237,8 +293,9 @@ No object is returned.
The following example assigns a new memory quota, of `512` MiB, to the existing bucket `testBucket`.
+[source,bash]
----
-curl -v -X POST http://10.143.201.101:8091/pools/default/buckets/testBucket \
+curl -v -X POST http://127.0.0.1:8091/pools/default/buckets/testBucket \
-u Administrator:password \
-d ramQuota=512
----
@@ -249,17 +306,21 @@ No object is returned.
[#storagebackend]
=== storageBackend
-The _storage backend_ to be assigned to and used by the bucket.
+The storage backend to be assigned to and used by the bucket.
This can be either `couchstore` (which is the default) or `magma`.
For information, see xref:learn:buckets-memory-and-storage/storage-engines.adoc[Storage Engines].
-NOTE: You can edit this value after initially creating the bucket. Couchbase Server sets the new backend value globally. However, this change does not convert the bucket to the new backend storage engine. Instead, Couchbase Server adds overrides to every node containing the bucket to indicate that their vBuckets are still in the old format. You must take additional steps to complete the migration to the new storage backend. See xref:manage:manage-buckets/migrate-bucket.adoc[] for more information.
+NOTE: You can edit this value after initially creating the bucket. Couchbase Server sets the new backend value globally.
+However, this change does not convert the bucket to the new backend storage engine.
+Instead, Couchbase Server adds overrides to every node containing the bucket to indicate that their vBuckets are still in the old format. You must take additional steps to complete the migration to the new storage backend.
+See xref:manage:manage-buckets/migrate-bucket.adoc[] for more information.
[#example-storage-backend]
==== Example: Specifying the Storage Backend
A minimum of 1024 MiB is required if the `magma` option is used; a minimum of 100 MiB if the default `couchstore` is used.
+[source,bash]
----
curl -v -X POST http://127.0.0.1:8091/pools/default/buckets \
-u Administrator:password \
@@ -274,14 +335,14 @@ No object is returned.
[#evictionpolicy]
=== evictionPolicy
-The _ejection policy_ to be assigned to and used by the bucket.
-(Note that _eviction_ is, in the current release, referred to as _ejection_; and this revised naming will continue to be used in future releases.)
+The ejection policy to be assigned to and used by the bucket.
+(Note that eviction is, in the current release, referred to as ejection; and this revised naming will continue to be used in future releases.)
Policy-assignment depends on bucket type.
-For a _Couchbase_ bucket, the policy can be `valueOnly` (which is the default) or `fullEviction`.
-For an _Ephemeral_ bucket, the policy can be `noEviction` (which is the default) or `nruEviction`.
-No policy can be assigned to a _Memcached_ bucket.
+For a Couchbase bucket, the policy can be `valueOnly` (which is the default) or `fullEviction`.
+For an Ephemeral bucket, the policy can be `noEviction` (which is the default) or `nruEviction`.
+No policy can be assigned to a Memcached bucket.
-This value _can_ be modified, following bucket-creation.
+This value can be modified, following bucket-creation.
If such modification occurs, the bucket is restarted with the new setting: this may cause inaccessibility of data, during the bucket's warm-up period.
Incorrect specification of an ejection policy returns an error-notification, such as `{"evictionPolicy":"Eviction policy must be either 'valueOnly' or 'fullEviction' for couchbase buckets"}`.
@@ -294,8 +355,9 @@ For general information on memory management in the context of ejection, see xre
The following example creates a new bucket, named `testBucket`, which is a Couchbase bucket by default; and assigns it the `fullEviction` policy.
+[source,bash]
----
-curl -v -X POST http://10.143.201.101:8091/pools/default/buckets \
+curl -v -X POST http://127.0.0.1:8091/pools/default/buckets \
-u Administrator:password \
-d name=testBucket -d ramQuota=256 \
-d evictionPolicy=fullEviction
@@ -309,8 +371,9 @@ No object is returned.
The following example modifies the eviction policy of the existing bucket `testBucket`, specifying that it should be `valueOnly`.
+[source,bash]
----
-curl -v -X POST http://10.143.201.101:8091/pools/default/buckets/testBucket \
+curl -v -X POST http://127.0.0.1:8091/pools/default/buckets/testBucket \
-u Administrator:password \
-d evictionPolicy=valueOnly
----
@@ -321,23 +384,24 @@ No object is returned.
[#durabilityminlevel]
=== durabilityMinLevel
-A _durability level_ to be assigned to the bucket, as the minimum level at which all writes to the bucket must occur.
+A durability level to be assigned to the bucket, as the minimum level at which all writes to the bucket must occur.
Level-assignment depends on bucket type.
-For a _Couchbase_ bucket, the level can be `none`, `majority`, `majorityAndPersistActive`, or `persistToMajority`.
-For an _Ephemeral_ bucket, the level can be `none` or `majority`.
-No level can be assigned to a _Memcached_ bucket.
+For a Couchbase bucket, the level can be `none`, `majority`, `majorityAndPersistActive`, or `persistToMajority`.
+For an Ephemeral bucket, the level can be `none` or `majority`.
+No level can be assigned to a Memcached bucket.
-This parameter _can_ be modified, following bucket-creation.
+This parameter can be modified, following bucket-creation.
-For information on durability and levels, see xref:learn:data/durability.adoc[Durability].
+For information about durability and levels, see xref:learn:data/durability.adoc[Durability].
[#example-durabilityminlevel-create]
==== Example: Specifying a Minimum Durability Level, when Creating
The following example creates a new bucket, named `testBucket`, which is a Couchbase bucket by default; and assigns it the minimum durability level of `majorityAndPersistActive`.
+[source,bash]
----
-curl -v -X POST http://10.143.201.101:8091/pools/default/buckets \
+curl -v -X POST http://127.0.0.1:8091/pools/default/buckets \
-u Administrator:password \
-d name=testBucket \
-d ramQuota=256 \
@@ -352,8 +416,9 @@ No object is returned.
The following example modifies the minimum durability level of the existing bucket `testBucket`, changing the level to `persistToMajority`.
+[source,bash]
----
-curl -v -X POST http://10.143.201.101:8091/pools/default/buckets/testBucket \
+curl -v -X POST http://127.0.0.1:8091/pools/default/buckets/testBucket \
-u Administrator:password \
-d durabilityMinLevel=persistToMajority
----
@@ -364,25 +429,26 @@ No object is returned.
[#threadsnumber]
=== threadsNumber
-The _priority_ for the bucket, as described in xref:manage:manage-buckets/create-bucket.adoc#bucket-priority[Create a Bucket].
-Priority can be established as either _Low_ or _High_.
-To establish priority as _Low_ (which is the default), the value of `threadsNumber` must be `3`.
-To establish priority as _High_, the value must be `8`.
+The priority for the bucket, as described in xref:manage:manage-buckets/create-bucket.adoc#bucket-priority[Create a Bucket].
+Priority can be established as either Low or High.
+To establish priority as Low (which is the default), the value of `threadsNumber` must be `3`.
+To establish priority as High, the value must be `8`.
If any other value is used, the value is ignored; and the bucket's priority remains low.
If this parameter is incorrectly specified, an error-notification such as the following is returned: `{"threadsNumber":"The number of threads must be an integer between 2 and 8"}`.
(Note that, as indicated above, all values other than `3` and `8` are ignored.)
-This parameter _can_ be modified, following bucket-creation.
+This parameter can be modified, following bucket-creation.
If such modification occurs, the bucket is restarted with the new setting: this may cause inaccessibility of data, during the bucket's warm-up period.
[#example-threadsnumber-create]
==== Example: Specifying a Bucket Priority, when Creating
-The following example creates a new bucket, named `testBucket`, which is a Couchbase bucket by default; and assigns it a _High_ priority, by specifying `8` as the value to the `threadsNumber` parameter.
+The following example creates a new bucket, named `testBucket`, which is a Couchbase bucket by default; and assigns it a High priority, by specifying `8` as the value to the `threadsNumber` parameter.
+[source,bash]
----
-curl -v -X POST http://10.143.201.101:8091/pools/default/buckets \
+curl -v -X POST http://127.0.0.1:8091/pools/default/buckets \
-u Administrator:password \
-d name=testBucket \
-d ramQuota=256 \
@@ -395,10 +461,11 @@ No object is returned.
[#example-threadsnumber-edit]
==== Example: Specifying a New Bucket Priority, when Editing
-The following example modifies the priority of the existing bucket `testBucket`, changing the level to _Low_, by establishing `3` as the value of the `threadsNumber` parameter.
+The following example modifies the priority of the existing bucket `testBucket`, changing the level to Low, by establishing `3` as the value of the `threadsNumber` parameter.
+[source,bash]
----
-curl -v -X POST http://10.143.201.101:8091/pools/default/buckets/testBucket \
+curl -v -X POST http://127.0.0.1:8091/pools/default/buckets/testBucket \
-u Administrator:password \
-d threadsNumber=3
----
@@ -409,7 +476,7 @@ No object is returned.
[#rank]
=== rank
-The _rank_ for the bucket: this determines the bucket's place in the order in which the _rebalance_ process handles the buckets on the cluster.
+The rank for the bucket: this determines the bucket's place in the order in which the rebalance process handles the buckets on the cluster.
The bucket can be either a Couchbase or an Ephemeral bucket.
Rank can be established as an integer, from `0` (the default) to `1000`.
The higher a bucket's assigned integer (in relation to the integers assigned other buckets), the sooner in the rebalance process the bucket is handled.
@@ -422,18 +489,20 @@ This assignment of `rank` allows a cluster's most mission-critical data to be re
The following establishes a new bucket named `testBucket`, and assigns it a `rank` of 100.
+[source,bash]
----
curl -v -X POST http://localhost:8091/pools/default/buckets -u Administrator:password -d name=testBucket -d ramQuota=125 -d rank=100
----
If the call is successful, `202 Accepted` is returned.
-Assigned the rank of `100`, `testBucket` will be handled by the rebalance process _before_ any bucket whose assignment is _less_ than `100`, and _after_ and bucket whose assignment is _greater_.
+Assigned the rank of `100`, `testBucket` will be handled by the rebalance process before any bucket whose assignment is less than `100`, and after and bucket whose assignment is greater.
[#example-rank-edit]
==== Example: Specifying a Bucket's Rank, when Editing
The following edits the previously established value of `rank` for `testBucket`:
+[source,bash]
----
curl -v -X POST http://localhost:8091/pools/default/buckets/testBucket /
-u Administrator:password /
@@ -445,14 +514,14 @@ Success returns `200 OK`, and changes the `rank` of `testBucket` to `200`.
[#replicanumber]
=== replicaNumber
-The number of _replicas_ for the bucket.
+The number of replicas for the bucket.
For information on replicas and replication, see xref:learn:clusters-and-availability/intra-cluster-replication.adoc[Intra-Cluster Replication] and xref:learn:buckets-memory-and-storage/vbuckets.adoc[vBuckets].
-The possible values are `0` (which _disables_ replication, and therefore ensures that no replicas will be maintained), `1` (which is the default), `2`, and `3`.
+The possible values are `0` (which disables replication, and therefore ensures that no replicas will be maintained), `1` (which is the default), `2`, and `3`.
If a number greater than `3` is specified, the following error-notification is returned: `{"replicaNumber":"Replica number larger than 3 is not supported."}`.
If more replicas are requested than can be assigned to the cluster, due to an insufficient number of nodes, no notification is returned. Instead, the maximum possible number of replicas is created: additional replicas will be added subsequently, if more nodes become available.
-This parameter _can_ be modified, following bucket-creation.
+This parameter can be modified, following bucket-creation.
Such modification may require a rebalance: for information, see xref:learn:clusters-and-availability/rebalance.adoc[Rebalance].
[#example-replicanumber-create]
@@ -460,7 +529,7 @@ Such modification may require a rebalance: for information, see xref:learn:clust
The following example creates a new bucket, named `testBucket`, and specifies that it should have `3` replicas.
----
-curl -v -X POST http://10.143.201.101:8091/pools/default/buckets \
+curl -v -X POST http://127.0.0.1:8091/pools/default/buckets \
-u Administrator:password \
-d name=testBucket \
-d ramQuota=256 \
@@ -475,8 +544,9 @@ No object is returned.
The following example changes the replica-number of the existing bucket `testBucket`, specifying that the number be `2`:
+[source,bash]
----
-curl -v -X POST http://10.143.201.101:8091/pools/default/buckets/testBucket \
+curl -v -X POST http://127.0.0.1:8091/pools/default/buckets/testBucket \
-u Administrator:password \
-d replicaNumber=2
----
@@ -487,11 +557,11 @@ No object is returned.
[#compressionmode]
=== compressionMode
-The _compression mode_ for the bucket.
+The compression mode for the bucket.
The possible values are `off`, `passive` (which is the default), and `active`.
If the value is incorrectly specified, the following error-notification is returned: `{"compressionMode":"compressionMode can be set to 'off', 'passive' or 'active'"}`.
-This parameter _can_ be modified following bucket-creation.
+This parameter can be modified following bucket-creation.
For information on compression and compression modes, see xref:learn:buckets-memory-and-storage/compression.adoc[Compression].
@@ -500,8 +570,9 @@ For information on compression and compression modes, see xref:learn:buckets-mem
The following example creates a new bucket, named `testBucket`, and assigns it the `active` compression mode:
+[source,bash]
----
-curl -v -X POST http://10.143.201.101:8091/pools/default/buckets \
+curl -v -X POST http://127.0.0.1:8091/pools/default/buckets \
-u Administrator:password \
-d name=testBucket \
-d ramQuota=256 \
@@ -516,8 +587,9 @@ No object is returned.
The following example changes the compression mode of the existing bucket `testBucket`, specifying that the mode now be `off`:
+[source,bash]
----
-curl -v -X POST http://10.143.201.101:8091/pools/default/buckets/testBucket \
+curl -v -X POST http://127.0.0.1:8091/pools/default/buckets/testBucket \
-u Administrator:password \
-d compressionMode=off
----
@@ -528,7 +600,7 @@ No object is returned.
[#maxttl]
=== maxTTL
-Sets the bucket's _maximum time to live_. The default value is `0`, which does not automatically expire documents.
+Sets the bucket's maximum time to live. The default value is `0`, which does not automatically expire documents.
It also does not affect expiration values you directly set on a document.
Setting this parameter to a non-zero value has two effects:
@@ -549,10 +621,11 @@ For more information, see xref:learn:data/expiration.adoc[Expiration].
[#example-maxttl-create]
==== Example: Specifying a Time-to-Live Value, when Creating
-The following example creates a new bucket, named `testBucket`, and assigns it a _time-to-live_ of 500,000 seconds:
+The following example creates a new bucket, named `testBucket`, and assigns it a time-to-live of 500,000 seconds:
+[source,bash]
----
-curl -v -X POST http://10.143.201.101:8091/pools/default/buckets \
+curl -v -X POST http://127.0.0.1:8091/pools/default/buckets \
-u Administrator:password \
-d name=testBucket \
-d ramQuota=256 \
@@ -565,10 +638,11 @@ No object is returned.
[#example-maxttl-edit]
==== Example: Specifying a New Time-to-Live value, when Editing
-The following example modifies the _time-to-live_ setting of the existing bucket `testBucket`, reducing it to `0`, and thereby _disabling_ expiration.
+The following example modifies the time-to-live setting of the existing bucket `testBucket`, reducing it to `0`, and thereby disabling expiration.
+[source,bash]
----
-curl -v -X POST http://10.143.201.101:8091/pools/default/buckets/testBucket \
+curl -v -X POST http://127.0.0.1:8091/pools/default/buckets/testBucket \
-u Administrator:password \
-d maxTTL=0
----
@@ -579,25 +653,26 @@ No object is returned.
[#replicaindex]
=== replicaIndex
-Specifies whether _View Indexes_ are to be replicated.
-The value can be either `0` (which is the default), specifying that they are _not_ to be replicated; or `1`, specifying that they _are_ to be replicated.
+Specifies whether View Indexes are to be replicated.
+The value can be either `0` (which is the default), specifying that they are not to be replicated; or `1`, specifying that they are to be replicated.
Specifying any other value returns an error-notification such as the following: `{"replicaIndex":"replicaIndex can only be 1 or 0"}`.
This option is valid for Couchbase buckets only.
-Note that there may be, at most, _one_ replica view index.
+Note that there may be, at most, one replica view index.
-This parameter _cannot_ be modified, following bucket-creation.
+This parameter cannot be modified, following bucket-creation.
[#example-replicaindex-create]
==== Example: Specifying View Index Replication, when Creating
-View index replication can _only_ be specified when a bucket is created.
+View index replication can only be specified when a bucket is created.
Attempts to change the value subsequently are ignored.
The following example creates a new bucket, named `testBucket`, and specifies that View indexes are to be replicated:
+[source,bash]
----
-curl -v -X POST http://10.143.201.101:8091/pools/default/buckets \
+curl -v -X POST http://127.0.0.1:8091/pools/default/buckets \
-u Administrator:password \
-d name=testBucket \
-d ramQuota=256 \
@@ -610,9 +685,9 @@ No object is returned.
[#conflictresolutiontype]
=== conflictResolutionType
-Specifies the _conflict resolution type_ for the bucket.
-The value can be `seqno` (which is the default), specifying sequence-number based resolution; or `lww` (_last write wins_), specifying timestamp-based resolution
-This parameter _cannot_ be modified, following bucket-creation.
+Specifies the conflict resolution type for the bucket.
+The value can be `seqno` (which is the default), specifying sequence-number based resolution; or `lww` (last write wins), specifying timestamp-based resolution
+This parameter cannot be modified, following bucket-creation.
If modification is attempted, the following error-notification is returned: `{"conflictResolutionType":"Conflict resolution type not allowed in update bucket"}`.
For information on conflict resolution, see: xref:learn:clusters-and-availability/xdcr-conflict-resolution.adoc[XDCR Conflict Resolution].
@@ -620,12 +695,13 @@ For information on conflict resolution, see: xref:learn:clusters-and-availabilit
[#example-conflictresolutiontype-create]
==== Example: Specifying a Conflict Resolution Policy, when Creating
-A bucket's conflict resolution policy can _only_ be specified when the bucket is created: attempts to change the setting subsequently are ignored.
+A bucket's conflict resolution policy can only be specified when the bucket is created: attempts to change the setting subsequently are ignored.
The following example creates a new bucket, named `testBucket`, specifying the `lww` conflict resolution policy.
+[source,bash]
----
-curl -v -X POST http://10.143.201.101:8091/pools/default/buckets \
+curl -v -X POST http://127.0.0.1:8091/pools/default/buckets \
-u Administrator:password \
-d name=testBucket \
-d ramQuota=256 \
@@ -637,20 +713,21 @@ No object is returned.
[#flushenabled]
=== flushEnabled
-Whether _flushing_ is enabled for the bucket.
+Whether flushing is enabled for the bucket.
The value can be either `1`, which enables flushing; or `0`, which is the default, and disables flushing.
-Flushing deletes _every_ document in the bucket, and therefore should _not_ be enabled unless absolutely necessary.
+Flushing deletes every document in the bucket, and therefore should not be enabled unless absolutely necessary.
-This parameter _can_ be modified, following bucket-creation.
+This parameter can be modified, following bucket-creation.
[#example-create]
==== Example: Enable Flushing, when Creating
The following example creates a new bucket, named `testBucket`, and enables flushing:
+[source,bash]
----
-curl -v -X POST http://10.143.201.101:8091/pools/default/buckets \
+curl -v -X POST http://127.0.0.1:8091/pools/default/buckets \
-u Administrator:password \
-d name=testBucket \
-d ramQuota=256 \
@@ -663,10 +740,11 @@ No object is returned.
[#example-edit]
==== Example: Modify Flushing Enablement-Status, when Editing
-The following example modifies the flushing enablement-status of the existing bucket, `testBucket`, switching it to _disabled_, by specifying the value `0` for the parameter `flushEnabled`:
+The following example modifies the flushing enablement-status of the existing bucket, `testBucket`, switching it to disabled, by specifying the value `0` for the parameter `flushEnabled`:
+[source,bash]
----
-curl -v -X POST http://10.143.201.101:8091/pools/default/buckets/testBucket \
+curl -v -X POST http://127.0.0.1:8091/pools/default/buckets/testBucket \
-u Administrator:password \
-d flushEnabled=0
----
@@ -677,7 +755,7 @@ No object is returned.
[#magmaseqtreedatablocksize]
=== magmaSeqTreeDataBlockSize
-The block size, in bytes, for Magma _seqIndex_ blocks.
+The block size, in bytes, for Magma seqIndex blocks.
The minimum block size that can be specified is 4096; and the maximum is 131072.
The default size is 4096.
The larger the specified block size, the better may be the block compression; potentially at the cost of greater consumption of memory, CPU, and I/O bandwidth.
@@ -690,8 +768,9 @@ This setting cannot be established or retrieved until the entire cluster is runn
The following example creates the bucket `testBucket`, establishing the value of `magmaSeqTreeDataBlockSize` as `7000`.
+[source,bash]
----
-curl -v -X POST http://10.143.201.101:8091/pools/default/buckets \
+curl -v -X POST http://127.0.0.1:8091/pools/default/buckets \
-u Administrator:password \
-d name=testBucket \
-d ramQuota=1100 \
@@ -717,8 +796,9 @@ For an overview of change history, see xref:learn:data/change-history.adoc[Chang
[#example-retention-collection-create]
==== Example: Disable historyRetentionCollectionDefault, when Creating
-The following example creates a bucket, specifies its storage as _magma_, and specifies that a record of changes made to collections within the bucket should _not_ be made.
+The following example creates a bucket, specifies its storage as magma, and specifies that a record of changes made to collections within the bucket should not be made.
+[source,bash]
----
curl -X POST http://localhost:8091/pools/default/buckets \
-u Administrator:password \
@@ -735,6 +815,7 @@ Success returns `202 Accepted`.
The following example modifies the value of `historyRetentionCollectionDefault` for the existing bucket `testBucket`.
+[source,bash]
----
curl -v -X POST http://localhost:8091/pools/default/buckets/testBucket \
-u Administrator:password \
@@ -749,8 +830,8 @@ Note, however, that this call only results in a change history being written to
Specifies the maximum size, in bytes, of the change history that is written to disk for all collections in this bucket when the value of `historyRetentionCollectionDefault` is `true`.
-The minimum size for the change history is _2 GiB_ (which would be specified as `2147483648`).
-The maximum is _1.8 PiB_ (which would be specified as `18446744073709551615`).
+The minimum size for the change history is 2 GiB (which would be specified as `2147483648`).
+The maximum is 1.8 PiB (which would be specified as `18446744073709551615`).
If a positive integer outside this range is specified, an error is flagged, no file-size is established, and change history remains disabled for the bucket.
Each replica configured for the bucket maintains a copy of the change history.
@@ -764,9 +845,10 @@ For an overview of change history, see xref:learn:data/change-history.adoc[Chang
[#example-retention-bytes-create]
==== Example: Set historyRetentionBytes, when Creating
-The following example creates a bucket, specifies its storage as _magma_, accepts the default value of `true` for `historyRetentionCollectionDefault`, and specifies the maximum disk-size of the change-record as _2 GiB_.
+The following example creates a bucket, specifies its storage as magma, accepts the default value of `true` for `historyRetentionCollectionDefault`, and specifies the maximum disk-size of the change-record as 2 GiB.
Thus, when this size-limit is reached, the oldest key-value pairs in the current record will be successively removed, by means of compaction.
+[source,bash]
----
curl -v -X POST http://localhost:8091/pools/default/buckets \
-u Administrator:password \
@@ -781,8 +863,9 @@ Success returns `202 Accepted`.
[#example-retention-bytes-edit]
==== Example: Modify historyRetentionBytes, when Editing
-The following example modifies the value of `historyRetentionBytes` to _4 GiB_, for the existing bucket `testBucket`.
+The following example modifies the value of `historyRetentionBytes` to 4 GiB, for the existing bucket `testBucket`.
+[source,bash]
----
curl -v -X POST http://localhost:8091/pools/default/buckets/testBucket \
-u Administrator:password \
@@ -803,9 +886,10 @@ For an overview of change history, see xref:learn:data/change-history.adoc[Chang
[#example-retention-seconds-create]
==== Example: Set historyRetentionSeconds, when Creating
-The following example creates a bucket, specifies its storage as _magma_, accepts the default value of `true` for `historyRetentionCollectionDefault`, and specifies the maximum number of seconds for the change-record as 13,600.
+The following example creates a bucket, specifies its storage as magma, accepts the default value of `true` for `historyRetentionCollectionDefault`, and specifies the maximum number of seconds for the change-record as 13,600.
Thus, key-value pairs that have been recorded prior to 13,600 seconds before the current time will be removed, by means of compaction.
+[source,bash]
----
curl -v -X POST http://localhost:8091/pools/default/buckets \
-u Administrator:password \
@@ -822,6 +906,7 @@ Success returns `202 Accepted`.
The following example modifies the number of seconds to be covered by the change history for the existing bucket `testBucket` to 11,000.
+[source,bash]
----
curl -v -X POST http://localhost:8091/pools/default/buckets/testBucket \
-u Administrator:password \
@@ -830,30 +915,96 @@ curl -v -X POST http://localhost:8091/pools/default/buckets/testBucket \
Success returns `200 OK`.
+
+[[encryptionAtRestKeyId]]
+=== encryptionAtRestKeyId
+
+Sets the encryption-at-rest key ID for the bucket.
+The default value, `-1`, indicates that the bucket is not encrypted.
+When you set this value to the `id` for an encrytion-at-rest-key, Couchbase Server encrypts the the bucket's data at rest.
+The key ID must be for an existing key and the key must be configured to encrypt either all buckets or for this bucket specifically.
+
+For more information about encryption at rest, see xref:learn:security/native-encryption-at-rest-overview.adoc[].
+
+
+==== Example: Create Bucket With Native Encryption-at-Rest Enabled
+
+The following example creates a new bucket, named `testBucket`, and enables encryption-at-rest for the bucket by setting `encryptionAtRestKeyId` to `0`.
+
+include::example$encryption-at-rest/bucket-encryption-examples.adoc[tag=create-bucket]
+
+==== Example: Change Encryption-at-Rest Key Used to Encrypt Bucket
+
+The following example changes the existing `testBucket` to use the encryption-at-rest key whose `id` is `18`.
+If this bucket was already encrypted using a different key, Couchbase Server re-encrypts the data with the new key.
+If the bucket was not encrypted, Couchbase Server encrypts the data.
+
+include::example$encryption-at-rest/bucket-encryption-examples.adoc[tag=alter-bucket]
+
+[[encryptionAtRestDekRotationInterval]]
+=== encryptionAtRestDekRotationInterval
+
+Sets how often in seconds Couchbase Server rotates the bucket's data encryption keys (DEKs).
+After this period elapses, Couchbase Server marks the DEK inactive and creates a new active DEK.
+It keeps the inactive DEK to decrypt data that's still encrypted with it until its lifetime elapses (see <>).
+
+The default value is `2592000`, which means Couchbase Server rotates the DEKs every 30 days.
+Set this value to 0 to turn off DEK rotation.
+
+For more information about key rotation, see xref:learn:security/native-encryption-at-rest-overview.adoc#rotation-expiration[Encryption Key Rotation and Expiration].
+
+The following example sets the DEK rotation interval to 15 days (1,296,000 seconds):
+
+include::example$encryption-at-rest/bucket-encryption-examples.adoc[tag=set-dek-rotation]
+
+
+[[encryptionAtRestDekLifetime]]
+=== encryptionAtRestDekLifetime
+
+Sets the lifetime of the bucket's data encryption keys (DEKs) in seconds from the moment it was created.
+Once this period passes, Couchbase Server uses the active DEK to re-encrypts any data that's still encrypted using the expired DEK.
+It then deletes the expired DEK.
+
+This value defaults to `31536000`, which means Couchbase Server keeps expired DEKs for 365 days.
+Setting this value to 0 means Couchbase Server never deletes expired DEKs.
+
+If you set `encryptionAtRestDekRotationInterval` to a non-zero value and `encryptionAtRestDekLifetime` to 0, Couchbase Server keeps old DEKs forever.
+Depending on how often you rotate the DEKs, this can lead to a Couchbase Server keeping a large number of DEKs.
+Couchbase Server limits the number of DEKs to 50 per node.
+When this limit is reached, Couchbase Server refuses to rotate the DEKs until you adjust the DEK lifetime so some DEKs can expire.
+
+IMPORTANT: Setting this value too low can cause performance issues because Couchbase Server may need to re-encrypt large amounts of data.
+
+For more information about key lifetime, see xref:learn:security/native-encryption-at-rest-overview.adoc##rotation-expiration[Encryption Key Rotation and Expiration].
+
+The following example sets the DEK lifetime to 90 days (7,776,000 seconds):
+include::example$encryption-at-rest/bucket-encryption-examples.adoc[tag=set-dek-lifetime]
+
+
[#auto-compaction-parameters]
== Auto-Compaction Parameters
-The parameters listed in the following subsections are all included in the _Auto-compaction_ group
+The parameters listed in the following subsections are all included in the Auto-compaction group
[#autocompactiondefined]
=== autoCompactionDefined
-Specifies whether the default _auto-compaction_ settings are to be modified for this bucket.
+Specifies whether the default auto-compaction settings are to be modified for this bucket.
The value specified can be either `true` or `false` (which is the default).
-If the value is `false`, any parameter-values specified in order to modify the default auto-compaction settings are ignored.
+If the value is `false`, any parameter-values specified to modify the default auto-compaction settings are ignored.
If the value is incorrectly specified, an error-notification such as the following is returned: `{"autoCompactionDefined":"autoCompactionDefined is invalid"}`.
-Note that if `autoCompactionDefined` is specified as `true`:
+If you set `autoCompactionDefined` to `true`:
* All other auto-compaction-related parameters that need to be established should themselves be explicitly specified in the current call.
-* The parameter `parallelDBAndViewCompaction` _must_ be defined.
+* The parameter `parallelDBAndViewCompaction` must be defined.
If it is not defined, an error-notification such as the following is returned: `{"parallelDBAndViewCompaction":"parallelDBAndViewCompaction is missing"}`.
-Auto-compaction settings are unnecessary for _memory-optimized_ indexes.
-For information on index storage, see xref:indexes:storage-modes.adoc[].
+Auto-compaction settings are unnecessary for memory-optimized indexes.
+For information about index storage, see xref:indexes:storage-modes.adoc[].
-For further information on auto-compaction settings, see xref:manage:manage-settings/configure-compact-settings.adoc[Auto-Compaction].
+For further information about auto-compaction settings, see xref:manage:manage-settings/configure-compact-settings.adoc[Auto-Compaction].
[#example-autocompactiondefined-create]
==== Example: Enabling Auto-Compaction, when Creating
@@ -861,8 +1012,9 @@ For further information on auto-compaction settings, see xref:manage:manage-sett
The following example creates a new bucket, named `testBucket`, and enables auto-compaction for the bucket.
Necessarily, a setting is also explicitly made for `parallelDBAndViewCompaction`:
+[source,bash]
----
-curl -v -X POST http://10.143.201.101:8091/pools/default/buckets \
+curl -v -X POST http://127.0.0.1:8091/pools/default/buckets \
-u Administrator:password \
-d name=testBucket \
-d ramQuota=256 \
@@ -876,10 +1028,11 @@ No object is returned.
[#example-autocompactiondefined-edit]
==== Example: Modifying Auto-Compaction Enablement, when Editing
-The following example changes the auto-compaction enablement of the existing bucket `testBucket`, _disabling_ auto-compaction, by specifying the value `false` to the `autoCompactionDefined` parameter:
+The following example changes the auto-compaction enablement of the existing bucket `testBucket`, disabling auto-compaction, by specifying the value `false` to the `autoCompactionDefined` parameter:
+[source,bash]
----
-curl -v -X POST http://10.143.201.101:8091/pools/default/buckets/testBucket \
+curl -v -X POST http://127.0.0.1:8091/pools/default/buckets/testBucket \
-u Administrator:password \
-d autoCompactionDefined=false
----
@@ -887,10 +1040,11 @@ curl -v -X POST http://10.143.201.101:8091/pools/default/buckets/testBucket \
This disables auto-compaction for the bucket, and removes all auto-compaction-related settings.
If the call is successful, a `200 OK` notification is returned, with no object.
-To _enable_ auto-compaction after bucket creation, the `parallelDBAndViewCompaction` parameter must also be specified; as in the following example, which sets `parallelDBAndViewCompaction` to `false`:
+To enable auto-compaction after bucket creation, the `parallelDBAndViewCompaction` parameter must also be specified; as in the following example, which sets `parallelDBAndViewCompaction` to `false`:
+[source,bash]
----
-curl -v -X POST http://10.143.201.101:8091/pools/default/buckets/testBucket \
+curl -v -X POST http://127.0.0.1:8091/pools/default/buckets/testBucket \
-u Administrator:password \
-d autoCompactionDefined=true \
-d parallelDBAndViewCompaction=false
@@ -903,8 +1057,8 @@ No object is returned.
=== parallelDBAndViewCompaction
Specifies whether compaction should occur to documents and view indexes in parallel.
-This is a _global_ setting, which therefore affects _all_ buckets on the cluster.
-The value can either be `true` or `false`: one value or the other _must_ be specified.
+This is a global setting, which therefore affects all buckets on the cluster.
+The value can either be `true` or `false`: one value or the other must be specified.
If the value is incorrectly specified, the following error-notification is returned: `{"parallelDBAndViewCompaction":"parallelDBAndViewCompaction is invalid"}`.
This parameter-value is ignored if `autoCompactionDefined` is `false` (which is its default value).
@@ -929,8 +1083,9 @@ This parameter is ignored if `autoCompactionDefined` is `false` (which is its de
The following example establishes a value for `databaseFragmentationThreshold[percentage]`, and for all other auto-compaction-related parameters, in its creation of a new bucket, named `testBucket`:
+[source,bash]
----
-curl -v -X POST http://10.143.201.101:8091/pools/default/buckets \
+curl -v -X POST http://127.0.0.1:8091/pools/default/buckets \
-u Administrator:password \
-d name=testBucket \
-d ramQuota=256 \
@@ -957,10 +1112,11 @@ No object is returned.
==== Example: Specifying a Data Fragmentation Threshold as a Percentage, when Editing
The following example modifies the `databaseFragmentationThreshold[percentage]` setting for the existing bucket `testBucket`; establishing a new value of `47`.
-Note that although other auto-compaction settings are intended to be unchanged from their previous, explicit settings, all _must be respecified_ correspondingly in the new call: otherwise, all revert to their default values.
+Note that although other auto-compaction settings are intended to be unchanged from their previous, explicit settings, all must be respecified correspondingly in the new call: otherwise, all revert to their default values.
+[source,bash]
----
-curl -v -X POST http://10.143.201.101:8091/pools/default/buckets/testBucket \
+curl -v -X POST http://127.0.0.1:8091/pools/default/buckets/testBucket \
-u Administrator:password \
-d autoCompactionDefined=true \
-d parallelDBAndViewCompaction=false \
@@ -1025,7 +1181,7 @@ See the examples provided above, in xref:rest-api:rest-bucket-create.adoc#exampl
=== purgeInterval
Specifies the tombstone (or metadata) purge interval.
-The value can be either an integer (indicating a number of days), or a float (indicating an interval that may be greater or less than one day, and entails a number of hours, with `0.04` indicating _one hour_).
+The value can be either an integer (indicating a number of days), or a float (indicating an interval that may be greater or less than one day, and entails a number of hours, with `0.04` indicating one hour).
The default value is three days.
If this parameter is incorrectly specified, an error-notification such as the following is returned: `{"purgeInterval":"metadata purge interval must be a number"}`.
@@ -1118,7 +1274,7 @@ Information on memory-management options for Couchbase Server is provided in For
Information on auto-compaction settings is provided in xref:manage:manage-settings/configure-compact-settings.adoc[Auto-Compaction].
For an overview of change history, see xref:learn:data/change-history.adoc[Change History].
-Information on other, Couchbase-Server key concepts can be found as follows: for durability, in xref:learn:data/durability.adoc[Durability]; for expiration (_time-to-live_), in xref:learn:data/expiration.adoc[Expiration]; for ejection, in xref:learn:buckets-memory-and-storage/memory.adoc[Memory]; for replication, in xref:learn:clusters-and-availability/intra-cluster-replication.adoc[Intra-Cluster Replication]; for compression, in xref:learn:/buckets-memory-and-storage/compression.adoc[Compression]; for conflict resolution, in xref:learn:/clusters-and-availability/xdcr-conflict-resolution.adoc[XDCR Conflict Resolution]; for purging, in xref:manage:manage-settings/configure-compact-settings.adoc#tombstone-purge-interval[Tombstone Purge Interval].
+Information on other, Couchbase-Server key concepts can be found as follows: for durability, in xref:learn:data/durability.adoc[Durability]; for expiration (time-to-live), in xref:learn:data/expiration.adoc[Expiration]; for ejection, in xref:learn:buckets-memory-and-storage/memory.adoc[Memory]; for replication, in xref:learn:clusters-and-availability/intra-cluster-replication.adoc[Intra-Cluster Replication]; for compression, in xref:learn:/buckets-memory-and-storage/compression.adoc[Compression]; for conflict resolution, in xref:learn:/clusters-and-availability/xdcr-conflict-resolution.adoc[XDCR Conflict Resolution]; for purging, in xref:manage:manage-settings/configure-compact-settings.adoc#tombstone-purge-interval[Tombstone Purge Interval].
See xref:learn:security/roles.adoc[Roles], for information on roles and privileges.
diff --git a/modules/rest-api/pages/rest-buckets-summary.adoc b/modules/rest-api/pages/rest-buckets-summary.adoc
index ffc8c71160..da6c488e07 100644
--- a/modules/rest-api/pages/rest-buckets-summary.adoc
+++ b/modules/rest-api/pages/rest-buckets-summary.adoc
@@ -1,5 +1,5 @@
= Getting Bucket Information
-:description: Information on buckets defined on the cluster can be retrieved, by means of the REST API.
+:description: information about buckets defined on the cluster can be retrieved, by means of the REST API.
:page-topic-type: reference
:page-aliases: rest-bucket-info
@@ -18,8 +18,8 @@ GET /pools/default/buckets/
[#description]
== Description
-`GET /pools/default/buckets` retrieves information on all buckets defined on the cluster.
-If the `` path-parameter is added, only information on the specified bucket is retrieved.
+`GET /pools/default/buckets` retrieves information about all buckets defined on the cluster.
+If the `` path-parameter is added, only information about the specified bucket is retrieved.
[#curl-syntax]
@@ -32,7 +32,7 @@ curl -X GET http://:8091/pools/default/buckets/>
+* <<#drop-type>>
+
+[#drop-bucket]
+== Drop DEKs and Re-encrypt Data for a Bucket
+
+Drop all DEKs for a bucket and re-encrypt all data in that bucket with new DEK.
+
+.Drop DEKs for Bucket and Re-encrypt Data
+----
+POST /controller/dropEncryptionAtRestDeks/bucket/{BUCKET_NAME}
+----
+
+.Path Parameters
+`BUCKET_NAME`::
+The name of the bucket where you want to drop the DEKs and re-encrypt.
+This bucket must already have encryption at rest enabled.
+
+=== curl Syntax
+
+[source,bash]
+----
+curl -sS -u $USER:$PASSWORD \
+ -X POST 'http[s]://:{PORT}/controller/dropEncryptionAtRestDeks/bucket/{BUCKET_NAME}'
+----
+
+.Path Parameters
+:priv-link: bucket-privs
+include::partial$user-pw-host-port-params.adoc[]
+
+`BUCKET_NAME`::
+The name of the bucket where you want to drop DEKs and re-encrypt data.
+This bucket must already have encryption at rest enabled.
+
+[#bucket-privs]
+=== Required Privileges
+
+* xref:learn:security/roles.adoc#backup_admin[Backup Admin]
+* xref:learn:security/roles.adoc#bucket_admin[Bucket Admin] that has privileges on the bucket to be encrypted.
+* xref:learn:security/roles.adoc#cluster_admin[Cluster Admin]
+* xref:learn:security/roles.adoc#eventing_admin[Eventing Admin]
+* xref:learn:security/roles.adoc#admin[Full Admin]
+
+=== Responses
+
+`200 OK`::
+The DEKs for the bucket were dropped and the data was re-encrypted with the new DEK.
+It also returns a JSON object containing a timestamp of when the drop and re-encryption process started.
+See <<#drop-bucket-example,the example in the next section>> for an example of the response.
+
+`403 Forbidden`::
+You do not have the required privileges to drop the DEKs for the bucket.
+
+`404 Not Found`::
+The bucket passed in the `BUCKET_NAME` path parameter does not exist.
+
+[#drop-bucket-example]
+=== Example
+
+The following example drops the DEKs for the `travel-sample` bucket and re-encrypts all data in that bucket with the new DEK.
+
+[source,bash]
+----
+curl -sS -u Administrator:password -X POST \
+ http://localhost:8091/controller/dropEncryptionAtRestDeks/bucket/travel-sample \
+ | jq
+----
+
+The result of the command is a JSON object similar to the following:
+
+[source,json]
+----
+{
+ "dropKeysDate": "2025-08-06T19:00:42Z"
+}
+----
+
+[#drop-type]
+== Drop DEKs and Re-encrypt Audit, Configuration, or Log Data
+
+Drop the DEKs for a type of system data and re-encrypt all data with the new DEKs.
+The data types you can re-encrypt are:
+
+* Audit
+* Configuration
+* Logs
+
+
+.Drop DEKs for Audit, Configuration, or Logs and Re-encrypt Data
+----
+POST /controller/dropEncryptionAtRestDeks/{TYPE}
+----
+
+.Path Parameters
+`TYPE`::
+The type of data whose DEKs you want dropped and data re-encrypted.
+Can be one of the following values:
+
++
+* `audit`: Encrypts unencrypted audit data.
+* `config`: Encrypts unencrypted configuration data.
+* `log`: Encrypts unencrypted log data.
+
+=== curl Syntax
+
+[source,bash]
+----
+curl -sS -u $USER:$PASSWORD \
+ -X POST 'http[s]://:{PORT}/controller/dropEncryptionAtRestDeks/{TYPE}'
+----
+
+.Path Parameters
+:priv-link: type-privs
+include::partial$user-pw-host-port-params.adoc[]
+
+`TYPE`::
+The type of data whose DEKs you want dropped and data re-encrypted.
+Can be one of the following values:
+
++
+* `audit`: Encrypts unencrypted audit data.
+* `config`: Encrypts unencrypted configuration data.
+* `log`: Encrypts unencrypted log data.
+
+[#type-privs]
+=== Required Privileges
+
+* xref:learn:security/roles.adoc#cluster_admin[Cluster Admin]
+* xref:learn:security/roles.adoc#eventing_admin[Eventing Admin]
+* xref:learn:security/roles.adoc#admin[Full Admin]
+
+=== Responses
+
+`200 OK`::
+The DEKs for the type of data were dropped and its data was re-encrypted with the new DEK.
+It also returns a JSON object containing a timestamp of when the drop and re-encryption process started.
+See <<#drop-type-example,the example in the next section>> for an example of the response.
+
+`403 Forbidden`::
+You do not have the required privileges to drop the DEKs for system data.
+
+`404 Not Found`::
+The type of data passed in the `TYPE` path parameter does not exist.
+
+[#drop-type-example]
+=== Example
+
+The following example drops the DEKs for the `audit` data and re-encrypts all data of that type with the new DEK.
+
+[source,bash]
+----
+curl -v -u Administrator:password -X POST \
+ http://localhost:8091/controller/dropEncryptionAtRestDeks/audit \
+ | jq
+----
+
+The result of the command is a JSON object similar to the following:
+[source,json]
+----
+{
+ "dropKeysDate": "2025-08-06T19:05:42Z"
+}
+----
+
diff --git a/modules/rest-api/pages/security/encryption-at-rest/encryption-at-rest.adoc b/modules/rest-api/pages/security/encryption-at-rest/encryption-at-rest.adoc
new file mode 100644
index 0000000000..7f76b609fe
--- /dev/null
+++ b/modules/rest-api/pages/security/encryption-at-rest/encryption-at-rest.adoc
@@ -0,0 +1,74 @@
+= Encryption-at-Rest API
+:description: pass:q[The encryption-at-rest API lets you encrypt audit, configuration, logging, and bucket data when written to disk.]
+:page-edition: Enterprise Edition
+:page-topic-type: reference
+
+[abstract]
+{description}
+See xref:learn:security/native-encryption-at-rest-overview.adoc[] for more information.
+
+== APIs in this Section
+
+[cols="76,215,249"]
+|===
+| HTTP Method | URI | Documented at
+
+| `GET`
+| `/settings/encryptionKeys/`
+| xref:rest-api:security/encryption-at-rest/manage-encryption-keys.adoc#list-keys[List Encryption-at-Rest Keys]
+
+| `GET`
+| `/settings/encryptionKeys/{KEY_ID}`
+| xref:rest-api:security/encryption-at-rest/manage-encryption-keys.adoc#list-keys[List Single Encryption-at-Rest Key]
+
+| `POST`
+| `/settings/encryptionKeys`
+| xref:rest-api:security/encryption-at-rest/manage-encryption-keys.adoc#create-key[Create an Encryption-at-Rest Key]
+
+| `POST`
+| `/settings/encryptionKeys/{KEY_ID}/test`
+| xref:rest-api:security/encryption-at-rest/manage-encryption-keys.adoc#test-key[Test an Encryption-at-Rest Key]
+
+| `PUT`
+| `/settings/encryptionKeys/{KEY_ID}`
+| xref:rest-api:security/encryption-at-rest/manage-encryption-keys.adoc#create-key[Update an Encryption-at-Rest Key]
+
+| `PUT`
+| `/settings/encryptionKeys/{KEY_ID}/test`
+| xref:rest-api:security/encryption-at-rest/manage-encryption-keys.adoc#test-key-changes[Test changes to an Encryption-at-Rest Key]
+
+| `DELETE`
+| `/settings/encryptionKeys/{KEY_ID}`
+| xref:rest-api:security/encryption-at-rest/manage-encryption-keys.adoc#delete-key[Delete an Encryption-at-Rest Key]
+
+| `GET`
+| `/settings/security/encryptionAtRest`
+| xref:rest-api:security/encryption-at-rest/manage-system-encryption-at-rest.adoc#get-settings[Get Audit, Config, and Log Encryption-at-Rest Settings]
+
+| `POST`
+| `/settings/security/encryptionAtRest`
+| xref:rest-api:security/encryption-at-rest/manage-system-encryption-at-rest.adoc#change-settings[Change Audit, Config, and Log Data Encryption-at-Rest Settings]
+
+| `POST`
+| `/controller/dropEncryptionAtRestDeks/bucket/{BUCKET_NAME}`
+| xref:rest-api:security/encryption-at-rest/drop-encryption-deks.adoc#drop-bucket[Rotate DEKs for Bucket and Re-encrypt Data]
+
+| `POST`
+| `/controller/dropEncryptionAtRestDeks/{TYPE}`
+| xref:rest-api:security/encryption-at-rest/drop-encryption-deks.adoc#drop-type[Rotate DEKs and Re-encrypt Data for a Type of Encrypted Data]
+
+| `POST`
+| `/controller/rotateEncryptionKey/{KEY_ID}`
+| xref:rest-api:security/encryption-at-rest/rotate-encryption-at-rest-key.adoc#rotate-key[Rotate Encryption-at-Rest Key]
+
+| `POST`
+| `/controller/forceEncryptionAtRest/bucket/{BUCKET_NAME}`
+| xref:rest-api:security/encryption-at-rest/force-encryption-at-rest.adoc#bucket[Force Encryption of Unencrypted Bucket Data]
+
+| `POST`
+| `/controller/forceEncryptionAtRest/{TYPE}`
+| xref:rest-api:security/encryption-at-rest/force-encryption-at-rest.adoc#type[Force Encryption of Unencrypted Data of a Type]
+
+
+
+|===
diff --git a/modules/rest-api/pages/security/encryption-at-rest/force-encryption-at-rest.adoc b/modules/rest-api/pages/security/encryption-at-rest/force-encryption-at-rest.adoc
new file mode 100644
index 0000000000..be0fb1ab0f
--- /dev/null
+++ b/modules/rest-api/pages/security/encryption-at-rest/force-encryption-at-rest.adoc
@@ -0,0 +1,210 @@
+= Force Encryption of Unencrypted Data
+:description: pass:q[Use these REST APIs to force Couchbase Server to encrypt existing data.]
+:page-edition: Enterprise Edition
+:page-topic-type: reference
+:tabs:
+:page-toclevels: 3
+
+[abstract]
+{description}
+
+== Description
+
+When you enable encryption at rest for a bucket or a type of data, Couchbase Server begins encrypting newly written data.
+However, it does not encrypt existing data.
+These APIs let you force Couchbase Server to encrypt existing data in a bucket or all data of a specific type.
+See xref:learn:security/native-encryption-at-rest-overview.adoc[] for more information about encryption at rest.
+
+NOTE: This method is similar to the xref:rest-api:security/encryption-at-rest/drop-encryption-deks.adoc[`/controller/dropEncryptionAtRestDeks`] endpoint, but it does not rotate the data encryption keys (DEKs) nor does it re-encrypt already-encrypted data.
+
+== HTTP Methods
+
+This API endpoint supports the following methods:
+
+* <<#bucket>>
+* <<#type>>
+
+[#bucket]
+== Force Encryption of Unencrypted Bucket Data
+
+Force the unencrypted data in a bucket to be encrypted immediately.
+
+.Encrypt Unencrypted Data in Bucket
+----
+POST /controller/forceEncryptionAtRest/bucket/{BUCKET_NAME}
+----
+
+.Path Parameters
+`BUCKET_NAME`::
+The name of the bucket whose unencrypted data you want to encrypt.
+This bucket must already have encryption at rest enabled.
+
+=== curl Syntax
+
+[source,bash]
+----
+curl -sS -u $USER:$PASSWORD \
+ -X POST 'http[s]://:{PORT}/controller/forceEncryptionAtRest/bucket/{BUCKET_NAME}'
+----
+
+.Path Parameters
+:priv-link: bucket-privs
+include::partial$user-pw-host-port-params.adoc[]
+
+`BUCKET_NAME`::
+The name of the bucket whose unencrypted data you want to encrypt.
+This bucket must already have encryption at rest enabled for this method to have an effect.
+
+[#bucket-privs]
+=== Required Privileges
+
+You must have at least one of the following roles:
+
+* xref:learn:security/roles.adoc#backup_admin[Backup Admin]
+* xref:learn:security/roles.adoc#bucket_admin[Bucket Admin] that has privileges on the bucket to be encrypted.
+* xref:learn:security/roles.adoc#cluster_admin[Cluster Admin]
+* xref:learn:security/roles.adoc#eventing_admin[Eventing Admin]
+* xref:learn:security/roles.adoc#admin[Full Admin]
+
+=== Responses
+
+`200 OK`::
+The request was successful and Couchbase Server starts encrypting the data.
+Returns a JSON object with a timestamp of when Couchbase Server started encrypting the data.
+See <<#bucket-example,the example in the next section>> for an example of the response.
+
++
+NOTE: This endpoint also returns `200 OK` for buckets that do not have encryption at rest enabled.
+In this case, the request does not encrypt any data.
+
+`400 Bad Request`::
+The request was malformed or Couchbase Server could not process it.
+
+`401 Unauthorized`::
+The user credentials you supplied were not valid.
+
+`403 Forbidden`::
+Your user account does not have one of the required roles to call this endpoint.
+
+`404 Not Found`::
+The bucket named in the `BUCKET_NAME` path parameter does not exist.
+
+
+[#bucket-example]
+=== Example
+
+The following example demonstrates how to force Couchbase Server to encrypt the unencrypted data in a bucket named `travel-sample`:
+
+[source,bash]
+----
+curl -v -u Administrator:password
+ -X POST http://localhost:8091/controller/forceEncryptionAtRest/bucket/travel-sample
+ | jq
+----
+
+The result of request is a JSON object with a `forceEncryptionDate` attribute that contains the date and time when Couchbase Server started encrypting the data:
+
+[source,json]
+----
+{
+ "forceEncryptionDate": "2025-08-04T17:58:39Z"
+}
+----
+
+
+[#type]
+== Force Encryption of a Type of Non-bucket Data
+
+Force the encryption of unencrypted data of one of the following types:
+
+* Audit
+* Configuration
+* Logging
+
+.Encrypt Unencrypted Data of a Type
+----
+POST /controller/forceEncryptionAtRest/{TYPE}
+----
+
+.Path Parameter
+`TYPE`::
+The type of data to encrypt.
+Can be one of the following values:
+
++
+* `audit`: Encrypts unencrypted audit data.
+* `config`: Encrypts unencrypted configuration data.
+* `log`: Encrypts unencrypted log data.
+
+=== curl Syntax
+
+[source,bash]
+----
+curl -sS -u $USER:$PASSWORD \
+ -X POST 'http://localhost:8091/controller/forceEncryptionAtRest/{TYPE}'
+----
+
+.Path Parameters
+:priv-link: type-privs
+include::partial$user-pw-host-port-params.adoc[]
+
+`TYPE`::
+The type of data to encrypt.
+Must be one of the following values:
+
++
+* `audit`: Encrypts unencrypted audit data.
+* `config`: Encrypts unencrypted configuration data.
+* `log`: Encrypts unencrypted log data.
+
+[#type-privs]
+=== Required Privileges
+
+To call this endpoint, you must have at least one of the following roles:
+
+* xref:learn:security/roles.adoc#admin[Full Admin]
+* xref:learn:security/roles.adoc#security_admin[Security Admin]
+
+=== Responses
+
+`200 OK`::
+The request was successful and Couchbase Server starts encrypting the data.
+Returns a JSON object with a timestamp of when Couchbase Server started encrypting the data.
+See <<#type-example,the example in the next section>> for an example of the response.
+
++
+NOTE: This endpoint also returns `200 OK` if you have not enabled encryption at rest for the type of data set by the `TYPE` path parameter.
+In this case, the request does not encrypt any data.
+
+`400 Bad Request`::
+The request was malformed or Couchbase Server could not process it.
+
+`401 Unauthorized`::
+The user credentials you supplied were not valid.
+
+`403 Forbidden`::
+Your user account does not have one of the required roles to call this endpoint.
+
+`404 Not Found`::
+The `TYPE` path did not contain one of the valid values: `audit`, `config`, or `log`.
+
+[#type-example]
+=== Example
+
+The following example demonstrates how to force Couchbase Server to encrypt unencrypted log data:
+
+[source,console]
+----
+curl -sS -u Administrator:password -X POST \
+ http://localhost:8091/controller/forceEncryptionAtRest/log \
+ | jq
+----
+
+The result of request is a JSON object with a `forceEncryptionDate` attribute that contains the date and time when Couchbase Server started encrypting the data:
+
+[source,json]
+----
+{
+ "forceEncryptionDate": "2025-08-05T13:18:34Z"
+}
+----
diff --git a/modules/rest-api/pages/security/encryption-at-rest/manage-encryption-keys.adoc b/modules/rest-api/pages/security/encryption-at-rest/manage-encryption-keys.adoc
new file mode 100644
index 0000000000..147b55f7b7
--- /dev/null
+++ b/modules/rest-api/pages/security/encryption-at-rest/manage-encryption-keys.adoc
@@ -0,0 +1,842 @@
+= Manage Encryption-at-Rest Keys
+:description: pass:q[You must create encryption-at-rest keys before you can have Couchbase Server encrypt data as it saves it to disk.]
+:page-edition: Enterprise Edition
+:page-topic-type: reference
+:tabs:
+:page-toclevels: 3
+
+[abstract]
+{description}
+
+== Description
+
+These APIs let you list, create, change, test, and delete encryption-at-rest keys.
+See xref:learn:security/native-encryption-at-rest-overview.adoc[] for more information about encryption at rest.
+
+== HTTP Methods
+
+This API endpoint supports the following methods:
+
+* <<#list-keys>>
+* <<#create-key>>
+* <<#test-key>>
+* <<#test-key-changes>>
+* <<#delete-key>>
+
+[#list-keys]
+== List Encryption-at-Rest Keys
+
+List one or all encryption-at-rest keys defined in the cluster.
+
+.List All Keys
+----
+GET /settings/encryptionKeys/
+----
+
+.Get details of a specific key
+----
+GET /settings/encryptionKeys/{KEY_ID}
+----
+
+.Path Parameters
+`KEY_ID` (integer)::
+The `id` attribute of the key you want to view.
+See the <<#gey-keys-example,example>> for an explanation of getting this value.
+
+=== curl Syntax
+
+[source,bash]
+----
+curl -sS -u $USER:$PASSWORD \
+ -X GET 'http[s]://:{PORT}/settings/encryptionKeys/[{KEY_ID}]'
+----
+
+.Path Parameters
+:priv-link: get-privs
+include::partial$user-pw-host-port-params.adoc[]
+
+`KEY_ID` (optional)::
+The id of the single encryption-at-rest key whose details you want to retrieve.
+
+
+[[get-privs]]
+=== Required Privileges
+
+The role you need to view specific keys depends on their use.
+
+The following roles let you view all keys, including keys that can encrypt other keys (KEKs), audit, logs, and configuration data:
+
+* xref:learn:security/roles.adoc#admin[Full Admin]
+* xref:learn:security/roles.adoc#read-only-admin[Read-Only Admin]
+* xref:learn:security/roles.adoc#security_admin[Security Admin]
+
+The following roles let you view keys that can encrypt data in buckets.
+Some of the role's ability to read keys depends on whether you have rights to access the bucket.
+For example, the Data Reader role only grants you access to keys that can encrypt data in buckets you have read access to.
+
+* xref:learn:security/roles.adoc#admin[Full Admin]
+* xref:learn:security/roles.adoc#read-only-admin[Read-Only Admin]
+* xref:learn:security/roles.adoc#security-admin[Security Admin]
+* xref:learn:security/roles.adoc#local-user-security-admin[Local User Admin]
+* xref:learn:security/roles.adoc#external-user-security-admin[External User Admin]
+* xref:learn:security/roles.adoc#cluster-admin[Cluster Admin]
+* xref:learn:security/roles.adoc#eventing-full-admin[Eventing Full Admin]
+* xref:learn:security/roles.adoc#admin[Backup Full Admin]
+* xref:learn:security/roles.adoc#backup-full-admin[Bucket Admin]
+* xref:learn:security/roles.adoc#application-access[Application Access]
+* xref:learn:security/roles.adoc#views-admin[Views Admin]
+* xref:learn:security/roles.adoc#xdcr-admin[XDCR Admin]
+* xref:learn:security/roles.adoc#data-reader[Data Reader]
+* xref:learn:security/roles.adoc#data-writer[Data Writer]
+* xref:learn:security/roles.adoc#data-dcp-reader[Data DCP Reader]
+* xref:learn:security/roles.adoc#data-backup-and-restore[Data Backup & Restore]
+* xref:learn:security/roles.adoc#data-monitor[Data Monitor]
+* xref:learn:security/roles.adoc#search-admin[Search Admin]
+* xref:learn:security/roles.adoc#search-reader[Search Reader]
+* xref:learn:security/roles.adoc#query-select][Query Select]
+* xref:learn:security/roles.adoc#query-update[Query Update]
+* xref:learn:security/roles.adoc#query-insert[Query Insert]
+* xref:learn:security/roles.adoc#query-delete[Query Delete]
+* xref:learn:security/roles.adoc#query-manage-index[Query Manage Index]
+* xref:learn:security/roles.adoc#query-list-index[Query List Index]
+* xref:learn:security/roles.adoc#query-system-catalog[Query System Catalog]
+* xref:learn:security/roles.adoc#query-curl-access[Query CURL Access]
+* xref:learn:security/roles.adoc#xdcr-inbound[XDCR Inbound]
+* xref:learn:security/roles.adoc#sync-gateway[Sync Gateway]
+
+=== Responses
+
+`200 OK`::
+Returns the encryption-at-rest keys or a particular key if you specified the `KEY_ID` path parameter.
+See examples for an example of the keys.
+
++
+NOTE: Call returns `200 OK` and an empty JSON message if user does not have permission to view keys.
+
+`404 Object Not Found`::
+Returned if you specified a `KEY_ID` path parameter which does not match the ID of an encryption-at-rest key.
+
+[#gey-keys-example]
+=== Examples
+
+The following example gets all of the encryption-at-rest keys defined in the system.
+
+[source,bash]
+----
+ curl -sS -u Administrator:password \
+ -X GET 'http://127.0.0.1:8091/settings/encryptionKeys/' | jq
+----
+
+An example of running the previous command:
+
+[source,json]
+----
+[
+ {
+ "data": {
+ "keys": [
+ {
+ "id": "b3dd8518-e747-4a64-ad6b-db9c5d306a6c",
+ "active": true,
+ "creationDateTime": "2025-04-23T16:22:39Z",
+ "keyMaterial": "******"
+ }
+ ],
+ "encryptionApproach": "nodeSecretManager",
+ "canBeCached": true,
+ "autoRotation": false
+ },
+ "id": 7,
+ "name": "data-one-buckey-key",
+ "type": "cb-server-managed-aes-key-256",
+ "usage": [
+ "bucket-encryption-beer-sample",
+ "bucket-encryption-test"
+ ],
+ "creationDateTime": "2025-04-23T16:22:39Z"
+ },
+ {
+ "data": {
+ "port": 5696,
+ "host": "https://kms.example.com",
+ "reqTimeoutMs": 1000,
+ "keyPath": "/scripts/certs/cb_key.pem",
+ "keyPassphrase": "******",
+ "encryptionApproach": "useGet",
+ "certPath": "/scripts/certs/cb_cert.pem",
+ "caSelection": "useSysAndCbCa",
+ "encryptionApproach": "nodeSecretManager",
+ "historicalKeys": [],
+ "activeKey": {
+ "id": "0788edb1-1418-4225-903b-bc1f9f59aa4d",
+ "kmipId": "550e8400-e29b-41d4-a716-446655440000",
+ "creationDateTime": "2025-04-23T14:44:20Z"
+ },
+ "encryptionApproachKeyId": -1
+ },
+ "id": 2,
+ "name": "kmip-key",
+ "type": "kmip-aes-key-256",
+ "usage": [
+ "KEK-encryption",
+ "bucket-encryption",
+ "config-encryption",
+ "log-encryption",
+ "audit-encryption"
+ ],
+ "creationDateTime": "2025-04-23T14:44:20Z"
+ },
+ {
+ "data": {
+ "profile": "",
+ "configFile": "",
+ "useIMDS": true,
+ "region": "us-east-1",
+ "keyARN": "arn:aws:kms:us-east-1:000000000000:key/aaaaaaaa-bbbb-dddd-eeee-ffffffffffff",
+ "credentialsFile": "",
+ "storedKeyIds": [
+ {
+ "id": "c1cddf80-720e-47f0-adb7-641f5cb2ce22",
+ "creationDateTime": "2025-04-23T16:00:22Z"
+ }
+ ]
+ },
+ "id": 6,
+ "name": "Example AWS key",
+ "type": "awskms-symmetric-key",
+ "usage": [
+ "KEK-encryption"
+ ],
+ "creationDateTime": "2025-04-23T16:00:22Z"
+ }
+]
+----
+
+
+All keys have the following fields:
+
+* `id`: the integer identifying the encryption key
+* `name`: the friendly name assigned by the administrator who created the key.
+* `usage`: what the key is allowed to encrypt.
+* `type`: which key management system (KMS) manages the key.
++
+NOTE: The `type` also contains the encryption algorithm used for the encryption-at-rest key.
+Currently, this is always `aes-key-256`.
+
+The `data` object defines the KMS-specific details for each encryption key.
+You'll notice different fields for each type of key:
+
+Keys managed by Couchbase Server::
+
+* The `keys` list contains the current and expired encryption keys.
+The other key types have their contents stored within the remote KMS.
+* The `autorotation` field indicates whether Couchbase Server automatically rotates the key.
+When set to `true``, additional fields, such as `data.rotationIntervalInDays` and `nextRotationTime` show details of the key's rotation.
+*
+
+Keys managed by a KMIP-compatible KMS::
+
+* The fields configure the authentication with the KMS.
+
+Keys Managed by AWS::
+
+* `keyANN` is the identity of the key in the AWS KMS.
+* The `profile`, `credentialsFile`, and `configFile` hold the credentials Couchbase Server uses to authenticate with AWS KMS.
+These values are empty when Couchbase Server uses IAM to authenticate with AWS instead of stored credentials.
+
+[[create-key]]
+== Create or Update an Encryption-at-Rest Key
+
+You can create or update an encryption-at-rest-key key using the REST API.
+
+.Create an Encryption Key
+----
+POST /settings/encryptionKeys/
+----
+
+.Update a Key
+----
+PUT /settings/encryptionKeys/{KEY_ID}
+----
+
+.Path Parameters
+`KEY_ID` (integer)::
+The `id` attribute of the key you want to update.
+
+
+=== curl Syntax
+
+.Create an Encryption at Rest Key
+[source,bash]
+----
+curl -sS -u $USER:$PASSWORD \
+ -X POST http://{HOST}:{PORT}/settings/encryptionKeys \
+ --data-binary @- <",
+ "usage": [
+ ""[.""...]
+ ],
+ "type": "",
+ "data": {
+
+ }
+}
+EOF
+----
+
+.Update an Encryption at Rest Key
+[source,bash]
+----
+curl -sS -u $USER:$PASSWORD \
+ -X PUT http://{HOST}:{PORT}/settings/encryptionKeys/{KEY_ID} \
+ --data-binary @- <",
+ "usage": [
+ ""[.""...]
+ ],
+ "type": "",
+ "data": {
+
+ }
+}
+EOF
+----
+
+NOTE: Updating a key has the same required fields as the creating a new key.
+For example, you must supply the `name` field, even if you want the key's name to remain the same.
+Couchbase Server sets any value you do not supply in the update call to the default value (if any) or is left empty, overwriting any existing value.
+
+
+:priv-link: create-privs
+.Path Parameters
+include::partial$user-pw-host-port-params.adoc[]
+
+`KEY_ID` (integer)::
+ The `id` attribute of the key you want to update.
+
+.Fields
+:field-use: create
+include::partial$encryption-at-rest-post-put-fields.adoc[]
+
+[#create-privs]
+=== Required Privileges
+
+The role you need to create or update keys depends on what the key you're creating or updating can encrypt:
+
+include::rest-api:partial$encryption-at-rest-key-write-roles.adoc[]
+
+=== Responses
+
+`200 OK`::
+Returns a JSON message containing the new encryption-at-rest key.
+See <<#create-examples>> for examples of the returned JSON.
+
+`400 Bad Request`::
+Returned when errors occur, such as leaving out a required setting or invalid JSON.
+Also returns a descriptive JSON message.
+For example, if you set `encryptionApproach` to `encryptionKey` but do not set `encryptionApproachKeyID`, you receive this message:
+
++
+[source,json]
+----
+{
+ "errors": {
+ "data": {
+ "encryptionApproach": "encryptionApproachKeyId must be set when 'encryptionKey' is used"
+ }
+ }
+}
+----
+
+`403 Forbidden`::
+Returned if you do not have the proper roles to call this API.
+See <<#create-privs>>.
+
+`404 Object Not Found`::
+Returned if you specified a `encryptionApproachKeyId` field or a `KEY_ID` path parameter which does not match the `id` field of an existing encryption-at-rest key.
+
+
+[#create-examples]
+=== Examples
+
+[#create-managed-example]
+.Create a Couchbase Server Managed Key
+
+The following example creates an auto-generated key (one managed by Couchbase Server).
+The only data it can encrypt is the travel sample bucket.
+It can also encrypt the configuration and logs.
+
+include::example$encryption-at-rest/create-auto-generated-key.adoc[]
+
+The output of running the previous command in the previous example looks like this:
+
+include::example$encryption-at-rest/create-auto-generated-key-response.adoc[]
+
+
+.Create AWS KMS Managed Key
+
+The following example creates a key managed by the AWS KMS.
+It relies on IAM roles configured outside of Couchbase Server to authenticate with AWS KMS.
+The key it creates can only encrypt other encryption-at-rest keys.
+This is the best practice when using AWS KMS to store encryption-at-rest keys.
+See xref:learn:security/native-encryption-at-rest-overview.adoc#aws-kms-caution[this caution] for more information.
+
+[source,bash]
+----
+curl -sS -u Administrator:password \
+ -X POST \
+ http://127.0.0.1:8091/settings/encryptionKeys \
+ --data-binary @- <>.
+The update makes the key able to encrypt any bucket and sets the next rotation time to a later date.
+
+[source,bash]
+----
+curl -sS -u Administrator:password \
+ -X PUT \
+ http://127.0.0.1:8091/settings/encryptionKeys/13 \
+ --data-binary @- <> for an explanation of getting this value.
+
+=== curl Syntax
+
+[source,bash]
+----
+curl -sS -u $USER:$PASSWORD \
+ -X POST 'http[s]://:{PORT}/settings/encryptionKeys/{KEY_ID}/test'
+----
+
+.Path Parameters
+:priv-link: test-privs
+include::partial$user-pw-host-port-params.adoc[]
+
+`KEY_ID`::
+The `id` attribute of the encryption-at-rest key that you want to test.
+
+[#test-privs]
+=== Required Privileges
+
+You must have at least one of the following roles:
+
+* xref:learn:security/roles.adoc#security_admin_external[External User Admin]
+* xref:learn:security/roles.adoc#admin[Full Admin]
+* xref:learn:security/roles.adoc#security_admin_local[Local User Admin]
+* xref:learn:security/roles.adoc#read-only-admin[Read-Only Admin]
+* xref:learn:security/roles.adoc#security_admin[Security Admin]
+
+=== Responses
+
+`200 OK`::
+If Couchbase Server was able to use the key to encrypt and decrypt some sample data, it just returns this return code and nothing else.
+
+`404 Object Not Found`::
+Returned if you specified a `KEY_ID` path parameter which does not match the ID of an encryption-at-rest key.
+
+`400 Bad Request`::
+Returned if the key you tried to test is misconfigured or cannot access the remote KMS.
+You also receive an error message in JSON format describing the problem.
+
+
+[#gey-keys-example]
+=== Examples
+
+The following example tests the encryption-at-rest key with `id` 2.
+
+[source,bash]
+----
+ curl -v -u Administrator:password \
+ -X POST 'http://127.0.0.1:8091/settings/encryptionKeys/2/test'
+----
+
+If successful, the previous example just returns the `200 OK` status code and nothing else.
+The verbose output of the `curl` command looks like this (notice the `HTTP/1.1 200 OK` indicating the successful call):
+
+[source,console]
+----
+* Trying 127.0.0.1:8091...
+* Connected to 127.0.0.1 (127.0.0.1) port 8091
+* Server auth using Basic with user 'Administrator'
+> POST /settings/encryptionKeys/2/test HTTP/1.1
+> Host: 127.0.0.1:8091
+> Authorization: Basic QWRtaW5pc3RyYXRvcjpwYXNzd29yZA==
+> User-Agent: curl/8.7.1
+> Accept: */*
+>
+* Request completely sent off
+< HTTP/1.1 200 OK
+< Cache-Control: no-cache,no-store,must-revalidate
+< Content-Length: 0
+< Date: Tue, 05 Aug 2025 14:42:23 GMT
+< Expires: Thu, 01 Jan 1970 00:00:00 GMT
+< Pragma: no-cache
+< Server: Couchbase Server
+< X-Content-Type-Options: nosniff
+< X-Frame-Options: DENY
+< X-Permitted-Cross-Domain-Policies: none
+< X-XSS-Protection: 1; mode=block
+<
+* Connection #0 to host 127.0.0.1 left intact
+----
+
+[#test-key-changes]
+== Test Possible Changes to an Encryption-at-Rest Key
+
+You can test changes you want to make to an encryption-at-rest key managed by a remote KMS before you actually make them.
+Calling this REST API method does not actually make the changes to the key.
+It just tests an altered copy of the key to determine if it able to encrypt and decrypt data.
+The call to this API method is the same as altering the key using the xref:rest-api:security/encryption-at-rest/manage-encryption-keys.adoc#create-key[Create or Update an Encryption-at-Rest Key] API method, except it adds a `/test` suffix to the URL.
+
+NOTE: This endpoint only works for AWS and KMIP keys.
+It does not work for Couchbase Server managed keys.
+
+.Test Possible CHanges to a Key
+----
+PUT /settings/encryptionKeys/{KEY_ID}/test
+----
+
+.Path Parameters
+`KEY_ID` (integer)::
+The `id` attribute of the key you want to test.
+See the <<#gey-keys-example,example>> for an explanation of getting this value.
+
+=== curl Syntax
+
+[source,bash]
+----
+curl -sS -u $USER:$PASSWORD \
+ -X PUT 'http[s]://:{PORT}/settings/encryptionKeys/{KEY_ID}/test'
+{
+ "name": "",
+ "usage": [
+ ""[.""...]
+ ],
+ "type": "",
+ "data": {
+
+ }
+}
+EOF
+----
+
+.Path Parameters
+:priv-link: test-changes-privs
+include::partial$user-pw-host-port-params.adoc[]
+
+`KEY_ID`::
+The id of the single encryption-at-rest key that you want to test.
+
+.Fields
+// Variable to hide the CB managed key fields because they do not apply for this APi call
+:field-use: test
+include::partial$encryption-at-rest-post-put-fields.adoc[]
+
+[[test-changes-privs]]
+=== Required Privileges
+
+The role you need to test changes to a key depends on what the key you're testing can encrypt:
+
+include::rest-api:partial$encryption-at-rest-key-write-roles.adoc[]
+
+=== Responses
+
+`200 OK`::
+Couchbase Server returns this status and nothing else if it was able encrypt and decrypt some sample data with your changes applied to the key.
+
+`404 Object Not Found`::
+Returned if you specified a `KEY_ID` path parameter which does not match the ID of an encryption-at-rest key.
+
+`400 Bad Request`::
+Returned if the key you tried to test is misconfigured or cannot access the remote KMS.
+Couchbase Server also returns an error message in JSON format describing the problem.
+For example, the following error message occurs when Couchbase Server cannot unlock the key file specified in the `keyPath` field:
+
++
+[source,json]
+----
+{
+ "errors": {
+ "_": "Encryption key test failed on node1.:8091, node2.:8091, node3.:8091: encryption failed: incorrect password for private key: full error: x509KeyPair: parsePrivateKey returned err: parsePrivateKey: failed to parse private key. Error: asn1: structure error: tags don't match (2 vs {class:0 tag:16 length:95 isCompound:true}) {optional:false explicit:false application:false private:false defaultValue: tag: stringType:0 timeType:0 set:false omitEmpty:false} int @2; pkcs8: incorrect password; x509: failed to parse EC private key: asn1: structure error: tags don't match (2 vs {class:0 tag:16 length:95 isCompound:true}) {optional:false explicit:false application:false private:false defaultValue: tag: stringType:0 timeType:0 set:false omitEmpty:false} int @2"
+ }
+}
+----
+
+[#test-changes-example]
+=== Example
+
+The following example tests changing the hostname of the KMIP key created in <<#create-kmip-example>>.
+
+[source,bash]
+----
+ curl -v -u Administrator:password \
+ -X PUT http://127.0.0.1:8091/settings/encryptionKeys/1/test \
+ --data-binary @- <>
+* <<#change-settings>>
+
+
+
+[#get-settings]
+== Get Audit, Config, and Log Encryption-at-Rest Settings
+
+Use this endpoint to get the current encryption-at-rest settings for non-bucket data.
+
+.List All Settings
+----
+GET /settings/security/encryptionAtRest
+----
+
+=== curl Syntax
+
+[source,bash]
+----
+ curl -s -u $USER:$PASSWORD -X GET \
+ 'http://{HOST}:{PORT}/settings/security/encryptionAtRest' | jq
+----
+
+.Path Parameters
+:priv-link: get-privs
+include::partial$user-pw-host-port-params.adoc[]
+
+
+[[get-privs]]
+=== Required Privileges
+
+You must have at least on one of the following roles:
+
+* xref:learn:security/roles.adoc#admin[Full Admin]
+* xref:learn:security/roles.adoc#read-only-admin[Read-Only Admin]
+* xref:learn:security/roles.adoc#security_admin[Security Admin]
+
+=== Responses
+
+`200 OK`::
+Returns the encryption-at-rest settings for audit, config, and logs.
+See examples for an example of the output.
+
+`403 Forbidden`::
+Returned if the user does not have one of the roles listed in <>.
+
+
+[#gey-keys-example]
+=== Examples
+
+The following example gets the current encryption-at-rest status.
+
+[source,bash]
+----
+curl -Ss -u Administrator:password -X \
+ GET 'http://127.0.0.1:8091/settings/security/encryptionAtRest' | jq
+----
+
+An example of running the previous command:
+
+[source,json]
+----
+{
+ "audit": {
+ "dekLastDropDate": "",
+ "dekLifetime": 0,
+ "dekRotationInterval": 2592000,
+ "encryptionKeyId": 0,
+ "encryptionMethod": "encryptionKey",
+ "info": {
+ "dataStatus": "encrypted",
+ "dekNumber": 3,
+ "issues": [],
+ "oldestDekCreationDatetime": "2025-04-23T18:35:40Z"
+ }
+ },
+ "config": {
+ "dekLastDropDate": "2025-04-23T18:43:23Z",
+ "dekLifetime": 31536000,
+ "dekRotationInterval": 2592000,
+ "encryptionKeyId": 0,
+ "encryptionMethod": "encryptionKey",
+ "info": {
+ "dataStatus": "encrypted",
+ "dekNumber": 3,
+ "issues": [],
+ "oldestDekCreationDatetime": "2025-04-23T18:43:27Z"
+ }
+ },
+ "log": {
+ "dekLastDropDate": "",
+ "dekLifetime": 0,
+ "dekRotationInterval": 2592000,
+ "encryptionKeyId": 0,
+ "encryptionMethod": "encryptionKey",
+ "info": {
+ "dataStatus": "partiallyEncrypted",
+ "dekNumber": 3,
+ "issues": [],
+ "oldestDekCreationDatetime": "2025-04-23T18:34:34Z"
+ }
+ }
+}
+----
+
+Each type of system data that you can configure to be encrypted has its own object in the output (`audit`, `config`, `log`).
+Some important fields in each of these objects are:
+
+* The `info.dataStatus` field shows whether the data is being encrypted.
+* If Couchbase Server is encrypting the data, `encryptionMethod` indicates what it's using to encrypt it.
+This value can be:
+** `disabled`: not being encrypted
+** `encryptionKey`: encrypted using an encryption-at-rest key.
+** `nodeSecretManager`: Couchbase Server uses the xref:manage:manage-security/manage-system-secrets.adoc#setting-the-master-password[master password] to encrypt the data.
+
+[[change-settings]]
+== Change Audit, Config, and Log Data Encryption-at-Rest Settings
+
+You can create or update an encryption-at-rest-key key using the REST API.
+
+
+.Change Audit, Config, and Log Encryption at Rest Settings
+----
+POST /settings/security/encryptionAtRest
+----
+
+=== curl Syntax
+
+[source,bash]
+----
+curl -sS -u $USER:$PASSWORD \
+ -X POST http://{HOST}:{PORT}/settings/security/encryptionAtRest \
+ [-d '.encryptionMethod=']
+ [-d '.encryptionKeyId=']
+ [-d '.dekRotationInterval=']
+ [-d '.dekLifetime=']
+----
+
+:priv-link: change-privs
+.Path Parameters
+include::partial$user-pw-host-port-params.adoc[]
+
+
+.Fields
+`type`::
+The type of the data whose encryption-at-rest-settings you want to change.
+Must be one of these values:
+
++
+* `audit`: change settings for encrypting audit data.
+* `config`: change settings for encrypting configuration data.
+* `log`: change settings for encrypting log data.
+
+`encryptionMethod`::
+Controls whether and how the data is encrypted.
+Allowed values are:
+
++
+* `disabled`: The data is not encrypted.
+* `encryptionKey`: Couchbase Server encrypts the data using an encryption-at-rest key.
+When you choose this option, you must also set `encryptionKeyId`.
+* `nodeSecretManager`: Couchbase Server encrypts the data using the master database password.
+
+`encryptionKeyId` (integer)::
+The `id` field value of the encryption-at-rest-key that Couchbase Server uses to encrypt the data.
+See xref:manage-encryption-keys.adoc#list-keys[List Encryption-at-Rest Keys] to learn how to get the `id` of the key you want to use.
+This field is required when you set `encryptionMethod`` to `encryptionKey`.
+
+`dekRotationInterval` (integer)::
+The duration of time, in seconds, that the data encryption key (DEK) Couchbase Server uses to encrypt the data is valid.
+Once this time elapses, Couchbase Server rotates the DEK automatically.
+Defaults to `2592000` (30 days).
+See xref:learn:security:native-encryption-at-rest-overview.adoc[Encryption Key Rotation and Expiration] for more information about key rotation.
+
+`dekLifetime` (integer)::
+The period of time, in seconds, that Couchbase Server keeps expired DEKs before deleting them.
+Couchbase Server keeps expired DEKs until either the lifetime elapses or no data remains encrypted with the DEK.
+If the DEK’s lifetime elapses while data is still encrypted with it, Couchbase Server re-encrypts the data using the active DEK and deletes the expired one.
+Defaults to `31536000` (1 year).
+See xref:learn:security:native-encryption-at-rest-overview.adoc[Encryption Key Rotation and Expiration] for more information about key lifetime.
+
+
+[[change-privs]]
+=== Required Privileges
+
+You must have at least on one of the following roles:
+
+* xref:learn:security/roles.adoc#admin[Full Admin]
+* xref:learn:security/roles.adoc#security_admin[Security Admin]
+
+
+=== Responses
+
+`200 OK`::
+Returns a JSON message containing the settings for audit, config, and log after your changes were applied.
+See <<#change-examples>> for examples of the returned JSON.
+
+`400 Bad Request`::
+Returned when errors occur, such as leaving out a required setting or invalid JSON.
+Also returns a descriptive JSON message.
+For example, if you set `config.encryptionMethod` to `encryptionKey` but do not set `encryptionKeyId`, you receive this message:
+
++
+[source,json]
+----
+{
+ "errors": {
+ "config.encryptionMethod": "encryptionKeyId must be set when encryptionMethod is set to encryptionKey"
+ }
+}
+----
+
+If you set `config.encryptionKeyId` to a non-existent key, you get the following message:
+
+[source,json]
+----
+{
+ "errors": {
+ "config.encryptionKeyId": "Key does not exist"
+ }
+}
+----
+
+`403 Forbidden`::
+Returned if you do not have the proper roles to call this API.
+See <>.
+
+
+
+[#create-examples]
+=== Examples
+
+[#log-use-master]
+.Encrypt Log Data Using the Master Database Password
+
+The following example configures logs to use the master database password to encrypt data by setting `log.encryptionMethod` to `nodeSecretManager`.
+
+[source,bash]
+----
+ curl -v -u Administrator:password \
+ -X POST 'http://127.0.0.1:8091/settings/security/encryptionAtRest' \
+ -d "log.encryptionMethod=nodeSecretManager" | jq
+----
+
+The output of running the previous example looks like this:
+
+[source,json]
+----
+{
+ "audit": {
+ "dekLastDropDate": "",
+ "dekLifetime": 0,
+ "dekRotationInterval": 2592000,
+ "encryptionKeyId": -1,
+ "encryptionMethod": "disabled",
+ "info": {
+ "dataStatus": "unknown",
+ "dekNumber": 0,
+ "issues": []
+ }
+ },
+ "config": {
+ "dekLastDropDate": "2025-04-23T18:43:23Z",
+ "dekLifetime": 31536000,
+ "dekRotationInterval": 2592000,
+ "encryptionKeyId": -1,
+ "encryptionMethod": "nodeSecretManager",
+ "info": {
+ "dataStatus": "encrypted",
+ "dekNumber": 3,
+ "issues": [],
+ "oldestDekCreationDatetime": "2025-04-23T18:43:27Z"
+ }
+ },
+ "log": {
+ "dekLastDropDate": "",
+ "dekLifetime": 0,
+ "dekRotationInterval": 2592000,
+ "encryptionKeyId": -1,
+ "encryptionMethod": "nodeSecretManager",
+ "info": {
+ "dataStatus": "partiallyEncrypted",
+ "dekNumber": 3,
+ "issues": [],
+ "oldestDekCreationDatetime": "2025-04-23T18:34:34Z"
+ }
+ }
+}
+----
+
+
+
+.Encrypt Audit Data Using Encryption-at-Rest Key
+
+
+The following example uses an encryption-at-rest key to encrypt the audit data.
+
+include::example$encryption-at-rest/system-encryption-examples.adoc[tag=encrypt-data-with-key]
+
+The output of the previous example looks like this:
+
+[source,json]
+----
+{
+ "audit": {
+ "dekLastDropDate": "",
+ "dekLifetime": 0,
+ "dekRotationInterval": 2592000,
+ "encryptionKeyId": 0,
+ "encryptionMethod": "encryptionKey",
+ "info": {
+ "dataStatus": "unknown",
+ "dekNumber": 0,
+ "issues": []
+ }
+ },
+ "config": {
+ "dekLastDropDate": "2025-04-23T18:43:23Z",
+ "dekLifetime": 31536000,
+ "dekRotationInterval": 2592000,
+ "encryptionKeyId": -1,
+ "encryptionMethod": "nodeSecretManager",
+ "info": {
+ "dataStatus": "encrypted",
+ "dekNumber": 3,
+ "issues": [],
+ "oldestDekCreationDatetime": "2025-04-23T18:43:27Z"
+ }
+ },
+ "log": {
+ "dekLastDropDate": "",
+ "dekLifetime": 0,
+ "dekRotationInterval": 2592000,
+ "encryptionKeyId": -1,
+ "encryptionMethod": "nodeSecretManager",
+ "info": {
+ "dataStatus": "partiallyEncrypted",
+ "dekNumber": 3,
+ "issues": [],
+ "oldestDekCreationDatetime": "2025-04-23T18:34:34Z"
+ }
+ }
+}
+----
+
+NOTE: In the example, you may notice that `audit.info.dataStatus` indicates the data's status is `unknown`.
+It reports this state because Couchbase Server was still encrypting the data when the call to the `encryptionAtRest` endpoint returned the JSON message.
+Eventually, this status becomes `encrypted` once Couchbase Server finishes encrypting the audit data.
+
+
+.Disable Encryption-at-Rest for Logs and Audit
+
+[source,bash]
+----
+curl -v -u Administrator:password \
+ -X POST 'http://127.0.0.1:8091/settings/security/encryptionAtRest' \
+ -d "audit.encryptionMethod=disabled" \
+ -d "log.encryptionMethod=disabled" | jq
+----
+
+The output from the previous example looks like this:
+
+[source,json]
+----
+{
+ "audit": {
+ "dekLastDropDate": "",
+ "dekLifetime": 0,
+ "dekRotationInterval": 2592000,
+ "encryptionKeyId": -1,
+ "encryptionMethod": "disabled",
+ "info": {
+ "dataStatus": "encrypted",
+ "dekNumber": 3,
+ "issues": [],
+ "oldestDekCreationDatetime": "2025-05-08T17:59:46Z"
+ }
+ },
+ "config": {
+ "dekLastDropDate": "2025-04-23T18:43:23Z",
+ "dekLifetime": 31536000,
+ "dekRotationInterval": 2592000,
+ "encryptionKeyId": -1,
+ "encryptionMethod": "nodeSecretManager",
+ "info": {
+ "dataStatus": "encrypted",
+ "dekNumber": 3,
+ "issues": [],
+ "oldestDekCreationDatetime": "2025-04-23T18:43:27Z"
+ }
+ },
+ "log": {
+ "dekLastDropDate": "",
+ "dekLifetime": 0,
+ "dekRotationInterval": 2592000,
+ "encryptionKeyId": -1,
+ "encryptionMethod": "disabled",
+ "info": {
+ "dataStatus": "partiallyEncrypted",
+ "dekNumber": 3,
+ "issues": [],
+ "oldestDekCreationDatetime": "2025-04-23T18:34:34Z"
+ }
+ }
+}
+----
+
+NOTE: As with the previous example, the values of the `audit.info.dataStatus` and `log.info.dataStatus` do not match the `encryptionMethod` setting.
+It takes time for Couchbase Server to decrypt the data when you turn off encryption-at-rest.
+
diff --git a/modules/rest-api/pages/security/encryption-at-rest/rotate-encryption-at-rest-key.adoc b/modules/rest-api/pages/security/encryption-at-rest/rotate-encryption-at-rest-key.adoc
new file mode 100644
index 0000000000..3617784438
--- /dev/null
+++ b/modules/rest-api/pages/security/encryption-at-rest/rotate-encryption-at-rest-key.adoc
@@ -0,0 +1,173 @@
+= Rotate Data Encryption Keys
+:description: pass:q[You can use the REST API have Couchbase Server immediately rotate an encryption-at-rest key that it manages.]
+:page-edition: Enterprise Edition
+:page-topic-type: reference
+:tabs:
+:page-toclevels: 3
+
+[abstract]
+{description}
+
+== Description
+
+You can manually trigger the rotation of an encryption-at-rest key that Couchbase Server manages.
+You may want to manually rotate the key if you believe it's compromised.
+
+You can only rotate keys managed by an external KMS through that KMS.
+See xref:manage:security/manage-native-encryption-at-rest.adoc#rotate-keys[Manually Rotate Encryption-at-rest Keys] for more information.
+
+When you rotate an encryption-at-rest key, Couchbase Server creates a new key and uses it to re-encrypt all DEKs that were encrypted with the previous version of the key.
+
+See xref:learn:security/native-encryption-at-rest-overview.adoc#rotation-expiration[Encryption Key Rotation and Expiration] for more information about key rotation.
+
+== HTTP Methods
+
+This API endpoint supports the following methods:
+
+* <<#rotate-key>>
+
+
+[#rotate-key]
+== Rotate an Encryption-at-Rest Key
+
+Use this endpoint to rotate an encryption-at-rest key.
+
+.Rotate a Key
+----
+POST /controller/rotateEncryptionKey/{KEY_ID}
+----
+
+.Path Parameters
+
+`KEY_ID` (integer, required)::
+The encryption-at-rest key to rotate identified by its `data.id` value.
+See xref:manage-encryption-keys.adoc#list-keys[List Encryption-at-Rest Keys] to learn how to get the `data.id` value of the key you want to rotate.
+
+=== curl Syntax
+
+[source,bash]
+----
+ curl -u $USER:$PASSWORD -X GET \
+ 'http://{HOST}:{PORT}//controller/rotateEncryptionKey/{KEY_ID}' | jq
+----
+
+.Path Parameters
+:priv-link: rotate-privs
+include::partial$user-pw-host-port-params.adoc[]
+
+`KEY_ID` (integer, required)::
+The encryption-at-rest key to rotate identified by its `data.id` value.
+See xref:manage-encryption-keys.adoc#list-keys[List Encryption-at-Rest Keys] to learn how to get the `data.id` value of the key you want to rotate.
+
+
+[[rotate-privs]]
+=== Required Privileges
+
+You must have at least one of the following roles:
+
+* xref:learn:security/roles.adoc#admin[Full Admin]
+* xref:learn:security/roles.adoc#security_admin[Security Admin]
+
+=== Responses
+
+`200 OK`::
+Does not return any other message other than the response code.
+
+`403 Forbidden`::
+Returned if the user does not have one of the roles listed in <>.
+
+`404 Object Not Found`::
+Returned if the `KEY_ID` does not match an encryption-at-rest key.
+
+[#gey-keys-example]
+=== Examples
+
+The following example rotates the encryption-at-rest key for the named `Example Auto-Generated Key`:
+
+[source,json]
+----
+ {
+ "data": {
+ "keys": [
+ {
+ "id": "5fb1ef72-b3db-47f3-b989-0c156ee6eb40",
+ "active": true,
+ "creationDateTime": "2025-05-07T14:11:53Z",
+ "keyMaterial": "******"
+ }
+ ],
+ "encryptionApproach": "nodeSecretManager",
+ "canBeCached": true,
+ "autoRotation": false
+ },
+ "id": 18,
+ "name": "Example Auto-Generated Key",
+ "type": "cb-server-managed-aes-key-256",
+ "usage": [
+ "KEK-encryption",
+ "bucket-encryption",
+ "config-encryption",
+ "log-encryption",
+ "audit-encryption"
+ ],
+ "creationDateTime": "2025-05-07T14:11:53Z"
+}
+----
+
+This key's `data.id` is `18`.
+The command to rotate this key is:
+
+[source,bash]
+----
+curl -u Administrator:password \
+ -X POST 'http://127.0.0.1:8091/controller/rotateEncryptionKey/18'
+----
+
+This command does not return output.
+To see its effect, you can call the `/settings/encryptionKey/` endpoint (see xref:rest-api:security/encryption-at-rest/manage-encryption-keys.adoc#list-keys[List Encryption-at-Rest Keys] for details) to get the current status of the key:
+
+[source,bash]
+----
+ curl -u Administrator:password -X GET \
+ http://127.0.0.1:8091/settings/encryptionKeys/18 | jq
+----
+
+The JSON returned by this command shows the encryption-at-rest has a new key within the `data.keys` object whose `active` attribute is `true`:
+
+[source,json]
+----
+{
+ "data": {
+ "keys": [
+ {
+ "id": "3887ad84-7535-4d54-a9d2-fd9d855985b6",
+ "active": true,
+ "creationDateTime": "2025-05-09T12:49:01Z",
+ "keyMaterial": "******"
+ },
+ {
+ "id": "5fb1ef72-b3db-47f3-b989-0c156ee6eb40",
+ "active": false,
+ "creationDateTime": "2025-05-07T14:11:53Z",
+ "keyMaterial": "******"
+ }
+ ],
+ "encryptionApproach": "nodeSecretManager",
+ "lastRotationTime": "2025-05-09T12:49:01Z",
+ "canBeCached": true,
+ "autoRotation": false
+ },
+ "id": 18,
+ "name": "Example Auto-Generated Key",
+ "type": "cb-server-managed-aes-key-256",
+ "usage": [
+ "KEK-encryption",
+ "bucket-encryption",
+ "config-encryption",
+ "log-encryption",
+ "audit-encryption"
+ ],
+ "creationDateTime": "2025-05-07T14:11:53Z"
+}
+----
+
diff --git a/modules/rest-api/partials/encryption-at-rest-key-write-roles.adoc b/modules/rest-api/partials/encryption-at-rest-key-write-roles.adoc
new file mode 100644
index 0000000000..2edeacc850
--- /dev/null
+++ b/modules/rest-api/partials/encryption-at-rest-key-write-roles.adoc
@@ -0,0 +1,22 @@
+
+For keys that can encrypt audit, configuration, or log data or can encrypt other encryption-at-rest keys (KEKs), you must have one or more of the following roles:
+
+* xref:learn:security/roles.adoc#admin[Full Admin]
+* xref:learn:security/roles.adoc#security-admin[Security Admin]
+
+For keys that can encrypt any bucket in the cluster, you must have one or more of the following roles:
+
+* xref:learn:security/roles.adoc#admin[Backup Full Admin]
+* xref:learn:security/roles.adoc#cluster-admin[Cluster Admin]
+* xref:learn:security/roles.adoc#eventing-full-admin[Eventing Full Admin]
+* xref:learn:security/roles.adoc#admin[Full Admin]
+* xref:learn:security/roles.adoc#security-admin[Security Admin]
+
+For keys that can encrypt one or more specific buckets, you must have one or more of the following roles:
+
+* xref:learn:security/roles.adoc#admin[Backup Full Admin]
+* xref:learn:security/roles.adoc#backup-full-admin[Bucket Admin] that has privileges on the bucket to be encrypted.
+* xref:learn:security/roles.adoc#cluster-admin[Cluster Admin]
+* xref:learn:security/roles.adoc#eventing-full-admin[Eventing Full Admin]
+* xref:learn:security/roles.adoc#admin[Full Admin]
+* xref:learn:security/roles.adoc#security-admin[Security Admin]
diff --git a/modules/rest-api/partials/encryption-at-rest-post-put-fields.adoc b/modules/rest-api/partials/encryption-at-rest-post-put-fields.adoc
new file mode 100644
index 0000000000..d95a21cd9a
--- /dev/null
+++ b/modules/rest-api/partials/encryption-at-rest-post-put-fields.adoc
@@ -0,0 +1,228 @@
+`name` (required)::
+A name to give to the key.
+This name must be different from any other encryption-at-rest key.
+
+[#usage-{field-use}]
+`usage`::
+A comma-separated list of what this key can encrypt.
+Allowed values for this list are:
+
++
+* `"KEK-encryption"`: Can encrypt other encryption-at-rest keys (KEK).
+* `"bucket-encryption"`: Can encrypt any bucket in the cluster.
+* `"bucket-encryotion-"`: Can encrypt the bucket named `bucket-name`.
+You can include multiple instances of this value to list specific buckets the key can encrypt.
+* `"config-encryption"`: Can encrypt configuration information.
+* `"log-encryption"`: Can encrypt logs.
+* `"audit-encryption"`: Can encrypt audit data.
+
+`type`::
+Defines the encryption standard and the key management system for the key.
+All encryption-at-rest keys use AES 256 encryption.
+Allowed values are:
+
++
+* `"awskms-symmetric-key"`: AWS KMS manages the key.
+* `"kmip-aes-key-256"`: A KMIP-compatible KMS manages the key.
+* `"cb-server-managed-aes-key-256"`: Couchbase Server manages the key.
+
+`data`::
+The contents of the `data` object depend on the KMS set in the `type` field because each KMS has unique settings.
+
+
+[{tabs}]
+====
+AWS::
++
+--
+
+When using the AWS KMS, the `data` object has the following schema:
+
+[source,json]
+----
+ "data": {
+ "keyARN": "",
+ "region": "",
+ "useIMDS": ,
+ "profile": "",
+ "credentiials-file": "",
+ "configFile": ""
+ }
+----
+
+.Fields
+
+* `keyARN`: The https://docs.aws.amazon.com/IAM/latest/UserGuide/reference-arns.html[Amazon Resource Name (ARN)^] that identifies the encryption key in the AWS KMS.
+* `region` (optional): The region hosting your AWS KMS.
+* `useIMDS` (Boolean, optional): Whether to use Amazon's https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/configuring-instance-metadata-service.html[Instance Metadata Service (IMD)^] when contacting the AWS KMS.
+Set this to `true` when your cluster runs on AWS EC2 instances.
+Defaults to `false`.
+
+
+You must give Couchbase Server a way to authenticate with the AWS KMS.
+See Amazon's https://docs.aws.amazon.com/kms/latest/developerguide/control-access.html[KMS key access and permissions] for details of configuring authentication.
+
+You can use https://docs.aws.amazon.com/kms/latest/developerguide/iam-policies.html[IAM policies^] to allow Couchbase Server to transparently connect to the AWS KMS.
+If you configure IAM, you do not need any additional authentication configuration within Couchbase Server.
+Always use this method if your database runs on an AWS EC2 cluster.
+It's also possible to configure IAM for your cluster when it's not running in AWS.
+See the AWS documentation for using https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_common-scenarios_non-aws.html[IAM Roles Anywhere^].
+
+The other authentication method is to use three optional parameters to pass Couchbase Server the necessary credentials in several files.
+These files must exist on all servers in your cluster.
+
+Use the following parameters to tell Couchbase Server where these files are located:
+
+* `credentials-file` the absolute path to a file containing the AWS credentials to use when authenticating with the AWS KMS.
+When you supply this path, the file must exist on all nodes.
+This file often stored at `~/.aws/credentials` on Linux systems.
+For example:
+
++
+[source,ini]
+----
+[my-profile]
+aws_access_key_id = ABCDE...
+aws_secret_access_key = xyz123...
+----
+
+* `configFile`: the absolute path to a file that defines one or more profiles for accessing AWS.
+ This file is often stored in `~/.aws/config` on Linux systems.
+ The format of
+
++
+[source,ini]
+----
+[profile profile-name]
+region = us-east-1
+output = json
+role_arn = arn:aws:iam::123456789012:role/RoleName
+source_profile = base
+----
+
+* `profile`: The name of the profile defined in the configuration file to use when authenticating with AWS KMS.
+
+NOTE: Couchbase Server does not verify the information you give it during key creation.
+It only attempts to connect to AWS when you select the key to encrypt data or another key.
+See xref:rest-api:security/encryption-at-rest/manage-encryption-keys.adoc#test-key[Test an Encryption-at-Rest Key] to learn how to test the key.
+--
+
+KMIP KMS::
++
+--
+When using a KMIP-compatible KMS, the `data` object has the following schema:
+
+[source,json]
+----
+"data": {
+ "port": ,
+ "host": "",
+ "reqTimeoutMs": ,
+ "keyPath": "",
+ "keyPassphrase": "",
+ "encryptionApproach": "",
+ "certPath": "",
+ "caSelection": "",
+ "encryptionApproach": "",
+ "activeKey": {
+ "kmipId": ""
+ },
+ "encryptionApproachKeyId":
+ }
+----
+
+.Fields
+
+* `port`: Integer port number for the KMS server.
+Most KMS servers use port 5696.
+* `host`: The URL for the KMS.
+* `reqTimeoutMs` (integer, optional): The timeout for network communication with the KMS in milliseconds.
+Defaults to 1000.
+* `keyPath`: Absolute path on each server to the private key Couchbase Server uses to authenticate with the KMS.
+This key file must be in PEM format.
+* `keyPassphrase` (optional): The private key's passphrase, if it has one.
+* `encryptionApproach`: Controls which system performs the decryption of keys.
+Can be one of the following values:
+
+** `"useGet"`: Couchbase Server retrieves the encryption key from the KMS and uses it to decrypt local DEKs and encryption keys.
+** `"useEncryptDecrypt"`: Send local DEKs and encryption keys to the KMS.
+The KMS decrypts the keys locally and returns the decrypted keys back to Couchbase Server.
+
+* `certPath`: The absolute path on all servers to the certificate to use when authenticating with the KMS.
+The certificate file must be in PEM format.
+* `caSelection` (optional): Where to look for certificates when verifying the identity of the KMS.
+Can be one of the following values:
+
+** `"useSysAndCbCa"` (default): Use the certificates in both the operating system's and Couchbase Server's trust stores.
+** `"useSysCa"`: Use the certificates in the operating system's trust store.
+** `"useCbCa"`: Use the certificates in Couchbase Server's trust store.
+** `"skipServerCertVerification"`: Skip verification of the KMS.
++
+CAUTION: Not verifying the identity of the KMS is insecure.
+
+* `encryptionApproach` (optional): controls how the passphrase for the private key is encrypted for local storage.
+The two options are:
+
+** `"nodeSecretManager"` (default): Couchbase Server encrypts the passphrase using the xref:manage:manage-security/manage-system-secrets.adoc#setting-the-master-password[master password].
+** `"encryptionKey"`: Use a KEK-enabled encryption key to encrypt the passphrase.
+If you choose this option, you must also supply the `encryptionApproachKeyId` parameter.
+
+* `activeKey.kmipId`: The ID of the encryption key stored in the KMS.
+The format of this value depends on the KMS.
+It's often in the form of a UUID or a friendly name.
+
+* `encryptionApproachKeyId` (integer): The `id` attribute of the encryption key Couchbase Server uses to encrypt the private key's passphrase when storing it locally.
+See <<#list-keys>> to learn how to get an encryption key's `id`.
+Required if you set `encryptionApproach` to `encryptionKey`.
+
+NOTE: Couchbase Server does not verify the information you give it during key creation.
+It only attempts to connect to the KMS when you assign the key to encrypt something.
+See xref:rest-api:security/encryption-at-rest/manage-encryption-keys.adoc#test-key[Test an Encryption-at-Rest Key] to learn how to test the key.
+--
+
+ifeval::['{field-use}' == 'create']
+Couchbase Server::
++
+--
+
+When having Couchbase Server manage the key, the `data` object has the following schema:
+
+[source,json]
+----
+ "data": {
+ "autoRotation": ,
+ "encryptionApproach": "",
+ "encryptionApproachKeyId":
+ "canBeCached":
+ "nextRotationTime": "
+ }
+----
+
+.Fields
+
+* `autoRotation` (Boolean, optional): Controls whether Couchbase Server automatically rotates the key.
+See xref:learn:security/native-encryption-at-rest-overview.adoc#rotation-expiration[Encryption Key Rotation and Expiration] for more information about key rotation.
+Defaults to `true`, which means that Couchbase Server automatically rotates the key.
+In this case, you must supply both the `nextRotationTime` and `rotationIntervalInDays` fields as well.
+* `encryptionApproach` (optional): How Couchbase Server should encrypt this key for storage.
+The two options are:
+
+** `"nodeSecretManager"`: (default): Couchbase Server encrypts the key using the xref:manage:manage-security/manage-system-secrets.adoc#setting-the-master-password[master password].
+** `"encryptionKey"`: Couchbase Server uses a KEK-enabled encryption key to encrypt the key.
+If you choose this option, you must also supply the `encryptionApproachKeyId` field.
+
+* `encryptionApproachKeyId` (integer): The `id` attribute of an existing encryption-at-rest key to use to encrypt this key.
+The key you select must have `KEK-encryption` in its `usage` list.
+* `canBeCached` (Boolean, optional): Set this value to `true` (the default) to allow Couchbase Server to cache the decrypted key in memory.
+The default `true` value makes using the key more efficient because Couchbase Server does not have to decrypt it each time it needs to use it.
+Disabling caching by setting this value to `false` can significantly increase node start time because the node decrypts all of its DEKs on startup.
+It can also increase the time it takes for operations that re-encrypts DEKs, such as key rotation or changing encryption at rest settings.
+The `false` setting can reduce the chance of in-mmeory key exposure attacks.
+* `nextRotationTime`: A date and time string in https://en.wikipedia.org/wiki/ISO_8601[ISO 8601 format^] that sets when Couchbase Server must rotate this key.
+You must set this value if you set `autoRotation` to `true`.
+* `rotationIntervalInDays` (integer): How often, in days, Couchbase Server rotates this key.
+You must set this value if you set `autoRotation` to `true`.
+--
+endif::[]
+====
diff --git a/modules/rest-api/partials/get_bucket_travel_sample.json b/modules/rest-api/partials/get_bucket_travel_sample.json
index bbe2812419..27e8dc63e1 100644
--- a/modules/rest-api/partials/get_bucket_travel_sample.json
+++ b/modules/rest-api/partials/get_bucket_travel_sample.json
@@ -2,25 +2,26 @@
"name": "travel-sample",
"nodeLocator": "vbucket",
"bucketType": "membase",
- "storageBackend": "couchstore",
- "uuid": "85ff541d1f4cfbc9e67cda3db698cac6",
- "uri": "/pools/default/buckets/travel-sample?bucket_uuid=85ff541d1f4cfbc9e67cda3db698cac6",
- "streamingUri": "/pools/default/bucketsStreaming/travel-sample?bucket_uuid=85ff541d1f4cfbc9e67cda3db698cac6",
- "numVBuckets": 1024,
+ "storageBackend": "magma",
+ "uuid": "35031bb1cf40af5c89d9094d1e09463d",
+ "uri": "/pools/default/buckets/travel-sample?bucket_uuid=35031bb1cf40af5c89d9094d1e09463d",
+ "streamingUri": "/pools/default/bucketsStreaming/travel-sample?bucket_uuid=35031bb1cf40af5c89d9094d1e09463d",
+ "numVBuckets": 128,
"bucketCapabilitiesVer": "",
"bucketCapabilities": [
"collections",
"durableWrite",
"tombstonedUserXAttrs",
- "couchapi",
"subdoc.ReplaceBodyWithXattr",
"subdoc.DocumentMacroSupport",
"subdoc.ReviveDocument",
+ "nonDedupedHistory",
"dcp.IgnorePurgedTombstones",
"preserveExpiry",
"querySystemCollection",
"mobileSystemCollection",
"subdoc.ReplicaRead",
+ "subdoc.BinaryXattr",
"rangeScan",
"dcp",
"cbhello",
@@ -31,9 +32,6 @@
"xattr"
],
"collectionsManifestUid": "2",
- "ddocs": {
- "uri": "/pools/default/buckets/travel-sample/ddocs"
- },
"vBucketServerMap": {
"hashAlgorithm": "CRC",
"numReplicas": 1,
@@ -42,23 +40,7 @@
"node2.:11210",
"node3.:11210"
],
- "vBucketMap": [
- [
- 0,
- 1
- ],
- [
- 0,
- 1
- ],
- .
- .
- .
- [
- 2,
- 1
- ]
- ]
+ "vBucketMap": ""
},
"localRandomKeyUri": "/pools/default/buckets/travel-sample/localRandomKey",
"controllers": {
@@ -67,235 +49,7 @@
"purgeDeletes": "/pools/default/buckets/travel-sample/controller/unsafePurgeBucket",
"startRecovery": "/pools/default/buckets/travel-sample/controller/startRecovery"
},
- "nodes": [
- {
- "couchApiBaseHTTPS": "https://node3.:18092/travel-sample%2B85ff541d1f4cfbc9e67cda3db698cac6",
- "couchApiBase": "http://node3.:8092/travel-sample%2B85ff541d1f4cfbc9e67cda3db698cac6",
- "clusterMembership": "active",
- "recoveryType": "none",
- "status": "healthy",
- "otpNode": "ns_1@node3.",
- "hostname": "node3.:8091",
- "nodeUUID": "d6bfd3cccf28f3e648bca46cb30ac271",
- "clusterCompatibility": 524288,
- "version": "8.0.0-1649-enterprise",
- "os": "aarch64-unknown-linux-gnu",
- "cpuCount": 4,
- "ports": {
- "direct": 11210,
- "httpsMgmt": 18091,
- "httpsCAPI": 18092,
- "distTCP": 21100,
- "distTLS": 21150
- },
- "services": [
- "backup",
- "index",
- "kv",
- "n1ql"
- ],
- "nodeEncryption": false,
- "nodeEncryptionClientCertVerification": false,
- "addressFamilyOnly": false,
- "configuredHostname": "node3.:8091",
- "addressFamily": "inet",
- "externalListeners": [
- {
- "afamily": "inet",
- "nodeEncryption": false
- }
- ],
- "serverGroup": "Group 1",
- "replication": 1,
- "nodeHash": 48264202,
- "systemStats": {
- "cpu_utilization_rate": 10.20000000018626,
- "cpu_stolen_rate": 0,
- "swap_total": 2147479552,
- "swap_used": 396525568,
- "mem_total": 8327258112,
- "mem_free": 1855406080,
- "mem_limit": 8327258112,
- "cpu_cores_available": 4,
- "allocstall": 37181
- },
- "interestingStats": {
- "cmd_get": 0,
- "couch_docs_actual_disk_size": 48142369,
- "couch_docs_data_size": 32943627,
- "couch_spatial_data_size": 0,
- "couch_spatial_disk_size": 0,
- "couch_views_actual_disk_size": 0,
- "couch_views_data_size": 0,
- "curr_items": 21189,
- "curr_items_tot": 42289,
- "ep_bg_fetched": 0,
- "get_hits": 0,
- "index_data_size": 37010997,
- "index_disk_size": 16332886,
- "mem_used": 63213008,
- "ops": 0,
- "vb_active_num_non_resident": 0,
- "vb_replica_curr_items": 21100
- },
- "uptime": "788913",
- "memoryTotal": 8327258112,
- "memoryFree": 1855406080,
- "mcdMemoryReserved": 6353,
- "mcdMemoryAllocated": 6353
- },
- {
- "couchApiBaseHTTPS": "https://node2.:18092/travel-sample%2B85ff541d1f4cfbc9e67cda3db698cac6",
- "couchApiBase": "http://node2.:8092/travel-sample%2B85ff541d1f4cfbc9e67cda3db698cac6",
- "clusterMembership": "active",
- "recoveryType": "none",
- "status": "healthy",
- "otpNode": "ns_1@node2.",
- "hostname": "node2.:8091",
- "nodeUUID": "b737df3d566f6c6ccb2bcafec61e85a2",
- "clusterCompatibility": 524288,
- "version": "8.0.0-1649-enterprise",
- "os": "aarch64-unknown-linux-gnu",
- "cpuCount": 4,
- "ports": {
- "direct": 11210,
- "httpsMgmt": 18091,
- "httpsCAPI": 18092,
- "distTCP": 21100,
- "distTLS": 21150
- },
- "services": [
- "eventing",
- "fts",
- "kv",
- "n1ql"
- ],
- "nodeEncryption": false,
- "nodeEncryptionClientCertVerification": false,
- "addressFamilyOnly": false,
- "configuredHostname": "node2.:8091",
- "addressFamily": "inet",
- "externalListeners": [
- {
- "afamily": "inet",
- "nodeEncryption": false
- }
- ],
- "serverGroup": "Group 1",
- "replication": 1,
- "nodeHash": 34469021,
- "systemStats": {
- "cpu_utilization_rate": 10.23397660196727,
- "cpu_stolen_rate": 0,
- "swap_total": 2147479552,
- "swap_used": 396525568,
- "mem_total": 8327258112,
- "mem_free": 1855901696,
- "mem_limit": 8327258112,
- "cpu_cores_available": 4,
- "allocstall": 37181
- },
- "interestingStats": {
- "cmd_get": 0,
- "couch_docs_actual_disk_size": 56100897,
- "couch_docs_data_size": 32866921,
- "couch_spatial_data_size": 0,
- "couch_spatial_disk_size": 0,
- "couch_views_actual_disk_size": 0,
- "couch_views_data_size": 0,
- "curr_items": 21118,
- "curr_items_tot": 42167,
- "ep_bg_fetched": 0,
- "get_hits": 0,
- "mem_used": 63213888,
- "ops": 0,
- "vb_active_num_non_resident": 0,
- "vb_replica_curr_items": 21049
- },
- "uptime": "788913",
- "memoryTotal": 8327258112,
- "memoryFree": 1855901696,
- "mcdMemoryReserved": 6353,
- "mcdMemoryAllocated": 6353
- },
- {
- "couchApiBaseHTTPS": "https://node1.:18092/travel-sample%2B85ff541d1f4cfbc9e67cda3db698cac6",
- "couchApiBase": "http://node1.:8092/travel-sample%2B85ff541d1f4cfbc9e67cda3db698cac6",
- "clusterMembership": "active",
- "recoveryType": "none",
- "status": "healthy",
- "otpNode": "ns_1@node1.",
- "thisNode": true,
- "hostname": "node1.:8091",
- "nodeUUID": "87a797d06f374f8006cc4a3a683db4e1",
- "clusterCompatibility": 524288,
- "version": "8.0.0-1649-enterprise",
- "os": "aarch64-unknown-linux-gnu",
- "cpuCount": 4,
- "ports": {
- "direct": 11210,
- "httpsMgmt": 18091,
- "httpsCAPI": 18092,
- "distTCP": 21100,
- "distTLS": 21150
- },
- "services": [
- "cbas",
- "index",
- "kv",
- "n1ql"
- ],
- "nodeEncryption": false,
- "nodeEncryptionClientCertVerification": false,
- "addressFamilyOnly": false,
- "configuredHostname": "node1.:8091",
- "addressFamily": "inet",
- "externalListeners": [
- {
- "afamily": "inet",
- "nodeEncryption": false
- }
- ],
- "serverGroup": "Group 1",
- "replication": 1,
- "nodeHash": 72627629,
- "systemStats": {
- "cpu_utilization_rate": 10.24295140934561,
- "cpu_stolen_rate": 0,
- "swap_total": 2147479552,
- "swap_used": 396525568,
- "mem_total": 8327258112,
- "mem_free": 1854889984,
- "mem_limit": 8327258112,
- "cpu_cores_available": 4,
- "allocstall": 37181
- },
- "interestingStats": {
- "cmd_get": 0,
- "couch_docs_actual_disk_size": 44320702,
- "couch_docs_data_size": 32823159,
- "couch_spatial_data_size": 0,
- "couch_spatial_disk_size": 0,
- "couch_views_actual_disk_size": 0,
- "couch_views_data_size": 0,
- "curr_items": 21036,
- "curr_items_tot": 42230,
- "ep_bg_fetched": 0,
- "get_hits": 0,
- "index_data_size": 38186104,
- "index_disk_size": 23976600,
- "mem_used": 62882016,
- "ops": 0,
- "vb_active_num_non_resident": 0,
- "vb_replica_curr_items": 21194
- },
- "uptime": "788913",
- "memoryTotal": 8327258112,
- "memoryFree": 1854889984,
- "mcdMemoryReserved": 6353,
- "mcdMemoryAllocated": 6353
- }
- ],
+ "nodes": "",
"stats": {
"uri": "/pools/default/buckets/travel-sample/stats",
"directoryURI": "/pools/default/buckets/travel-sample/stats/Directory",
@@ -303,7 +57,6 @@
},
"authType": "sasl",
"autoCompactionSettings": false,
- "replicaIndex": false,
"rank": 0,
"enableCrossClusterVersioning": false,
"versionPruningWindowHrs": 720,
@@ -314,22 +67,44 @@
"rawRAM": 209715200
},
"basicStats": {
- "quotaPercentUsed": 30.08984120686849,
+ "quotaPercentUsed": 21.78021494547526,
"opsPerSec": 0,
"diskFetches": 0,
- "itemCount": 63343,
- "diskUsed": 148563968,
- "dataUsed": 98633707,
- "memUsed": 189308912,
+ "itemCount": 63321,
+ "diskUsed": 128995011,
+ "dataUsed": 128995011,
+ "memUsed": 137029264,
"vbActiveNumNonResident": 0
},
"evictionPolicy": "fullEviction",
"durabilityMinLevel": "none",
- "pitrEnabled": false,
- "pitrGranularity": 600,
- "pitrMaxHistoryAge": 86400,
+ "storageQuotaPercentage": 50,
+ "historyRetentionSeconds": 0,
+ "historyRetentionBytes": 0,
+ "historyRetentionCollectionDefault": true,
+ "magmaKeyTreeDataBlockSize": 4096,
+ "magmaSeqTreeDataBlockSize": 4096,
+ "continuousBackupEnabled": false,
+ "continuousBackupInterval": 2,
+ "continuousBackupLocation": "",
"conflictResolutionType": "seqno",
"maxTTL": 0,
"compressionMode": "passive",
- "accessScannerEnabled": false
+ "expiryPagerSleepTime": 600,
+ "memoryLowWatermark": 75,
+ "memoryHighWatermark": 85,
+ "durabilityImpossibleFallback": "disabled",
+ "warmupBehavior": "background",
+ "invalidHlcStrategy": "error",
+ "hlcMaxFutureThreshold": 3900,
+ "dcpConnectionsBetweenNodes": 1,
+ "accessScannerEnabled": true,
+ "encryptionAtRestInfo": {
+ "dataStatus": "unencrypted",
+ "dekNumber": 0,
+ "issues": []
+ },
+ "encryptionAtRestKeyId": -1,
+ "encryptionAtRestDekRotationInterval": 2592000,
+ "encryptionAtRestDekLifetime": 31536000
}
\ No newline at end of file
diff --git a/modules/rest-api/partials/user-pw-host-port-params.adoc b/modules/rest-api/partials/user-pw-host-port-params.adoc
new file mode 100644
index 0000000000..ae17104e59
--- /dev/null
+++ b/modules/rest-api/partials/user-pw-host-port-params.adoc
@@ -0,0 +1,13 @@
+
+`USER`::
+The name of a user who has one of the roles listed in <<{priv-link}>>.
+
+`PASSWORD`::
+The password for the `user`.
+
+`HOST`::
+Hostname or IP address of a Couchbase Server.
+
+`PORT`::
+Port number for the REST API.
+Defaults are 8091 for unencrypted and 18901 for encrypted connections.
\ No newline at end of file
diff --git a/preview/HEAD.yml b/preview/HEAD.yml
new file mode 100644
index 0000000000..017c256160
--- /dev/null
+++ b/preview/HEAD.yml
@@ -0,0 +1,8 @@
+override:
+ asciidoc:
+ attributes:
+ kroki-server-url: http://127.0.0.1:8000
+ kroki-fetch-diagram: true
+
+
+