Introduction
Before the Backup Service was available, backups were handled exclusively using the cbbackupmgr tool. This is a command line tool included within a Couchbase Server installation, located at /opt/couchbase/bin.
The cbbackupmgr is a high-performance backup and restore client for Couchbase Server. The cbbackupmgr command is used for backing up Couchbase clusters, managing those backups, and restoring them.
The cbbackupmgr command was built around the concept of taking only incremental backups. This concept is important because as the data in a cluster grows it becomes increasingly difficult to take full backups in a reasonable amount of time.
The cbbackupmgr command manages the backups it has taken by using the concept of a backup archive and a backup repository. A backup repository is a directory that contains a backup configuration for backing up a specific cluster. Each time you want to back up this cluster you will specify this backup repository with the cbbackupmgr-backup command and the backup tool will automatically find where the last backup finished and incrementally backup new data in that cluster.
The backup archive is the top-level directory and contains one or more backup repositories and a logs folder. Logging for all backup repositories is contained in the logs folder in the backup.log file.
In an incremental approach, the amount of data being stored in the backup archive is always increasing. To handle this issue the backup command allows backups to be merged. This allows data to be deduplicated resulting in a single backup that takes up less disk space than the multiple previous backups. We will review this in the Recommended backup strategies for cbbackupmgr part of this article.
The minimum hardware requirement for running cbbackupmgr is 4 CPU cores and 8GiB RAM. The recommended hardware is 16 CPU cores, 16GiB RAM, and SSD disks.
Operations (commands or sub-commands) that connect to a cluster are not supported during major cluster configuration changes (for example, performing an import/export, making a backup, or performing a restore whilst changing the TLS configuration/security settings is unsupported).
These types of changes (e.g. changing the TLS mode to strict) are not expected to be time consuming so it’s generally expected that operations should be started after completing the configuration change.
Please note that this does not include rebalances; operations may be performed during a rebalance. The reason for this distinction is that major cluster configuration changes are generally quick, whilst rebalances for large data sets may be time consuming.
Another important note is that you never should edit cbbackupmgr archive folders or files manually. Usually, it will corrupt your archive and may lead to the inability to restore anything from the archive/repository/backup.
Recommended backup strategies for cbbackupmgr
Backing up data is an important part of any production database deployment. In this section, we will go through the most common cbbackupmgr backup strategies and also provide recommendations for how and where to run cbbackupmgr.
Periodic Merge
The recommended backup strategy for cbbackupmgr is the Periodic Merge strategy. This backup strategy is intended to have the lowest cluster overhead and will require the least amount of time. The periodic merge strategy takes full advantage of the fact that cbbackupmgr only takes incremental backups as well as its ability to merge incremental backups. In a Periodic Merge strategy, we would take an incremental backup each day. Each day we increase the amount of incremental backups in the backup repository, but to reclaim space we merge the incremental backups from the previous week on Sundays to reclaim space.
Sunday: Config Backup Repo (0 backups in backup repo)
Sunday: Backup 1 (1 backup in backup repo)
Monday: Backup 2 (2 backups in backup repo)
Tuesday: Backup 3 (3 backups in backup repo)
Wednesday: Backup 4 (4 backups in backup repo)
Thursday: Backup 5 (5 backups in backup repo)
Friday: Backup 6 (6 backups in backup repo)
Saturday: Backup 7 (7 backups in backup repo)
Sunday: Backup 8 (8 backups in backup repo)
Sunday: Merge 1-7 (2 backups in backup repo)
Full/Incremental Approach
The Full/Incremental Approach is similar to the Periodic Merge strategy but has one key difference. Instead of relying on the merge feature to merge backups we create a new backup repository periodically and back up the entire cluster again. We then take incremental backups daily. In this strategy, we don’t use the merge command but instead rely on creating a new backup repository each week on Sunday.
Sunday: Config Backup Repo 1 (0 backups in backup repo)
Sunday: Backup 1 (1 backup in backup repo)
Monday: Backup 2 (2 backups in backup repo)
Tuesday: Backup 3 (3 backups in backup repo)
Wednesday: Backup 4 (4 backups in backup repo)
Thursday: Backup 5 (5 backups in backup repo)
Friday: Backup 6 (6 backups in backup repo)
Saturday: Backup 7 (7 backups in backup repo)
Sunday: Config Backup Repo 2 (0 backup in backup repo)
Full Backup Only
In this strategy, we only take full backups. This strategy is only useful for small clusters and puts the most strain on the cluster compared to other strategies.
Sunday: Config Backup Repo 1 (0 backups in backup repo)
Sunday: Backup 1 (1 backup in backup repo)
Monday: Config Backup Repo 2 (0 backups in backup repo)
Monday: Backup 2 (1 backup in backup repo)
Tuesday: Config Backup Repo 3 (0 backups in backup repo)
Tuesday: Backup 3 (1 backup in backup repo)
etc.
Short Tutorial on how to use cbbackupmgr
In this tutorial, we will show how to take backups and restore data using cbbackupmgr. This tutorial uses a cluster that contains both the travel-sample and beer-sample buckets installed and requires modifying some of the documents in the travel-sample bucket.
Configuring a Backup
Before getting started with cbbackupmgr we must first decide the directory where to store all of our backups. This directory is referred to as the backup archive. The backup archive contains one or more backup repositories. These backup repositories are where your backups will be contained. The backup repository also contains a configuration for how to back up that cluster. A backup repository is created by using the config subcommand.
$ cbbackupmgr config -a /data/backup -r cluster
Backup repository `cluster` created successfully in archive `/data/backup`
Backing up a Cluster
Now that we have created some backup repositories we should take a look at our backup archive to see what it looks like. The easiest way to do this is to use the info subcommand. This subcommand is used to retrieve information from a backup archive.
$ cbbackupmgr info -a /data/backup --all
| Archive
| -------
| Name | UUID | Size | # Repos |
| backup_repo | 32c97d5f-821a-4284-840b-9ee7cf8733a3 | 0B | 2 |
|
| Repos
| -----
|
| + Repo
| ----
| Name | Size | # Backups | Encrypted | Point in Time |
| cluster | 0B | 0 | false | false |
Now that we have our backup repository configured it’s time to start taking backups. Since the backup repository contains all of the configuration information for how the backup should be taken we just need to specify the backup repository name and the information for the target cluster we intend to back up. Below is an example of how to take a backup on the "cluster" backup repository. We will assume that we have our cluster running on localhost.
$ cbbackupmgr backup -c 127.0.0.1 -u Administrator -p password -a /data/backup -r cluster
Backing up to 2020-03-25T08_08_11.770436Z
Copied all data in 33.02s (Avg. 759.44KB/Sec) 38894 items / 24.47MB
beer-sample [===================================] 100.00%
travel-sample [===================================] 100.00%
Backup successfully completed
Backed up bucket "beer-sample" succeeded
Mutations backed up: 7303, Mutations failed to backup: 0
Deletions backed up: 0, Deletions failed to backup: 0
Backed up bucket "travel-sample" succeeded
Mutations backed up: 31591, Mutations failed to backup: 0
Deletions backed up: 0, Deletions failed to backup: 0
One of the most important features of cbbackupmgr is that it is an incremental-only backup utility. This means that once we have backed up some data we will never need to back it up again.
After we have modified some data(let's assume we did 4 mutations), we will run the backup subcommand on the "cluster" backup repository again. Note that we have backed up our new 4 mutations we did: Mutations backed up: 4
$ cbbackupmgr backup -a /data/backup -r cluster -c couchbase://127.0.0.1 -u Administrator -p password
Backing up to 2020-03-25T08_41_21.461311Z
Copied all data in 3s (Avg. 18.98KB/Sec) 4 items / 56.95KB
travel-sample [==================================] 100.00%
beer-sample [==================================] 100.00%
Backup successfully completed
Backed up bucket "beer-sample" succeeded
Mutations backed up: 0, Mutations failed to backup: 0
Deletions backed up: 0, Deletions failed to backup: 0
Backed up bucket "travel-sample" succeeded
Mutations backed up: 4, Mutations failed to backup: 0
Deletions backed up: 0, Deletions failed to backup: 0
Restoring a Backup
Now that we have some backup data let’s restore that data backup to the cluster. To restore data we just need to know the name of the backup that we want to restore. To find the name we can again use the info subcommand to see what is in our backup archive. The backup name will always be a timestamp. For example, let’s say we want to restore the 2016-03-22T10_26_08.933579821-07_00 from the "cluster" backup repository. To do this we run the command below.
$ cbbackupmgr restore -a /data/backup -r cluster \
-c http://127.0.0.1:8091 -u Administrator -p password \
--start 2016-03-22T14_00_16.892277632-07_00 \
--end 2016-03-22T14_00_16.892277632-07_00 --force-updates
(1/1) Restoring backup 2016-03-22T14_00_16.892277632-07_00
Copied all data in 2s (Avg. 19.96MB/Sec) 38894 items / 39.91MB
travel-sample [==================================] 100.00%
beer-sample [==================================] 100.00%
Restore completed successfully
In the command above we use the --start and --end flags to specify the range of backups we want to restore. We also added the --force-updates flag to skip Couchbase conflict resolution. This tells cbbackupmgr to force overwrite key-value pairs being restored even if the key-value pair on the cluster is newer and the one being restored. That's an important feature, please be careful when you use it as you may overwrite your newest data with it. The restore subcommand also allows you to exclude data that was backed up from the restore and provides various other options.
Merging backups
Using an incremental backup solution means that each backup we take increases disk space. Since disk space is not infinite we need to be able to reclaim this disk space. To do this we use the cbbackupmgr-merge subcommand to merge two or more backups. Since we have two backups in the "cluster" backup repository we will merge these backups using the command below.
$ cbbackupmgr merge -a /data/backup -r cluster \
--start oldest --end latest
Merge completed successfully
Removing a Backup Repository
If we no longer need a backup repository then we can use the remove subcommand to remove the backup repository. Below is an example showing how to remove the "cluster" backup repository.
$ cbbackupmgr remove -a /data/backup -r cluster
Backup repository `cluster` deleted successfully from archive `/data/backup`
Logging in cbbackupmgr
In case of any backup-related issues please create a support ticket for Couchbase to investigate and analyze the issue. For Couchbase to investigate the issue, you will be requested to upload backup logs. You can do it by running cbbackupmgr collect-logs subcommand:
cbbackupmgr collect-logs --archive <archive_dir> --output-dir <dir>
Please collect the logs using the above command and upload them to the ticket alongside the cluster logs of the corresponding cluster. It will ensure we have all the required information and can start the investigation immediately.
Comments
0 comments
Please sign in to leave a comment.