Creating Additional Subsystem Instances - Red Hat Certificate System 8.0 Install Guide

IMPORTANT

Chapter 5. Creating Additional Subsystem Instances

The number of subsystems that you have is flexible. There can be a single instance, there can be multiple instances on the same machine, or there can be multiple instances on multiple servers. Creating additional subsystem instances is similar to installing and configuring the default instances; there is a script to run to create a basic installation and then an HTML-based configuration wizard to complete the setup for the instance.

All additional CA, RA, DRM, OCSP, TKS, and TPS instances are installed by running a special tool, pkicreate. After that, they are configured through the HTML-based administration page. For more information on pkicreate, see the Certificate System Command-Line Tools Guide.

TIP

Existing instances can be duplicated (cloned) for load balancing for heavily trafficked servers and for failover support. Cloning is described in Chapter 6, Cloning Subsystems.

5.1. About pkicreate

Certificate System subsystem instances are created and defined using a script called pkicreate. This script is run automatically when the subsystem packages are first installed, and it creates the default subsystem instances with their predefined settings.

The pkicreate script can be invoked after the packages are installed to create additional individual subsystem instances, with user-defined settings like the configuration and log directories and port numbers. After the instance is created, it is then configured through the HTML-based configuration wizard or by using the pkisilent script.

The syntax for pkicreate is slightly different between subsystems because of the different port configurations. The CA, OCSP, DRM, and TKS all have three SSL service ports and an unsecure service port, while the RA and TPS have two SSL service ports and an unsecure service port.

Example 5.1. Syntax for Creating a CA, OCSP, DRM, or TKS

pkicreate -pki_instance_root=/directory/path -subsystem_type=type -pki-

instance_name=instance_ID -secure_port=SSLport | {-agent_secure_port=SSLport - ee_secure_port=SSLport -admin_secure_port=SSLport -

ee_secure_client_auth_port=SSLport_CA_only} -unsecure_port=port - tomcat_server_port=port [-user=user_name] [-group=group_name] [- redirect_conf=conf_directory] [-redirect_logs=log_directory]

Example 5.2. Syntax for Creating an RA or TPS

pkicreate -pki_instance_root=/directory/path -subsystem_type=type -pki- instance_name=instance_ID -secure_port=SSLport -

non_clientauth_secure_port=SSLport -unsecure_port=port [-user=user_name] [- group=group_name] [-redirect_conf=conf_directory] [-

TIP

Table 5.1. pkicreate Parameters

Parameter Description

pki_instance_root Gives the full path to the new instance

configuration directory.

subsystem_type Gives the type of subsystem being created.

pki_instance_name Gives the name of the new instance. Instance

names must be unique on a single machine, but do not have to be unique within the security domain (since instances are identified by hostname and port, not instance name).

secure_port Sets a single SSL port number for the subsystem.

This parameter is required if port separation is not configured, meaning that separate ports are not assigned for the administrator, agent, and end-entities services.

agent_secure_port[a] Sets the SSL port for the agent web services. If

this is specified, then both ee_secure_port and adm in_secure_port must be specified. For CAs only, an end-entities client authentication port is also required with the

ee_secure_client_auth_port option. ee_secure_port[a] Sets the SSL port for the end-entities web

services. If this is specified, then both agent_secure_port and

adm in_secure_port must be specified. For CAs only, an end-entities client authentication port is also required with the

ee_secure_client_auth_port option. ee_secure_client_auth_port[a] For CAs only. Sets the SSL port for the end-entity

client authentication. If this is specified, then ee_secure_port, agent_secure_port, and adm in_secure_port must be specified. admin_secure_port[a] Sets the SSL port number for the administrator

services, usually the pkiconsole. If this is specified, then both agent_secure_port and ee_secure_port must be specified. For CAs only, an end-entities client authentication port is also required with the

ee_secure_client_auth_port option. non_clientauth_secure_port[a] Sets the end entities SSL port for RA and TPS

subsystems.

unsecure_port[a] Sets the regular port number. If this is not set, the

number is randomly generated. Still, it is

recommended that administrators set this value to make sure there are no conflicts with SELinux labels for other services.

tomcat_server_port[a] Sets the port number for the Tomcat web server

new instance.

redirect_logs Sets the location for the log files for the new

instance.

user Sets the user as which the Certificate System

instance will run. This option must be set.

group Sets the group as which the Certificate System

instance will run. This option must be set.

For more information on the pkicreate tool options, see the Certificate System Command-Line Tools Guide.

5.2. Running pkicreate for a Single SSL Port

1. Run the pkicreate command, specifying the type of subsystem being created, the configuration directory, instance name, and port numbers. For example, this created a second DRM instance:

pkicreate -pki_instance_root=/var/lib -subsystem_type=kra -

pki_instance_name=pki-drm2 -secure_port=10543 -unsecure_port=10180 - tomcat_server_port=1802 -verbose

2. When the instance is successfully created, the process returns a URL for the HTML configuration page. For example:

http://server.example.com:10180/kra/admin/console/config/login? pin=nt2z2keqcqAZiBRBGLDf

TIP

The configuration URL is written to the end of the instance's installation file,

/var/log/subsystem_name-install.log. This log is also useful for debugging an instance.

3. Open the new instance URL, and go through the configuration wizard as described in Chapter 3, Installation and Configuration. Supply the security domain, CA, instance ID, internal LDAP

database, and agent information.

4. When the configuration is complete, restart the subsystem. service instance_ID restart

5.3. Running pkicreate with Port Separation

To create an instance with three separate ports for the different subsystem services, run pkicreate with three options which specify the services ports: -adm in_secure_port, -agent_secure_port, and -ee_secure_port. For CAs only, there is an additional port for end-entity client authentication, - ee_secure_client_auth_port.

Separated SSL ports is the default instance configuration because it is more secure than using a single [a] The p o rts selected fo r the new instance sho uld no t co nflict with any o ther p o rts assig ned o n the ho st o r SELinux. Check the

/etc/services file to see p o rt assig nments fo r the system. Then, run semanage port -l |grep port# to check SELinux; if there is no o utp ut, then there is no co nflict with SELinux assig nments.

SSL port.

1. Run the pkicreate command. For example:

pkicreate -pki_instance_root=/var/lib -subsystem_type=ca -

pki_instance_name=pki-ca2 -admin_secure_port=9545 -agent_secure_port-9544 - ee_secure_port=9543 -ee_secure_client_auth_port=9546 -unsecure_port=9180 - tomcat_server_port=1802 -verbose