Creates a backup of operational disk stores for all members running in the distributed system. Each member with persistent data creates a backup of its own configuration and disk stores.
Use the mcast-port and -mcast-address, or the -locators options, on the command line to connect to the GemFire XD cluster.
gfxd backup [-baseline=<baseline directory>] <target directory> [-J-D<vmprop>=<prop-value>] [-mcast-port=<port>] [-mcast-address=<address>] [-locators=<addresses>] [-bind-address=<address>] [-<prop-name>=<prop-value>]*
Alternatively, you can specify these and other distributed system properties in a gemfirexd.properties file that is available in the directory where you run the gfxd command.
The table describes options for gfxd backup.
|-baseline||The directory that contains a baseline backup used for comparison during an
incremental backup. The baseline directory corresponds to the date
when the original backup command was performed, rather than the
backup location you specified (for example, a valid baseline
directory might resemble
An incremental backup operation backs up any data that is not already present in the specified -baseline directory. If the member cannot find previously backed up data or if the previously backed up data is corrupt, then command performs a full backup on that member. (The command also performs a full backup if you omit the -baseline option.
|<target-directory>||The directory in which GemFire XD stores the backup content. See Specifying the Backup Directory.|
|-mcast-port|| Multicast port used to communicate with
other members of the distributed system. If zero, multicast is not used for
member discovery (specify
Valid values are in the range 0–65535, with a default value of 10334.
|-mcast-address|| Multicast address used to discover other
members of the distributed system. This value is used only if the
-locators option is not specified.
The default multicast address is 126.96.36.199.
|-locators||List of locators used to discover members of the distributed system. Supply all locators as comma-separated host:port values.|
|-bind-address||The address to which this peer binds for receiving peer-to-peer messages. By default gfxd uses the hostname, or localhost if the hostname points to a local loopback address.|
|-prop-name||Any other GemFire XD distributed system property.|
An online backup saves the following:
- For each member with persistent data, the backup includes disk store files for all stores containing persistent table data.
- Configuration files from the member startup.
- gemfirexd.properties, with the properties the member was started with.
- A restore script, written for the member's operating system, that copies the files back to their original locations. For example, in Windows, the file is restore.bat and in Linux, it is restore.sh.
Prerequisites and Best Practices
- Run this command during a period of low activity in your system. The backup does not block system activities, but it uses file system resources on all hosts in your distributed system and can affect performance.
- Do not try to create backup files from a running system using file copy commands. You will get incomplete and unusable copies.
- Make sure the target backup directory directory exists and has the proper permissions for your members to write to it and create subdirectories.
- You might want to compact your disk store before running the backup. See the compact-all-disk-stores command.
- Make sure that those GemFire XD members that host persistent data are running in the distributed system. Offline members cannot back up their disk stores. (A complete backup can still be performed if all table data is available in the running members.)
Specifying the Backup Directory
- Use a single physical location, such as a network file server. (For example, /export/fileServerDirectory/gfxdBackupLocation).
- Use a directory that is local to all host machines in the system. (For example, ./gfxdBackupLocation).
gfxd backup ./gfxdBackupLocation -locators=warsaw.pivotal.com
See also Backing Up and Restoring Disk Stores.
gfxd backup -baseline=./gfxdBackupLocation/2012-10-01-12-30 ./gfxdBackupLocation -locators=warsaw.pivotal.com
Output Messages from gfxd backup
When you run gfxd backup, it reports on the outcome of the operation.
The backup may be incomplete. The following disk stores are not online: DiskStore at hostc.pivotal.com /home/dsmith/dir3A complete backup can still be performed if all table data is available in the running members.
The tool reports on the success of the operation. If the operation is successful, you see a message like this:
Connecting to distributed system: locators=warsaw.pivotal.com26340 The following disk stores were backed up: DiskStore at hosta.pivotal.com /home/dsmith/dir1 DiskStore at hostb.pivotal.com /home/dsmith/dir2 Backup successful.
If the operation does not succeed at backing up all known members, you see a message like this:
Connecting to distributed system: locators=warsaw.pivotal.com26357 The following disk stores were backed up: DiskStore at hosta.pivotal.com /home/dsmith/dir1 DiskStore at hostb.pivotal.com /home/dsmith/dir2 The backup may be incomplete. The following disk stores are not online: DiskStore at hostc.pivotal.com /home/dsmith/dir3
A member that fails to complete its backup is noted in this ending status message and leaves the file INCOMPLETE_BACKUP in its highest level backup directory.
Backup Directory Structure and Its Contents
Below is the structure of files and directories backed up in a distributed system:
2011-05-02-18-10 /: pc15_8933_v10_10761_54522 2011-05-02-18-10/pc15_8933_v10_10761_54522: config diskstores README.txt restore.sh 2011-05-02-18-10/pc15_8933_v10_10761_54522/config: gemfirexd.properties 2011-05-02-18-10/pc15_8933_v10_10761_54522/diskstores: GFXD_DD_DISKSTORE 2011-05-02-18-10/pc15_8933_v10_10761_54522/diskstores/GFXD_DD_DISKSTORE: dir0 2011-05-02-18-10/pc15_8933_v10_10761_54522/diskstores/GFXD_DD_DISKSTORE/dir0: BACKUPGFXD-DD-DISKSTORE_1.crf BACKUPGFXD-DD-DISKSTORE_1.drf BACKUPGFXD-DD-DISKSTORE_2.crf BACKUPGFXD-DD-DISKSTORE_2.drf BACKUPGFXD-DD-DISKSTORE.if
Restoring an Online Backup
The restore script (restore.sh or restore.bat) copies files back to their original locations. You can do this manually if you wish:
- Restore your disk stores when your members are offline and the system is down.
- Read the restore scripts to see where they will place the files and make sure the destination locations are ready. The restore scripts refuse to copy over files with the same names.
- Run the restore scripts. Run each script on the host where the backup originated.
The restore copies these back to their original location.