6.3. Backing up and Restoring Data

Databases can be backed up and restored using the Directory Server Console or a command-line script. A backup contains, for example:
  • All database files, such as for userRoot and NetscapeRoot, including the data stored within these databases
  • The transaction logs
  • The Indices
In contrast to a backup, you can export data as described in Section 6.2, “Exporting Data”. Use the export feature to export specific data, such as a subtree, from a server in the LDAP Data Interchange Format (LDIF) format.
This section describes the following procedures:

Warning

Do not stop the server during a backup or restore operation.

6.3.1. Backing up All Databases

The following procedures describe backing up all of the databases in the directory using the Directory Server Console and from the command line.

Note

These backup methods cannot be used to back up the data contained by databases on a remote server that are chained using database links.

6.3.1.1. Backing up All Databases from the Console

When backing up databases from the Directory Server Console, the server copies all of the database contents and associated index files to a backup location. A backup can be performed while the server is running.
To back up databases from the Directory Server Console:
  1. Select the Tasks tab.
  2. Click Back Up Directory Server.
  3. Enter the full path of the directory to store the backup file in the Directory text box, or click Use default, and the server provides a name for the backup directory.
    If the Console is running on the same machine as the directory, click Browse to select a local directory.
    With the default location, the backup files are placed in /var/lib/dirsrv/slapd-instance/bak. By default, the backup directory name contains the name of the server instance and the time and date the backup was created (instance-YYYY_MM_DD_hhmmss).

6.3.1.2. Backing up All Databases from the Command Line

Databases can be backed up from the command line using either the db2bak command-line script or the db2bak.pl Perl script. The command-line script works when the server is running or when the server is stopped; the Perl script can only be used when the server is running.

Important

If the database being backed up is a master database, meaning it keeps a changelog, then it must be backed up using the db2bak.pl Perl script or using the Directory Server Console if the server is kept running. The changelog only writes its RUV entries to the database when the server is shut down; while the server is running, the changelog keeps its changes in memory. For the Perl script and the Console, these changelog RUVs are written to the database before the backup process runs. However, that step is not performed by the command-line script.
The db2bak should not be run on a running master server. Either use the Perl script or stop the server before performing the backup.
Configuration information cannot be backed up using this backup method. For information on backing up the configuration information, see Section 6.3.2, “Backing up the dse.ldif Configuration File”.
To back up the directory from the command line using the db2bak.pl script, run the db2bak.pl Perl script, specifying the backup filename and directory. 
# db2bak.pl -Z instance_name -D "cn=Directory Manager" -w password -a /var/lib/dirsrv/slapd-example/bak/instance-2020_04_30_16_27_5-custom-name

Note

Do not use a trailing slash character ("/") when using the -a option to specify the default backup directory that is configured using the nsslapd-bakdir directive. For example: 
# db2bak.pl -Z instance_name -D "cn=Directory Manager" -w password -a /var/lib/dirsrv/slapd-example/bak
Note the lack of slash after slapd-example/bak.
This limitation only applies when specifying exactly the same directory which is configured in nsslapd-bakdir. Any other directory, even inside the default backup directory (for example, bak/custom-name/) can be specified with or without a trailing slash.
The backup directory where the server saves the backed up databases can be specified with the script. If a directory is not specified, the backup file is stored in /var/lib/dirsrv/slapd-instance/bak. By default, the backup directory is named with the Directory Server instance name and the date of the backup (serverID-YYYY_MM_DD_hhmmss).
For information about ldif2db, see the script's description in the Red Hat Directory Server Configuration, Command, and File Reference.

6.3.1.3. Backing up the Database through the cn=tasks Entry

The cn=tasks,cn=config entry in the Directory Server configuration is a container entry for temporary entries that the server uses to manage tasks. Several common directory tasks have container entries under cn=tasks,cn=config. Temporary task entries can be created under cn=backup,cn=tasks,cn=config to initiate a backup operation.
The backup task entry requires three attributes:
  • A unique name (cn).
  • The directory to write the backup file to (nsArchiveDir). The backup file is named with the Directory Server instance name and the date of the backup (serverID-YYYY_MM_DD_hhmmss).
  • The type of database (nsDatabaseType); the only option is ldbm database.
The entry is simply added using ldapmodify, as described in Section 3.1.3.2, “Adding an Entry Using ldapmodify”. For example: 
# ldapmodify -a -D "cn=Directory Manager" -W -p 389 -h server.example.com -x

dn: cn=example backup,cn=backup,cn=tasks,cn=config
changetype: add
objectclass: extensibleObject
cn: example backup
nsArchiveDir: /export/backups/
nsDatabaseType: ldbm database
As soon as the task is completed, the entry is removed from the directory configuration.
For details about the attributes used in the example and other attributes you can set in this entry, see the cn=backup,cn=tasks,cn=config entry description in the Red Hat Directory Server Configuration, Command, and File Reference

6.3.2. Backing up the dse.ldif Configuration File

Directory Server automatically backs up the dse.ldif configuration file. When the Directory Server is started, the directory creates a backup of the dse.ldif file automatically in a file named dse.ldif.startOK in the /etc/dirsrv/slapd-instance directory.
When the dse.ldif file is modified, the file is first backed up to a file called dse.ldif.bak in the /etc/dirsrv/slapd-instance directory before the directory writes the modifications to the dse.ldif file.

6.3.3. Restoring All Databases

The following procedures describe restoring all of the databases in the directory using the Directory Server Console and from the command line.

Note

Restoring a database from backup also restores the changelog.

Important

While restoring databases, the server must be running. However, the databases will be unavailable for processing operations during the restore.
Therefore, stop all replication processes before restoring a database. For details, see Section 15.9, “Disabling and Re-enabling a Replication Agreement”.

6.3.3.1. Restoring All Databases from the Console

If the databases become corrupted, restore data from a previously generated backup using the Directory Server Console. This process consists of stopping the server and then copying the databases and associated index files from the backup location to the database directory.

Warning

Restoring databases overwrites any existing database files.

Important

While restoring databases, the server must be running. However, the databases will be unavailable for processing operations during the restore.
Therefore, stop all replication processes before restoring a database. For details, see Section 15.9, “Disabling and Re-enabling a Replication Agreement”.
To restore databases from a previously created backup:
  1. In the Directory Server Console, select the Tasks tab.
  2. Click Restore Directory Server.
  3. Select the backup from the Available Backups list, or enter the full path to a valid backup in the Directory text box.
    The Available Backups list shows all backups located in the default directory, /var/lib/dirsrv/slapd-instance/bak/backup_directory. backup_directory is the directory of the most recent backup, in the form serverID-YYYY_MM_DD_hhmmss.

6.3.3.2. Restoring Databases from the Command Line

There are three ways to restore databases from the command line:
  • Using the bak2db command-line script. This script requires the server to be shut down.
  • Using the bak2db.pl Perl script. This script works while the server is running.
  • Creating a temporary entry under cn=restore,cn=tasks,cn=config. This method can also be run while the server is running.

Important

While restoring databases, the server must be running (with the exception of running the bak2db command-line script). However, the databases will be unavailable for processing operations during the restore.
Therefore, stop all replication processes before restoring a database. For details, see Section 15.9, “Disabling and Re-enabling a Replication Agreement”.
6.3.3.2.1. Using the bak2db Command-Line Script
  1. If the Directory Server is running, stop it: 
    # systemctl stop dirsrv@instance
  2. Run the bak2db command-line script. The bak2db script requires the full path and name of the input file. 
    # bak2db -Z instance_name /var/lib/dirsrv/slapd-instance/bak/instance-2020_04_30_11_48_30
    For information about the parameters used in the example, see the description of the bak2db script in the Red Hat Directory Server Configuration, Command, and File Reference.
6.3.3.2.2. Using bak2db.pl Perl Script
Run the bak2db.pl Perl script. 
# bak2db.pl -Z instance_name -D "cn=Directory Manager" -w secret -a /var/lib/dirsrv/slapd-instance/bak/instance-2020_04_30_11_48_30
For information about the parameters used in the example, see the description of the bak2db.pl script in the Red Hat Directory Server Configuration, Command, and File Reference.

Important

While restoring databases, the server must be running. However, the databases will be unavailable for processing operations during the restore.
Therefore, stop all replication processes before restoring a database. For details, see Section 15.9, “Disabling and Re-enabling a Replication Agreement”.
6.3.3.2.3. Restoring the Database through the cn=tasks Entry
The cn=tasks,cn=config entry in the Directory Server configuration is a container entry for temporary entries that the server uses to manage tasks. Several common directory tasks have container entries under cn=tasks,cn=config. Temporary task entries can be created under cn=restore,cn=tasks,cn=config to initiate a restore operation.

Important

While restoring databases, the server must be running. However, the databases will be unavailable for processing operations during the restore.
Therefore, stop all replication processes before restoring a database. For details, see Section 15.9, “Disabling and Re-enabling a Replication Agreement”.
The restore task entry requires three attributes, the same as the backup task:
  • A unique name (cn).
  • The directory from which to retrieve the backup file (nsArchiveDir).
  • The type of database (nsDatabaseType); the only option is ldbm database.
The entry is simply added using ldapmodify, as described in Section 3.1.3.2, “Adding an Entry Using ldapmodify”. For example: 
# ldapmodify -a -D "cn=Directory Manager" -W -p 389 -h server.example.com -x

dn: cn=example restore,cn=restore,cn=tasks,cn=config
changetype: add
objectclass: extensibleObject
cn: example restore
nsArchiveDir: /export/backups/
nsDatabaseType: ldbm database
As soon as the task is completed, the entry is removed from the directory configuration.
For details about the attributes used in the example and other attributes you can set in this entry, see the cn=restore,cn=tasks,cn=config entry description in the Red Hat Directory Server Configuration, Command, and File Reference

6.3.4. Restoring a Single Database

It is possible to restore a single database through the command line, but not in the Directory Server Console. To restore a single database:
  1. Stop the Directory Server if it is running. 
    # systemctl stop dirsrv@instance
  2. Restore the back end from the /var/lib/dirsrv/slapd-instance/bak archives with the bak2db script, using the -n parameter to specify the database name. For example: 
    # bak2db -Z instance_name /var/lib/dirsrv/slapd-instance/bak/backup_file -n userRoot
  3. Restart the Directory Server. 
    # systemctl start dirsrv@instance

    Note

    If the Directory Server fails to start, remove the database transaction log files in /var/lib/dirsrv/slapd-instance/db/log.###, then retry starting the server.

6.3.5. Restoring Databases That Include Replicated Entries

Several situations can occur when a supplier server is restored:
  • The consumer servers are also restored.
    For the very unlikely situation, that all databases are restored from backups taken at exactly the same time (so that the data are in sync), the consumers remain synchronized with the supplier, and it is not necessary to do anything else. Replication resumes without interruption.
  • Only the supplier is restored.
    If only the supplier is restored or if the consumers are restored from backups taken at a different times, reinitialize the consumers for the supplier to update the data in the database. If only the supplier is restored or if the consumers are restored from backups taken at a different times, reinitialize the consumers for the supplier to update the data in the database.
  • Changelog entries have not yet expired on the supplier server.
    If the supplier's changelog has not expired since the database backup was taken, then restore the local consumer and continue with normal operations. This situation occurs only if the backup was taken within a period of time that is shorter than the value set for the maximum changelog age attribute, nsslapd-changelogmaxage, in the cn=changelog5,cn=config entry. For more information about this option, see the Red Hat Directory Server Configuration, Command, and File Reference.
    Directory Server automatically detects the compatibility between the replica and its changelog. If a mismatch is detected, the server removes the old changelog file and creates a new, empty one.
  • Changelog entries have expired on the supplier server since the time of the local backup.
    If changelog entries have expired, reinitialize the consumer. For more information on reinitializing consumers, see Section 15.18, “Initializing Consumers”.

Example 6.1. Restoring a Directory Server Replication Topology

For example, to restore all servers in a replication environment, consisting of two masters and two consumer server:
  1. Restore the first master. Use the ldif2db utility without the -r option to import the data. See Section 6.1.4, “Importing from the Command Line”.
  2. Online-initialize the remaining servers by using replication:
    1. Initialize the second master from the first one.
    2. Initialize the consumers from the master.
    For details, see Section 15.18, “Initializing Consumers”.
  3. On each server, display the nsds5replicaLastUpdateStatus attribute to verify that replication works correctly: 
    # ldapsearch -D "cn=Directory Manager" -W -p 389 -h server.example.com -b "cn=example_agreement,cn=replica,cn=dc\=example\,dc\=com,cn=mapping tree,cn=config" nsds5replicaLastUpdateStatus
    For details about possible statuses, see the Replication Agreement Status appendix in the Red Hat Directory Server Configuration, Command, and File Reference.
The changelog associated with the restored database will be erased during the restore operation. A message will be logged to the supplier servers' log files indicating that reinitialization is required.
For information on managing replication, see Chapter 15, Managing Replication.

6.3.6. Restoring the dse.ldif Configuration File

The directory creates two backup copies of the dse.ldif file in the /etc/dirsrv/slapd-instance directory. The dse.ldif.startOK file records a copy of the dse.ldif file at server start up. The dse.ldif.bak file contains a backup of the most recent changes to the dse.ldif file. Use the version with the most recent changes to restore the directory.
To restore the dse.ldif configuration file:
  1. Stop the server. 
    # systemctl stop dirsrv@instance
  2. Restore the database as outlined in Section 6.3.4, “Restoring a Single Database” to copy the backup copy of the dse.ldif file into the directory.
  3. Restart the server. 
    # systemctl restart dirsrv@instance