Hot Backup Examples

Create

Hot backups are created near instantaneously. The single server aswell as other deployment modes try to obtain a global write transaction lockto enforce consistency across all servers, databases, collectionsetc. Hot backups still require no Data Definition operations (e.g., createdatabase, create collection) to be active at the time of hot backup, pleasereview the requirements and limitationsfor more details.

Once that lock could be acquired the hot backup itself is mostreadily described as a consistent snapshot on the local file system.

  1. arangobackup create --server.endpoint tcp://myserver:8529 --label my-label

The above will create a hot backup with a unique identifier consistingof the UTC time according to the local computer clock output and thespecified label and report the success like below.

  1. 2019-05-15T13:57:11Z [15213] INFO {backup} Server version: 3.5.1
  2. 2019-05-15T14:20:16Z [15397] INFO {backup} Backup succeeded. Generated identifier '2019-05-15T14.20.15Z_my-label'

If the label marker is omitted then a unique identifier string isgenerated instead.

There are more options for the cluster mode regarding the acquisition of theglobal write transaction lock:

  • —max-wait-for-lock: configures how long the system tries to get the globalwrite transaction lock before it reports failure. Its value must be a numberin seconds (default: 120 seconds).
  • —allow-inconsistent: if set to false (default), the operation isconsidered to have failed if the maximal waiting time for the lock isexceeded. If set to true, the system will take a potentially non-consistenthot backup when the timeout is exceeded.
  • —force: will make arangobackup abort ongoing write transactions in orderto more quickly acquire the global write transaction lock. This option shouldbe used with caution, as it will potentially abort valid write transactions,meaning client applications will see errors for otherwise valid operationsand queries. The force option currently only aborts stream transactions butno JavaScript transactions.

Restore

Once a hot backup is created, one can use the generated backup id,for example 2019-05-15T14.36.38Z_my-label to restore the entireinstance to that “snapshot”.

Keep in mind that such a restore is a global operation and affectsall databases in an installation. The restore will roll back all dataincluding in the meantime databases, collections, indexes etc.The DB-Server of a single server instance and all DB-Serversof a cluster will subsequently be restarted.

  1. arangobackup restore --server.username root --identifier 2019-05-15T14.36.38Z_my-label

The output will reflect the restore operation’s success:

  1. 2019-05-15T15:24:14Z [16201] INFO {backup} Server version: 3.5.1
  2. 2019-05-15T15:24:14Z [16201] INFO {backup} Successfully restored '2019-05-15T14.36.38Z_my-label'

Note that current ArangoSearch views are not stored in hot backups,therefore, after a successful restore operation, all views have to bedropped and recreated. This is done automatically in the background, butthe recreation of the ArangoSearch indexes can take some time, inparticular if a lot of data has to be indexed.

Delete

Hot backups, analogous to virtual machine snapshots, cause additionaldisk usage. With every hot backup a consistent state in time isfrozen. Later changes will then have to hold a difference to olderhot backups. Compactions can no longer cover events before the lasthot backup. Naturally, one may want to be able to free disk space, oncehot backups become obsolete.

  1. arangobackup delete --server.username root --identifier <identifier>

The result of the operation is thus delivered:

  1. 2019-05-15T15:34:34Z [16257] INFO {backup} Server version: 3.5.1
  2. 2019-05-15T15:34:34Z [16257] INFO {backup} Successfully deleted '2019-05-15T13.57.03Z'

List

One may hold a multitude of hot backups. Those would all be availableto restore from. In order to get a listing of such hot backups, onemay use the list command.

  1. arangobackup list

The output lists all available hot backups:

  1. 2019-05-15T15:28:17Z [16224] INFO {backup} Server version: 3.5.1
  2. 2019-05-15T15:28:17Z [16224] INFO {backup} The following backups are available:
  3. 2019-05-15T15:28:17Z [16224] INFO {backup}  - 2019-05-15T13.57.11Z_my-label
  4. 2019-05-15T15:28:17Z [16224] INFO {backup}  - 2019-05-15T13.57.03Z-other-label

Upload

Hot backups can be uploaded to a remote repository, here is an example whichuses the S3 protocol:

  1. arangobackup upload --server.endpoint tcp://myserver:8529 --rclone-config-file /path/to/remote.json --identifier 2019-05-13T07.15.43Z_some-label --remote-path S3://remote-endpoint/remote-directory

The output will look like this:

  1. 2019-07-30T08:10:10Z [17184] INFO [06792] {backup} Server version: 3.5.1
  2. 2019-07-30T08:10:10Z [17184] INFO [a9597] {backup} Backup initiated, use 
  3. 2019-07-30T08:10:10Z [17184] INFO [4c459] {backup}     arangobackup upload --status-id=114
  4. 2019-07-30T08:10:10Z [17184] INFO [5cd70] {backup}  to query progress.

This uses a file remote.json in the current directory to configurecredentials for the remote site. Here is an example:

  1. {
  2.   "my-s3": {
  3.     "type": "s3",
  4.     "provider": "aws",
  5.     "env_auth": "false",
  6.     "access_key_id": "XXXXXXXXXXXXXXXXXXXX",
  7.     "secret_access_key": "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
  8.     "region": "xx-xxxx-x",
  9.     "acl": "private"
  10.   }
  11. }

This process may take as long as it needs to upload the data from thesingle server or all of the cluster’s DB-Servers to the remotelocation. However, the upload will take advantage from previouslyuploaded hot backups which might contain identical files. Therefore, thefunctionality is incremental, if regular hot backups are taken and uploadedto the same remote site.

The status of the process may be acquired at any later time.

  1. arangobackup upload --server.endpoint tcp://myserver:8529 --status-id=114

where the number given in the —status-id option is the one which wasreported in the original upload command.

The output will look like this:

  1. 2019-07-30T08:11:09Z [17465] INFO [06792] {backup} Server version: 3.5.1
  2. 2019-07-30T08:11:09Z [17465] INFO [24d75] {backup} SNGL Status: COMPLETED
  3. 2019-07-30T08:11:09Z [17465] INFO [68cc8] {backup} Last progress update 2019-07-30T08:10:10Z: 5/5 files done

See Rclone Configuration for details about the remote.jsonfile to configure the remote site for rclone for different protocols than S3.

Download

Hot backups can be downloaded from a remote repository like this:

  1. arangobackup download --server.endpoint tcp://myserver:8529 --rclone-config-file /path/to/remote.json --identifier 2019-05-13T07.15.43Z_some-label --remote-path S3://remote-endpoint/remote-directory

The output will look like this:

  1. 2019-07-30T08:14:43Z [17621] INFO [06792] {backup} Server version: 3.5.1
  2. 2019-07-30T08:14:43Z [17621] INFO [a9597] {backup} Backup initiated, use 
  3. 2019-07-30T08:14:43Z [17621] INFO [4c459] {backup}     arangobackup download --status-id=250
  4. 2019-07-30T08:14:43Z [17621] INFO [5cd70] {backup}  to query progress.

This process may take as long as it needs to download the data tothe single server or all of the cluster’s DB-Servers from the remoteendpoint given network limitations. However, the download will takeadvantage from other hot backups which might already or still be presentlocally that contain identical files. Therefore, the functionality isincremental, if a hot backup is downloaded and a similar one is alreadypresent.

The status of the download process may be acquired at any later time.

  1. arangobackup download --server.endpoint tcp://myserver:8529 --status-id=250

The output will look like this:

  1. 2019-07-30T08:18:07Z [17753] INFO [06792] {backup} Server version: 3.5.1
  2. 2019-07-30T08:18:07Z [17753] INFO [24d75] {backup} SNGL Status: COMPLETED
  3. 2019-07-30T08:18:07Z [17753] INFO [68cc8] {backup} Last progress update 2019-07-30T08:14:43Z: 5/5 files done

Rclone Configuration

Rclone is a versatile open-sourceremote file sync program that can deal with over 30 different remote fileIO protocols. Enterprise Editions of ArangoDB come with a bundled versionof Rclone, which is distributed under the MIT license. It is used toboth download and upload hot backup sets to and from local and cloudoperated storage resources.

Hot backup directories, which are subject to an ongoing download cannotbe used for restores until the download has finished.

To configure Rclone, use the rclone-config-file startup option topoint arangobackup to a JSON configuration file. The expected formatis an object with user-chosen remote names as attribute keys, and theactual configuration as attribute value (a nested object). The optionnames and values in the Rclone documentationdirectly translate into attribute/value pairs in the JSON file.Note that "true" and "false" must be enclosed by double quotes.

  1. {
  2.   "my-remote": {
  3.     "option": "value",
  4.     "boolean": "true"
  5.   }
  6. }

The remote path can be specified via the remote-path startup option.The syntax for remote paths is remote:path, where remote is thename of a top-level attribute in the configuration file, path is aremote path, and both are separated by a colon (e.g. my-remote:/a/b/c).

S3

  1. … --rclone-config-file ~/my-s3.json --remote-path my-s3://remote-endpoint/remote-directory

The file my-s3.json could look like this:

  1. {
  2.   "my-s3": {
  3.     "type": "s3",
  4.     "provider": "aws",
  5.     "env_auth": "false",
  6.     "access_key_id": "XXXXXXXXXXXXXXXXXXXX",
  7.     "secret_access_key": "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
  8.     "region": "xx-xxxx-x",
  9.     "acl": "private"
  10.   }
  11. }

More examples and details for S3 configurations can be found atrclone.org/s3.

Locally mounted local or remote volumes

  1. … --rclone-config-file ~/my-local.json --remote-path my-local://mnt/backup/arangodb

The file my-local.json could look like this:

  1. {
  2.   "my-local": {
  3.     "type": "local",
  4.     "copy-links": "false",
  5.     "links": "false",
  6.     "one_file_system": "false"
  7.   }
  8. }

More examples and details for local configurations can be found atrclone.org/local.

WebDAV

  1. … --rclone-config-file ~/my-dav.json --remote-path my-dav://remote-endpoint/remote-directory

Thie file my-dav.json could look like this:

  1. {
  2.   "my-dav": {
  3.     "pass": "A0OeLviBmwqKyCi7S6Rnn6dG576cJeRN1Nh0Dm5h8k0",
  4.     "type": "webdav",
  5.     "url": "https://dav.myserver.com",
  6.     "user": "davuser",
  7.     "vendor": "other"
  8.   }
  9. }

More examples and details on WebDAV configurations can be foundrclone.org/webdav.