Netscape logo Command-Line Tools Guide
Netscape Certificate Management System
Previous      Contents      Index      Next     

Chapter 7   Backing Up and Restoring Data


This chapter explains how to back up the Netscape Certificate Management System (CMS) 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 Management System provides tools to backup and restore the data and configuration for a CMS instance. These tools can be used, for example, to back up just your CMS 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 CMS data than a nightly disk backup would record.

Since only CMS 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 CMS data. When you restore the CMS 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 CMS instance:

Be aware that the backup archives contain sensitive information (for example, your CMS 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.

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

Optionally, CMS 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 (cmsbackup) 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 CMS instance. This file calls the Perl script <server_root>/bin/cert/tools/CMSBackup.pl (using a Perl 5.005 interpreter bundled with Certificate Management System). CMSBackup.pl does the following:

The log file is in <server_root>/cert-<instance_id>/logs/cmsbackup.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 CMSBackup.pl.

The CMS database, non-CMS 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 Netscape Directory Server db2bak tool to create a backup of the CMS server instance internal database directory and the configuration directory (if it is running locally). Check the Netscape 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 CMS global and local class files are Java classes for custom plug-ins used by CMS servers. To back up this data, all files and subdirectories in the following directories are backed up:

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

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

The CMS 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 cmsbackup script backs up only configuration and data related to a single CMS 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 cmsbackup 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 Management System, Netscape Console, and Netscape Directory Server binaries and related tools before you use cmsrestore to recover your previous configuration.

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

Running the Backup Tool

Before you run cmsbackup, 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 cmsbackup:

  1. Log in to the machine where your CMS instance is running and open a command shell.
  2. Change to the CMS server instance directory in the server root. For example, if your server root is /usr/netscape/servers and the instance ID of the server you want to back up is cmsinstance:
    3. # cd /usr/netscape/servers/cert-cmsinstance
     
  3. Execute the backup script: either cmsbackup on UNIX or cmsbackup.bat on Windows NT systems. For example,
    4. # ./cmsbackup
     

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/cmsbackup.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 cmsbackup. If necessary, change the permissions on the required files, delete the zip archive in the output directory, and run cmsbackup 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 CMS 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.

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

Optionally, CMS 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 cmsutil

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

  1. Generating an EMAIL Signing User Certificate:
  2. Sign the Backup Data

Verifying Signed Backup Data using cmsutil

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

  1. Verify the Backup Data File Signature

Restoring Data

The purpose of creating back up archives, of course, is to allow you to restore a previous state of the CMS 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 CMS 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 cmsbackup 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/CMS_cmsdemo_BACKUP-19991115093827.zip.
 

CMS backup data files can be optionally signed (and verified) from the command-line utilizing a separate tool called <server_root>/bin/cert/tools/cmsutil. 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 cmsutil". For an example of verifying signed backup data utilizing this tool, see "Verifying Signed Backup Data using cmsutil".

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 cmsbackup 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 CMS instance that has not been configured. If you re-installed CMS prior to attempting to restore data, you must configure the new CMS 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 cmsrestore:

  1. Log in to the machine where the CMS instance you want to restore is installed and open a command shell.
  2. Change to the CMS server instance directory in the server root. For example, if your server root is /usr/netscape/servers and the instance ID of the server you want to restore is cmsinstance:
    3. # cd /usr/netscape/servers/cert-cmsinstance
     
  3. Execute the restore script: either cmsrestore on UNIX or cmsrestore.bat on Windows NT systems.
    4. You can either provide the <archive_path> as an argument or use the argument automatic (to read the archive path from logs/latest_backup):
     
    # ./cmsrestore <archive_path> | automatic
     
    For example,
     
    # ./cmsrestore \
    /var/tmp/CMS_cmsdemo_BACKUP-19991115093827.zip
     
    If you use automatic as the argument, the restore proceeds automatically; go to Step 9 when cmsrestore completes.
     
  4. The script asks if you would like to perform a complete or prompted restore. Enter
  5. 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.
    6. 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.
     
  6. Next you are asked if you want to restore selected Administration Server data.
    7. 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-CMS HTTP ACLs.
    3. Non-CMS admin ACLs.
    4. Non-CMS user database.
    5. Non-CMS shared data is data in the <server_root>/shared/config directory.
    6. CMS 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.
     
  7. Next you are asked if you want to restore the CMS internal database Directory Server. This is the Directory Server this CMS instance uses as its internal database.
    8. 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.
     
  8. Next you are asked if you want to restore selected data for this CMS server instance.
    9. If you answer yes, you will be asked five more questions about the following CMS server instance data that you can restore:
     
    1. Global CMS classes are Java classes that are shared by all CMS servers in the same server root.
    2. Critical CMS data includes the configuration files, and password cache in the config directory for this CMS instance.
    3. Local CMS emails.
    4. Local CMS classes are Java classes used only by this server instance.
    5. Custom CMS UI data includes all HTML files and templates in the web-apps and emails directory of this CMS instance.
    After you answer these questions, the tool stops the CMS 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 CMS Administrator's Guide.)
     
  9. After the tool finishes restoring data, view the cmsrestore.log file in the server instance logs directory.
    10. 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 cmsrestore again. You may need to change permissions on some files or manually start some servers before running cmsrestore 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. Portions copyright 1999, 2002-2004 Netscape Communications Corporation. All rights reserved.


Last Updated November 23, 2004