From 5104c1771b5933ef74fa7a4ae44ceb9a3c51d228 Mon Sep 17 00:00:00 2001 From: Supritha Date: Wed, 17 Jun 2026 11:12:14 +0530 Subject: [PATCH 1/2] initial commit --- .../manage-backup-and-restore/manage-backup-and-restore.adoc | 2 ++ 1 file changed, 2 insertions(+) diff --git a/modules/manage/pages/manage-backup-and-restore/manage-backup-and-restore.adoc b/modules/manage/pages/manage-backup-and-restore/manage-backup-and-restore.adoc index e73d049202..5b82eee450 100644 --- a/modules/manage/pages/manage-backup-and-restore/manage-backup-and-restore.adoc +++ b/modules/manage/pages/manage-backup-and-restore/manage-backup-and-restore.adoc @@ -53,6 +53,8 @@ The page for xref:backup-restore:cbbackupmgr.adoc[cbbackupmgr] also provides a s The remainder of the current page describes how to configure and use the Backup Service, using Couchbase Web Console. +=== Encryption at Rest Backup Overview + [#node-configuration] == Assign and Run the Backup Service From 9f38b4331b7eda73ac9e19f5996c04d280acf720 Mon Sep 17 00:00:00 2001 From: Supritha Date: Wed, 17 Jun 2026 15:53:23 +0530 Subject: [PATCH 2/2] updates for encryption at rest backup --- .../manage-backup-and-restore.adoc | 173 ++++++++++++++---- 1 file changed, 140 insertions(+), 33 deletions(-) diff --git a/modules/manage/pages/manage-backup-and-restore/manage-backup-and-restore.adoc b/modules/manage/pages/manage-backup-and-restore/manage-backup-and-restore.adoc index 5b82eee450..771ce12cb2 100644 --- a/modules/manage/pages/manage-backup-and-restore/manage-backup-and-restore.adoc +++ b/modules/manage/pages/manage-backup-and-restore/manage-backup-and-restore.adoc @@ -1,5 +1,5 @@ = Manage Backup and Restore -:description: Couchbase Server allows one or more buckets, and selected subsets of their data, to be backed up, restored, and archived. +:description: Couchbase Server allows 1 or more buckets, and selected subsets of their data, to be backed up, restored, and archived. :page-aliases: backup-restore:backup-restore.adoc,backup-restore:incremental-backup.adoc :page-toclevels: 3 @@ -53,14 +53,43 @@ The page for xref:backup-restore:cbbackupmgr.adoc[cbbackupmgr] also provides a s The remainder of the current page describes how to configure and use the Backup Service, using Couchbase Web Console. -=== Encryption at Rest Backup Overview +== Encryption at Rest for Backup + +Encryption at rest for backup ensures that backup data is encrypted before it is written to disk, protecting sensitive information from unauthorized access even if the underlying storage media is compromised. Backup repositories can be encrypted using the centralized Encryption-at-Rest framework provided by Couchbase Server. + +When encryption at rest is enabled for a backup repository, all data — including key-value documents, index definitions, and metadata — is encrypted using strong cryptographic algorithms before being persisted to the backup archive. Restore operations on encrypted repositories require access to the appropriate decryption material (either a passphrase or external Key Management Service credentials) to read the backup data. + +=== Key Concepts +Encryption at rest for backups uses an envelope encryption model: +* Repository Encryption Key — An auto-generated encryption key that is used to encrypt the actual backup data. This key is created when the encrypted repository is configured. + +* Data Encryption Keys (DEKs) — Derived keys are created per backup, per bucket, and per vBucket to avoid issues with repeated nonces. This ensures cryptographic safety even for very large datasets. + +* Key Encryption Keys (KEKs) — The repository encryption key is itself encrypted (enveloped) using either a passphrase-derived key or an external key from a Key Management Service (KMS). + +For more information about the core encryption-at-rest architecture, including DEKs and KEKs, see xref:learn/security/encryption-at-rest.adoc[Encryption at Rest]. + +=== Backup Workflows That Support Encryption + +Encryption at rest for backups is supported through both of the following backup workflows: + +* cbbackupmgr — The command-line backup utility supports creating encrypted repositories, performing encrypted backups, merges, and restores. +Encryption is configured at repository creation time using the cbbackupmgr config command. +See xref:backup-restore/cbbackupmgr-encryption.adoc[cbbackupmgr encryption] for details. + +* Backup Service — The Backup Service UI in Couchbase Web Console provides encryption options when creating a repository. +You can specify the KMS key URL, region, endpoint, and authentication type directly in the Create Repository dialog. +See <> for details. + + + [#node-configuration] == Assign and Run the Backup Service For backup, restore, and other related tasks to be scheduled and performed, the Backup Service must be running on an assigned node. The service (as is the case with all other Couchbase services) can be assigned either when a node is initially provisioned as a one-node cluster (as described in xref:manage:manage-nodes/create-cluster.adoc[Create a Cluster]), or when a node is added to an existing cluster (as described in xref:manage:manage-nodes/add-node-and-rebalance.adoc[Add a Node and Rebalance]). -Provided that at least one node runs the Backup Service, data for the entire cluster can be backed up, restored, and archived. +Provided that at least 1 node runs the Backup Service, data for the entire cluster can be backed up, restored, and archived. Locations to be used for saving data must be accessible to all cluster-nodes that are running the Backup Service. Note also that Couchbase Server must have read and write access to the location. On Linux, therefore, for a filesystem location, use the `chgrp` command to set the group ID of the folder to `couchbase`; unless a non-root installation has been performed, in which case set the group ID either to the username of the current user, or to a group of which the current user is a member — see xref:install:non-root.adoc[Non-Root Install and Upgrade], for more information. @@ -73,24 +102,24 @@ To access the Backup Service UI, proceed as follows: . On Couchbase Web Console, click the *Backup* tab, in the vertical navigation bar to invoke the *Backup* screen. + -The *Backup* screen features two tabs, located on the upper, horizontal navigation bar: these are *Repositories* and *Plans*. -By default, the *Repositories* tab is selected: the corresponding *Repositories* view features three panels, for *Active*, *Imported*, and *Archived* repositories respectively. +The *Backup* screen features 2 tabs, located on the upper, horizontal navigation bar: these are *Repositories* and *Plans*. +By default, the *Repositories* tab is selected: the corresponding *Repositories* view features 3 panels, for *Active*, *Imported*, and *Archived* repositories respectively. Currently, all panels are blank. [#schedule-backups] == Schedule Backups -The Backup Service allows backups (and merges) to be scheduled, as _tasks_. +The Backup Service allows backups (and merges) to be scheduled, as tasks. This section describes how task-definition and scheduling can be accomplished. -For any given repository, the Backup Service performs one task at a time, with each task maintaining a lock on the repository. +For any given repository, the Backup Service performs 1 task at a time, with each task maintaining a lock on the repository. Therefore, the administrator-defined interval between tasks should always be enough to allow each task to run to completion. If a new task is scheduled to start while a previously started task is still running, the new task cannot run. For information, see xref:learn:services-and-indexes/services/backup-service.adoc#avoiding-task-overlap[Avoiding Task Overlap]. -To schedule one or more backups, proceed as follows: +To schedule 1 or more backups, proceed as follows: -. Choose to add a _repository_. -When fully defined, the repository will combine the definitions of one or more backup and related activities, scheduled for one or more buckets, targeted at a storage location accessible to all nodes on the cluster. +. Choose to add a repository. +When fully defined, the repository combines the definitions of 1 or more backup and related activities, scheduled for 1 or more buckets, targeted at a storage location accessible to all nodes on the cluster. Each repository must have a name unique among repositories on the cluster. + To add a repository, click the *ADD REPOSITORY* tab, at the upper right of the screen. @@ -105,7 +134,7 @@ The *_hourly_backups* plan appears as the default selection. (For more information, see xref:manage:manage-backup-and-restore/manage-backup-and-restore.adoc#default-plans[Default Plans], below.) + Click the control that appears at the right-hand side of the *Select plan* dialog's interactive text-field. -A pull-down menu appears with the following options: +A dropdown menu appears with the following options: + -- * *_daily_backups* @@ -127,7 +156,7 @@ The name must be unique across the cluster, can only use the characters `[`, `]` + Then, optionally, add a description for the plan in the [.ui]*Description* field. + -Next, specify the services for which data will be backed up. +Next, specify the services for which data is backed up. Click *Services* to display the list of Couchbase Services. + To specify that only data for the Data and Index Services should be backed up, clear the boxes for all the other services. @@ -144,12 +173,12 @@ In the *Name* field, enter an appropriate name for the task: for example, *hourl + The *Period* field allows specification of the frequency of the task. If the default selection, *Weekly Calendar*, is chosen, this specifies a daily backup according to details added lower in the panel for the task. -Alternatively, to choose a specific frequency, access the control at the right-hand of the *Period* field. -A pull-down menu appears: +Alternatively, to choose a specific frequency, access the control on the *Period* field. +A dropdown menu appears: + image::manage-backup-restore/periodPullDownMenu.png[,420,align=left] + -From the pull-down menu, select *Hours*, to set the frequency is in units of hours. +From the dropdown menu, select *Hours*, to set the frequency is in units of hours. This removes from the dialog the day-specification controls associated with *Weekly Calendar*. + In the *Start Time* field, specify a time of day at which the task is to be run. @@ -159,9 +188,9 @@ When the frequency-unit specified is *Hours* (as is the case in the current exam To make sure that the hourly task is performed on the hour, leave these numbers as *00*. + In the *Type* field, specify the task to be performed, by accessing the control at the right-hand side of the field. -This displays the following pull-down menu: +This displays the following dropdown menu: + -Select *Backup*, from the pull-down menu. +Select *Backup*, from the dropdown menu. Then, in the *Frequency* field, specify the frequency with which the task should be performed. The field only accepts integers: these must be between 1 and 200 inclusive. To specify that the task be performed hourly, enter *1*. @@ -189,7 +218,7 @@ The name must be unique across the cluster, can only use the characters `[`, `]` For example, `hourlyBackupRepo`. + The *Bucket* should be the name of either a Couchbase or an Ephemeral bucket, whose data is to be backed up. -Selection can be made with a pull-down menu, accessed by means of the control at the right of the field. +Selection can be made with a dropdown menu, accessed by means of the control at the right of the field. If a bucket-name is selected, only data from this bucket is backed up. If the default selection, *All buckets*, is used, data from all buckets on the cluster (including all Couchbase and all Ephemeral buckets) is backed up. + @@ -205,7 +234,7 @@ If on the local filesystem, this location must be a pathname accessible to all n Couchbase Server must have read and write access to the location. On Linux, therefore, for a filesystem location, use the `chgrp` command to set the group ID of the folder to `couchbase`; unless a _non-root installation_ has been performed, in which case set the group ID either to the username of the current user, or to a group of which the current user is a member. + -A location should be used for only one repository: when multiple repositories are to be archived, a different location should be used for each. +A location should be used for only 1 repository: when multiple repositories are to be archived, a different location should be used for each. If appropriate, locations may be specified as subdirectories, within a top-level directory. + To backup the cluster user groups and users, including roles, permissions, and hashed passwords to the repository, select *Backup Users and User Groups*. @@ -303,7 +332,7 @@ Collections can be searched for, based on strings entered into the *filter colle The upper panel of the *Data* screen provides interactive fields labelled *Key* and *Search Path*. These can be used to search for a specific document within the repository. Optionally, the subset of backups within the repository can be specified, by means of the *Start* and *End* fields. -For example, by accessing the control at the left-hand side of the *Start* field, a pull-down menu is displayed: this lists backups any one of which can be used as the starting point for the search. +For example, by accessing the control at the left-hand side of the *Start* field, a dropdown menu is displayed: this lists backups any 1 of which can be used as the starting point for the search. For example, type a known document key into the *Key* field — such as `airline_10`. Then, enter the bucket name into the *Search Path* field. @@ -363,7 +392,7 @@ To delete a backup, with or without dependent incremental backups, follow these . Examine the backups in the repository. You can see a list of backups with expiry status. + -You can choose to do one of the following: +You can choose to do 1 of the following: ** Delete a backup that has no dependent incremental backups, which has the status _Expired_. ** Delete a backup that has dependent incremental backups, which has the status _Expired, but has dependent incrementals_. @@ -433,7 +462,7 @@ Means, the number of days specified in its retention period have passed. * No incremental backups dependent on this backup. -You can Prune backups in a repository in one of the following ways: +You can Prune backups in a repository in 1 of the following ways: * By scheduling a Prune task, which runs at regular intervals. @@ -453,7 +482,7 @@ You can Prune backups in a repository in one of the following ways: [#using-default-pruning-plan] === Schedule a Prune task using default plans -During the creation of a repository or xref:manage:manage-backup-and-restore/manage-backup-and-restore.adoc#schedule-backups[Schedule Backups], you can select one of the following default pruning plans from the *Plan* list on the *Select Plan* dialog: +During the creation of a repository or xref:manage:manage-backup-and-restore/manage-backup-and-restore.adoc#schedule-backups[Schedule Backups], you can select 1 of the following default pruning plans from the *Plan* list on the *Select Plan* dialog: * *_daily_full_backups_with_incrementals*: This plan performs full backups for all services every day and incremental backups every hour, and runs a prune every day. @@ -567,7 +596,7 @@ To set the retention period for a repository, follow these steps: . Start creating a repository, as explained in xref:manage:manage-backup-and-restore/manage-backup-and-restore.adoc#schedule-backups[Schedule Backups]. -. From the *Plan* list on the *Select Plan* dialog, continue with one of the following: +. From the *Plan* list on the *Select Plan* dialog, continue with 1 of the following: ** xref:manage:manage-backup-and-restore/manage-backup-and-restore.adoc#using-default-pruning-plan[Schedule a Prune task using default plans]. @@ -657,7 +686,7 @@ To set the retention period for a backup using the REST API, see xref:rest-api:b [#schedule-merges] == Schedule Merges -A merge allows multiple backups to be combined as one; with deduplication occurring. +A merge allows multiple backups to be combined as 1; with deduplication occurring. Merges are supported for filesystem-based repositories: however, merges are _not_ supported for cloud-based repositories. If a merge is scheduled for a cloud-based repository, the Backup Service skips the task. @@ -665,7 +694,7 @@ An immediate merge cannot be triggered for a cloud-based repository. Merges can be scheduled as _tasks_, to be applied to backed up data within a defined repository. This section describes how task-definition and scheduling for merges can be accomplished. -For any given repository, the Backup Service performs one task at a time; with each task maintaining a lock on the repository. +For any given repository, the Backup Service performs 1 task at a time; with each task maintaining a lock on the repository. Therefore, the administrator-defined interval between tasks should always be sufficient to allow each task to run to completion. If a new task is scheduled to start while a previously started task is still running, the new task cannot run. For information, see xref:learn:services-and-indexes/services/backup-service.adoc#avoiding-task-overlap[Avoiding Task Overlap]. @@ -736,11 +765,11 @@ image:manage-backup-restore/mergeDialog.png[,420,align=left] The dialog allows determination of which backups should be merged, based on specification of the _first_ and the _last_: these backups, and all backups that occurred between them, will be merged. . To specify the first backup, access the interactive control at the right-hand side of the *Start* field. -This produces a pull-down menu that displays all available backups for this repository: +This produces a dropdown menu that displays all available backups for this repository: . Select a backup that will be the starting backup for the merge. -Then, access the control at the right-hand side of the *End* field, and select, from its pull-down menu, a backup that will be the ending backup for the merge. +Then, access the control at the right-hand side of the *End* field, and select, from its dropdown menu, a backup that will be the ending backup for the merge. . Left-click on the *Merge Backups* button, at the lower right of the dialog. The dialog now disappears, and any you will receive a console notification stating that you have triggered a merge. @@ -759,13 +788,57 @@ image:manage-backup-restore/backupMergeConfirmation.png[,820,align=left] + The details in the expanded row confirm that five backups were merged by the operation just performed. +== Configure Encrypted Backup Repositories + +Before configuring an encrypted backup repository, ensure the following: + +* Couchbase Server Enterprise Edition — Encrypted backups are an Enterprise Edition feature. + +* Key Management Setup — If using an external KMS, ensure you have: + * A key created in your chosen KMS provider (AWS KMS, GCP KMS, Azure Key Vault, or HashiCorp Vault Transit Engine). + * Appropriate credentials or authentication configured for accessing the KMS. + * Network connectivity from the Couchbase Server node (or the machine running cbbackupmgr) to the KMS endpoint. + +* Permissions — The user must have the Full Admin role (for Backup Service) or the Full Admin or Data Backup & Restore role (for cbbackupmgr). +* HTTPS Endpoints — Use secure connections (https:// or couchbases://) to ensure data is encrypted in transit as well as at rest. + +Encrypted backup repositories can be configured in 1 of the following modes: + +* KMS Mode (Production) +In KMS mode, an external Key Management Service encrypts the repository encryption key using envelope encryption. +The external key does not directly encrypt the data — it wraps (envelopes) the auto-generated repository key. +This minimizes the number of API calls to the KMS (1 call per operation, except info which requires zero). + +* Passphrase Mode (Development/Testing Only) +In passphrase mode, a user-supplied passphrase is used to derive an encryption key. +This derived key encrypts the repository key. + +Important: Passphrase mode is not recommended for production use due to the inherent insecurity of human-friendly passphrases. + +To configure using `cbbackupmgr`, use the `config` command with the `--encrypted` flag. + +To configure using the Web Console: + +. Navigate to Backup and click btn:[ADD REPOSITORY]. +. Select or create a plan, then click *Next*. +. In the Create Repository dialog, under *Encryption Options*, select *Encrypted*. +. Configure the following fields: +* KM Key URL — The URL path to the key in the external key manager, prefixed with the provider scheme. +* KM Region (optional) — The region of the key manager (required for AWS KMS). +* KM Endpoint (optional) — Override the default endpoint for the KMS. +* KMS Authentication Type (optional) — Choose from Environmental Auth, File Auth, or Access Key Auth. +. Click *Add* to create the encrypted repository. + +After configuring an encrypted repository, backups are performed using the same commands as unencrypted backups, but you must supply the encryption credentials. +If the KMS credentials are missing, cbbackupmgr will fail with an error requesting the correct credentials. + [#restore-backups] == Restore Backups You can restore a backup to the same bucket or buckets that you originally backed up or to a different set of buckets. You can also restore a backup to a different cluster. The buckets you restore data to do not have to use the same xref:learn:buckets-memory-and-storage/storage-engines.adoc[storage engine] as the original buckets. -You can restore a backup of data from a bucket using the Couchstore storage engine to one using Magma. +You can restore a backup of data from a bucket using the Couchstore storage engine to 1 using Magma. You can also restore a Magma-backed bucket backup to a Couchstore bucket. [NOTE] @@ -846,7 +919,7 @@ For example, if you enter `^airline` in this field, then the restore task only r Filter Values:: Lets you enter a regular expression the restore task uses to filter documents based on their data. -The restore task only restores a document if one of its values matches the regular expression. +The restore task only restores a document if 1 of its values matches the regular expression. + For example, if you enter `MIL*` in this field, the restore task only restores a document if has a value that contains the string `MIL` followed by zero of more characters. @@ -920,6 +993,40 @@ Auto-create Buckets:: By default, the restore task exits with an error message if a bucket being restored from the backup does not currently exist in the cluster. Selecting *Auto-create Buckets* has the restore task create any missing buckets. +=== Restore Encrypted Backups + +Restoring data from an encrypted backup repository requires access to the same decryption material (KMS credentials or passphrase) that was used when the repository was created. +This section describes how restore works with encrypted repositories, the prerequisites, and behavioral differences from restoring unencrypted backups. + +When you restore from an encrypted repository, cbbackupmgr or the Backup Service: +. Connects to the KMS (or uses the passphrase) to decrypt the repository encryption key. +. Uses the decrypted repository key to derive per-backup, per-bucket, and per-vBucket decryption keys. +. Decrypts the backup data in memory. +. Sends the decrypted data to the target Couchbase cluster. + +The decryption process is transparent — the restore command syntax is the same as for unencrypted restores, with the addition of encryption credential flags. + +To restore an encrypted backup using the REST API, see xref:rest-api:backup-restore.adoc[Restore a Backup]. + +To restore an encrypted backup using the Web Console, follow these steps: + +. Navigate to Backup in Couchbase Web Console. +. Expand the encrypted repository and click Restore. +. Enter the target cluster URL, authentication credentials, and backup range. +. Click Restore. + +The Backup Service handles decryption automatically using the KMS credentials configured when the repository was created. + +Cross-Cluster Restore:: + +When restoring encrypted backups to a different cluster: + +* The target cluster does not need to have encryption at rest enabled. +Encryption at rest for backups is independent of the cluster's own encryption-at-rest configuration. + +* The machine performing the restore must still have access to the original KMS key used to encrypt the repository. + +* Encryption-at-rest settings are not backed up or restored as part of the bucket configuration. If you need encryption at rest on the target cluster, configure it separately. [#pause-backups] == Pause Backups @@ -1098,7 +1205,7 @@ For example, the following selection would indicate that a full backup should oc image:manage-backup-restore/simplifiedSchedule.png[,420,align=left] -A *Weekly Calendar* schedule means that one backup happens daily. +A *Weekly Calendar* schedule means that 1 backup happens daily. The time of the daily backup can be specified by means of the *Time* panel. No merge can be scheduled, nor can backups be scheduled more frequently. @@ -1106,7 +1213,7 @@ Alternatively scheduled merges and backups can be configured by accessing the co image:manage-backup-restore/scheduleOptionsMenu.png[,420,align=left] -The pull-down menu thus displayed contains three kinds of scheduling option. +The dropdown menu thus displayed contains three kinds of scheduling option. One is the default, *Weekly Calendar*. Another is by means of _time-units_: which are *Minutes*, *Hours*, *Days*, and *Weeks*. If a unit is specified, an appropriate integer must be entered into the *Frequency* field, to indicate the number of time-units that must elapse between repetitions of the task. @@ -1344,7 +1451,7 @@ This can be either `ID and Key` or `Instance Metadata Service`. For the `Instance Metadata Service` you will need to configure your GCP VM service account so that the VM instance can read and write to the cloud storage bucket. ===== + -You will require a different set of options depending on which one cloud authentication type you choose: +You will require a different set of options depending on which 1 cloud authentication type you choose: + ''' +