dirxbackup

Synopsis

Purpose

Saves and restores a database or verifies an archive.

Arguments

archive_name

Specifies the name of the archive file that the database is written to or read from; for example, Archive_0602 or D:\Archives\Archive1. If you do not specify an archive_name as an argument, dirxbackup writes the database to standard output or reads a database from standard input. This function enables you to run dirxbackup in conjunction with another tool or with a second dirxbackup call.

Options

-S

Saves the active database into an archive or to standard output if an archive name is not specified. After the database is saved, it runs a full database verification on the generated full backup unless the -n option is specified.

-R

Restores into the active database from an archive or from standard input if an archive name is not specified.

-I

(Upper case i.) Provides the following information about the archive:
- Full Backup time stamp—Time of the full backup of the database.
- Archive version—Version describing the format of the archive.
- Backup file type—Whether the archive contains a full backup or a delta backup.
- Delta backup version—Consecutive number for delta backups. This number starts with the value 0 and is incremented with every delta backup.
- Max. indexed attributes types—Maximum number of attributes that can be indexed.
- Number of AVIDX cluster—Number of attribute index clusters.
- AVIDX cluster size—Size of one attribute index cluster.
- Real object block size—Size of one real object block.
- Verified at—Timestamp of the last verification run on the backup.
- Verified with version—Version of the tool that last verified the backup.
- Verified components—Components that were verified in the last verification.
- Number of errors—Number of errors found during the last verification.
- Number of warnings—Number of warnings found during the last verification.
The archive information is read from standard input if no archive name is specified.

-L

Directs dirxbackup to create an LDIF content file from an archive or a list of archives, including one full and one or more delta backups. If one full and multiple delta backups are specified, the full backup must be the first one in the list and the delta backups should follow in the order of their creation. The delta backups must belong to the full backup specified as the first element of the list.

-a additional_indexed_attributes

Specifies the number of additional attribute types for which indexes can be created when post-indexing is performed on the database. The minimum is 1 and the maximum is 800. This option is valid for the -R option.

-c

Specifies the cache size in MB. The default cache size is 512 MB. This option is valid for the
-S and -R options.

-d

Specifies that a delta backup should be performed. This option is valid for the -S option.

-e

Enables expert mode. This mode is intended for support. This option is valid for the -S and -R options.

-f

Prevents dirxbackup from recording changes to the database made during a full backup save operation and appending them to the resulting archive. This option is valid for the -S option.

-i

Displays archive profile information. This option is valid for the -I option. It is not supported for delta backups.

-n

Controls automatic backup verification. This option is valid for the -S and -R options. When used with the -S option, it disables automatic verification for specific components of the created backup or for the entire backup. To disable verification for a specific component, specify the component identifier as an argument to the option on the command line. Possible component identifiers are A, X, D, S, and T and correspond to the consistency checking options to the dbamverify command. See the dbamverify command for details. If no components are specified, complete checking is disabled.

When used with the -R option, it loads a backup with unverified components. Only the A and X components can be selected. All other verifications are mandatory to be able to restore the backup.

-o

Specifies the path of the generated LDIF file when the -L option is used. This option is valid for the -L option. As the LDIF splitting feature is enabled by default, the specified path is used as a base path and the file name is extended with a suffix that contains the sequence number of the generated LDIF file(s).

-s

Specifies the subtree to be dumped from an archive to LDIF format when the -L option is used. This option is valid for the -L option. Specify the subtree as an LDAP distinguished name. If the -s option is not specified, the entire DIT is dumped, starting from root (/).

-u

Enables loading a backup that was verified but which contains warnings.

-U

Directs dirxbackup to uncompress the archive while performing a restore, information, LDIF dump, or verification operation. This option is valid for the -R and -L options. When specifying the -U option, the archive_name is required.

-v

Displays information about the progress of a save, restore, or verify operation.

-Z

Directs dirxbackup to compress the archive while performing the save operation. This option is valid for the -S option. When specifying the -Z option the archive_name is required.

-h

Prints a command usage message.

**-V__

Displays the DirX Directory product version, in the format:

product_version build_id date time

For example:

DirX Directory V9.0 9.4.428 2023:03:23 20:10 64-Bit

Description

The dirxbackup command saves or restores a database or verifies the consistency of a database archive. Do not use a non-DirX backup tool to save DBAM database files or devices. It can produce inconsistencies in the database and / or in the dirxbackup archive file.

Use the -S and -R options to save and restore a database. If you do not specify an archive name as an argument to these options, dirxbackup writes the database to standard output or reads a database from standard input.

You can use this function to run the command in conjunction with a file compress/uncompress tool such as gzip. For example, you can use the dirxbackup command in a “pipe” with a compress tool to take database backup and then compress it for storage. Keep in mind that not all compress tools support files larger than 2 GB. Note that the limitations of compress tools may be different for different operating systems.

Use the -S and -Z options to direct dirxbackup to compress the saved database with the gzip tool under the specified archive_name. If the archive_name does not end with the suffix .gz, the save operation appends this suffix automatically.

Use the -R and -U options to direct dirxbackup to uncompress an archive containing the database. The archive_name must be specified. If the specified archive_name ends with the suffix .gz, you can omit the -U option. dirxbackup tries to uncompress the archive automatically.

Use the -R and -n options to direct dirxbackup to restore unverified attribute value index blocks (A) or bit strings (X). Note that restoring an archive with disabled verification components is faster but is not recommended. If a partially-verified archive is restored, it is recommended to perform the omitted verification on the restored archive with the dbamverify command after restoration is complete. Performing the verification on the restored archive, and not the active database, has the following benefits:

The active database is locked for update operations while verification is performed on the database files. This is not the case with file-based verification.
If the archive itself is verified, the unverified components are also verified in the backup. As a result, the same backup can be re-used on a subsequent restore — for example, on another shadow server — without having to perform the verification again.
Each verification is performed on the same snapshot, so you know that the restored snapshot has been completely verified and is correct.

Use the -S and -d options to save only the updates performed after the last recent backup.

Use the -S and -n options to suppress automatic backup verification for specific components or the entire backup.

By default, dirxbackup records changes made to the database during a full backup save operation and appends them to the resulting archive. During this process, it may switch the DSA to read-only mode if a high number of modifications occur. Use the -f option with the -S option to disable this default behavior. The resulting archive will then contain the database state at the start of the save operation instead of the end of the operation.

It is strongly recommended to stop the DirX Directory service before restoring a database. While restoring a database, the DSA rejects all update operations. It is not possible to start the DBAM tools dbamverify and dbamdevinfo.

A database can only be restored on the same platform where the save command has been performed.

A database can only be restored if all components of all the backups, including the full and all delta backups, have been verified with a tool with the same or later major and minor version as dirxbackup. Full backup verification is automatically performed when a full backup is saved using the -S option. Use the -n option to preserve the original saving behavior. As delta backups contain only partial information about the database, they cannot be verified automatically. So, when delta backups are used, they must be verified by dbamverify together with the full backup before they are loaded.

When restoring a database, the configuration must fit the configuration of the saved database. Perform a dirxbackup -I -i archive_name_of_the_saved_database operation to display the profile information of the saved database. The values of the profile to which the database is restored must be equal to or greater than the values of the saved database profile.

Perform a dbamconfig -s -l -P*profile_name operation to display the profile info of the profile to which the database should be restored. (See the *dbamconfig command for details on how to create a database profile and the dbamboot command for details on how to initialize a database.)

When restoring the database into an enlarged configuration, use the -a option to specify how many additional attribute type indexes may be created. If the size of the attribute value index (AVIDX) blocks configured by dbamconfig is not big enough to save all possible attribute type index data, dirxbackup reduces the specified number of attribute type indexes and displays a message. See also the dbamboot command.

When restoring a database, you must restore the initial complete backup and all subsequent delta backups in the correct order. If the sequence of the archives is incorrect, the restore operation fails and an error message is displayed.

If you overwrite DirX Directory working directories, for example, by restoring a hard-disk backup, the DirX Directory service is not able to run. Thus, it is strongly recommended to use only dirxbackup to restore DirX Directory data.

Use the -I (capital i) option to display useful information about the archive. This information can help you, for example, to determine whether you should enlarge the profile in which you want to restore the database.

Use the -L option to generate an LDIF content file from an archive instead of from the active database. Make sure that the archive to be used for generating an LDIF content file has been verified by the dbamverify tool. Only error-free archives should be used. If dirxbackup finds any problem in the archive, it aborts the generation of the LDIF file.

If there are shadowing agreements, you must perform the steps described in sections titled Building the Shadow Configuration and Using DISP to Perform a Total Update of chapter Creating a Shadow DSA in the DirX Directory Administration Guide.

Examples

The following sample command saves the content of the active database into an archive ArchiveDB1.
```
dirxbackup -S ArchiveDB1
```
In the following sample, the administrator performs an initial complete backup into an archive ArchiveDB1. Then he performs two subsequent delta backups into the archives ArchiveDB1_Delta1 and ArchiveDB1_Delta2.
```
dirxbackup -S ArchiveDB1
dirxbackup -S -d ArchiveDB1_Delta1
dirxbackup -S -d ArchiveDB1_Delta2
```
In the following sample commands, the administrator restores the initial complete backup ArchiveDB1 followed by the two delta backups ArchiveDB1_Delta1 and ArchiveDB1_Delta2.
```
dirxbackup -R ArchiveDB1
dirxbackup -R -d ArchiveDB1_Delta1
dirxbackup -R -d ArchiveDB1_Delta2
```
The following sample command saves the content of the active database to standard output, pipes it to gzip, and redirects the gzip output to an archive ArchiveDB2.gz.
```
dirxbackup -S | gzip > ArchiveDB2.gz
```
Instead of using the command "in a pipe" with the gzip tool you can perform the following command:
```
dirxbackup -S -Z ArchiveDB2.gz
```
In the following command, the administrator restores a compressed archive:
```
dirxbackup -R -U ArchiveDB2.gz
```
You can omit the -U switch because the archive name ArchiveDB.gz ends with the suffix .gz.

In the following command, the administrator displays the archive information to find out whether he must enlarge the profile to which he wants to restore the database:

dirxbackup -I ArchiveDB2.gz

The output of the sample command is as follows:

Full backup time stamp       : Fri Feb 27 10:34:37 2009
Archive version              : 3
Backup file type             : Full backup
Max. indexed attribute types : 400
Number of AVIDX cluster      : 2559
AVIDX cluster size           : 32 MB
REAL object block size       : 1 KB
Verified at                  : Thu 04/13/23 08:53:34
Verified with version        : 9.6.349
Verified components          : AXDST
Number of errors             : 0
Number of warnings           : 0

The following sample command generates an LDIF content file of the archive ArchiveDB1:
```
dirxbackup -L -o ArchiveDB1.ldif ArchiveDB1
```
The following sample command generates an LDIF content file of the archive ArchiveDB1 starting from the subtree /O=My-Company:
```
dirxbackup -L -s /O=My-Company -o ArchiveDB1.ldif ArchiveDB1
```
The following sample command saves the content of the active database into an archive ArchiveDB1 without attribute index verification:
```
dirxbackup -n AX -S ArchiveDB1
```
In the following sample command, the administrator restores the complete backup ArchiveDB1 without requiring attribute index (AVIDX) component verification and then performs the verification with dbamverify on the archive. Restoring a backup without the component verification step makes the operation faster, but verification should be performed on the unverified component after the restore operation is finished:
```
dirxbackup -n AX -R ArchiveDB1
dbamverify -AX ArchiveDB1
```

Exit Codes

The dirxbackup command returns an exit code of 0 on success or a 1 if it encountered an error. The text of the error message is displayed on stderr.