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
pkispawnautomatically 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
-soption - Specifies the subsystem to be created and configured: CA, KRA, OCSP, TKS, or TPS
- the
-foption - 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.
