PingAuthorize Server Documentation Index
Command-Line Tool Reference Home

backup

Description
Examples
Arguments

Description

Back up one or more PingAuthorize Server backends.

Each backend backup is stored in a separate backend backup directory. A backend backup directory may contain multiple backups of the backend. Each backend backup directory contains a backup.info file providing information about each backup in the directory and an archive file for each backup. The name of the archive file includes both the backend ID and the backup ID. The backup ID may be provided to the backup command, or an ID is generated from a current timestamp.

Backups may be full or incremental. The archive file for incremental backups contains the incremental changes since a previous backup. Each backup can be optionally compressed, encrypted, hashed or signed. A backup taken on one system can be restored on another system.

This tool features both an offline mode of operation as well as the ability to schedule an operation to run within the PingAuthorize Server's process. To schedule an operation supply LDAP connection options that allow this tool to communicate with the server through its task interface. Tasks can be scheduled to run immediately or at a later time (see Task Scheduling Options below). Once scheduled, tasks can be managed using the manage-tasks tool.

Examples

Back up all backends in the PingAuthorize Server into separate directories under the directory 'backups'. Each backend backup is named using the backend ID. However, a backup ID is not specified, so each backup is assigned an ID generated from a current timestamp:
backup --backupDirectory backups --backUpAll


Create a full backup of the userRoot backend with ID 'monday' in the directory 'backups/userRoot'. If there are any previous full backups older than one week in that directory, then delete them along with any incremental backups that depend on them:
backup --backupDirectory backups/userRoot --backendID userRoot \
     --backupID monday --retainPreviousFullBackupAge "1 week"


Create an encrypted and signed backup of the userRoot backend in the directory 'backups/userRoot'. The encryption key will be generated from an interactively provided passphrase:
backup --backupDirectory backups/userRoot --backendID userRoot --incremental \
     --incrementalBaseID monday


Back up all backends in the PingAuthorize Server running on host 'server1' at port 389:
backup --task --hostname server1 --port 389 \
     --bindDN uid=admin,dc=example,dc=com --bindPassword password \
     --backupDirectory backups --backUpAll

For examples and help with LDAP options see LDAP Option Help. For help with SASL authentication, see SASL Option Help

Arguments

-V
--version

Description Display PingAuthorize Server version information

-H
--help

Description Display general usage information

--help-ldap

Description Display help for using LDAP options

--help-sasl

Description Display help for using SASL options

--help-debug

Description Display help for using debug options
Advanced Yes

-Z
--useSSL

Description Use SSL for secure communication with the server

-q
--useStartTLS

Description Use StartTLS to secure communication with the server

--useNoSecurity

Description Use no security when communicating with the server

-h {host}
--hostname {host}

Description PingAuthorize Server hostname or IP address
Default Value localhost
Required No
Multi-Valued No

-p {port}
--port {port}

Description PingAuthorize Server port number
Default Value 389
Required No
Multi-Valued No

-D {bindDN}
--bindDN {bindDN}

Description DN used to bind to the server
Default Value cn=Directory Manager
Required No
Multi-Valued No

-w {bindPassword}
--bindPassword {bindPassword}

Description Password used to bind to the server
Required No
Multi-Valued No

-j {bindPasswordFile}
--bindPasswordFile {bindPasswordFile}

Description Bind password file
Required No
Multi-Valued No

-o {name=value}
--saslOption {name=value}

Description SASL bind options
Required No
Multi-Valued Yes

-X
--trustAll

Description Trust all server SSL certificates

-P {truststorePath}
--trustStorePath {truststorePath}

Description Certificate truststore path
Default Value /home/centos/workspace/Core-Release-Pipeline/build/package/PingAuthorize/config/truststore
Required No
Multi-Valued No

-T {truststorePassword}
--trustStorePassword {truststorePassword}

Description Certificate truststore PIN
Required No
Multi-Valued No

-U {path}
--trustStorePasswordFile {path}

Description Certificate truststore PIN file
Required No
Multi-Valued No

--trustStoreFormat {trustStoreFormat}

Description Certificate truststore format
Required No
Multi-Valued No

-K {keystorePath}
--keyStorePath {keystorePath}

Description Certificate keystore path
Required No
Multi-Valued No

-W {keystorePassword}
--keyStorePassword {keystorePassword}

Description Certificate keystore PIN
Required No
Multi-Valued No

-u {keystorePasswordFile}
--keyStorePasswordFile {keystorePasswordFile}

Description Certificate keystore PIN file
Required No
Multi-Valued No

--keyStoreFormat {keyStoreFormat}

Description Certificate keystore format
Required No
Multi-Valued No

-N {nickname}
--certNickname {nickname}

Description Nickname of the certificate for SSL client authentication
Required No
Multi-Valued No

--useAdministrativeSession

Description Attempt to use an administrative session to have operations processed on a dedicated pool of worker threads. This may be useful when trying to diagnose problems in a server that is unresponsive because all normal worker threads are busy processing other requests

--propertiesFilePath {propertiesFilePath}

Description Path to the file that contains default property values used for command-line arguments
Required No
Multi-Valued No

--usePropertiesFile

Description Specify that a properties file will be used to get default command-line argument values

--script-friendly

Description Use script-friendly mode

--task

Description Indicates that this tool should be invoked as a task which runs inside the PingAuthorize Server rather than as a separate process. At present, this argument is optional, but in a future release it may be required for running as a task

-t {startTime}
--start {startTime}

Description Indicates the date/time, expressed in format 'YYYYMMDDhhmmss', when the operation starts when scheduled as a server task. A value of '0' causes the task to be scheduled for immediate execution. When this option is specified, the operation is scheduled to start at the specified time, after which this utility will exit immediately
Required No
Multi-Valued No

--startAlert

Description Generate an administrative alert when the task starts running

--successAlert

Description Generate an administrative alert when the task completes successfully

--errorAlert

Description Generate an administrative alert when the task fails to complete successfully

--startNotify {emailAddress}

Description Email address of a recipient to be notified when this task starts running
Required No
Multi-Valued Yes

--completionNotify {emailAddress}

Description Email address of a recipient to be notified when the task completes, regardless of whether it succeeded or failed
Required No
Multi-Valued Yes

--successNotify {emailAddress}

Description Email address of a recipient to be notified when this task completes successfully
Required No
Multi-Valued Yes

--errorNotify {emailAddress}

Description Email address of a recipient to be notified if an error occurs when this task executes
Required No
Multi-Valued Yes

--dependency {taskID}

Description ID of a task upon which this task depends. A task will not start execution until all its dependencies have completed execution
Required No
Multi-Valued Yes

--failedDependencyAction {action}

Description Action this task will take should one of its dependent tasks fail. The value must be one of the following: PROCESS,CANCEL,DISABLE. If not specified, the default value is CANCEL
Required No
Multi-Valued Yes

-Q
--quiet

Description Use quiet mode

-n {backendName}
--backendID {backendName}

Description Backend ID for the backend being archived
Required No
Multi-Valued Yes

-a
--backUpAll

Description Back up all backends in the server

-I {backupID}
--backupID {backupID}

Description Use the provided identifier for the backup
Required No
Multi-Valued No

-d {backupDir}
--backupDirectory {backupDir}

Description Path to the target directory for the backup file(s)
Required Yes
Multi-Valued No

-i
--incremental

Description Perform an incremental backup rather than a full backup

-B {backupID}
--incrementalBaseID {backupID}

Description Backup ID of the source archive for an incremental backup
Required No
Multi-Valued No

-c
--compress

Description Compress the backup contents

--maxMegabytesPerSecond {MB}

Description The maximum rate in megabytes per second at which the backup file may be written. Imposing a maximum write rate can help avoid incurring a performance penalty that may result from saturating the storage subsystem, especially on systems that cannot fully cache the data in memory. If this is not provided, then no maximum rate will be imposed. If a value is given, then it must be between 1 and 2047, inclusive
Lower Bound 1
Upper Bound 2047
Required No
Multi-Valued No

-y
--encrypt

Description Encrypt the backup. If either the --promptForEncryptionPassphrase or --encryptionPassphraseFile argument is provided, then that passphrase will be used to generate the encryption key. If the --encryptionSettingsDefinitionID argument is provided, then the encryption key will be generated from that definition. If no passphrase or encryption settings definition ID was specified, then the server's preferred encryption settings definition will be used, or an internal key shared among servers in the topology will be used if there are no encryption settings definitions. If neither the --encrypt nor the --doNotEncrypt argument is provided, then the determination as to whether to encrypt the data will be made based on the server's encrypt-backups-by-default global configuration property. Encrypted backups can be decrypted with the encrypt-file tool

--promptForEncryptionPassphrase

Description Interactively prompt for a passphrase that can be used to generate the encryption key. This argument can only be used if the --encrypt argument is also provided, and it cannot be used if either the --encryptionPassphraseFile or the --encryptionSettingsDefinitionID argument is provided, nor can it be used when running the backup as a task

--encryptionPassphraseFile {path}

Description The path to a file that contains a passphrase that can be used to generate the encryption key. This argument can only be used if the --encrypt argument is also provided, and it cannot be used if either the --promptForEncryptionPassphrase or the --encryptionSettingsDefinitionID argument is provided. The passphrase file must exist on the server system, regardless of whether the backup is running locally or as a task, and an absolute path is recommended when running as a task
Required No
Multi-Valued No

--encryptionSettingsDefinitionID {path}

Description The identifier for the encryption settings definition that will be used to generate the encryption key. This argument can only be used if the --encrypt argument is also provided, and it cannot be used if either the --promptForEncryptionPassphrase or the --encryptionPassphraseFile argument is provided
Required No
Multi-Valued No

--doNotEncrypt

Description Do not encrypt the backup, even if backups are normally encrypted by default

-A
--hash

Description Generate a hash of the backup contents

-s
--signHash

Description Sign the hash of the backup contents

--retainPreviousFullBackupCount {count}

Description The number of previous full backups contained in the same directory as the new backup that should be retained if the new backup completes successfully. If the backup directory contains more than this number of previous full backups, then the oldest full backups will be removed, along with any associated incremental backups, so that the specified number of the most recent full backups will be retained. A value of zero indicates that all previous backups should be removed and only the new backup should be left in the backup directory. If the backup directory does not yet exist, or if it contains fewer than the specified number of full backups, then no backups will be removed. If both the --retainPreviousFullBackupCount and --retainPreviousFullBackupAge arguments are provided, then only backups that satisfy the conditions for both arguments will be eligible for removal. If neither the --retainPreviousFullBackupCount nor the --retainPreviousFullBackupAge argument is provided, then no previous backups will be removed
Lower Bound 0
Required No
Multi-Valued No

--retainPreviousFullBackupAge {age}

Description The minimum age of full backups in the same directory as the new backup that should be retained if the new backup completes successfully. Values should be specified as an integer followed by a time unit (for example, '8 hours', '3 days', or '1 week"). If any full backups are removed, then all incremental backups associated with those full backups will also be removed. If the backup directory does not yet exist, or if it does not contain any full backups older than the specified age, then no backups will be removed. If both the --retainPreviousFullBackupCount and --retainPreviousFullBackupAge arguments are provided, then only backups that satisfy the conditions for both arguments will be eligible for removal. If neither the --retainPreviousFullBackupCount nor the --retainPreviousFullBackupAge argument is provided, then no previous backups will be removed
Required No
Multi-Valued No

--logFilePath {logFilePath}

Description Echo the console output to the specified log file, instead of the default '/logs/tools/ds-tool.log' file
Required No
Multi-Valued No