| Exit Print View | |
Sun OpenDS Standard Edition 2.0 Command-Line Usage Guide |
|
|
|
The backup command archives the contents of one or more directory server back ends.
backup options
The backup command archives the contents of one or more directory server back ends. The utility can perform this operation immediately or at a scheduled time. For more information, see Configuring Commands As Tasks in Sun OpenDS Standard Edition 2.0 Administration Guide.
The backup command can be run when the server is online, or offline. If the backup is run while the server is online, the command contacts the server over SSL, via the administration connector, and registers a backup task. For more information about use of the administration connector, see Managing Administration Traffic to the Server in Sun OpenDS Standard Edition 2.0 Administration Guide.
The backup command accepts an option in either its short form (for example, -B backupID) or its long form equivalent (for example, --incrementalBaseID backupID).
Back up all configured back ends. This option must not be used in conjunction with --backendID.
Generate a hash, or message digest, of the contents of the backup archive. The hash can be used as a checksum during the restore process to ensure that the backup has not been altered.
Specify the backup ID for the existing backup against which to take an incremental backup. If this ID is not provided, the incremental backup is based on the latest incremental or full backup contained in the backup directory.
Compress the contents of the backup archive. The compression algorithm used may vary based on the back end type.
Write the backup files to the specified directory. If multiple back ends are archived, a subdirectory is created below this path for each back end. Otherwise, the backup files are placed directly in this directory. Note that multiple backups for the same back end can be placed in the same directory. If an incremental backup is to be performed, the backup directory must already contain at least one full backup. This is a required option.
Perform an incremental backup rather than a full backup. An incremental backup includes only the data that has changed since a previous incremental or full backup. Thus, running an incremental backup can be notably faster than a full backup. When restoring an incremental backup, it is first necessary to restore the original full backup and then any intermediate incremental backups, which can make the restore process somewhat slower than restoring just a full backup. Note that some types of back ends might not support performing incremental backups. In this case, this option is ignored and a full backup is performed.
Specify an identifier to use for the backup. If this is not provided, a backup ID is generated, based on the current time. The backup ID must be unique among all backups in the provided backup directory.
Specify the ID of the back-end to be saved. This option can be used multiple times in a single command to indicate that multiple back ends should be backed up. The available back ends in the server can be determined by using the dsconfig list-backends command.
Generate a signed hash. This provides even stronger assurance that neither the backup archive nor the hash of its contents have been altered. This option can only be used if a connection to an online directory server instance is present. In this case, you must specify the --hostname, --port, --bindDN, and --bindPassword options of the online directory server that will generate a signed hash of the archive.
Encrypt the contents of the backup archive. This option can only be used if a connection to an online server instance is present. In this case, you must specify the --hostname, --port, --bindDN, and --bindPassword options of the online directory server that will encrypt the archive.
Running an online backup requires access to the tasks back end. Access to the tasks back end is provided over SSL via the administration connector. These connection options are used when the backup runs online.
Use the bind DN to authenticate to the directory server. This option is used when performing simple authentication and is not required if SASL authentication is to be used. The default value for this option is cn=Directory Manager.
Contact the directory server on the specified hostname or IP address. If this option is not provided, a default of localhost is used.
Use the bind password in the specified file when authenticating to the directory server. This option must not be used in conjunction with --bindPassword.
Use the client keystore certificate in the specified path.
Use the specified certificate for client authentication.
Use the specified options for SASL authentication .
Contact the directory server at the specified administration port. If this option is not provided, a default administration port of 4444 is used.
Use the client trust store certificate in the specified path. This option is not needed if --trustAll is used, although a trust store should be used when working in a production environment.
Use the password needed to access the certificates in the client trust store. This option is only required if --trustStorePath is used and the specified trust store requires a password in order to access its contents (which most trust stores do not require). This option must not be used in conjunction with --trustStorePasswordFile.
Use the password in the specified file to access the certificates in the client keystore. This option is only required if --keyStorePath is used. This option must not be used in conjunction with --keyStorePassword.
Use the password in the specified file to access the certificates in the client trust store. This option is only required if --trustStorePath is used and the specified trust store requires a password in order to access its contents (most trust stores do not require this). This option must not be used in conjunction with --trustStorePassword.
Use the bind password when authenticating to the directory server. This option can be used for simple authentication as well as password-based SASL mechanisms. This option must not be used in conjunction with --bindPasswordFile. To prompt for the password, type -w -.
Use the password needed to access the certificates in the client keystore. This option is only required if --keyStorePath is used. This option must not be used in conjunction with --keyStorePasswordFile.
Trust all server SSL certificates that the directory server presents. This option can be used for convenience and testing purposes, but for security reasons a trust store should be used to determine whether the client should accept the server certificate.
These options are used when you specify that the backup should run as a scheduled task.
Specify the email address of a recipient to be notified when the task completes. This option can be specified more than once in a single command.
Specify the ID of a task upon which this task depends. A task does not start executing until all of its dependencies have completed execution.
Specify the email address of a recipient to be notified if an error occurs when this task executes. This option can be specified more than once in a single command.
Specify the action that this task will take if one of its dependent tasks fails. The value must be one of PROCESS, CANCEL, or DISABLE. If no value is specified, the default action is CANCEL.
Indicates the date and time at which the operation starts when scheduled as a directory server task expressed in the format YYYYMMDDhhmmss. A value of 0 schedules the task for immediate execution. When this option is specified, the operation is scheduled to start at the specified time after which the utility exits immediately.
Indicates that a properties file is not used to obtain the default command-line options.
Specify the path to the properties file that contains the default command-line options.
Display command-line usage information for the utility and exit without making any attempt to back up data.
Display the version information for the directory server and exit rather than attempting to run this command.
The following examples show how to use the directory server commands. You can use the commands on any UNIX, Linux, or Windows system that has at least the Java SE 5 (at least Sun version 1.5.0_08, preferably the latest version of Java SE 6) runtime environment installed on its target system.
The following command archives all directory server back ends (-a), compresses them (-c), and saves them to a specified directory (-d).
$ backup -a -c -d /tmp/backup
Display the contents of the backup directory, to see the subdirectories for each back end:
$ ls /tmp/backup config schema tasks userRoot
Display the contents of a subdirectory, to see that the system assigned a backup ID based on the current time.
$ ls /tmp/backup/userRoot/ backup-userRoot-20081015151640Z backup.info
You can assign your own unique backup ID by using the -I option. For example:
$ backup -a -c -d /tmp/backup -I October08
Display the contents of the userRoot subdirectory to see the assigned backup ID.
$ ls /tmp/backup/userRoot/ backup-userRoot-October08 backup.info
Use the -n option to specify a back end to be backed up. The following command archives the userRoot back end only.
$ backup -n userRoot -d /tmp/backup
The following command archives all directory server back ends (-a), using incremental backup (-i), compresses them (-c), and saves the data to a directory (-d).
$ backup -a -i -c -d /tmp/backup
Use the list-backends utility to display the current configured back ends.
$ list-backends Backend ID : Base DN ---------------:-------------------- adminRoot : cn=admin data ads-truststore : cn=ads-truststore backup : cn=backups config : cn=config monitor : cn=monitor schema : cn=schema tasks : cn=tasks userRoot : "dc=example,dc=com"
The following command runs an incremental backup (-i) on the userRoot back end (-n), compresses the backup (-c), and saves the data to a directory (-d).
$ backup -i -n userRoot -c -d /tmp/backup/userRoot
Assume that you have created two archived incremental backup files by using the -I or --backupID option and assigned the IDs 1234 and 4898 to the two files, respectively:
/tmp/backup/userRoot> ls ./ backup-userRoot-1234 backup.info ../ backup-userRoot-4898 backup.info.save
The following command runs an incremental backup (-i) on all configured back ends (-a) based on the backup ID 1234 (-B), assigns a backup ID of 5438 to the incremental backup, and saves the data to a directory (-d).
$ backup -a -i -B 1234 -I 5438 -d /tmp/backup
The contents of backup.info show that the latest incremental backup (backup_id=5438) has a dependency on backup_id=1234:
$ backend_dn=ds-cfg-backend-id=userRoot,cn=Backends,cn=config backup_id=4898 backup_date=20070727202906Z incremental=false compressed=false encrypted=false signed_hash=VmBG/VkfMAMMPnR6M8b5kZil7FQ= property.last_logfile_name=00000000.jdb property.archive_file=backup-userRoot-4898 property.cipher_algorithm=AES/CBC/PKCS5Padding property.mac_algorithm=HmacSHA1 property.last_logfile_size=490554 backup_id=1234 backup_date=20070727202934Z incremental=false compressed=false encrypted=false signed_hash=VmBG/VkfMAMMPnR6M8b5kZil7FQ= property.last_logfile_name=00000000.jdb property.archive_file=backup-userRoot-1234 property.cipher_algorithm=AES/CBC/PKCS5Padding property.mac_algorithm=HmacSHA1 property.last_logfile_size=490554 backup_id=5438 backup_date=20070727203107Z incremental=true compressed=false encrypted=false dependency=1234 property.last_logfile_name=00000000.jdb property.archive_file=backup-userRoot-5438 property.last_logfile_size=490554
The directory server provides support for backup encryption (using --encrypt), hash generation (using --hash), and signed hash (using --signHash) to secure archived data. These options require a connection to an online server instance, over SSL via the administration connector. When you use these options, you must therefore specify the connection details, including the host, administration port, bind DN and bind password. You must also specify the certificate details for the SSL connection.
The following command archives all directory server back ends (-a), compresses them (-c), generates a hash (-A), signs the hash (-s), encrypts the data while archiving the data (-y), assigns a back end ID of 123, and saves the data to a directory (-d). The self signed certificate is trusted using the -X (--trustAll) option.
$ backup -h localhost -D "cn=Directory Manager" -w password -p 4444 -X \ -a -c -A -s -y -I 123 -d /tmp/backup Backup task 2008101609295810 scheduled to start immediately ...
Scheduling a backup requires online access to the tasks back end. Access to this back end is provided over SSL via the administration connector. When you schedule a backup, you must therefore specify the connection details, including the host, administration port, bind DN and bind password. You must also specify the certificate details for the SSL connection.
The following command schedules a backup of all components (-a) and writes it to the /tmp/backups directory (-d). The start time is specified with the --start option. The backup sends a completion notification and error notification to admin@example.com. The self signed certificate is trusted using the -X (--trustAll) option.
$ backup -h localhost -D "cn=Directory Manager" -w password -p 4444 -X \ -a -d /tmp/backups --start 20090124121500 --completionNotify admin@example.com \ --errorNotify admin@example.com Backup task 2007102914530410 scheduled to start Jan 24, 2009 12:15:00 PM SAST
You can view this scheduled task by using the manage-tasks utility. For more information, see Configuring Commands As Tasks in Sun OpenDS Standard Edition 2.0 Administration Guide.
An exit code of 0 indicates that the operation completed successfully. An exit code of 1 indicates that an error occurred during processing.
The directory server supports the use of a properties file that passes in any default option values used with the backup command. The properties file is convenient when working in different configuration environments, especially in scripted or embedded applications. For more information, see Using a Properties File With Directory Server Commands.
The backup command is located at these paths:
UNIX and Linux: install-dir/bin/backup
Windows: install-dir\bat\backup.bat
|
|