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

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

14.8.1.1. Backing up the LDAP Internal Database

Two pairs of subcommands of the dsctl command are available to back up the Directory Server instance. Each back-up subcommand has a counterpart to restore the files it generated:
  • The db2ldif subcommand creates a LDIF file you can restore using the ldif2db subcommand.
  • The db2bak subcommand creates a backup file you can restore using the bak2db subcommand.
14.8.1.1.1. Backing up using db2ldif
Running the db2ldif subcommand backs up a single subsystem database.

Note

As the db2ldif subcommand 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.
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, to back up the main database, userRoot:
  1. Stop the instance:
    # dsctl instance_name stop
  2. Export the database into an LDIF file:
    # dsctl instance_name db2ldif userroot /tmp/example.ldif
    OK group dirsrv exists
    OK user dirsrv exists
    ldiffile: /tmp/example.ldif
    [18/Jul/2018:10:46:03.353656777 +0200] - INFO - ldbm_instance_config_cachememsize_set - force a minimal value 512000
    [18/Jul/2018:10:46:03.383101305 +0200] - INFO - ldbm_back_ldbm2ldif - export userroot: Processed 160 entries (100%).
    [18/Jul/2018:10:46:03.391553963 +0200] - INFO - dblayer_pre_close - All database threads now stopped
    db2ldif successful
  3. Start the instance:
    # dsctl instance_name start
To restore the LDIF file using the ldif2db subcommand, see Section 14.8.1.2.1, “Restoring using ldif2db”.
14.8.1.1.2. Backing up using db2bak
Running the db2bak subcommand backs up all Certificate System subsystem databases for that Directory Server (and any other databases maintained by that Directory Server instance). For example:
For example:
  1. Stop the instance:
    # dsctl instance_name stop
  2. Backup the database:
    # dsctl instance_name db2bak
    OK group dirsrv exists
    OK user dirsrv exists
    [18/Jul/2018:14:02:37.358958713 +0200] - INFO - ldbm_instance_config_cachememsize_set - force a minimal value 512000
    ...
    db2bak successful
  3. Start the instance:
    # dsctl instance_name start

Note

As the db2bak subcommand runs with the dirsrv user, the target directory must be writeable by dirsrv. Running the subcommand 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 14.8.1.2.2, “Restoring using bak2db”.

14.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.
14.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 subcommand. You can specify a single database to restore from the backup. For example, for the main database, userRoot:
  1. Stop the Directory Server instance:
    # dsctl instance_name stop
  2. Import the data from the LDIF file:
    # dsctl instance_name ldif2db userroot /tmp/example.ldif
    OK group dirsrv exists
    OK user dirsrv exists
    [17/Jul/2018:13:42:42.015554231 +0200] - INFO - ldbm_instance_config_cachememsize_set - force a minimal value 512000
    ...
    [17/Jul/2018:13:42:44.302630629 +0200] - INFO - import_main_offline - import userroot: Import complete.  Processed 160 entries in 2 seconds. (80.00 entries/sec)
    ldif2db successful
  3. Start the Directory Server instance:
    # dsctl instance_name start
14.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 subcommand. For example:
  1. Stop the Directory Server instance:
    # dsctl instance_name stop
  2. Restore the databases:
    # dsctl instance_name bak2db /var/lib/dirsrv/slapd-instance_name/bak/instance_name-time_stamp/
    OK group dirsrv exists
    OK user dirsrv exists
    [20/Jul/2018:15:52:24.932598675 +0200] - INFO - ldbm_instance_config_cachememsize_set - force a minimal value 512000
    ...
    bak2db successful
  3. Start the Directory Server instance:
    # dsctl instance_name start

14.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.
    pki-server stop instance_name
  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.
    pki-server 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.
    pki-server stop instance_name
  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. Make sure the ownership and group permissions of the restored files are set to the pkiuser:
    # chown -R pkiuser:pkiuser /var/lib/pki/pki-tomcat/ca/
  5. Restart the subsystem instance.
    pki-server start instance_name