diff --git a/modules/ROOT/nav.adoc b/modules/ROOT/nav.adoc
index 8133ad9abe..62f51f5158 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,10 @@ 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: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..b943b80a2f
--- /dev/null
+++ b/modules/learn/pages/security/native-encryption-at-rest-overview.adoc
@@ -0,0 +1,175 @@
+= 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 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 read 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 in a bucket 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 it creates and uses to encrypt the information it stores on disk.
+This two-layer system lets Couchbase Server manage the rotation and deletion of the DEKs.
+
+You have two main choices to make when creating an encryption key:
+
+* What system you want to manage the key.
+The encryption keys can be managed by Couchbase Server, or by a Key Management Service.
+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).
+You use a KEK to encrypt other encryption keys instead of encrypting them with the database's master password.
+** **Buckets**
+You can enable a key to encrypt all buckets or restrict it to specific buckets.
+** **Configuration**
+By default, Couchbase Server uses the database's 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 database's master password instead.
+** **Audits**
+As with configuration and log data, you can choose to use an encryption-at-rest key or the database 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).
+You can also choose to leave less-sensitive data unencrypted (product catalog data, for example).
+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 can have 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 encrypting each type of information separately.
+You can use either an encryption-at-rest key or the database's master password to encrypt data.
+By default, Couchbase Server uses the database's master password to configuration data.
+
+[NOTE]
+====
+Some configuration cannot be encrypted.
+This includes:
+
+* Bootstrap information
+* Node and internal client certificates
+* Prometheus configuration, metric data, and tokens used to gather metrics
+====
+
+[#kms]
+== Encryption Key Management Services
+
+A key management service generates and stores the encryption keys Couchbase Server uses to encrypt its DEKs.
+When you create a key, you choose which key management service you want to manage it.
+Couchbase Server works with several key management services:
+
+Couchbase Server Secret Management::
+You can have Couchbase Server act as the key management system.
+This method does not require any additional configuration.
+However, using this method means that Couchbase Server stores your encryption keys locally, leaving them more vulnerable if there is a security breach.
+
+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.
+Using this method requires some configuration.
+However, this method is more secure because AWS keeps the encryption keys secure internally.
+Even if one or more nodes in your cluster suffer a security breach, the encryption keys remain secure within the AWS KMS.
+One downside of using the AWS KMS is that the cluster relies on an external source for its encryption keys.
+Disruptions in AWS or the network could result in errors because the cluster cannot retrieve encryption keys to encrypt or decrypt data.
+
++
+[#aws-kms-caution]
+[CAUTION]
+====
+Do not use encryption keys managed by AWS KMS to directly encrypt data.
+While retrieving individual encryption keys from AWS can take less than a second, cluster startup could result in many synchronous key retrievals.
+These key retrievals can cause delays during cluster start.
+
+Only use the encryption keys you store in the AWS KMS as Key Encryption Keys (KEKs).
+Use these keys to encrypt Couchbase Server managed encryption keys.
+This method limits the number of retrievals from AWS while maintaining the security advantage of having keys managed by a remote KMS.
+====
+
+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.
+If you use a MKIP KMS encryption key as a KEK, you can have the KMS decrypt keys that the KEK encrypted for you.
+This measure improves security because the KMS does not have to send a copy of its encryption key to Couchbase Server.
+Using a KMIP-compatile KMS also has the same downside--Couchbase Server may report errors due to KMS downtime or network issues.
+Couchbase Server cannot decrypt data without the KMS's encryption keys.
+Also, depending on the KMS implementation and its location, decrypting data could introduce performance issues due to latency.
+
+
+
+[#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.
+Also, because Couchbase Server stores the encryption key locally, it does not provide a high level of security.
+
+Couchbase Server does not limit you to a single KMS.
+You can choose any KMS 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.
+Remember that you should not use an AWS managed key to directly encrypt data because of the latency of fetching keys from a remote KMS.
+
+The following diagram shows a possible configuration using a single primary encryption key hosted by AWS KMS.
+This key encryption key encrypts five encryption-at-rest keys managed by Couchbase Server.
+Each of these keys are assigned to different types of data that's written to disk: audit, configuration, and log data and the data stored in two 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 two 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 retires old keys and generates new encryption keys to replace them.
+Frequent rotations limit the amount of data encrypted with any one 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.
+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) its encryption keys.
+
+When Couchbase Server generates a new encryption key or DEK during rotation, it does not immediately delete the expired key.
+It keeps the expired keys so it can decrypt the data encrypted with the older key.
+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 an expired DEK when either:
+
+* No data uses the DEK for encryption.
+Once the last piece of data that relies on the 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 an keep it after rotation.
+When a DEK's lifetime elapses, Couchbase Server uses the active DEK to re-encrypt any data that's still encrypted with the expired 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/pages/views/docs_server_docker b/modules/learn/pages/views/docs_server_docker
new file mode 160000
index 0000000000..d216fef465
--- /dev/null
+++ b/modules/learn/pages/views/docs_server_docker
@@ -0,0 +1 @@
+Subproject commit d216fef4652009e520a1a60dc9123f38fe268270
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..e010f09127 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:
@@ -168,12 +174,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..691fb50bde
--- /dev/null
+++ b/modules/manage/pages/manage-security/manage-native-encryption-at-rest.adoc
@@ -0,0 +1,382 @@
+= 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 master database 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 managed by an external Key Management Service (KMS).
+. Enable encryption for one or more types of data.
+
+The following sections explain these steps in greater detail.
+
+[[create-keys]]
+## Creating Encryption Keys
+
+Before encrypting bucket data at rest, you must create at least one encryption key.
+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 your encryption 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.
+Only users with the xref:learn:security/roles.adoc#full-admin[Full Admin] or xref:learn:security/roles.adoc#security-admin[Security Admin] roles can create them.
+
+### Create an Encryption Key Using the Couchbase Server Web Console
+
+To create an encryption key using the Couchbase Server Web Console:
+
+. Select menu:Security[] on the main menu.
+. Click the menu:Encryption at Rest[] tab.
+The *Encryption at Rest* page opens.
+
++
+image::manage-security/encryption-at-rest-page.png[]
+
+. Click the btn:[Add Encryption Key] button 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 the AWS KMS, only leave *Key Encryption Key (KEK)* selected.
+Do not use AWS KMS to directly encrypt any type of 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.
+However, this does result in more round trips to the KMS.
+Depending on the KMS configuration, network latency, and other factors, these addtional KMS requests may affect performance.
+
+--
+
+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 decrypt it for each read or write.
+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/encryptionKey` 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 database password instead of an encryption-at-rest key.
+
+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.
+
+#### 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 using the new key.
+If the bucket is not encrypted, Couchbase Server encrypts it.
+
+See xref:rest-api:rest-bucket-create.adoc[] for more inform,ation 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 database 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 Non-Bucket 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 the menu:Encryption at Rest[] tab.
+. Click the btn:[Edit] button 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.
+This key must be 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 Non-Bucket 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]
+
+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.
+
+## Manually Rotating Keys
+
+You can manually rotate encryption-at-rest keys that Couchbase Server manages.
+You can also manually rotate data encryption keys (DEKs) that the nodes maintain to perform actual data encryption.
+You may choose to manually rotate a key if you believe it has been compromised or if you your security requirements have changed.
+
+To manually rotate either type of key, you must have the xref:learn:security/roles.adoc#full-admin[Full Admin] or xref:learn:security/roles.adoc#security-admin[Security Admin] roles.
+
+To manually rotate an 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 btn:[Rotate] button next to the key you want to rotate.
+
+To manually rotate DEKs for a bucket using the Couchbase Server Web Console:
+
+. Click menu:Buckets[] on the main menu.
+. Click the name of the bucket whose DEKs you want to rotate.
+. Click the btn:[Re-encrypt] button.
+. In the *Confirm Rotate DEKs & Re-encrypt Data* dialog, click btn:[Rotate DEKs & Re-encrypt] to confirm you want to rotate the DEKs and re-encrypt the data.
+
+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.
+
+
+
+## Deleting Encryption Keys
+
+You can delete an encryption key using the Couchbase Server Web Console or the REST API.
+You can only delete an encryption key if it's not used to encrypt data.
+If you want to delete a that's in use, you must change any data or key that's encrypted by it to a different key.
+
+### Delete an Encryption Key Using the Couchbase Server Web Console
+
+To delete an encryption 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 delete.
+. Click the btn:[Delete] button next to the key you want to delete.
+. In the *Confirm Delete* dialog, click btn:[Delete Encryption Key] to confirm you want to delete the key.
+
+### Delete an Encryption Key Using the REST API
+
+To delete an encryption key using the REST API, send a DELETE request to the `/settings/encryptionKey/{KEY_ID}` endpoint.
+
+The following example shows how to delete the encryption key with the `id` `13` using the REST API:
+
+include::rest-api:example$encryption-at-rest/manage-key-examples.adoc[tag=delete-key]
+
diff --git a/modules/rest-api/examples/encryption-at-rest/bucket-encryption-examples.adoc b/modules/rest-api/examples/encryption-at-rest/bucket-encryption-examples.adoc
new file mode 100644
index 0000000000..fd373a5f0b
--- /dev/null
+++ b/modules/rest-api/examples/encryption-at-rest/bucket-encryption-examples.adoc
@@ -0,0 +1,39 @@
+
+// tag::create-bucket[]
+[source,bash]
+----
+curl -v -X POST http://127.0.0.1:8091/pools/default/buckets \
+-u Administrator:password \
+-d name=testBucket \
+-d ramQuota=100 \
+-d encryptionAtRestKeyId=0
+----
+// end::create-bucket[]
+
+// tag::alter-bucket[]
+[source,bash]
+----
+curl -v -X POST http://127.0.0.1:8091/pools/default/buckets/testBucket \
+-u Administrator:password \
+-d encryptionAtRestKeyId=18
+----
+// end::alter-bucket[]
+
+
+// tag::set-dek-rotation[]
+[source,bash]
+----
+curl -v -X POST http://127.0.0.1:8091/pools/default/buckets/testBucket \
+-u Administrator:password \
+-d encryptionAtRestDekRotationInterval=1296000
+----
+// end::set-dek-rotation[]
+
+// tag::set-dek-lifetime[]
+[source,bash]
+----
+curl -v -X POST http://127.0.0.1:8091/pools/default/buckets/testBucket \
+-u Administrator:password \
+-d encryptionAtRestDekLifetime=7776000
+----
+// end::set-dek-lifetime[]
\ No newline at end of file
diff --git a/modules/rest-api/examples/encryption-at-rest/create-auto-generated-key-response.adoc b/modules/rest-api/examples/encryption-at-rest/create-auto-generated-key-response.adoc
new file mode 100644
index 0000000000..44784cb8cc
--- /dev/null
+++ b/modules/rest-api/examples/encryption-at-rest/create-auto-generated-key-response.adoc
@@ -0,0 +1,29 @@
+[source,json]
+----
+{
+ "data": {
+ "keys": [
+ {
+ "id": "fad3d3ae-9195-4779-994e-69266c9360c9",
+ "active": true,
+ "creationDateTime": "2025-05-02T19:34:07Z",
+ "keyMaterial": "******"
+ }
+ ],
+ "encryptWith": "nodeSecretManager",
+ "canBeCached": true,
+ "nextRotationTime": "2025-07-31T19:27:19Z",
+ "autoRotation": true,
+ "rotationIntervalInDays": 90
+ },
+ "id": 13,
+ "name": "Example Auto-Generated Key",
+ "type": "auto-generated-aes-key-256",
+ "usage": [
+ "bucket-encryption-travel-sample",
+ "config-encryption",
+ "log-encryption"
+ ],
+ "creationDateTime": "2025-05-02T19:34:07Z"
+}
+----
\ No newline at end of file
diff --git a/modules/rest-api/examples/encryption-at-rest/create-auto-generated-key.adoc b/modules/rest-api/examples/encryption-at-rest/create-auto-generated-key.adoc
new file mode 100644
index 0000000000..2d914495ec
--- /dev/null
+++ b/modules/rest-api/examples/encryption-at-rest/create-auto-generated-key.adoc
@@ -0,0 +1,19 @@
+[source,bash]
+----
+curl -u Administrator:password \
+ -X POST \
+ http://127.0.0.1:8091/settings/encryptionKeys \
+ --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 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,94 @@ 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.
+Once this period passes after a DEK expires, Couchbase Server re-encrypts any data that's still encrypted the data using the active 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 large number of DEKs being kept.
+
+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 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 +1010,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 +1026,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 +1038,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 +1055,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 +1081,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 +1110,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 +1179,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 +1272,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/`
+// | xref:rest-api:rbac.adoc#check-permissions[Re-encrypt Data and Rotate DEKs for Bucket]
+
+
+// | `POST`
+// | `/controller/dropEncryptionAtRestKeys/`
+// | xref:rest-api:rbac.adoc#check-permissions[Check Permissions]
+
+| `POST`
+| `/controller/rotateEncryptionKey/{KEY_ID}`
+| xref:rest-api:security/encryption-at-rest/rotate-encryption-at-rest-key.adoc[Rotate Encryption-at-Rest Key]
+
+|===
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..373278ca58
--- /dev/null
+++ b/modules/rest-api/pages/security/encryption-at-rest/manage-encryption-keys.adoc
@@ -0,0 +1,819 @@
+= 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, 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>>
+* <<#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/encryptionKey/
+----
+
+.Get details of a specific key
+----
+GET /settings/encryptionKey/{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
+
+You must have at least on 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`::
+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 -v -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": "******"
+ }
+ ],
+ "encryptWith": "nodeSecretManager",
+ "canBeCached": true,
+ "autoRotation": false
+ },
+ "id": 7,
+ "name": "data-one-buckey-key",
+ "type": "auto-generated-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",
+ "encryptWith": "nodeSecretManager",
+ "historicalKeys": [],
+ "activeKey": {
+ "id": "0788edb1-1418-4225-903b-bc1f9f59aa4d",
+ "kmipId": "550e8400-e29b-41d4-a716-446655440000",
+ "creationDateTime": "2025-04-23T14:44:20Z"
+ },
+ "encryptWithKeyId": -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-aes-key-256",
+ "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/encryptionKey/
+----
+
+.Update a Key
+----
+PUT /settings/encryptionKey/{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/ \
+ --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
+
+`name`::
+A name to give to the key.
+This name must be different from any other encryption-at-rest key.
+
+[#usage]
+`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 have multiple entries so the key can encrypt multiple buckets.
+* `"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-aes-key-256"`: AWS KMS manages the key.
+* `"kmip-aes-key-256"`: A KMIP-compatible KMS manages the key.
+* `"auto-generated-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`: Path to a file containing the name of the profile defined in the `credentials-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.
+--
+
+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": "",
+ "encryptWith": "",
+ "activeKey": {
+ "kmipId": ""
+ },
+ "encryptWithKeyId":
+ }
+----
+
+.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.
+* `encryptWith`: 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.
+
+* `encryptWith` (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 database's master password.
+** `"encryptionKey"`: Use a KEK-enabled encryption key to encrypt the passphrase.
+If you choose this option, you must also supply the `encryptWithKeyId` 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.
+
+* `encryptWithKeyId` (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 `encryptWith` 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.
+--
+
+Couchbase Server::
++
+--
+
+When having Couchbase Server manage the key, the `data` object has the following schema:
+
+[source,json]
+----
+ "data": {
+ "autoRotation": ,
+ "encryptWith": "",
+ "encryptWithKeyId":
+ "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.
+* `encryptWith` (optional): How Couchbase Server should encrypt this key for storage.
+The two options are:
+
+** `"nodeSecretManager"`: (default): Couchbase Server encrypts the key using the database's 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 `encryptWithKeyId` field.
+
+* `encryptWithKeyId` (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): Determines if Couchbase Server is allowed to cache the decrypted key in memory.
+Setting this to `true` (the default) 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` slightly increases the overhead of using encryption at rest but helps reduce the chance of in-memory 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.
+This value is required if you set `autoRotation` to `true`.
+* `rotationIntervalInDays` (integer): How often, in days, Couchbase Server rotates this key.
+This field is required if you set `autoRotation` to `true`.
+--
+====
+
+[#create-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 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 `encryptWith` to `encryptionKey` but do not set `encryptWithKeyID`, you receive this message:
+
++
+[source,json]
+----
+{
+ "errors": {
+ "data": {
+ "encryptWith": "encryptWithKeyId 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 `encryptWithKeyId` 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 -v -u Administrator:password \
+ -X PUT \
+ http://127.0.0.1:8091/settings/encryptionKeys/13 \
+ --data-binary @- <
+----
+
+.Path Parameters
+:priv-link: del-privs
+include::partial$user-pw-host-port-params.adoc[]
+
+`KEY_ID` (integer)::
+ The `id` attribute of the key you want to delete.
+
+
+[[del-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`::
+Returned when Couchbase Server was able to delete the key.
+A successful call does not return any additional message.
+
+`400 Bad Request`::
+Returned when the key you tried to delete is in use.
+In addition, you receive a JSON message that explains why Couchbase Server cannot delete the key.
+For example:
+
++
+[source,json]
+----
+{
+ "errors": {
+ "_": "Can't be removed because this key is configured to encrypt configuration, logs,
+ audit, bucket \"beer-sample\", keys \"encrypted-with-kek\", \"kmip-key\""
+ }
+}
+----
+
+`404 Object Not Found`::
+Returned if the key you tried to delete does not exist.
+
+=== Examples
+
+The following example deletes the Couchbase Server managed key named Example Auto-Generated Key shown in earlier examples.
+
+include::example$encryption-at-rest/manage-encryption-kets.adoc[tag=delete-key]
+
+
+
+
diff --git a/modules/rest-api/pages/security/encryption-at-rest/manage-system-encryption-at-rest.adoc b/modules/rest-api/pages/security/encryption-at-rest/manage-system-encryption-at-rest.adoc
new file mode 100644
index 0000000000..06599577a1
--- /dev/null
+++ b/modules/rest-api/pages/security/encryption-at-rest/manage-system-encryption-at-rest.adoc
@@ -0,0 +1,434 @@
+= Manage Audit, Config, and Log Encryption at Rest
+:description: pass:q[You can use the REST API to view and change the state of encryption at rest for non-bucket data.]
+:page-edition: Enterprise Edition
+:page-topic-type: reference
+:tabs:
+:page-toclevels: 3
+
+[abstract]
+{description}
+
+== Description
+
+The REST API described in this page lets you control encryption at rest for audit data, configuration settings, and logs in Couchbase Server.
+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:
+
+* <<#get-settings>>
+* <<#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#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`::
+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 master database 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..85c08ea75e
--- /dev/null
+++ b/modules/rest-api/pages/security/encryption-at-rest/rotate-encryption-at-rest-key.adoc
@@ -0,0 +1,172 @@
+= 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 have Couchbase Server rotate an encryption-at-rest key that it manages by calling a REST API endpoint.
+
+
+Keys managed by an external KMS must be rotated by the KMS.
+Consult your KMS's documentation to learn how to rotate its keys.
+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 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`::
+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": "******"
+ }
+ ],
+ "encryptWith": "nodeSecretManager",
+ "canBeCached": true,
+ "autoRotation": false
+ },
+ "id": 18,
+ "name": "Example Auto-Generated Key",
+ "type": "auto-generated-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": "******"
+ }
+ ],
+ "encryptWith": "nodeSecretManager",
+ "lastRotationTime": "2025-05-09T12:49:01Z",
+ "canBeCached": true,
+ "autoRotation": false
+ },
+ "id": 18,
+ "name": "Example Auto-Generated Key",
+ "type": "auto-generated-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/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
+
+
+