13.8. Backing up and Restoring Certificate System

Certificate System does not include backup and restore tools. However, the Certificate System components can still be archived and restored manually, which can be necessary for deployments where information cannot be accessed if certificate or key information is lost. Three major parts of Certificate System need to be backed up routinely in case of data loss or hardware failure:
  • Internal database. Subsystems use an LDAP database to store their data. The Directory Server provides its own backup scripts and procedures.
  • Security databases. The security databases store the certificate and key material. If these are stored on an HSM, then consult the HSM vendor documentation for information on how to back up the data. If the information is stored in the default directories in the instance alias directory, then it is backed up with the instance directory. To back it up separately, use a utility such as tar or zip.
  • Instance directory. The instance directory contains all configuration files, security databases, and other instance files. This can be backed up using a utility such as tar or zip.

13.8.1. Backing up and Restoring the LDAP Internal Database

The Red Hat Directory Server documentation contains more detailed information on backing up and restoring the databases.

13.8.1.1. Backing up the LDAP Internal Database

Two pairs of tools are available to back up the Directory Server instance; each back-up tool has a counterpart to restore the files it generated:
  • The db2ldif tool creates a LDIF file you can restore using the ldif2db tool.
  • The db2bak command creates a backup file you can restore using the bak2db tool.
13.8.1.1.1. Backing up using db2ldif
Running the db2ldif command backs up a single subsystem database as specified by the -n option.

Note

As the db2ldif command runs with the dirsrv user, it doesn't have permissions to write under the /root/ directory, so you need to provide a path where it can write.
  1. Back up each Directory Server database used by PKI subsystems. You can use the pki-server ca-db-config-show command to check the database name for a given subsystem.
    For example: 
    # db2ldif -V -n pki-tomcat-CA -a /var/lib/dirsrv/slapd-pki1/ldif/pki-ca-backup.ldif
Exported ldif file: /var/lib/dirsrv/slapd-pki1/ldif/pki-ca-backup.ldif
ldiffile: /var/lib/dirsrv/slapd-pki1/ldif/pki-ca-backup.ldif
[05/Nov/2020:10:17:53.835635923 -0500] - INFO - ldbm_instance_config_cachememsize_set - force a minimal value 512000
[05/Nov/2020:10:17:53.845938266 -0500] - INFO - ldbm_instance_config_cachememsize_set - force a minimal value 512000
[05/Nov/2020:10:17:53.851851787 -0500] - INFO - ldbm_instance_config_cachememsize_set - force a minimal value 512000
[05/Nov/2020:10:17:53.874058831 -0500] - INFO - ldbm_back_ldbm2ldif - export pki-tomcat-CA: Processed 67 entries (100%).
[05/Nov/2020:10:17:53.884181122 -0500] - INFO - dblayer_pre_close - All database threads now stopped
  2. In addition to backing up all individual subsytem databases, you can back up the main database by adding userRoot as -n option. For example: 
    # db2ldif -V -n userRoot -a /var/lib/dirsrv/slapd-pki1/ldif/userRoot.ldif
To restore the LDIF file using the ldif2db, see Section 13.8.1.2.1, “Restoring using ldif2db”.
13.8.1.1.2. Backing up using db2bak
Running the db2bak command backs up all Certificate System subsystem databases for that Directory Server (and any other databases maintained by that Directory Server instance).
For example: 
# db2bak

Back up directory: /var/lib/dirsrv/slapd-pki1/bak/pki1-2020_11_05_11_20_21

Note

As the db2bak command runs with the dirsrv user, the target directory must be writeable by dirsrv. Running the command without any argument creates the backup in the /var/lib/dirsrv/slapd-<instance_name>/bak folder where db2bak has the proper write permissions.
To restore the LDIF file using bak2db, see Section 13.8.1.2.2, “Restoring using bak2db”.

13.8.1.2. Restoring the LDAP Internal Database

Depending on how you backed up the Directory Server instance, use ldif2db or bak2db with the corresponding file(s) to restore the database.

Note

Make sure you stop the instance before restoring databases.
13.8.1.2.1. Restoring using ldif2db
If you created a LDIF file with db2ldif, stop the Directory Server instance and import the files using the ldif2db command. You can specify a single database to restore from the backup. For example:
  1. Stop the Directory Server instance: 
    # systemctl stop dirsrv@instance_name
  2. Import the file specified by the -i option for the subsystem specified by the -n option: 
    # ldif2db -V -n pki-tomcat-CA -i /var/lib/dirsrv/slapd-pki1/ldif/pki-ca-backup.ldif
importing data ...
[06/Nov/2020:09:27:07.103094925 -0500] - INFO - ldbm_instance_config_cachememsize_set - force a minimal value 512000
[06/Nov/2020:09:27:07.118712207 -0500] - INFO - ldbm_instance_config_cachememsize_set - force a minimal value 512000
……...
[06/Nov/2020:09:27:09.213947960 -0500] - INFO - import_main_offline - import pki-tomcat-CA: Closing files...
[06/Nov/2020:09:27:09.470742715 -0500] - INFO - dblayer_pre_close - All database threads now stopped
[06/Nov/2020:09:27:09.479321728 -0500] - INFO - import_main_offline - import pki-tomcat-CA: Import complete.  Processed 67 entries in 2 seconds. (33.50 entries/sec)
  3. Start the Directory Server instance: 
    # systemctl start dirsrv@instance_name
13.8.1.2.2. Restoring using bak2db
If you created a backup file with db2bak, stop the Directory Server and import the file using the bak2db command; you can specify a single database to restore from the backup. For example:
  1. Stop the Directory Server instance: 
    # systemctl stop dirsrv@instance_name
  2. Import the file for the subsystem specified by the -n option: 
    # bak2db /var/lib/dirsrv/slapd-pki1/bak/pki1-2020_11_06_09_40_21/ -n pki-tomcat-CA -V
[06/Nov/2020:09:41:02.984808879 -0500] - INFO - ldbm_instance_config_cachememsize_set - force a minimal value 512000
[06/Nov/2020:09:41:02.991860094 -0500] - INFO - ldbm_instance_config_cachememsize_set - force a minimal value 512000
......
[06/Nov/2020:09:41:12.853686475 -0500] - INFO - dblayer_copy_directory - Restoring file 40 (/var/lib/dirsrv/slapd-pki1/db/pki-tomcat-CA/seeAlso.db)
[06/Nov/2020:09:41:12.873881494 -0500] - WARN - dblayer_start - DB already started.
[06/Nov/2020:09:41:12.883966616 -0500] - INFO - dblayer_pre_close - All database threads now stopped
[06/Nov/2020:09:41:12.888381193 -0500] - INFO - dblayer_restore -  Removing staging area /var/lib/dirsrv/slapd-pki1/db/../fribak.
    You can also restore the complete database from the backup using the command without the -n option. For example: 
    # bak2db /var/lib/dirsrv/slapd-pki1/bak/pki1-2020_11_06_09_40_21/ -V
[06/Nov/2020:09:53:01.977785135 -0500] - INFO - ldbm_instance_config_cachememsize_set - force a minimal value 512000
[06/Nov/2020:09:53:01.994426925 -0500] - INFO - ldbm_instance_config_cachememsize_set - force a minimal value 512000
.........
[06/Nov/2020:09:53:02.800340285 -0500] - INFO - dblayer_restore - Restoring file 68 (/var/lib/dirsrv/slapd-pki1/db/DBVERSION)
[06/Nov/2020:09:53:02.814235053 -0500] - INFO - dblayer_copyfile - Copying /var/lib/dirsrv/slapd-pki1/bak/pki1-2020_11_06_09_40_21/DBVERSION to /var/lib/dirsrv/slapd-pki1/db/DBVERSION
[06/Nov/2020:09:53:03.317071092 -0500] - INFO - dblayer_pre_close - All database threads now stopped
  3. Start the Directory Server instance: 
    # systemctl start dirsrv@instance_name

13.8.2. Backing up and Restoring the Instance Directory

The instance directory has all of the configuration information for the subsystem instance, so backing up the instance directory preserves the configuration information not contained in the internal database.

Note

Stop the subsystem instance before backing up the instance or the security databases.
  1. Stop the subsystem instance. 
    systemctl stop pki-tomcatd@instance_name.service
  2. Save the directory to a compressed file: 
    # cd /var/lib/pki/
# tar -chvf /export/archives/pki/instance_name.tar instance_name/
    For example: 
    # cd /var/lib/pki/
# tar -chvf /tmp/test.tar pki-tomcat/ca/
pki-tomcat/ca/
pki-tomcat/ca/registry/
pki-tomcat/ca/registry/ca/
...........
  3. Restart the subsystem instance. 
    systemctl start instance_name
You can use the Certificate System backup files, both the alias database backups and the full instance directory backups, to replace the current directories if the data is corrupted or the hardware is damaged. To restore the data, uncompress the archive file using the unzip or tar tools, and copy the archive over the existing files.
To restore the instance directory:
  1. Uncompress the archive: 
    cd /export/archives/pki/
tar -xvf instance_name.tar
    For example: 
    # cd /tmp/
# tar -xvf test.tar
pki-tomcat/ca/
pki-tomcat/ca/registry/
pki-tomcat/ca/registry/ca/
pki-tomcat/ca/registry/ca/default.cfg
.........
  2. Stop the subsystem instance if it is not already stopped. 
    systemctl stop pki-tomcatd@instance_name.service
  3. Copy the archived files to restore the instance directory: 
    cp -r /export/archives/pki/instance_name /var/lib/pki/instance_name
    For example: 
    # cp -r /tmp/pki-tomcat/ca/ /var/lib/pki/pki-tomcat/ca/
  4. Restart the subsystem instance. 
    systemctl start pki-tomcatd@instance_name.service