4.3. Backing up and Restoring Data

Databases can be backed up and restored using the Directory Server Console or a command-line script.

Warning

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

Note

The changelog database is backed up with the regular server database.

4.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.

4.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_name/bak. By default, the backup directory name contains the name of the server instance and the time and date the backup was created (instance_name-YYYY_MM_DD_hhmmss).

4.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 Perl script. The command-line script works when the server is running or when the server is stopped; the Perl script can only be run 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 4.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. 
[root@server ~]# /usr/lib[64]/dirsrv/slapd-example/db2bak.pl /var/lib/dirsrv/slapd-instance_name/bak/instance_name-2017_04_30_16_27_56
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_name/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 more information about using these scripts, see the Directory Server Configuration and Command-Line Tool Reference.

4.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.2.4, “Adding and Modifying Entries 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.
The Directory Server Configuration and Command-Line Tool Reference has more information on the available attributes for running tasks to back up databases under the cn=tasks entries.

4.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_name 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_name directory before the directory writes the modifications to the dse.ldif file.

4.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 attempting to restore a database.

4.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 attempting to restore a database.
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_name/bak/backup_directory. backup_directory is the directory of the most recent backup, in the form serverID-YYYY_MM_DD_hhmmss.

4.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 attempting to restore a database.
4.3.3.2.1. Using the bak2db Command-Line Script
  1. If the Directory Server is running, stop it: 
    [root@server ~]# service dirsrv stop instance
  2. Run the bak2db command-line script. The bak2db script requires the full path and name of the input file. 
    [root@server ~]# /etc/dirsrv/slapd-instance_name/bak2db /var/lib/dirsrv/slapd-instance_name/bak/instance_name-2017_04_30_11_48_30
    For more information about using this script, see the Directory Server Configuration and Command-Line Tool Reference.
4.3.3.2.2. Using bak2db.pl Perl Script
Run the bak2db.pl Perl script. 
[root@server ~]# /usr/lib[64]/dirsrv/slapd-example/bak2db.pl -D "cn=Directory Manager" -w secret -a /var/lib/dirsrv/slapd-instance_name/bak/instance_name-2017_04_30_11_48_30
For more information on using this Perl script, see the Directory Server Configuration and Command-Line Tool 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 attempting to restore a database.
Option Description
-a Defines the full path and name of the input file.
-D Specifies the DN of the administrative user.
-w Specifies the password of the administrative user.
4.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 attempting to restore a database.
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.2.4, “Adding and Modifying Entries 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.
The Directory Server Configuration and Command-Line Tool Reference has more information on the available attributes for running database restore tasks under the cn=tasks entries.

4.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. 
    service dirsrv stop instance
  2. Restore the back end from the /var/lib/dirsrv/slapd-instance_name/bak archives with the bak2db script, using the -n parameter to specify the database name. For example: 
    bak2db /var/lib/dirsrv/slapd-instance_name/bak/backup_file -n userRoot
  3. Restart the Directory Server. 
    service dirsrv start instance

    Note

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

4.3.5. Restoring Databases That Include Replicated Entries

Several situations can occur when a supplier server is restored:
  • The consumer servers are also restored.
    If all databases are restored from backups taken at 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 Directory Server Configuration and Command-Line Tool 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 11.15, “Initializing Consumers”.
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 11, Managing Replication.

4.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_name 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. 
    service dirsrv stop instance
  2. Restore the database as outlined in Section 4.3.4, “Restoring a Single Database” to copy the backup copy of the dse.ldif file into the directory.
  3. Restart the server. 
    service dirsrv restart instance