|
| 1 | += Backing up with cbbackup |
| 2 | +:page-aliases: cli:backup-cbbackup |
| 3 | + |
| 4 | +The `cbbackup` tool is a flexible backup command that enables you to backup both local data and remote nodes and clusters involving different combinations of your data: |
| 5 | + |
| 6 | +* Single bucket on a single node |
| 7 | +* All the buckets on a single node |
| 8 | +* Single bucket from an entire cluster |
| 9 | +* All the buckets from an entire cluster |
| 10 | +
|
| 11 | +Backups can be performed either locally, by copying the files directly on a single node or remotely by connecting to the cluster and then streaming the data from the cluster to your backup location. |
| 12 | +Backups can be performed either on a live running node or cluster or on an offline node. |
| 13 | + |
| 14 | +The `cbbackup` command stores data in a format that enables easy restoration. |
| 15 | +When restoring, using `cbrestore`, you can restore back to a cluster of any configuration. |
| 16 | +The source and destination clusters do not need to match if you used `cbbackup` to store the information. |
| 17 | + |
| 18 | +The `cbbackup` command will copy the data in each course from the source definition to a destination backup directory. |
| 19 | +The backup file format is unique to Couchbase and enables you to restore, all or part of the backed up data when restoring the information to a cluster. |
| 20 | + |
| 21 | +Selection can be made on a key (by a regular expression) or all the data stored in a particular vBucket ID. |
| 22 | +You can also select to copy the source data from a bucket name into a bucket of a different name on the cluster on which you are restoring the data. |
| 23 | + |
| 24 | +The `cbbackup` command takes the following arguments: |
| 25 | + |
| 26 | +---- |
| 27 | +cbbackup [options] [source] [backup_dir] |
| 28 | +---- |
| 29 | + |
| 30 | +[NOTE] |
| 31 | +==== |
| 32 | +The `cbbackup` tool is located within the standard Couchbase command-line directory. |
| 33 | +
|
| 34 | +Be aware that `cbbackup` does not support external IP addresses. |
| 35 | +If you install Couchbase Server with the default IP address, you cannot use an external hostname to access it. |
| 36 | +==== |
| 37 | + |
| 38 | +The following are `cbbackup [options]` arguments: |
| 39 | + |
| 40 | +The following options are used to configure `username` and `password` information for connecting to the cluster, back up type selection and bucket selection. |
| 41 | + |
| 42 | +You can use one or more options. |
| 43 | +The primary options select what will be backed up by `cbbackup`, including: |
| 44 | + |
| 45 | +* `--single-node` |
| 46 | ++ |
| 47 | +Back up only the single node identified by the source specification. |
| 48 | +
|
| 49 | +* `--bucket-source` or `-b` |
| 50 | ++ |
| 51 | +Back up only the specified bucket name. |
| 52 | +
|
| 53 | +The following are `cbbackup [source]` arguments: |
| 54 | + |
| 55 | +The source for the data, either a local data directory reference or a remote node/cluster specification: |
| 56 | + |
| 57 | +* Local Directory Reference |
| 58 | ++ |
| 59 | +A local directory specification is defined as a URL using the `couchstore-files` protocol. |
| 60 | +For example: |
| 61 | ++ |
| 62 | +`couchstore-files:///opt/couchbase/var/lib/couchbase/data/default` |
| 63 | ++ |
| 64 | +Using this method you are specifically backing up the specified bucket data on a single node only. |
| 65 | +To back up an entire bucket data across a cluster or all the data on a single node, you must use the cluster node specification. |
| 66 | +This method does not back up the design documents defined within the bucket. |
| 67 | +
|
| 68 | +* Cluster Node |
| 69 | ++ |
| 70 | +This is a node or a node within a cluster, specified as a URL to the node or cluster service. |
| 71 | +For example: |
| 72 | ++ |
| 73 | +---- |
| 74 | +http://HOST:8091 |
| 75 | +
|
| 76 | +// For distinction you can use the couchbase protocol prefix: |
| 77 | + couchbase://HOST:8091 |
| 78 | + |
| 79 | + |
| 80 | +// The administrator and password can also be combined with both forms of the URL for authentication. |
| 81 | +If you have named data buckets (other than the default bucket) that you want to backup, |
| 82 | +specify an administrative name and password for the bucket: |
| 83 | + |
| 84 | + couchbase://Administrator:password@HOST:8091 |
| 85 | +---- |
| 86 | +
|
| 87 | +The combination of additional options specifies whether the supplied URL refers to the entire cluster, a single node, or a single bucket (node or cluster). |
| 88 | +The node and cluster can be remote or local. |
| 89 | +This method also backs up the design documents used to define views and indexes. |
| 90 | +
|
| 91 | +The `cbbackup [backup_dir]` argument is the directory where the backup data files will be stored on the node on which the `cbbackup` is executed. |
| 92 | +This must be an absolute and explicit directory, as the files will be stored directly within the specified directory; no additional directory structure is created to differentiate between the different components of the data backup. |
| 93 | +The directory that you specify for the backup should either not exist, or exist and be empty with no other files. |
| 94 | +If the directory does not exist, it will be created, but only if the parent directory already exists. |
| 95 | +The backup directory is always created on the local node, even if you are backing up a remote node or cluster. |
| 96 | +The backup files are stored locally in the specified backup directory. |
| 97 | +Backups can take place on a live running cluster or a node for the IP. |
| 98 | +
|
| 99 | +Using this basic structure, you can back up a number of different combinations of data from your source cluster. |
| 100 | +Examples of the different combinations are provided below: |
| 101 | +
|
| 102 | +== Back up all nodes and all buckets |
| 103 | +
|
| 104 | +To back up an entire cluster consisting of all the buckets and all the node data: |
| 105 | +
|
| 106 | +---- |
| 107 | +cbbackup http://HOST:8091 /backups/backup-20120501 \ |
| 108 | + -u Administrator -p password |
| 109 | + [####################] 100.0% (231726/231718 msgs) |
| 110 | +bucket: default, msgs transferred... |
| 111 | + : |
| 112 | + total | last | per sec |
| 113 | + batch : 5298 | 5298 | 617.1 |
| 114 | + byte : 10247683 | 10247683 | 1193705.5 |
| 115 | + msg : 231726 | 231726 | 26992.7 |
| 116 | +done |
| 117 | + [####################] 100.0% (11458/11458 msgs) |
| 118 | +bucket: loggin, msgs transferred... |
| 119 | + : |
| 120 | + total | last | per sec |
| 121 | + batch : 5943 | 5943 | 15731.0 |
| 122 | + byte : 11474121 | 11474121 | 30371673.5 |
| 123 | + msg : 84 | 84 | 643701.2 |
| 124 | +done |
| 125 | +---- |
| 126 | +
|
| 127 | +When backing up multiple buckets, the progress and summary reports for the transferred information are listed for each backed-up bucket. |
| 128 | +The `msgs` count shows the number of documents backed up. |
| 129 | +The `byte` shows the overall size of the data document data. |
| 130 | +
|
| 131 | +The source specification is the URL of one of the nodes in the cluster. |
| 132 | +The backup process will stream data directly from each node in order to create the backup content. |
| 133 | +The initial node is only used to obtain the cluster topology so that the data can be backed up. |
| 134 | +
|
| 135 | +The created backup enables you to choose how you want to restore the information. |
| 136 | +You can restore the entire dataset, or a single bucket, or a filtered selection of that information on a cluster of any size or configuration. |
| 137 | +
|
| 138 | +== Back up all nodes, single bucket |
| 139 | +
|
| 140 | +To back up all the data for a single bucket containing all of the information from the entire cluster: |
| 141 | +
|
| 142 | +---- |
| 143 | +cbbackup http://HOST:8091 /backups/backup-20120501 \ |
| 144 | + -u Administrator -p password \ |
| 145 | + -b default |
| 146 | + [####################] 100.0% (231726/231718 msgs) |
| 147 | + bucket: default, msgs transferred... |
| 148 | + : total | last | per sec |
| 149 | + batch : 5294 | 5294 | 617.0 |
| 150 | + byte : 10247683 | 10247683 | 1194346.7 |
| 151 | + msg : 231726 | 231726 | 27007.2 |
| 152 | + done |
| 153 | +---- |
| 154 | +
|
| 155 | +The `-b` option specifies the name of the bucket that you want to back up. |
| 156 | +If the bucket is a named bucket, you must provide administrative name and password it. |
| 157 | +To back up an entire cluster, you must run the same operation on each bucket within the cluster. |
| 158 | +
|
| 159 | +== Back up single node, all buckets |
| 160 | +
|
| 161 | +To back up all of the data stored on a single node across different buckets: |
| 162 | +
|
| 163 | +---- |
| 164 | +cbbackup http://HOST:8091 /backups/backup-20120501 \ |
| 165 | + -u Administrator -p password \ |
| 166 | + --single-node |
| 167 | +---- |
| 168 | +
|
| 169 | +Using this method, the source specification must specify the node that you want backup. |
| 170 | +To back up an entire cluster using this method, you should back up each node individually. |
| 171 | +
|
| 172 | +== Back up single node, single bucket |
| 173 | +
|
| 174 | +To backup the data from a single bucket on a single node: |
| 175 | +
|
| 176 | +---- |
| 177 | +cbbackup http://HOST:8091 /backups/backup-20120501 \ |
| 178 | + -u Administrator -p password \ |
| 179 | + --single-node \ |
| 180 | + -b default |
| 181 | +---- |
| 182 | +
|
| 183 | +Using this method, the source specification must be the node that you want to back up. |
| 184 | +
|
| 185 | +== Back up single node, single bucket; back up files stored on the same node |
| 186 | +
|
| 187 | +There are two methods available to back up a single node and bucket, with the files stored on the same node as the source data. |
| 188 | +One uses a node specification, the other uses a file store specification. |
| 189 | +Using the node specification: |
| 190 | +
|
| 191 | +---- |
| 192 | +ssh USER@HOST |
| 193 | + remote-> sudo su - couchbase |
| 194 | + remote-> cbbackup http://127.0.0.1:8091 /mnt/backup-20120501 \ |
| 195 | + -u Administrator -p password \ |
| 196 | + --single-node \ |
| 197 | + -b default |
| 198 | +---- |
| 199 | +
|
| 200 | +This method backs up the cluster data of a single bucket on the local node, storing the backup data in the local filesystem. |
| 201 | +
|
| 202 | +Using a file store reference (in place of a node reference) is faster, because the data files can be copied directly from the source directory to the backup directory: |
| 203 | +
|
| 204 | +---- |
| 205 | +ssh USER@HOST |
| 206 | + remote-> sudo su - couchbase |
| 207 | + remote-> cbbackup couchstore-files:///opt/couchbase/var/lib/couchbase/data/default /mnt/backup-20120501 |
| 208 | +---- |
| 209 | +
|
| 210 | +To back up the entire cluster using this method, you will need to back up each node and each bucket individually. |
| 211 | +
|
| 212 | +NOTE: Choosing the right backup solution depends on your requirements and your expected method for restoring the data to the cluster. |
| 213 | +
|
| 214 | +== Filter keys during backup |
| 215 | +
|
| 216 | +The `cbbackup` command includes support for filtering the keys that are backed up into the database files you create. |
| 217 | +This can be useful if you want to specifically back up a portion of your dataset, or you want to move part of your dataset to a different bucket. |
| 218 | +
|
| 219 | +The specification is in the form of a regular expression, and is performed on the client-side within the `cbbackup` tool. |
| 220 | +For example, to back up information from a bucket where the keys have a prefix `object`: |
| 221 | +
|
| 222 | +---- |
| 223 | +cbbackup http://HOST:8091 /backups/backup-20120501 \ |
| 224 | + -u Administrator -p password \ |
| 225 | + -b default \ |
| 226 | + -k '^object.*' |
| 227 | +---- |
| 228 | +
|
| 229 | +The above copies only the keys matching the specified prefix into the backup file. |
| 230 | +When the data is restored, only those keys that were recorded in the backup file will be restored. |
| 231 | +
|
| 232 | +IMPORTANT: The regular expression match is performed on the client side. |
| 233 | +This means that the entire bucket contents must be accessed by the `cbbackup` command and then discarded if the regular expression does not match. |
| 234 | +
|
| 235 | +Key-based regular expressions can also be used when restoring data. |
| 236 | +You can back up an entire bucket and restore selected keys during the restore process using `cbrestore`. |
| 237 | +
|
| 238 | +== Back up using file copies |
| 239 | +
|
| 240 | +You can also back up by using either `cbbackup` and specifying the local directory where the data is stored, or by copying the data files directly using cp, tar, or similar. |
| 241 | +
|
| 242 | +For example, using `cbbackup`: |
| 243 | +
|
| 244 | +---- |
| 245 | +> cbbackup \ |
| 246 | + couchstore-files:///opt/couchbase/var/lib/couchbase/data/default \ |
| 247 | + /mnt/backup-20120501 |
| 248 | +---- |
| 249 | +
|
| 250 | +The same backup operation using `cp` : |
| 251 | +
|
| 252 | +---- |
| 253 | +> cp -R /opt/couchbase/var/lib/couchbase/data/default \ |
| 254 | + /mnt/copy-20120501 |
| 255 | +---- |
| 256 | +
|
| 257 | +The limitation of backing up information in this way is that the data can only be restored to offline nodes in an identical cluster configuration where an identical vBucket map is in operation. |
| 258 | +You should also copy the `config.dat` configuration file from each node. |
0 commit comments