|
||
|
|
If you have a previous installation of Netscape Certificate Management System (CMS), you can use the CMS Upgrade utility for upgrading its data to CMS 6.0 or later versions.
This chapter has five sections. The first two provide some background and an overview of the current version of CMS Upgrade utility. The remaining three sections explain the steps involved in upgrading.
This table summarizes all CMS releases up to CMS 7.0:
Table 2-1 Summary of CMS releases
6.1 (SP 1), 6.1 (SP 2), 6.1 (SP 3), 6.1 (SP 31), and 6.1 (SP 4)
Every version of CMS has been built with some capability to extract data from a previous version and migrate this data into the newest version:
- CMS 4.1 and CMS 4.2 contained a "migrate" utility included to extract data out of CMS's predecessor, Certificate Server 1.x.
![]()
- CMS 4.1, CMS 4.2, CMS 4.2 (SP 2), and CMS 4.5 contained in-place upgrades to automatically extract the data from one of its older CMS siblings.
![]()
- Since CMS 4.7 was developed by another company, it contained only an in-place upgrade facility for CMS 4.1, CMS 4.2, and CMS 4.2 (SP 2).
![]()
- CMS 6.0, CMS 6.1, CMS 6.2, and CMS 7.0 contain various versions of the CMS Upgrade utility as described in the remainder of this document.
![]()
Caveat: This document describes how to upgrade a previous CMS server instance to a CMS 7.0 instance. It does not cover moving from one machine to another. Although all the tools described here are platform-agnostic, this document also does not cover switching from one platform to another (such as from Solaris 8 to Red Hat Linux Advanced Server 2.1).
In the event that you want to switch machines or platforms, contact a CMS professional services representative for more details.
While the CMS Upgrade utility consists of numerous standalone programs, only two are actually required for any one version of CMS: one program to convert an LDIF data file exported from an existing previous version of CMS into a "normalized" LDIF text file, and another program to convert this "normalized" LDIF text file into an LDIF data file that can be imported into CMS 6.0 or later versions.
CMS Upgrade export utilities consist of 41ToTxt, 42ToTxt, 42SP2ToTxt, 45ToTxt, 47ToTxt, 60ToTxt, 61ToTxt, 62ToTxt, and 70ToTxt. Each CMS Upgrade export utility contains the following files:
- two precompiled java classes
![]()
- an executable shell script
![]()
- an executable batch script
![]()
- the Java source file that produced the precompiled Java classes
![]()
- a sample shell script that may be utilized to compile the source file
![]()
- Note: Each compilation shell script is dependent on a specific version of the Java development kit as defined in the comments.
- a sample batch script that may be utilized to compile the source file
![]()
- Note: Each compilation batch script is dependent on a specific version of the Java development kit as defined in the comments.
CMS Upgrade import utilities consist of TxtTo60, TxtTo61, TxtTo62, and TxtTo70. Each CMS Upgrade import utility contains the following files:
- three precompiled java classes
![]()
- an executable shell script
![]()
- an executable batch script
![]()
- the Java source file that produced the precompiled Java classes
![]()
- a sample shell script that may be utilized to compile the source file
![]()
- Note: Each compilation shell script is dependent upon a specific version of the Java development kit as defined in the comments.
- a sample batch script that may be utilized to compile the source file.
![]()
- Note: Each compilation batch script is dependent upon a specific version of the Java development kit as defined in the comments.
The following table defines the CMS upgrade export programs and corresponding import programs. An X indicates compatibility between the export and import programs.
Table 2-2 CMS upgrade compatibility matrix
In every case, with the exception of CMS 4.2 (SP 2), the major version number may be applied to all service packs (SP) of that version. For example, the 42ToTxt export package should be utilized for CMS 4.2, 4.2 (SP 1), and 4.2 (SP 1a). In the case of CMS 6.01, the 60ToTxt program should be used to export data, and the TxtTo60 program should be used to import data.
Note: Always perform the steps in the upgrade procedure for each and every instance to be migrated.
Before upgrading from a CMS 4.1, 4.2, 4.2 (SP 2), 4.5, 4.7, 6.0, 6.1, 6.2, or 7.0 instance to a CMS 7.0 instance, you must back up your previous CMS instance.
Backing Up Your Previous CMS Instance
You must back up your existing CMS 4.1, 4.2, 4.2 (SP 2), 4.5, 4.7, 6.0, 6.1, 6.2, or 7.0 instance before you can upgrade to CMS 7.0
- For instructions to back up a CMS 4.1, 4.2, 4.2 (SP 2), or 4.5 instance, check the CMS Command-Line Tools Guide that was provided with the product; open the
<server_root>/manual/en/cert/tools/backup.htmfile.![]()
- For instructions to back up a CMS 4.7 instance, check the documentation that was provided with the product.
![]()
- For instructions to back up a CMS 6.0, 6.1, 6.2, or CMS 7.0 instance, see Chapter 7 "Backing Up and Restoring Data."
![]()
This section provides instructions for migrating to CMS 7.0 from earlier versions.
- Install and Configure CMS 7.0
![]()
- The migration tools are available in the following directory:
<70_server_root>/bin/cert/upgrade
- Stop the CMS 7.0 instance. To stop the instance do the following:
![]()
- Go to the following directory:
![]()
<70_server_root>/cert-<instance>
- Execute the following command:
![]()
stop-cert
- Copy the key (cert7.db, key3.db) into CMS 7.0's alias directory. To do this, follow these steps:
![]()
- Go to the following directory:
![]()
<old_server_root>
- What you do next depends on which version you are converting. Follow the steps below that apply to the version you are converting:
![]()
- For migrating from CMS 4.1 or CMS 4.2:
- Remove the following file from the new server:
![]()
<70_server_root>/alias/cert-<instance>-<hostname>-cert8.db
- Copy the following file from the old server:
![]()
<old_server_root>/cert-<instance>/config/cert7.db
- to the following location in the new server:
<70_server_root>/alias/cert-<instance>-<hostname>-cert7.db
- Copy the following file from the older server:
![]()
<old_server_root>/cert-<instance>/config/key3.db
- to the following location in the new server:
<70_server_root>/alias/cert-<instance>-<hostname>-key3.db(overwrite this file)
- Copy the following file from the older server:
![]()
<old_server_root>/admin-serv/config/secmodule.db
- to the following location in the new server:
<70_server_root>/alias/secmod.db(overwrite this file)
- For migrating from CMS 4.2, CMS 4.5, or CMS 4.7:
- Remove the following file from the new server:
![]()
<70_server_root>/alias/cert-<instance>-<hostname>-cert8.db
- Copy the following file from the older server:
![]()
<old_server_root>/cert-<instance>/config/cert7.db
- to the following location in the new server:
<70_server_root>/alias/cert-<instance>-<hostname>-cert7.db
- Copy the following file from the older server:
![]()
<old_server_root>/cert-<instance>/config/key3.db
- to the following location in the new server:
<70_server_root>/alias/cert-<instance>-<hostname>-key3.db(overwrite this file)
- Copy the following file from the older server:
![]()
<old_server_root>/admin-serv/config/secmod.db
- to the following location in the new server:
<70_server_root>/alias/secmod.db(overwrite this file)
- For migrating from CMS 6.0:
- Remove the following file from the new server:
![]()
<70_server_root>/alias/cert-<instance>-<hostname>-cert8.db
- Copy the following file from the older server:
![]()
<60_server_root>/alias/cert-<instance>-<hostname>-cert7.db
- to the following location in the new server:
<70_server_root>/alias/cert-<instance>-<hostname>-cert7.db
- Copy the following file from the older server:
![]()
<60_server_root>/alias/cert-<instance>-<hostname>-key3.db
- to the following location in the new server:
<70_server_root>/alias/cert-<instance>-<hostname>-key3.db(overwrite this file)
- Copy the following file from the older server:
![]()
<60_server_root>/alias/secmod.db
- to the following location in the new server:
<70_server_root>/alias/secmod.db(overwrite this file)
- For migrating from CMS 6.1, CMS 6.2, or CMS 7.0:
- Copy the following file from the older server:
![]()
<old_server_root>/alias/cert-<instance>-<hostname>-cert8.db
- to the following location in the new server:
<70_server_root>/alias/cert-<instance>-<hostname>-cert8.db(overwrite this file)
- Copy the following file from the older server:
![]()
<old_server_root>/alias/cert-<instance>-<hostname>-key3.db
- to the following location in the new server:
<70_server_root>/alias/cert-<instance>-<hostname>-key3.db(overwrite this file)
- Copy the following file from the older server:
![]()
<old_server_root>/alias/secmod.db
- to the following location in the new server:
<70_server_root>/alias/secmod.db(overwrite this file)
- List the content of pwcache.p12 (CMS 4.1, CMS 4.2, CMS 4.2 (SP 2), CMS 4.5, or CMS 4.7) or pwcache.db (CMS 6.0, CMS 6.1, CMS 6.2, or CMS 7.0) in the old instance.
![]()
- Migrating from CMS 4.1:
- Unfortunately, no PasswordCache tool was shipped with CMS 4.1. However, it is possible to install CMS 4.2 or CMS 4.2 (SP 2), and then use the PasswordCache tool from one of these CMS servers. For the following instructions, presume that CMS 4.2 was installed.
![]()
- Go to the following directory:
![]()
<41_server_root>/cert-<instance>
- Execute the following command:
![]()
<42_server_root>/bin/cert/tools/PasswordCache <password> list
- For example:
<42_server_root>/bin/cert/tools/PasswordCache <password> list
----- Password Cache -----
Internal LDAP Database : <password>
Internal Key Storage Token : <password>
- Migrating from CMS 4.2, CMS 4.2 (SP1) CMS 4.5, or CMS 4.7:
- Go to the following directory:
![]()
<old_server_root>/cert-<instance>
- Execute the following command:
![]()
<old_server_root>/bin/cert/tools/PasswordCache <password> list
- For example:
<old_server_root>/bin/cert/tools/PasswordCache <password> list
----- Password Cache -----
Internal LDAP Database : <password>
Internal Key Storage Token : <password>
- Migrating from CMS 6.0, CMS 6.1, CMS 6.2, or CMS 7.0:
- Go to the following directory:
![]()
<old_server_root>/cert-<instance>/config
- Execute the following command:
<old_server_root>/bin/cert/tools/PasswordCache <password> -d <alias directory> -P <prefix> list
- For example:
<old_server_root>/bin/cert/tools/PasswordCache <password> -d <old_server_root>/alias -P cert-<instance>-<hostname>- list
cert/key prefix = cert-<instance>-<hostname>-
path = <old_server_root>/alias
about to read password cache
----- Password Cache Content -----
internal : <password>
Internal LDAP Database : <password>
- Recreate the pwcache.db in CMS 7.0 instance:
![]()
- Go to the following directory:
![]()
<70_server_root>/cert-<instance>/config/
- Remove pwcache.db (this is the original password cache file created during CMS 6.1 configuration)
![]()
- Generate protection key.
![]()
- To do this, execute the following command:
<70_server_root>/bin/cert/tools/PasswordCache <password> -d <alias directory> -P <prefix> -c <file> rekey
- For example:
<70_server_root>/bin/cert/tools/PasswordCache <password> -d <70_server_root>/alias -P cert-<instance>-<hostname>- -c pwcache.db rekey
- The following will be output to the screen when the command is run:
cert/key prefix = cert-<instance>-<hostname>-
cert/key db path = <70_server_root>/alias
password cache file = pwcache.db
token name = internal
generating new key...
PWsdrCache: mToken = internal
PWsdrCache: SDR key generated
key generated successfully with key id = OPHHNSQTY0RUGFJbcaco1g==
Save the VALUE portion of this key id in a local file,
and under variable "pwcKeyid" in CMS.cfg!!
If you have not already done so,
remove the old pwcache.db and use this local file to add passwords.
- Save the value portion of the key id into a local file such as key.txt
![]()
- Save the value portion of the key id into the CMS.cfg file under the variable "pwcKeyid"
![]()
- Execute the following command:
touch pwcache.db
- (This will recreate an empty file.)
- Add password tags and their associated passwords (from step 4) back to the cache. (You may need to do this multiple times). Do this by executing the following command:
![]()
<70_server_root>/bin/cert/tools/PasswordCache <password> -d <alias directory> -P <prefix> -c <file> -k <key file> add <tag> <associated_tag_password>
- For example:
<70_server_root>/bin/cert/tools/PasswordCache <password> -d <70_server_root>/alias -P cert-<instance>-<hostname>- -c pwcache.db -k key.txt add "Internal LDAP Database" <associated_tag_password>
- The following output will appear on the screen:
cert/key prefix = cert-<instance>-<hostname>-
cert/key db path = <70_server_root>/alias
password cache file = pwcache.db
token name = internal
PWsdrCache: mToken = internal
adding Internal LDAP Database:<associated_tag_password>
PWsdrCache: in addEntry
about to read password cache
PWsdrCache: after readPWcache()
adding new tag: Internal LDAP Database
operation completed for pwcache.db
<70_server_root>/bin/cert/tools/PasswordCache <password>
-d <70_server_root>/alias
-P cert-<instance>-<hostname>-
-c pwcache.db
-k key.txt add "Internal Key Storage Token" <associated_tag_password>
cert/key prefix = cert-<instance>-<hostname>-
cert/key db path = <70_server_root>/alias
password cache file = pwcache.db
token name = internal
PWsdrCache: mToken = internal
adding Internal Key Storage Token:<associated_tag_password>
PWsdrCache: in addEntry
about to read password cache
PWsdrCache: after readPWcache()
adding new tag: Internal Key Storage Token
operation completed for pwcache.db
- Confirm everything is OK. Execute the following command:
![]()
<70_server_root>/bin/cert/tools/PasswordCache <password> -d <alias directory> -P <prefix> -c <file> list
- For example:
<70_server_root>/bin/cert/tools/PasswordCache <password> -d <70_server_root>/alias -P cert-<instance>-<hostname>- -c pwcache.db list
- The following is the output for this command:
cert/key prefix = cert-<instance>-<hostname>-
cert/key db path = <70_server_root>/alias
password cache file = pwcache.db
token name = internal
PWsdrCache: mToken = internal
about to read password cache
----- Password Cache Content -----
Internal Key Storage Token : <associated_tag_password>
Internal LDAP Database : <associated_tag_password>
- Update server.xml and CMS.cfg files for the CMS 7.0 instance to use the appropriate nicknames in the values of any of the parameters. Look for nickname-related parameters. To do this:
![]()
- Go to the following directory:
![]()
<70_server_root>/cert-<instance>/config
- What you do next depends on which version you are converting. Follow the steps below that apply to the version you are converting:
![]()
- Migrating from CMS 4.1 or CMS 4.2:
- Note: Replace the ca.ocsp_signing.cacertnickname with the ca.signing.cacertnickname (in CMS.cfg) since one does not exist in CMS 4.1 or CMS 4.2
- For example, edit the following:
servercertnickname (in server.xml)
ca.signing.cacertnickname (in CMS.cfg)
- Copy the second line above and rename it as follows:
ca.ocsp_signing.cacertnickname (in CMS.cfg)
- Migrating from CMS 4.2 (SP 2), CMS 4.5, CMS 4.7, CMS 6.0, CMS 6.1, CMS 6.2, or CMS 7.0:
- For example, edit the following:
servercertnickname (in server.xml)
ca.ocsp_signing.cacertnickname (in CMS.cfg)
ca.signing.cacertnickname (in CMS.cfg)
- Dump the old internal directory content into LDIF format. To do this:
![]()
- Go to the following directory:
<old_server_root>/slapd-<instance>-db![]()
- Execute the db2ldif command to export the internal directory content.
![]()
- Migrating from CMS 4.1, CMS 4.2, CMS 4.2 (SP 2), or CMS 4.5, use the following command:
db2ldif
- Migrating from CMS 4.7, CMS 6.0, CMS 6.1, CMS 6/2, or CMS 7.0, use the following command:
db2ldif -n userRoot
- The LDIF file will be created in the following file:
<old_server_root>/slapd-<instance>-db/ldif
- Go to the following directory:
![]()
<old_server_root>/slapd-<instance>-db/ldif
- Rename the LDIF file
old.ldif![]()
- Dump the new internal directory content into LDIF format. To do this:
![]()
- Go to the following directory:
![]()
<70_server_root>/slapd-<instance>-db
- Execute the following db2ldif command to export the internal directory content:
![]()
db2ldif -n userRoot
- The LDIF file will be created in the following directory:
<70_server_root>/slapd-<instance>-db/ldif
- Go to the following directory:
![]()
<70_server_root>/slapd-<instance>-db/ldif
- Rename the LDIF file
new.ldif![]()
- Adjust the LDIF content. To do this:
![]()
- Migrating from CMS 4.1, CMS 4.2, CMS 4.2 (SP 2), or CMS 4.5:
- Go to the following directory:
![]()
<old_server_root>/slapd-<instance>-db/ldif
- Delete the first 2 entries in old.ldif. They look like the following:
![]()
Entry 1: <machine domain>
Entry 2: cn=ldap://:<port>,<machine domain>
- For example:
Entry 1: dc=cert,dc=netscape,dc=com
Entry 2: cn=ldap://:38900,dc=cert,dc=netscape,dc=com
- Replace the following entry with the one in new.ldif from step 8:
![]()
cn=aclResources,o=netscapeCertificateServer
- Migrating from CMS 4.7, CMS 6.0, CMS 6.1, CMS 6.2, or CMS 7.0:
- Replace the following entry with the one in new.ldif from step 8:
![]()
cn=aclResources,o=netscapeCertificateServer
- Convert old.ldif into old.txt format by running the following (examples are for a UNIX system).
![]()
- What you do next depends on which version you are converting. Follow the steps below that apply to the version you are converting:
![]()
- Migrating from CMS 4.1
- Go to the following directory:
![]()
<70_server_root>/bin/cert/upgrade/41ToTxt
- In run.sh, set
SERVER_ROOT=<41_server_root>and uncomment it![]()
- In run.sh, uncomment
export SERVER_ROOT![]()
- In run.sh, set
INSTANCE=<instance>and uncomment it![]()
- In run.sh, uncomment
export INSTANCE![]()
- Execute the following command:
![]()
run.sh <41_server_root>/slapd-<instance>-db/ldif/old.ldif > <41_server_root>/slapd-<instance>-db/ldif/old.txt
- Migrating from CMS 4.2:
- Go to the following directory:
![]()
<70_server_root>/bin/cert/upgrade/42ToTxt
- In run.sh, set
SERVER_ROOT=<42_server_root>and uncomment it![]()
- In run.sh, uncomment
export SERVER_ROOT![]()
- In run.sh, set
INSTANCE=<instance>and uncomment it![]()
- In run.sh, uncomment
export INSTANCE![]()
- Execute the following command:
![]()
run.sh <42_server_root>/slapd-<instance>-db/ldif/old.ldif > <42_server_root>/slapd-<instance>-db/ldif/old.txt
- Migrating from CMS 4.2 (SP 2):
- Go to the following directory:
![]()
<70_server_root>/bin/cert/upgrade/42SP2ToTxt
- In run.sh, set
SERVER_ROOT=<42SP2_server_root>and uncomment it![]()
- In run.sh, uncomment
export SERVER_ROOT![]()
- In run.sh, set
INSTANCE=<instance>and uncomment it![]()
- In run.sh, uncomment
export INSTANCE![]()
- Execute the following command:
![]()
run.sh <42SP2_server_root>/slapd-<instance>-db/ldif/old.ldif > <42SP2_server_root>/slapd-<instance>-db/ldif/old.txt
- Migrating from CMS 4.5:
- Go the following directory:
![]()
<70_server_root>/bin/cert/upgrade/45ToTxt
- In run.sh, set
SERVER_ROOT=<45_server_root>and uncomment it![]()
- In run.sh, uncomment
export SERVER_ROOT![]()
- In run.sh, set
INSTANCE=<instance>and uncomment it![]()
- In run.sh, uncomment
export INSTANCE![]()
- Execute the following command:
![]()
run.sh <45_server_root>/slapd-<instance>-db/ldif/old.ldif > <45_server_root>/slapd-<instance>-db/ldif/old.txt
- Migrating from CMS 4.7:
- Go the following directory:
![]()
<70_server_root>/bin/cert/upgrade/47ToTxt
- In run.sh, set
SERVER_ROOT=<47_server_root>and uncomment it![]()
- In run.sh, uncomment export
SERVER_ROOT![]()
- In run.sh, set
INSTANCE=<instance>and uncomment it![]()
- In run.sh, uncomment
export INSTANCE![]()
- Execute the following command:
![]()
run.sh <47_server_root>/slapd-<instance>-db/ldif/old.ldif > <47_server_root>/slapd-<instance>-db/ldif/old.txt
- Migrating from CMS 6.0:
- Go to the following directory:
![]()
<70_server_root>/bin/cert/upgrade/60ToTxt
- In run.sh, set
SERVER_ROOT=<60_server_root>and uncomment it![]()
- In run.sh, uncomment
export SERVER_ROOT![]()
- In run.sh, set
INSTANCE=<instance>and uncomment it![]()
- In run.sh, uncomment
export INSTANCE![]()
- Execute the following command:
![]()
run.sh <60_server_root>/slapd-<instance>-db/ldif/old.ldif > <60_server_root>/slapd-<instance>-db/ldif/old.txt
- Migrating from CMS 6.1:
- Go to the following directory:
![]()
<70_server_root>/bin/cert/upgrade/61ToTxt
- In run.sh, set
SERVER_ROOT=<61_server_root>and uncomment it![]()
- In run.sh, uncomment
export SERVER_ROOT![]()
- In run.sh, set
INSTANCE=<instance>and uncomment it![]()
- In run.sh, uncomment
export INSTANCE![]()
- Execute the following command:
![]()
run.sh <61_server_root>/slapd-<instance>-db/ldif/old.ldif > <61_server_root>/slapd-<instance>-db/ldif/old.txt
- Migrating from CMS 6.2:
- Go to the following directory:
![]()
<70_server_root>/bin/cert/upgrade/62ToTxt
- In run.sh, set
SERVER_ROOT=<62_server_root>and uncomment it![]()
- In run.sh, uncomment
export SERVER_ROOT![]()
- In run.sh, set
INSTANCE=<instance>and uncomment it![]()
- In run.sh, uncomment
export INSTANCE![]()
- Execute the following command:
![]()
run.sh <62_server_root>/slapd-<instance>-db/ldif/old.ldif > <62_server_root>/slapd-<instance>-db/ldif/old.txt
- Migrating from CMS 7.0:
- Go to the following directory:
![]()
<70_server_root>/bin/cert/upgrade/70ToTxt
- In run.sh, set
SERVER_ROOT=<old_server_root>and uncomment it![]()
- In run.sh, uncomment
export SERVER_ROOT![]()
- In run.sh, set
INSTANCE=<instance>and uncomment it![]()
- In run.sh, uncomment
export INSTANCE![]()
- Execute the following command:
![]()
run.sh <old_server_root>/slapd-<instance>-db/ldif/old.ldif > <old_server_root>/slapd-<instance>-db/ldif/old.txt
- Move old.txt into CMS 70's LDIF directory. To do this:
![]()
- Go to the following directory:
![]()
<old_server_root>/slapd-<instance>-db/ldif
- Move
<old_server_root>/slapd-<instance>-db/ldif/old.txtinto<70_server_root>/slapd-<instance>-db/ldif![]()
- Convert
old.txtintoold.ldif(7.0 format) as follows:![]()
- Go to the following directory:
![]()
<70_server_root>/bin/cert/upgrade/TxtTo70
- In run.sh, set
SERVER_ROOT=<70_server_root>and uncomment it![]()
- In run.sh, uncomment
export SERVER_ROOT![]()
- In run.sh, set
INSTANCE=<instance>and uncomment it![]()
- In run.sh, uncomment
export INSTANCE![]()
- Execute the following command:
![]()
run.sh <70_server_root>/slapd-<instance>-db/ldif/old.txt > <70_server_root>/slapd-<instance>-db/ldif/old.ldif
- Stop internal directory instance, import old LDIF file into new instance. To do this:
![]()
- Go to the following directory:
![]()
<70_server_root>/slapd-<instance>-db
- Execute the following command:
![]()
stop-slapd
- Execute the following command:
![]()
ldif2db -n userRoot -i <70_server_root>/slapd-<instance>-db/ldif/old.ldif
- Execute the following command:
![]()
start-slapd
- Start CMS 7.0
![]()
After upgrading to CMS 7.0, access the End-Entity Services and the Agent Services interfaces of the new CMS 7.0 instance to ensure that everything is working properly.
You must also log in to the CMS Console and verify that you can manage the server via the console.
The port numbers for all these interfaces can be found in this file:
© 2001 Sun Microsystems, Inc. Portions copyright 1999, 2002-2004 Netscape Communications Corporation. All rights reserved.
Last Updated November 23, 2004