Red Hat SYSTEM 8.0 - MIGRATION GUIDE 7.X TO 8.0 User manual

Red Hat Certificate
System 8.0
Migration Guide
7.x to 8.0
Matthew Harmsen
Publication date: July 22, 2009, updated on March 22, 2010

Migration Guide
Red Hat Certificate System 8.0 Migration Guide
7.x to 8.0
Edition 8.0.7
Author Matthew Harmsen
Editor Ella Deon Lackey
Copyright © 2009 Red Hat, Inc.
Copyright © 2009 Red Hat, Inc.
The text of and illustrations in this document are licensed by Red Hat under a Creative Commons
Attribution–Share Alike 3.0 Unported license ("CC-BY-SA"). An explanation of CC-BY-SA is available
at http://creativecommons.org/licenses/by-sa/3.0/. In accordance with CC-BY-SA, if you distribute this
document or an adaptation of it, you must provide the URL for the original version.
Red Hat, as the licensor of this document, waives the right to enforce, and agrees not to assert,
Section 4d of CC-BY-SA to the fullest extent permitted by applicable law.
Red Hat, Red Hat Enterprise Linux, the Shadowman logo, JBoss, MetaMatrix, Fedora, the Infinity
Logo, and RHCE are trademarks of Red Hat, Inc., registered in the United States and other countries.
Linux® is the registered trademark of Linus Torvalds in the United States and other countries.
All other trademarks are the property of their respective owners.
1801 Varsity Drive
Raleigh, NC 27606-2072 USA
Phone: [phone]
Phone: [phone]
Fax: [phone]
PO Box 13588
Research Triangle Park, NC 27709 USA
This migration guide provides in-depth procedures to migrate subsystems, user information, and
certificate and key materials from Red Hat Certificate System 7.1, 7.2, and 7.3 to Red Hat Certificate
System 8.0.

iii
About This Guide vii
1. Recommended Knowledge ............................................................................................. vii
2. Examples and Formatting .............................................................................................. vii
2.1. Formatting for Examples and Commands ............................................................. vii
2.2. Tool Locations .................................................................................................... viii
2.3. Guide Formatting ............................................................................................... viii
3. Additional Reading ........................................................................................................ viii
4. Giving Feedback ............................................................................................................ ix
5. Document History ............................................................................................................ x
1. Introduction to Red Hat Certificate System Migration 1
1.1. Certificate System Migration Overview ........................................................................... 1
1.1.1. Migration Scripts ................................................................................................ 1
1.1.2. Certificate System Subsystems .......................................................................... 2
1.2. Considerations Before Migration .................................................................................... 3
2. Setting up Certificate System 8.0 Subsystems 7
2.1. Installing New Certificate System Subsystem Instances .................................................. 7
2.2. Default File and Directory Locations for Certificate System Subsystems ......................... 11
2.2.1. Default CA Instance Information ....................................................................... 11
2.2.2. Default RA Instance Information ....................................................................... 12
2.2.3. Default DRM Instance Information .................................................................... 12
2.2.4. Default OCSP Instance Information .................................................................. 13
2.2.5. Default TKS Instance Information ..................................................................... 14
2.2.6. Default TPS Instance Information ..................................................................... 14
2.2.7. Shared Certificate System Subsystem File Locations ......................................... 16
3. Migrating a CA Instance to Certificate System 8.0 17
3.1. Flush the Request Queue ........................................................................................... 17
3.2. Migrating the Security Databases ................................................................................ 17
3.2.1. Option 1: Security Databases to Security Databases Migration ............................ 17
3.2.2. Option 2: Security Databases to HSM Migration ................................................ 19
3.2.3. Option 3: HSM to Security Databases Migration ................................................ 22
3.2.4. Option 4: HSM to HSM Migration ..................................................................... 24
3.3. Migrating Subsystem Password Stores ........................................................................ 27
3.3.1. Migrating Passwords from 7.1 .......................................................................... 27
3.3.2. Migrating Passwords from 7.2 and 7.3 .............................................................. 28
3.4. Migrating the LDAP Database ..................................................................................... 29
3.5. Migrating Custom CS.cfg Settings and Other Data ....................................................... 35
3.6. Restarting the CA Instance ......................................................................................... 36
3.7. Setting Custom Configuration in the Console ............................................................... 37
3.8. Verifying the CA Migration .......................................................................................... 37
4. Migrating an RA to 8.0 39
4.1. Dumping the 7.3 Databases ........................................................................................ 39
4.2. Preparing 7.3 Security Databases ............................................................................... 39
4.3. Importing the 7.3 SQL Database Information into the 8.0 SQL Database ........................ 40
4.4. Migrating the 7.3 Security Databases to the 8.0 RA ...................................................... 41
4.5. Migrating Passwords .................................................................................................. 42
4.6. Migrating Custom Configuration .................................................................................. 42
4.7. Restarting the RA Instance ......................................................................................... 42
4.8. Verifying the RA Migration .......................................................................................... 42
5. Migrating a DRM Instance to Certificate System 8.0 43

Migration Guide
iv
5.1. Migrating the Security Databases ................................................................................ 43
5.1.1. Option 1: Security Databases to Security Databases Migration ............................ 43
5.1.2. Option 2: Security Databases to HSM Migration ................................................ 45
5.1.3. Option 3: HSM to Security Databases Migration ................................................ 48
5.1.4. Option 4: HSM to HSM Migration ..................................................................... 51
5.2. Migrating Subsystem Password Stores ........................................................................ 54
5.2.1. Migrating Passwords from 7.1 .......................................................................... 54
5.2.2. Migrating Passwords from 7.2 and 7.3 .............................................................. 55
5.3. Migrating the LDAP Database ..................................................................................... 56
5.4. Migrating Custom CS.cfg and Other Data Settings ....................................................... 60
5.5. Restarting the DRM Instance ...................................................................................... 61
5.6. Setting Custom Configuration in the Console ............................................................... 61
5.7. Verifying the DRM Migration ....................................................................................... 61
6. Migrating a OCSP Instance to Certificate System 8.0 63
6.1. Migrating the Security Databases ................................................................................ 63
6.1.1. Option 1: Security Databases to Security Databases Migration ............................ 63
6.1.2. Option 2: Security Databases to HSM Migration ................................................ 65
6.1.3. Option 3: HSM to Security Databases Migration ................................................ 68
6.1.4. Option 4: HSM to HSM Migration ..................................................................... 70
6.2. Migrating Subsystem Password Stores ........................................................................ 73
6.2.1. Migrating Passwords from 7.1 .......................................................................... 73
6.2.2. Migrating Passwords from 7.2 and 7.3 .............................................................. 74
6.3. Migrating the LDAP Database ..................................................................................... 75
6.4. Migrating Custom Data and Settings ........................................................................... 79
6.5. Restarting the OCSP Instance .................................................................................... 79
6.6. Setting Custom Configuration in the Console ............................................................... 79
6.7. Verifying the OCSP Migration ...................................................................................... 80
7. Migrating a TKS Instance to Certificate System 8.0 81
7.1. Migrating the Security Databases ................................................................................ 81
7.1.1. Option 1: Security Databases to Security Databases Migration ............................ 81
7.1.2. Option 2: Security Databases to HSM Migration ................................................ 83
7.1.3. Option 3: HSM to Security Databases Migration ................................................ 87
7.1.4. Option 4: HSM to HSM Migration ..................................................................... 91
7.2. Migrating Subsystem Password Stores ........................................................................ 95
7.2.1. Migrating Passwords from 7.1 .......................................................................... 95
7.2.2. Migrating Passwords from 7.2 and 7.3 .............................................................. 96
7.3. Migrating the LDAP Database ..................................................................................... 96
7.4. Migrating Custom CS.cfg Settings and Other Data ...................................................... 101
7.5. Restarting the TKS Instance ..................................................................................... 101
7.6. Setting Custom Configuration in the Console ............................................................. 101
8. Migrating a TPS Instance to 8.0 103
8.1. Migrating the LDAP Database ................................................................................... 103
8.2. Migrating the Security Databases .............................................................................. 105
8.2.1. Option 1: Security Databases to Security Databases Migration .......................... 105
8.2.2. Option 2: Security Databases to HSM Migration ............................................... 107
8.2.3. Option 3: HSM to Security Databases Migration ............................................... 109
8.2.4. Option 4: HSM to HSM Migration .................................................................... 111
8.3. Migrating the TPS Configuration ................................................................................ 113
8.4. Migrating Passwords ................................................................................................. 113
8.5. Restarting the TPS Instance ..................................................................................... 114

v
8.6. Verifying the TPS Migration ....................................................................................... 114

vi

vii
About This Guide
This guide explains how to migrate a Red Hat Certificate System 7.1, 7.2, and 7.3 deployment to
a Red Hat Certificate System 8.0. Installation and administration topics are covered in the Red Hat
Certificate System Administrator's Guide, while processing certificate requests and other aspects of
managing the certificate lifecycle is covered in Certificate System Agent's Guide and using smart cards
is covered in the Managing Smart Cards with the Enterprise Security Client. For more information on
the tools used in this migration guide, see the Certificate System Command-Line Tools Guide.
1. Recommended Knowledge
Before reading this guide, be familiar with the following concepts:
• Intranet, extranet, and Internet security and the role of digital certificates in a secure enterprise,
including the following topics:
• Encryption and decryption
• Public keys, private keys, and symmetric keys
• Significance of key lengths
• Digital signatures
• Digital certificates, including different types of digital certificates
• The role of digital certificates in a public-key infrastructure (PKI)
• Certificate hierarchies
• LDAP and Red Hat Directory Server
• Public-key cryptography and the Secure Sockets Layer (SSL) protocol, including the following:
• SSL cipher suites
• The purpose of and major steps in the SSL handshake
2. Examples and Formatting
2.1. Formatting for Examples and Commands
All of the examples for Red Hat Certificate System commands, file locations, and other usage are
given for Red Hat Enterprise Linux 5 (32-bit) systems. Be certain to use the appropriate commands
and files for your platform.
To start the Red Hat Certificate System:
service pki-ca start
Example 1. Example Command

About This Guide
viii
2.2. Tool Locations
All of the tools for Red Hat Certificate System are located in the /usr/bin directory. These tools can
be run from any location without specifying the tool location.
2.3. Guide Formatting
Certain words are represented in different fonts, styles, and weights. Different character formatting is
used to indicate the function or purpose of the phrase being highlighted.
Formatting Style Purpose
Monospace font Monospace is used for commands, package names, files and
directory paths, and any text displayed in a prompt.
Monospace
with a
background
This type of formatting is used for anything entered or returned
in a command prompt.
Italicized text Any text which is italicized is a variable, such as
instance_name or hostname. Occasionally, this is also used to
emphasize a new term or other phrase.
Bolded text Most phrases which are in bold are application names, such as
Cygwin, or are fields or options in a user interface, such as a
User Name Here: field or Save button.
Other formatting styles draw attention to important text.
NOTE
A note provides additional information that can help illustrate the behavior of the system or
provide more detail for a specific issue.
IMPORTANT
Important information is necessary, but possibly unexpected, such as a configuration
change that will not persist after a reboot.
WARNING
A warning indicates potential data loss, as may happen when tuning hardware for
maximum performance.
3. Additional Reading
The documentation for Certificate System includes the following guides:
•Certificate System Deployment Guide1 describes basic PKI concepts and gives an overview of the
planning process for setting up Certificate System.
This manual is intended for Certificate System administrators.

Giving Feedback
ix
•Certificate System Installation Guide2 covers the installation process for all Certificate System
subsystems.
This manual is intended for Certificate System administrators.
•Certificate System Administrator's Guide3 explains all administrative functions for the Certificate
System. Administrators maintain the subsystems themselves, so this manual details backend
configuration for certificate profiles, publishing, and issuing certificates and CRLs. It also covers
managing subsystem settings like port numbers, users, and subsystem certificates.
This manual is intended for Certificate System administrators.
•Certificate System Agent's Guide4 describes how agents — users responsible for processing
certificate requests and managing other aspects of certificate management — can use the
Certificate System subsystems web services pages to process certificate requests, key recovery,
OCSP requests and CRLs, and other functions.
This manual is intended for Certificate System agents.
•Managing Smart Cards with the Enterprise Security Client5 explains how to install, configure,
and use the Enterprise Security Client, the user client application for managing smart cards, user
certificates, and user keys.
This manual is intended for Certificate System administrators, agents, privileged users (such as
security officers), and regular end users.
•Using End User Services6 is a quick overview of the end-user services in Certificate System, a
simple way for users to learn how to access Certificate System services.
This manual is intended for regular end users.
•Certificate System Command-Line Tools Guide7 covers the command-line scripts supplied with Red
Hat Certificate System.
This manual is intended for Certificate System administrators.
•Certificate System Migration Guide8 covers version-specific procedures for migrating from older
versions of Certificate System to Red Hat Certificate System 8.0.
This manual is intended for Certificate System administrators.
•Release Notes9 contains important information on new features, fixed bugs, known issues and
workarounds, and other important deployment information for Red Hat Certificate System 8.0.
All of the latest information about Red Hat Certificate System and both current and archived
documentation is available at http://www.redhat.com/docs/manuals/cert-system/.
4. Giving Feedback
If there is any error in this Migration Guide: 7.x to 8.0 or there is any way to improve the
documentation, please let us know. Bugs can be filed against the documentation for Red Hat
Certificate System through Bugzilla, http://bugzilla.redhat.com/bugzilla. Make the bug report as
specific as possible, so we can be more effective in correcting any issues:
• Select the Red Hat Certificate System product.

About This Guide
x
• Set the component to Doc - migration-guide.
• Set the version number to 8.0.
• For errors, give the page number (for the PDF) or URL (for the HTML), and give a succinct
description of the problem, such as incorrect procedure or typo.
For enhancements, put in what information needs to be added and why.
• Give a clear title for the bug. For example, "Incorrect command example for setup
script options" is better than "Bad example".
We appreciate receiving any feedback — requests for new sections, corrections, improvements,
enhancements, even new ways of delivering the documentation or new styles of docs. You are
welcome to contact Red Hat Content Services directly at [email protected].
5. Document History
Revision 8.0.7 March 22, 2010
Removed last reference to changing subsystem names at migration (which is not supported).
Revision 8.0.6 March 18, 2010
Made a lot of minor text edits and clarifications request by SEG, including Bugzilla #561558, Bugzilla
#561556, Bugzilla #561559, Bugzilla #561561, Bugzilla #559790, Bugzilla #559778, Bugzilla
#559792, and Bugzilla #561555.
Revision 8.0.5 October 13, 2009
Minor edits to the TPS migration section, from input by Ade Lee in Bugzilla #519038.
Revision 8.0.4 September 18, 2009
Tech edits to chapter 1 (introduction) and chapter 2 (installing new instances), per review bugs
Bugzilla #510574 and Bugzilla #519032, respectively.
Revision 8.0.3 September 9, 2009
Revising the TPS security databases migration section to include scenarios for migrating to and from
HSMs, Bugzilla #519038.
Revision 8.0.2 September 4, 2009
Minor corrections to command line examples for the tech review in OCSP migration, Bugzilla
#519036.
Revision 8.0.1 August 1, 2009
Adding an extra step to the installation procedure to unset the DONT_RUN_PKICREATE
environment variable before running pkicreate.
Revision 8.0.0 July 22, 2009
Initial draft.

Chapter 1.
1
Introduction to Red Hat Certificate
System Migration
Red Hat Certificate System 7.1, 7.2, and 7.3 can be migrated to Red Hat Certificate System version
8.0 using the Red Hat Certificate System migration utility. These migration scripts can extract data
from the installation of a previous version and migrate this data to 8.0. Each Certificate System
subsystem is migrated independently.
• Product downgrade, extracting information from a newer version to import into an older version, is
not supported by the migration utility in any version of the Certificate System.
• Certificate System 8.0 does not support in-place upgrades. This is true even when the installations
are on the same machine, running the same platform. For example, a Red Hat Certificate System
7.1 installation on a machine named delta.example.com running Red Hat Enterprise Linux
has to be migrated to Certificate System 8.0 installation, even if the 8.0 installation is on the same
machine named delta.example.com running Red Hat Enterprise Linux. This is accomplished
simply by supplying a different installation directory for each instance.
Release Date Product Name
May 27, 2005 Red Hat Certificate System 7.1
November 6, 2006 Red Hat Certificate System 7.2
May 2007 Red Hat Certificate System 7.3
July 22, 2009 Red Hat Certificate System 8.0
Table 1.1. Summary of Certificate System Releases
1.1. Certificate System Migration Overview
The migration process is staged to migrate the different subsets of Certificate System information
separately. The general process is as follows:
1. Install the Certificate System 8.0 subsystem instances.
2. Migrate the Certificate Management System 7.x security databases, which contains the key and
certificate materials for the server, to the Certificate System 8.0 instances.
3. Migrate the password database information for Certificate Management System 7.x to the
Certificate System 8.0 password file.
4. Migrate the Certificate Management System 7.x internal databases, which contain user and group
entries, to the Certificate System 8.0 server.
5. Migrate customized server configuration data from the 7.x server to Certificate System 8.0.
6. Renew all migrated certificates.
1.1.1. Migration Scripts
The Certificate System migration utility contains several separate platform-independent tools, but only
two are required for migrating a Certificate System installation: one program to convert all of the data
in an LDIF that was exported from the 7.x installation into a normalized LDIF text file, and another

Chapter 1. Introduction to Red Hat Certificate System Migration
2
program to convert the normalized LDIF text file into an LDIF data file that can be imported into the
newer Certificate System.
NOTE
The major version number of the migration export/import package is applied to all service
packs for that version. This also applies to installations which contain hot-fixes, individual
bug fixes made after a service pack is released.
Certificate System migration export utilities are files named versionToTxt. For migrating 7.1, 7.2, and
7.3 servers to Certificate System 8.0, there are three migration scripts available, depending on the 7.x
version:
• 71ToTxt
• 72ToTxt
• 73ToTxt
Each export tool directory (71ToTxt/, 72ToTxt/, and 73ToTxt/) contains the following files:
• Two precompiled Java™ classes
• A tool shell script
• A tool batch script
The export file to use is determined by the older version of the Certificate System being migrated.
NOTE
Each compilation batch and shell script is dependent on a specific version of the Java
software development kit defined in its comments.
Certificate System migration import utilities are files named TxtToversion. To migrate the Certificate
Management System 7.x servers to Certificate System 8.0, use the TxtTo80 script. The import tool
directory (TxtTo80/) contains the following files:
• Two precompiled Java™ classes
• A tool shell script
Each compilation batch and shell script is dependent upon a specific version of the Java™ software
development kit as defined in the comments.
1.1.2. Certificate System Subsystems
Certificate System installations may exist on different platforms. Additionally, each Certificate System
installation may contain more than one type of subsystem or more than one instance of a type of
subsystem. The following subsystems may be present in a Certificate System installation:
• Certificate Authority (CA)
• Data Recovery Manager (DRM)

Considerations Before Migration
3
• Online Certificate Status Protocol (OCSP) Manager
• Registration Authority (RA)
• Token Key Service (TKS)
• Token Processing System (TPS)
Table 1.2, “Certificate System Subsystem Types and Platforms” defines the platforms and subsystems
supported by different versions of Certificate System:
Product (including service packs and hot-fixes) Subsystems Platforms
Red Hat Certificate System 7.1 CA
DRM
OCSP
TKS
TPS
Red Hat Enterprise Linux AS/ES 3
Red Hat Enterprise Linux AS/ES 4
Solaris 9
Red Hat Certificate System 7.2 CA
DRM
OCSP
TKS
TPS
Red Hat Enterprise Linux AS/ES 4 (i386)
Red Hat Enterprise Linux AS/ES 4 (AMD64,
Intel EM64T)
Solaris 9 (64-bit)
Red Hat Certificate System 7.3 CA
DRM
OCSP
RA
TKS
TPS
Red Hat Enterprise Linux AS/ES 4 (i386)
Red Hat Enterprise Linux AS/ES 4 (for AMD64
and Intel EM64T)
Solaris 9 (64-bit)
Red Hat Certificate System 8.0 CA
DRM
OCSP
RA
TKS
TPS
Red Hat Enterprise Linux 5.3 (i386)
Red Hat Enterprise Linux 5.3 (for AMD64 and
Intel EM64T)
Table 1.2. Certificate System Subsystem Types and Platforms
1.2. Considerations Before Migration
Since all migrations are unique to a deployment, it is strongly recommended that the entire migration
process be planned in advance. Here are some common issues related to migration.
The Migration Procedure
• Not all steps in the migration processes apply to every deployment. Follow only the steps which
apply to the deployment being migrated.
• Perform all steps in the migration procedure for every instance of each subsystem being migrated.
Always follow the steps for migration in the order which they are presented in the manual, even if
not every step needs to be performed.
• Perform each subsystem migration as a separate migration. Wait until one subsystem migration is
complete before starting the migration of the next subsystem.

Chapter 1. Introduction to Red Hat Certificate System Migration
4
Directory Names, Directory Locations, and FHS
In Certificate System 7.2, the Certificate System instance directories were changed from a single
server root to follow Filesystem Hierarchy Standards. The configuration files were then stored, for
example, in /var/lib while the log files were moved to /var/log, and the tools are located in /
usr/bin. Therefore, the server directories and file locations are very different in Certificate System
8.0 than Certificate System 7.1, if you migrate from that version.
Additionally, the directory names are different in Certificate System 8.0 than in Certificate System
7.2 or 7.3. In those earlier versions, the directories were prefaced with rhpki, such as /var/lib/
rhpki-ca/conf. In Certificate System 8.0, the directories are named with pki, such as /var/
lib/new_CA_instance/conf.
Setting File Permissions
• On Linux and UNIX systems, make sure that the file owner (user and group) and the file
permissions are correct when the file is copied between two instances. Also make sure that the
target machine allows the file transfer.
• The chmod command used in the examples have the permissions 00600 (octal, no sticky bit
permissions, user read/write permissions, no group permissions, no other permissions). These are
the recommended permissions, but are not required.
Extracting Data from a Hardware Security Module
While the migration procedure refers to extracting data from a hardware security module (HSM),
no Certificate System tool can extract public/private key pairs from an HSM because of Federal
Information Processing Standard (FIPS) 140-1, which protects the private key portion of an entry.
Contact the HSM vendor for information on how to extract data from an old HSM. Extracted keys
should not have any dependencies, such as nickname prefixes, on the old HSM.
IMPORTANT
For migration to work on a LunaSA HSM, then the following line must be added to the /
etc/Chrystoki.conf configuration file:
Misc { NetscapeCustomize=1023; }
Additionally, these two lines must be removed:
AppIdMajor=2;
AppIdMinor=4;
Updating Port Numbers
The default subsystems are installed and configured with a separate TCP/IP port for each service,
called port separation. Each Certificate System subsystem uses up to five ports:
• A standard port
• An SSL port for end users services
• An SSL port for agent services

Considerations Before Migration
5
• An SSL port for the administrative console or admin services
• A web server port (Tomcat for CA, DRM, OCSP, and TKS subsystems, Apache for the TPS and RA
subsystems)
However, Certificate System versions older than 8.0 used only three ports, a web server port, an
unsecure port, and a single SSL port. This means that special care needs to be taken when migrating
to Certificate System 8.0 from any Certificate System 7.x server. Either the port configuration must be
updated in the 7.x server configuration, or the Certificate System 8.0 subsystem has to be installed
using pkicreate to specify a single SSL port. Using pkicreate is described in the Installation
Guide, and reconfiguring ports is described in the Administrator's Guide.
Because port numbers are stored in the server.xml file, which is unaffected by subsystem
migration, port numbers can be changed between instances without difficulty.
About Usage Examples
All examples assume that a 7.3 instance is being migrated, so default directory paths and file names
correspond to the 7.3 subsystem versions. Make sure that the information in your migration steps
correspond to your appropriate version and platform.
All examples assume that the new passwords are the same as the old passwords.
Backing up Existing Data
Before migrating any Certificate System instance, back up the information for the Certificate System
instance, including the security databases in the alias/ directory and all data stored in the internal
LDAP database. When the backup process is complete, then stop the old Certificate System, Directory
Server, and Administration Server instances.

6

Chapter 2.
7
Setting up Certificate System 8.0
Subsystems
For every Certificate System 7.x subsystem which will be migrated, there must be a new Certificate
System 8.0 subsystem installed and properly configured.
2.1. Installing New Certificate System Subsystem Instances
The configuration of the new Certificate System 8.0 instances is extremely important. As mentioned
in Section 1.2, “Considerations Before Migration”, the instance names, directory locations, and port
numbers in Certificate System 8.0 are different than those in the Certificate System 7.x versions.
Since port numbers are easily updated in instances, the separated SSL ports in Certificate System
8.0 can be easily used since they enhance security. However, having different instance names makes
migration much more difficult because it changes the certificate names, directory paths, and database
names used by the instance. Therefore, the new Certificate System 8.0 instances must be specially
installed to reuse the original instance names.
The standard installation process described in the Certificate System Installation Guide will not work
for a typical migration scenario because it automatically uses version 8.0 instance settings. To install a
migration instance, use this procedure.
NOTE
There is an environment variable, DONT_RUN_PKICREATE, which stops the pkicreate
script from running automatically after the subsystems are installed. This allows the
default instances to be installed in user-defined installation directories, instead of the
default locations in /var/lib. To use custom directory locations, install the subsystems
through the ISO image with this environment variable set to block the pkicreate script.
1. Certificate System requires OpenJDK 1.6.0. On Red Hat Enterprise Linux systems, this JDK must
be installed separately.
The OpenJDK can be installed by using yum or by downloading the packages directly from http://
openjdk.java.net/install/. For example:
yum install java-1.6.0-openjdk
After installing the JDK, run /usr/sbin/alternatives as root to insure that the proper JDK
is available:
/usr/sbin/alternatives --config java
There are 3 programs which provide 'java'.
Selection Command
-----------------------------------------------
1 /usr/lib/jvm/jre-1.4.2-gcj/bin/java
2 /usr/lib/jvm/jre-1.6.0-openjdk/bin/java
*+ 3 /usr/lib/jvm/jre-1.6.0-sun.x86_64/bin/java
2. Install Red Hat Directory Server 8.1, if a directory service is not already available. For example:

Chapter 2. Setting up Certificate System 8.0 Subsystems
8
yum install redhat-ds
3. Install Apache if it is not already available. For example:
yum install httpd
4. Install mod_nss.
yum install mod_nss
5. Before installing any Red Hat Certificate System 8.0 packages, set an environment variable
which prevents the installation program from automatically creating the default instances. These
instances must be created manually so that they have the same settings as the 7.x instances.
export DONT_RUN_PKICREATE=1
6. Install the subsystem, management, and migration packages for the subsystem:
yum install pki-type pki-console pki-migrate
Each subsystem has its own package, and it is possible to install any or all subsystems on the
same machine. For example:
yum install pki-ca pki-kra pki-ra pki-ocsp pki-tks pki-tps pki-console pki-migrate
IMPORTANT
If you are installing Certificate System on multiple hosts, make sure that you always
set the DONT_RUN_PKICREATE before installing any packages, and then unset the
environment variable to run the pkicreate command manually with user-defined
settings.
7. Unset the DONT_RUN_PKICREATE environment variable, so that pkicreate can be run
manually.
export DONT_RUN_PKICREATE=0
8. Manually run the pkicreate command to create a new 8.0 subsystem instance for each and
every Certificate System 7.x instance that will be migrated. It is strongly recommended that the
new instance name is the same for the new version as for the original one.
The port settings are slightly different for the CA, DRM, OCSP, and TKS compared to the RA and
TPS because of the different kinds of administrative interfaces and web services that they use. For
example, to install a CA with the 7.2 and 7.3 instance name of rhpki-ca:
pkicreate -pki_instance_root=/var/lib -pki_instance_name=rhpki-ca -subsystem_type=ca -
agent_secure_port=9443 -ee_secure_port=9444 -admin_secure_port=9445 -unsecure_port=9180 -
tomcat_server_port=9701 -redirect conf=/etc/rhpki-ca -redirect logs=/var/log/rhpki-ca

Installing New Certificate System Subsystem Instances
9
Installing the DRM, OCSP, and TKS subsystems are similar to installing the CA, except for the
subsystem type and instance-specific settings, like the name and port numbers.
To install an RA with the 7.2 and 7.3 instance name of rhpki-ra:
pkicreate -pki_instance_root=/var/lib -pki_instance_name=rhpki-ra -subsystem_type=ra -
secure_port=12889 -non_clientauth_secure_port=12890 -unsecure_port=12888 -redirect conf=/
etc/rhpki-ra -redirect logs=/var/log/rhpki-ra
Installing the TPS subsystem is similar to installing the RA because it has a similar port setup. The
differences, obviously, include the subsystem type and instance-specific settings like the name
and port numbers.
NOTE
The default name for instances in 8.0 is pki-type, like pki-ca. In versions 7.2 and
7.3, the default naming scheme was rhpki-type. The examples for creating a new
instance use the 7.x naming convention, because it is easier to migrate between
instances of the same name.
The pkicreate command is described in more detail in the Certificate System Command-Line
Tools Guide.
9. When the installation process is complete, a URL to access this instance is printed to the screen
which gives the subsystem instances hostname, port, and a login PIN to access the configuration
wizard. For example:
PKI instance creation Utility ...
PKI instance creation completed ...
Starting pki-ca: [ OK ]
pki-ca (pid 17990) is running ...
'pki-ca' must still be CONFIGURED!
(see /var/log/pki-ca-install.log)
Before proceeding with the configuration, make sure
the firewall settings of this machine permit proper
access to this subsystem.
Please start the configuration by accessing:
http://server.example.com:9445/ca/admin/console/config/login?pin=Yc6EuvuY2OeezKeX7REk
After configuration, the server can be operated by the command:
/sbin/service pki-ca start | stop | restart
10. Go through the configuration wizard to set up the CA; this is described in detail in the Certificate
System Installation Guide.
11. Restart the new instance; this is required as part of the installation. For example:

Chapter 2. Setting up Certificate System 8.0 Subsystems
10
service new_CA_instance restart
12. Run pkicreate, configure, and restart every new instance which will be migrated on the server.
13. Once every instance has been created and configured, stop all of the new instances. The new
instance cannot be running when the migration process is started. For example:
service new_CA_instance stop
service new_DRM_instance stop
service new_RA_instance stop
service new_OCSP_instance stop
service new_TKS_instance stop
service new_TPS_instance stop
14. Last, stop the Red Hat Directory Server 8.1 and Administration Server instances used by the
Certificate System 8.0 instances.
service instance_name stop
service dirsrv-admin stop
15. Certificate System 8.0 automatically configures signed audit logging for every subsystem (except
the RA). However, Certificate System 7.x servers did not configure signed audit logging the same
way. The new instances, then, must be reconfigured to accommodate the migrated certificate
information.
The simplest option is to disable the signed audit logs in the Certificate System 8.0 instances.
Reset the signed audit log parameter to false:
log.instance.SignedAudit.enable=false
The other option is to re-enroll for new signed audit certificate for the migrated instance.
Requesting and retrieving certificates through the end users services for the CA is described in the
Using End User Services guide; the basic process is:
a. Generate a signing certificate request. For example:
certutil -R -k ec -g 256 -s "CN=CA auditSigningCert,O=Example Domain" -n
"auditSigningCert cert-new_CA_instance" -o request.cert -v 12 -d /var/
lib/new_CA_instance/alias -1 -7 -8
b. Submit the certificate to the Audit Signing Certificate Enrollment form or the Manual Log
Signing Certificate Enrollment form.
c. Retrieve the certificate from the end-entities pages, and install it in the migrated certificate
database.
certutil -A -n "auditSigningCert cert-new_CA_instance" -d /var/lib/new_CA_instance/
alias