Appendix B Backing Up and Restoring Data

This appendix explains how to back up the CMS data and configuration information and how to use the backups to restore data if there is a need.

• Backup and Restore Tools
• Backing Up Data
• Restoring Data

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

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

• <server_root>/alias/*
• <server_root>/shared/config/*.conf

• 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)

• <server_root>/bin/cert/classes
• <server_root>/cert-<instance_id>/classes

• <server_root>/cert-<instance_id>/web

• 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.
• pwcache.p12, the server instance password cache.

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.

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

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.

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/server4 and the instance id of the server you want to back up is cmsinstance:

# cd /usr/netscape/server4/cert-cmsinstance

3. Execute the backup script: either cmsbackup on UNIX or cmsbackup.bat on Windows NT systems. For example,

# ./cmsbackup

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

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

/var/tmp/CMS_cmsdemo_BACKUP-19991115093827.zip.

• 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).

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/server4 and the instance id of the server you want to restore is cmsinstance:

# cd /usr/netscape/server4/cert-cmsinstance

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

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

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.

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.

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:

1. Main admin data is data in the Administration Server's config directory.
2. Non-CMS shared data is data in the <server_root>/shared/config directory.
3. 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.

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.

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.

If you answer yes, you will be asked four 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, certificate and key databases, and password cache in the config directory for this CMS instance.
3. Local CMS classes are Java classes used only by this server instance.
4. 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 "Password Cache".

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