Previous
Contents
Index
Next
|
| iPlanet Certificate Management System Command-Line Tools Guide |
Chapter 6 Backing Up and Restoring Data
This chapter explains how to back up the iPlanet Certificate Management Server (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
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:
cmsbackup[.bat] copies all of the pertinent data and configuration files for a CMS instance, the local Administration Server, and local Netscape Directory Servers that the instance uses into an compressed archive (a zip file). See Backing Up Data for instructions on how to use this tool.
cmsrestore[.bat] opens a named archive, extracts the data, and uses it to restore the configuration of a CMS instance. You have the option to restore everything or to select a subset of the archived data. See Restoring Data for instructions on how to use this tool. 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.
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.003 interpreter bundled with Certificate Management System). CMSBackup.pl does the following:
Creates a log file where all backup actions are logged
Creates a temporary backup directory
Copies non-CMS certificate and key databases and shared files
Copies files required to configure the Netscape Console and Administration Server
Backs up the configuration directory server using that server's db2bak backup utility (if the server is running locally)
Backs up the CMS internal database directory server using that server's db2bak backup utility
Copies CMS global and local class files
Copies CMS user interface files and templates
Copies CMS instance configuration files
Creates a compressed archive of all files in the backup directory 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 non-CMS databases and shared files that are backed up are:
The Netscape Console Administration Server files that are backed up are the following files from <server_root>/admin-serv/config/:
admpw, the Administration Server password cache
*.conf, the Configuration files for the server and its associated LDAP data
*.db, the certificate and key databases for the Administration Server and secmodule.db (database of PKCS#11 modules available to all server instances) 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). See Chapter 4, "Managing Directory Server Databases," in iPlanet Directory Server Administrator's Guide for full details of 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 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
<server_root>/cert-<instance_id>/web The CMS configuration files that get backed up are in
<server_root>/cert-<instance_id>/config. The specific files and their purposes are:
CMS.cfg, the current master configuration file for the instance.
CMS.cfg.*, previous configuration files, available for reverting to an earlier configuration.
*.db, the server instance key and certificate databases.
*.ldif, ldif-format files that describe objects in the configuration database. 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:
Other instances of CMS servers in the same server root
Each instance has a copy of the cmsbackup script that backs up only data related to that instance.
External PKCS#11 module data
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 CMS server. It may be possible to extend the CMSBackup.pl and CMSRestore.pl Perl scripts to include this data in the archives used by the CMS backup tools.
Server binaries, libraries, and 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 cmsbackup, make sure that
You are logged in as a user with permission to run cmsbackup, to run db2bak for the LDAP servers, and to write to the output directory; you may need to become superuser on a UNIX system or Administrator on a Windows NT system.
There is plenty of disk space in the output directory; the size of the backup archive will vary with the amount of data in your system, so you will learn from experience how much space you require. 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.
Log in to the machine where your CMS instance is running and open a command shell.
Change to the CMS server instance directory in the server root. For example, if your server root is /usr/netscape/server4 and the instance ID of the server you want to back up is cmsinstance:
# cd /usr/netscape/server4/cert-cmsinstance
Execute the backup script: either cmsbackup on UNIX or cmsbackup.bat on Windows NT systems. For example,
# ./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.
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.
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:
All services should be running on the same network ports as they were when the backup archive was created. For example, the administration console port is a random number by default; be sure to change the default to the same port that your original installation used.
During configuration, you still need to create new keys and certificates for any servers that use the internal token. You only need to create these keys to complete the configuration process. Your signing, SSL, or DRM transport certificates will be restored (replacing whatever you create during the new configuration) when you run the restore script. 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:
Read the backup zip archive
Create a temporary working directory in the directory where the archive is located
Create directories and files in the server root and server instance directories (for example, if the CMS.cfg file needs to be restored)
Run the bak2db tool for any Netscape Directory Servers that are being restored
(UNIX) Change file ownership of the LDAP database backup files to the directory server user. The directory server user is defined by the localuser parameter in slapd.conf. If the directory server user is different from the user running cmsrestore, the user running the tool must be able to run chown to change the owner of the files to the LDAP server user (typically only the superuser has this privilege). 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:
Log in to the machine where the CMS instance you want to restore is installed and open a command shell.
Change to the CMS server instance directory in the server root. For example, if your server root is /usr/netscape/server4 and the instance ID of the server you want to restore is cmsinstance:
# cd /usr/netscape/server4/cert-cmsinstance
Execute the restore script: either cmsrestore on UNIX or cmsrestore.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):
# ./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.
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.
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.
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 three more questions about specific Administration Server data you want to restore:
Main admin data is data in the Administration Server's config directory.
Non-CMS shared data is data in the <server_root>/shared/config directory.
Non-CMS certificate and key databases are the databases in the <server_root>/alias directory; CMS instances maintain their own alias directories in the instance subdirectories.
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.
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.
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.
Next you are asked if you want to restore selected data for this CMS server instance.
If you answer yes, you will be asked four more questions about the following CMS server instance data that you can restore:
Global CMS classes are Java classes that are shared by all CMS servers in the same server root.
Critical CMS data includes the configuration files, certificate and key databases, and password cache in the config directory for this CMS instance.
Local CMS classes are Java classes used only by this server instance.
Custom CMS UI data includes all HTML files and templates in the web subdirectory 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 (see section "Password Cache" in Chapter 8, "Starting and Stopping CMS Instances" of CMS Installation and Setup Guide.)
After the tool finishes restoring data, view the cmsrestore.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 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
Copyright © 2002 Sun Microsystems, Inc. All rights reserved.
Last Updated October 07, 2002