Chapter 1. The pkispawn and pkidestroy Utilities

The Certificate System includes two command-line utilities to create and remove subsystems: pkispawn and pkidestroy.

Note

In previous versions of Certificate System, installation and configuration were split into two separate tasks managed by the pkicreate and pkisilent utilities. In Certificate System version 9 and later, the single pkispawn utility now manages all these operations.
The pkiremove utility was used to remove subsystems in previous Certificate System versions. The utility is now replaced with pkidestroy.

1.1. The pkispawn Utility

The pkispawn utility creates a Certificate System subsystem and configures it. It supports two installation modes:
  • non-interactive mode, where the user supplies installation and configuration settings using command-line options and a configuration file
  • interactive mode, where pkispawn automatically prompts the user for basic information required for installation
Both installation modes can also be combined, allowing you to pass some configuration directly to pkispawn and let the utility prompt you for other settings interactively. For example, if you add the -s option to pkispawn, but not the -f option to provide a configuration file, the installation uses default configuration settings from the /etc/pki/default.cfg file and interactively prompts you for any additional required custom information, such as passwords.
This section provides an overview of how to use pkispawn to install Certificate System subsystems. For more information about pkispawn, see the pkispawn(8) man page. The man page includes various examples of pkispawn usage.

1.1.1. Non-interactive pkispawn Mode

The utility accepts only a few command-line options because the configuration parameters are supplied through a pre-created configuration file.
To create and configure a subsystem using pkispawn, run the utility with the following options:
the -s option
Specifies the subsystem to be created and configured: CA, KRA, OCSP, TKS, or TPS
the -f option
Specifies the path to the configuration file
For example, the following command creates a CA subsystem based on the myconfig.txt file:
# pkispawn -s CA -f myconfig.txt

The Configuration File for pkispawn

Certificate System stores some default configuration settings in the /etc/pki/default.cfg file. To create a custom configuration file that can be supplied to the pkispawn utility, copy default.cfg to a different location. Then modify the copied file to define the configuration settings you want pkispawn to apply to the new subsystem.
The custom configuration file takes precedence over the default default.cfg file. Common practice is to only store parameters that are different from the default configuration in the user-provided custom configuration file.
The default.cfg file is divided into several sections:
General sections
General sections contain the default and Tomcat configuration options. For example:
[DEFAULT]
pki_admin_password=
pki_backup_password=
pki_client_database_password=
pki_client_pkcs12_password=
pki_ds_password=
pki_replication_password=
pki_security_domain_password=
pki_token_password=
[Tomcat]
pki_clone_pkcs12_password=
Subsystem-specific sections
Subsystem sections contain subsystem-specific configuration options. For example:
[CA]
pki_admin_name=caadmin
pki_admin_email=caadmin@example.com
Configuration defined in later sections takes precedence over configuration in earlier sections. For example, configuration in the subsystem-specific sections takes precedence over the Tomcat section, which then takes precedence over configuration in the DEFAULT section. This behavior allows you to specify parameters shared by all subsystems in the DEFAULT or Tomcat sections, and options specific for a particular subsystem in the section for that subsystem.

Note

A copy of the default.cfg file is saved within the created subsystem after running pkispawn. The copy is then used when removing the subsystem with pkidestroy.
For various example custom configuration files that can be supplied to pkispawn, see the pkispawn(8) man page. For more information about default.cfg, see the pki_default.cfg(5) man page.

1.1.2. Interactive pkispawn Mode

If you do not supply any configuration options to pkispawn, the utility enters interactive installation mode and automatically prompts you for basic required installation options. The interactive pkispawn installation mode is suitable for users who are getting familiar with Certificate System. For a list of the basic options used for the interactive mode, see the pkispawn(8) man page.
Other configuration options are not available with the interactive installation. If you want to use advanced settings, provide a configuration file to pkispawn using the -f option, as described in Section 1.1.1, “Non-interactive pkispawn Mode”.
The parameters specified during the interactive installation mode are saved in the /etc/sysconfig/pki/tomcat/instance_name/subsystem/deployment.cfg file.

1.1.3. Creating Multiple Subsystems Within a Single Instance

A single Tomcat instance can contain multiple subsystems. However, one instance can only contain one of each type of subsystem. For example, an instance can contain one CA and one KRA subsystem, but not two CA or two KRA subsystems.
To create an instance with multiple subsystems, run pkispawn multiple times and specify a different subsystem each time. For example, to create an instance with a CA and a KRA, run the pkispawn -s CA command and then the pkispawn -s KRA command.

1.1.4. Shared and Non-shared Instances

With a shared PKI instance, every subsystem within the shared instance uses the same instance name and ports. With a non-shared PKI instance, the subsystems use unique instance names and ports if the instance resides on the same machine as another PKI instance. When installing such PKI instances, define the required parameters in the pkispawn configuration file.

Note

An instance is always created as a non-shared instance, regardless of what type of subsystem is installed into it. An instance becomes a shared instance after a second subsystem of a different type is installed into it.
To install a shared Tomcat instance on a machine different from the machine on which the CA is installed, see the KRA, OCSP, or TKS connecting to a remote CA example in the pkispawn(1) man page for the parameters required in the KRA, OCSP, TKS, or TPS configuration file. If you want to specify a custom name for the PKI instance, also define the pki_instance_name parameter in the DEFAULT section of the file.
To install a non-shared Tomcat instance on the same machine on which the CA is installed, apart from following the mentioned configuration example, also define the unique instance names and ports. To do this, use the following parameters in the KRA, OCSP, TKS, or TPS configuration file:
[DEFAULT]
pki_instance_name=unique_value
pki_http_port=unique_value
pki_https_port=unique_value
[Tomcat]
pki_ajp_port=unique_value
pki_tomcat_server=unique_value