Show Table of Contents
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
andNetscapeRoot
, 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:
- Select the Tasks tab.
- Click Back Up Directory Server.
- Enter the full path of the directory to store the backup file in the Directory text box, or click , and the server provides a name for the backup directory.If the Console is running on the same machine as the directory, clickto 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 isldbm 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:
- In the Directory Server Console, select the Tasks tab.
- Click Restore Directory Server.
- 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
- If the Directory Server is running, stop it:
# systemctl stop dirsrv@instance
- Run the
bak2db
command-line script. Thebak2db
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 thebak2db
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 isldbm 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:
- Stop the Directory Server if it is running.
# systemctl stop dirsrv@instance
- Restore the back end from the
/var/lib/dirsrv/slapd-instance/bak
archives with thebak2db
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
- 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 thecn=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:
- 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”. - Online-initialize the remaining servers by using replication:
- Initialize the second master from the first one.
- Initialize the consumers from the master.
For details, see Section 15.18, “Initializing Consumers”. - 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:
- Stop the server.
# systemctl stop dirsrv@instance
- 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. - Restart the server.
# systemctl restart dirsrv@instance