Command Line Tools Guide
Red Hat Certificate System                                                            
Previous
 Contents
 Index
 Next

Chapter 7

Backing Up and Restoring Data

This chapter explains how to back up the Red Hat Certificate System (CS) data and configuration information and how to use the backups to restore data if there is a need.

The chapter has the following sections:

Backup and Restore Tools

Certificate System provides tools to backup and restore the data and configuration for a CS instance. These tools can be used, for example, to back up just your CS data before you upgrade hardware or software on a machine. You might also use these tools as part of your overall system backup plan, perhaps to provide more frequent checkpoints of the CS data than a nightly disk backup would record.

Since only CS configuration and data are backed up, you will need to take other measures to back up data for external PKCS#11 cryptographic or key storage devices (such as smart card readers). If you rely on an external device for key storage (for example, to store the CA signing key), make sure that its data is backed up whenever you back up CS data. When you restore the CS data, it will rely on the external keys still being available. Refer to the PKCS#11 module vendor's instructions for how to back up the data.

The backup and restore tools are simple Perl scripts; most Perl programmers should find no difficulty in customizing or extending them. Read this chapter to familiarize yourself with how the scripts work as well as their capabilities and limitations.

The Perl scripts that perform the backup or restore are called from shell scripts installed in the <server_root>/cert-<instance_id>/ directory of every CS instance:

Be aware that the backup archives contain sensitive information (for example, your CS key database). Protect the backup archives as carefully as you protect the server itself. The backups are stored on a local disk by default. To avoid losing both the current data and the backup because of a disk failure, move the backup archives to another medium as soon as they are created. If possible, encrypt the archives or store them on removable media in a secured location.

CS backup data files can be optionally signed (and verified) from the command-line utilizing a separate tool called <server_root>/bin/cert/tools/CSutil. For an example of signing backup data utilizing this tool, see "Signing Backup Data Using CSutil," on page 383. For an example of verifying signed backup data utilizing this tool, see "Verifying Signed Backup Data using CSutil," on page 384.

Optionally, CS backup data files can be manually encrypted using some operating system specific utility; encrypted files must be manually decrypted using the same operating system specific utility prior to attempting data recovery

Backing Up Data

Backing up your data is actually a very simple process. You run the script, and it creates an archive that you store securely. This section explains what the backup tool (CSbackup) does and does not do so that you can plan your overall system maintenance and backup procedures.

What the Backup Tool Does

There is a script or batch file installed in the instance directory of every CS instance. This file calls the Perl script <server_root>/bin/cert/tools/CSBackup.pl (using a Perl 5.005 interpreter bundled with Certificate System). CSBackup.pl does the following:

The log file is in <server_root>/cert-<instance_id>/logs/CSbackup.log. You should review the log file after each backup to make sure that all phases of the backup completed successfully. If all or part of the backup fails it is usually due to a directory that is missing or not readable by the user running the backup.

The default temporary backup directory is /var/tmp (Unix) or C:\Temp (Windows NT). Ensure that access to this directory is restricted so that no one can intercept backup files while the archive is being built. You can change the working backup directory by changing the value of $backup_path_prefix in CSBackup.pl.

The CS database, non-CS databases and shared files that are backed up are:

The Administration Server files that are backed up are the following files from <server_root>/admin-serv/config/:

The backup tool will use the Red Hat Directory Server db2bak tool to create a backup of the CS server instance internal database directory and the configuration directory (if it is running locally). Check the Red Hat Directory Server documentation for full details on what this tool does. The data backed up includes all schema and object class definitions and, of course, all entries in the directory.

These CS global and local class files are Java classes for custom plug-ins used by CS servers. To back up this data, all files and subdirectories in the following directories are backed up:

The following CS global configuration files, which are used for access control and the certificate mapping, are also backed up:

The CS user interface files and templates are the files used to create the forms end entities and agents use to interact with CS servers. All of these files for the instance you are backing up are in

The CS configuration files that get backed up are in <server_root>/cert-<instance_id>/config. The specific files and their purposes are:

All of the data to be backed up is copied to the temporary backup directory. After all of the data has been copied, the script archives the entire backup directory into a compressed archive using zip (a copy of zip is installed in <server_root>/bin/cert/tools/zip). The script deletes the backup directory once the zip archive is created.

What the Backup Tool Does Not Do

The CSbackup script backs up only configuration and data related to a single CS server instance. You may need to back up other files to recover from a failure completely, depending on the nature of the failure. For example, if some entries in your configuration Directory Server become corrupted then the data backed up by CSbackup is sufficient to restore the directory to a previous state. If, however, you suffer a catastrophic disk failure, you will probably have to reinstall or restore Certificate System, Red Hat Console, and Red Hat Directory Server binaries and related tools before you use CSrestore to recover your previous configuration.

The following is a list of items which may be part of your overall CS deployment, but which are not backed up by CSbackup:

Each instance has a copy of the CSbackup script that backs up only data related to that instance.
If you use an external PKCS#11 device for key storage, make sure you follow the vendor's instructions for backing up its data whenever you back up your CS server. It may be possible to extend the CSBackup.pl and CSRestore.pl Perl scripts to include this data in the archives used by the CS backup tools.
These files do not change after installation, and are not backed up. To restore these files, you can install the software again from the original media. You can also use a more generic disk backup tool to archive the contents of all directories beneath the server root.

Running the Backup Tool

Before you run CSbackup, make sure that

The configuration that you back up, of course, will use all of your current passwords. You will need to remember the current passwords if you restore this data after you change some passwords.

To run CSbackup:

  1. Log in to the machine where your CS instance is running and open a command shell.
  2. Change to the CS server instance directory in the server root. For example, if your server root is /opt/redhat-cs and the instance ID of the server you want to back up is CSinstance:
# cd /opt/redhat-cs/cert-CSinstance
  1. Execute the backup script: either CSbackup on UNIX or CSbackup.bat on Windows NT systems. For example,
# ./CSbackup

The script will run. Control returns to the command prompt when the script has finished.

After You Finish a Backup

Immediately after running the backup tool, you should check the log file to make sure that all systems were archived successfully. The log file is

<server_root>/cert-<instance>/logs/CSbackup.log

If the any part of the backup was not successful, there will be a message labeled WARNING or ERROR that tells you why. Most of the time, the problems are the result of directories or files that are missing or inaccessible to the user running CSbackup. If necessary, change the permissions on the required files, delete the zip archive in the output directory, and run CSbackup again.

Once you have a successful zip archive, you should secure it. The output directory is probably accessible to any user on the system, and it may be on the same physical disk as the server instance itself. You want to make sure the archive is not accessible to unauthorized users and that you can use the archive if there is a system hardware failure. Remember, the archive contains a database of private keys. Although it is not easy to extract a key from the database without the correct passwords, you do not want anyone to have the opportunity to try.

Move the zip archive to another machine or removable medium. If possible, encrypt the archive (do not use the private keys stored in your CS server's database, since they may not be available when you need to restore the data). If you copy the archive to removable media such as tape or CD, make sure the copy is kept in a limited-access, locked area.

CS backup data files can be optionally signed (and verified) from the command-line utilizing a separate tool called <server_root>/bin/cert/tools/CSutil. For an example of signing backup data utilizing this tool, see "Signing Backup Data Using CSutil," on page 383. For an example of verifying signed backup data utilizing this tool, see "Verifying Signed Backup Data using CSutil," on page 384.

Optionally, CS backup data files can be manually encrypted using some operating system specific utility; encrypted files must be manually decrypted using the same operating system specific utility prior to attempting data recovery

Signing Backup Data Using CSutil

The following provides an example of using the tool called <server_root>/bin/cert/tools/CSutil to sign backup data for a specific CS subsystem instance on a UNIX system:

  1. Generating an EMAIL Signing User Certificate:
    • Using the browser, issue a request for a user certificate.
    • Using the browser, approve the request for this user certificate.
    • Import this user certificate into the browser.
    • Export this user certificate out of the browser into a Public Key Cryptography Standard (PKCS) #12 file.
    • Move this file to the <server_root>/alias directory.
  2. Sign the Backup Data
    • Invoke a command-line interface such as a telnet session.
    • From the command line, assuming a Bourne Shell ("sh") on a Solaris system, set and export the LD_LIBRARY_PATH environment variable:
LD_LIBRARY_PATH=<server_root>/bin/cert/lib:$LD_LIBRARY_PATH
export LD_LIBRARY_PATH
PATH=<server_root>/bin/cert/tools:$PATH
export PATH
cd <server_root>/alias
ln -s <server_root>/alias/cert-<instance>-<hostname>-cert8.db cert8.db
ln -s <server_root>/alias/cert-<instance>-<hostname>-key3.db key3.db
pk12util -i <PKCS #12 file> -d .
cd /var/tmp
certutil -d <server_root>alias -L to obtain the nickname of the EMAIL Signing user certificate
CSutil -S -N <nickname of EMAIL Signing user certificate> -T -i /var/tmp/<CS backup data file> -o /var/tmp/<CS backup data file signature file> -d <server_root>/alias -p <password>
where the CS backup data file signature file is of the form CS_<instance_name_minus_cert-_prefix>_BACKUP-<YYYYMMDDhhmmss>.signature

Verifying Signed Backup Data using CSutil

The following provides an example of using the tool called <server_root>/bin/cert/tools/CSutil to verify signed backup data for a specific CS subsystem instance on a UNIX system:

  1. Verify the Backup Data File Signature
    • Invoke a command-line interface such as a telnet session
    • From the command line, assuming a Bourne Shell ("sh") on a Solaris system, set and export the LD_LIBRARY_PATH environment variable:
LD_LIBRARY_PATH=<server_root>/bin/cert/lib:$LD_LIBRARY_PATH
export LD_LIBRARY_PATH
PATH=<server_root>/bin/cert/tools:$PATH
export PATH
cd <server_root>/alias
ln -s <server_root>/alias/cert-<instance>-<hostname>-cert8.db cert8.db
ln -s <server_root>/alias/cert-<instance>-<hostname>-key3.db key3.db
pk12util -i <PKCS #12 file> -d .
cd /var/tmp
certutil -d <server_root>alias -L to obtain the nickname of the EMAIL Signing user certificate
CSutil -D -c /var/tmp/<CS backup data file> -n -h 1 -i /var/tmp/<CS backup data file signature file> -d <server_root>/alias
where the CS backup data file signature file is of the form CS_<instance_name_minus_cert-_prefix>_BACKUP-<YYYYMMDDhhmmss>.signature

Restoring Data

The purpose of creating back up archives, of course, is to allow you to restore a previous state of the CS server instance after a hardware or software failure corrupts your current state. The restore tool allows you to recover all or part of the configuration that was backed up. For example, you can use the tool to restore just the internal database of a CS server instance.

A special case, automatic restore, allows you to completely restore the configuration from the latest backup archive quickly and without interaction.

Before You Restore Data

Before you can restore from a backup archive, the archive you want to use has to be available on a disk accessible from the server instance directory. If you want to use the automatic restore feature, you should put the archive in the output directory where CSbackup originally created it (C:\Temp on Windows NT or /var/tmp on UNIX).

Note the full path name to the backup archive; in the instructions later it will be referred to as <archive_path>. For example, on a UNIX system, the <archive_path> might be

/var/tmp/CS_CSdemo_BACKUP-19991115093827.zip.

CS backup data files can be optionally signed (and verified) from the command-line utilizing a separate tool called <server_root>/bin/cert/tools/CSutil. If the file was signed, you might want to use this utility to verify. For an example of signing backup data utilizing this tool, see "Signing Backup Data Using CSutil," on page 383. For an example of verifying signed backup data utilizing this tool, see "Verifying Signed Backup Data using CSutil," on page 384.

You can use the word automatic instead of a path name to indicate the location of the backup archive. If you use automatic, the restore tool will read the file logs/latest_backup to find the path name of the archive. This file is created by CSbackup and contains the name of the last archive created. Note that automatic always causes all data to be restored: you will not be able to select only a subset of the data.

If you moved the zip archive to another machine or removable medium, copy it back to the local file system. If you encrypted the archive, decrypt it before you try to restore the data.

You cannot restore data to a CS instance that has not been configured. If you re-installed CS prior to attempting to restore data, you must configure the new CS instance. When you configure the new installation, keep the following points in mind:

The user running the restore tool will probably need superuser (UNIX) or Administrator (Windows NT) privileges. The user running the tool will need privileges to do the following:

The process of restoring data will require that some servers be stopped and restarted. If any of your servers require passwords to start (for example, if they need to unlock the key database in order to listen for SSL requests), you will be prompted for the password. If any passwords have changed since you created the backup archive, make sure you know the password that was valid at the time the archive was created.

Running the Restore Tool

To run CSrestore:

  1. Log in to the machine where the CS instance you want to restore is installed and open a command shell.
  2. Change to the CS server instance directory in the server root. For example, if your server root is /opt/redhat-cs and the instance ID of the server you want to restore is CSinstance:
# cd /opt/redhat-cs/cert-CSinstance
  1. Execute the restore script: either CSrestore on UNIX or CSrestore.bat on Windows NT systems.
You can either provide the <archive_path> as an argument or use the argument automatic (to read the archive path from logs/latest_backup):
# ./CSrestore <archive_path> | automatic
For example,
# ./CSrestore \
/var/tmp/CS_CSdemo_BACKUP-19991115093827.zip
If you use automatic as the argument, the restore proceeds automatically; go to Step 9 when CSrestore completes.
  1. The script asks if you would like to perform a complete or prompted restore. Enter
    • c (complete) to completely restore the contents of the archive without further prompts. Proceed with Step 9 when the restore is complete.
    • p (prompted) to have the script ask you whether you want to restore specific parts of the archive.
  2. If the configuration Directory Server is located in the same server root, the first prompt asks if you want to restore it. The configuration Directory Server is the directory used by the Administration Server to store information about servers, users, and groups.
If you answer yes, the restore tool stops the Directory Server, restores the data, then restarts the server. You may be asked to enter a password if one is required to start the server.
  1. Next you are asked if you want to restore selected Administration Server data.
If you answer no, no Administration Server data will be restored; proceed with the next step.
If you answer yes, you will be asked six more questions about specific Administration Server data you want to restore:
  1. Main admin data is data in the Administration Server's configuration directory.
  2. Non-CS HTTP ACLs.
  3. Non-CS admin ACLs.
  4. Non-CS user database.
  5. Non-CS shared data is data in the <server_root>/shared/config directory.
  6. CS certificate and key databases are the databases in the <server_root>/alias directory.
After you answer the questions, the Administration Server is stopped, the data restored from the archive, and the server is started again. If necessary, you will be prompted to enter a password to start the Administration Server.
  1. Next you are asked if you want to restore the CS internal database Directory Server. This is the Directory Server this CS instance uses as its internal database.
If you answer yes, the restore tool stops the Directory Server, restores the data, then restarts the server. You may be asked to enter a password if one is required to start the server.
  1. Next you are asked if you want to restore selected data for this CS server instance.
If you answer yes, you will be asked five more questions about the following CS server instance data that you can restore:
  1. Global CS classes are Java classes that are shared by all CS servers in the same server root.
  2. Critical CS data includes the configuration files, and password cache in the config directory for this CS instance.
  3. Local CS emails.
  4. Local CS classes are Java classes used only by this server instance.
  5. Custom CS UI data includes all HTML files and templates in the web-apps and emails directory of this CS instance.
After you answer these questions, the tool stops the CS server, restores the data, then restarts the server. You will be asked to enter the single sign-on password that unlocks the password cache when the server restarts ( usee section "Password Cache" in Chapter 7, "Administrative Basics" of CS Administrator's Guide.)
  1. After the tool finishes restoring data, view the CSrestore.log file in the server instance logs directory.
Review each step to make sure there were no errors in restoring the data. If there were errors or warnings, you may want to run CSrestore again. You may need to change permissions on some files or manually start some servers before running CSrestore again.

The restore tool deletes the working directory where it unpacked the archive, but it does not delete the archive itself. You probably will not want to keep the backup archive on disk. Remember that the backup archive contains sensitive information. Delete or secure the archive when you are done using it to restore data.




Previous
 Contents
 Index
 Next
© 2001 Sun Microsystems, Inc. Used by permission. © 2005 Red Hat, Inc. All rights reserved.
Read the Full Copyright and Third-Party Acknowledgments.

 last updated July 18, 2005