pkispawn(8) PKI Instance Creation Utility pkispawn(8)NAMEpkispawn - Sets up an instance of Certificate Server.
SYNOPSISpkispawn-s <subsystem> -f <config_file> [-h] [-v] [-p <prefix>]
DESCRIPTION
Sets up an instance of Certificate Server. This utility creates any of
the Java-based Certificate Server subsystems (CA, KRA, OCSP, and TKS).
Note: A 389 Directory Server instance must be configured and running
before this script can be run. Certificate Server requires an
internal directory database. The default configuration assumes a
Directory Server instance running on the same machine on port
389. For more information on creating a Directory Server
instance, see setup-ds.pl(8).
Note: This utility creates only Java-based subsystems. The Apache-
based Certificate Server subsystems (RA and TPS) are created
using pkicreate.
An instance can contain multiple subsystems, although it may contain at
most one of each type of subsystem on a single machine. So, for exam‐
ple, an instance could contain CA and KRA subsystems, but not two CA
subsystems. To create an instance with a CA and a KRA, simply run
pkispawn twice, with values -s CA and -s KRA respectively.
The instances are created based on values for configuration parameters
in the default configuration (/etc/pki/default.cfg) and the user-pro‐
vided configuration file. The user-provided configuration file is read
after the default configuration file, so any parameters defined in that
file will override parameters in the default configuration file. In
general, most users will store only those parameters which are differ‐
ent from the default configuration in their user-provided configuration
file.
This configuration file contains directives that are divided into sec‐
tions for different subsystem types (such as [DEFAULT], [CA], and
[KRA]). These sections are stacked, so that parameters read in earlier
sections can be overwritten by parameters in later sections. For the
Java subsystems (CA, KRA, OCSP and TKS), the sections read are
[DEFAULT], [Tomcat] and the subsystem-type section ([CA], [KRA],
[OCSP], or [TKS]), in that order. This allows the ability to specify
parameters to be shared by all subsystems in [DEFAULT] or [Tomcat], and
system-specific upgrades in the [CA], [KRA], and other sections.
At a minimum, the user-defined configuration file must provide some
passwords needed for the install. An example configuration file is
provided in the EXAMPLES section below. For more information on the
default configuration file and the parameters it contains (and can be
customized), see pki_default.cfg(5).
The pkispawn run creates several different installation files that can
be referenced later, if need be:
* For Tomcat-based instances, a Tomcat instance is created at
/var/lib/pki/<pki_instance_name>, where pki_instance_name is
defined in the configuration file.
* A log file of pkispawn operations is written to
/var/log/pki/pki-<subsystem>-spawn.<timestamp>.log.
* A .p12 (PKCS #12) file containing a certificate for a subsys‐
tem administrator is stored in pki_client_dir.
When the utility is done running, the CA can be accessed by pointing a
browser to https://<hostname>:<pki_https_port>/. The agent pages can be
accessed by importing the CA certificate and administrator certificate
into the browser.
The Certificate Server instance can also be accessed using the pki com‐
mand line interface. See pki(1). For more extensive documentation on
how to use Certificate Server features, see the Red Hat Certificate
System Documentation at https://access.redhat.com/knowl‐
edge/docs/Red_Hat_Certificate_System/.
Instances created using pkispawn can be removed using pkidestroy. See
pkidestroy(8).
pkispawn supersedes and combines the functionality of pkicreate and
pkisilent, which were available in earlier releases of Certificate
Server. It is now possible to completely create and configure the Cer‐
tificate Server subsystem in a single step using pkispawn.
Although pkispawn can be used to install and configure an instance in a
single invocation, it can also still be directed to split this work
into separate 'installation' and 'configuration' tasks (e. g. - to sup‐
port an organization's policy where 'installation' and 'configuration'
tasks must be fulfilled by separate roles).
To run pkispawn for instance installation only, leave the configuration
parameter pki_skip_installation set to False (the default), and set the
configuration parameter pki_skip_configuration to True. This instance
must then be configured using either a pkispawn command line interface
(CLI) configuration, or a browser-based (GUI) configuration.
To configure an instance using the CLI-based configuration, set the
configuration parameter pki_skip_installation to True, leave the con‐
figuration parameter pki_skip_configuration to False (the default), and
run pkispawn for configuration only.
To configure an instance using the GUI-based configuration, launch a
browser, input the configuration URL located inside the
/var/log/pki/pki-<subsystem>-spawn.<timestamp>.log file, and fill-in
the desired/required information for each panel. The final panel will
instruct the user to restart the server.
Note: CLI-based configuration and GUI-based configuration go through
different code. There is additional code in the CLI-based con‐
figuration to support instances that contain more than one sub‐
system; the GUI-based configuration does not contain this code.
Consequently, GUI-based configuration must not be used to con‐
figure a PKI instance which contains more than one subsystem.
OPTIONS-s <subsystem>
Specifies the subsystem to be installed and configured, where
<subsystem> is CA, KRA, OCSP, or TKS.
-f <config_file>
Specifies the path to the user-defined configuration file. This
file contains differences between the default configuration and
the custom configuration.
-h, --help
Prints additional help information.
-v Displays verbose information about the installation. This flag
can be provided multiple times to increase verbosity. See
pkispawn-h for details.
INTERACTIVE MODE
If no options are specified, pkispawn will provide an interactive menu
to collect the parameters needed to install the Certificate Server
instance. Note that only the most basic installation options are pro‐
vided. This includes root CAs, KRAs, OCSPs and TKS, connecting to the
LDAP port of a directory server. More complicated setups such as:
cloned subsystems, subordinate or externally signed CAs, subsystems
that connect to the directory server using LDAPS, and subsystems that
are customized beyond the options described below - require the use of
a configuration file with the -f option.
The interactive option is most useful for those users getting familiar
with Certificate Server. The parameters collected are written to the
installation file of the subsystem, which can be found at /etc/syscon‐
fig/pki/tomcat/<instance name>/<subsystem>/deployment.cfg.
The following parameters are queried interactively during the installa‐
tion process:
Subsystem Type
Subsystem (CA/KRA/OCSP/TKS):
the type of subsystem to be installed. Prompted when the -s
option is not specified. The default value chosen is CA.
Instance Specific Parameters
Instance name:
the name of the tomcat instance in which the subsystem is to be
installed. The default value is pki-tomcat.
Note: Only one subsystem of a given type (CA, KRA, OCSP, TKS)
can exist within a given instance.
HTTP port:
the HTTP port of the Tomcat instance. The default value is 8080.
Secure HTTP port:
the HTTPS port of the Tomcat instance. The default value is
8443.
AJP port:
the AJP port of the Tomcat instance. The default value is 8009.
Management port:
the management port of the Tomcat instance. The default value is
8005.
Administrative User Parameters
Username:
the username of the administrator of this subsystem. The default
value is <ca/kra/tks/ocsp>admin.
Password:
password for the administrator user.
Import certificate:
An optional parameter that can be used to import an already
available CA admin certificate into this instance.
Export certificate:
setup the path where the admin certificate of this <subsystem>
should be stored. The default value is /root/.dogtag/pki-tom‐
cat/<ca/kra/tks/ocsp>_admin.cert.
Directory Server Parameters
Hostname:
Hostname of the directory server instance. The default value is
the hostname of the system.
Port: Port for the directory server instance. The default value is
389.
Base DN:
the Base DN to be used for the internal database for this sub‐
system. The default value is o=pki-tomcat-<subsystem>.
Bind DN:
the bind DN required to connect for the directory server. This
user must have sufficient permissions to install the required
schema and database. The default value is cn=Directory Manager.
Password:
password for the bind DN.
Security Domain Parameters
Name: the name of the security domain. Required only if installing a
root CA. Default value: <DNS domain name> Security Domain.
Hostname:
the hostname for the security domain CA. Required only for non-
CA subsystems. The default value is the hostname of this system.
Secure HTTP port:
the https port for the security domain. Required only for non-CA
subsystems. The default value is 8443.
Username:
the username of the security domain administrator of the CA.
Required only for non-CA subsystems. The default value is caad‐
min.
Password:
password for the security domain administrator. Required for all
subsystems that are not root CAs.
EXAMPLES
CA using default configuration
pkispawn-s CA -f myconfig.txt
where myconfig.txt contains the following text:
[DEFAULT]
pki_admin_password=password123
pki_client_pkcs12_password=password123
pki_ds_password=password123
Prior to running this command, a Directory Server instance should be
created and running. This command assumes that the Directory Server
instance is using its default configuration:
* Installed on the local machine
* Listening on port 389
* The user is cn=Directory Manager, with the password specified
in pki_ds_password
This invocation of pkispawn creates a Tomcat instance containing
a CA running on the local machine with secure port 8443 and
unsecure port 8080. To access this CA, simply point a browser
to https://<hostname>:8443.
The instance name (defined by pki_instance_name) is pki-tomcat, and it
is located at /var/lib/pki/pki-tomcat. Logs for the instance are
located at /var/log/pki/pki-tomcat, and an installation log is written
to /var/log/pki/pki-<subsystem>-spawn.<timestamp>.log.
A PKCS #12 file containing the administrator certificate is created in
$HOME/.dogtag/pki-tomcat. This PKCS #12 file uses the password desig‐
nated by pki_client_pkcs12_password in the configuration file.
To access the agent pages, first import the CA certificate by accessing
the CA End Entity Pages and clicking on the Retrieval Tab. Be sure to
trust the CA certificate. Then, import the administrator certificate
in the PKCS #12 file.
KRA, OCSP, or TKS using default configuration
pkispawn-s <subsystem> -f myconfig.txt
where subsystem is KRA, OCSP, or TKS, and myconfig.txt contains the
following text:
[DEFAULT]
pki_admin_password=password123
pki_client_pkcs12_password=password123
pki_ds_password=password123
pki_security_domain_password=password123
The pki_security_domain_password is the admin password of the CA
installed in the same default instance. This command should be run
after a CA is installed. This installs another subsystem within the
same default instance using the certificate generated for the CA admin‐
istrator for the subsystem's administrator. This allows a user to
access both subsystems on the browser with a single administrator cer‐
tificate. To access the new subsystem's functionality, simply point
the browser to https://<hostname>:8443 and click the relevant top-level
links.
KRA, OCSP, or TKS connecting to a remote CA
pkispawn-s <subsystem> -f myconfig.txt
where subsystem is KRA, OCSP, or TKS, and myconfig.txt contains the
following text:
[DEFAULT]
pki_admin_password=password123
pki_client_pkcs12_password=password123
pki_ds_password=password123
pki_security_domain_password=password123
pki_security_domain_hostname=<ca_hostname>
pki_security_domain_https_port=<ca_port>
pki_security_domain_user=caadmin
pki_issuing_ca_uri=https://<ca_hostname>:<ca_port>
[KRA]
pki_import_admin_cert=False
A remote CA is one where the CA resides in another Certificate Server
instance, either on the local machine or a remote machine. In this
case, myconfig.txt must specify the connection information for the
remote CA and the information about the security domain (the trusted
collection of subsystems within an instance).
The subsystem section is [KRA], [OCSP], or [TKS]. This example assumes
that the specified CA hosts the security domain. The CA must be run‐
ning and accessible.
A new administrator certificate is generated for the new subsystem and
stored in a PKCS #12 file in $HOME/.dogtag/pki-tomcat.
Installing a CA clone
pkispawn-s CA -f myconfig.txt
where myconfig.txt contains the following text:
[DEFAULT]
pki_admin_password=password123
pki_client_pkcs12_password=password123
pki_ds_password=password123
pki_security_domain_password=password123
pki_security_domain_hostname=<master_ca_hostname>
pki_security_domain_https_port=<master_ca_https_port>
pki_security_domain_user=caadmin
[CA]
pki_clone=True
pki_clone_pkcs12_password=password123
pki_clone_pkcs12_path=<path_to_pkcs12_file>
pki_clone_replicate_schema=True
pki_clone_uri=https://<master_ca_hostname>:<master_ca_https_port>
A cloned CA is a CA which uses the same signing, OCSP signing, and
audit signing certificates as the master CA, but issues certificates
within a different serial number range. It has its own internal data‐
base -- separate from the master CA database -- but using the same base
DN, that keeps in sync with the master CA through replication agree‐
ments between the databases. This is very useful for load sharing and
disaster recovery. To create a clone, the myconfig.txt uses pki_clone-*
parameters in its [CA] section which identify the original CA to use as
a master template. Additionally, it connects to the master CA as a
remote CA and uses its security domain.
Before the clone can be generated, the Directory Server must be created
that is separate from the master CA's Directory Server. The example
assumes that the master CA and cloned CA are on different machines, and
that their Directory Servers are on port 389. In addition, the mas‐
ter's system certs and keys have been stored in a PKCS #12 file that is
copied over to the clone subsystem in the location specified in
<path_to_pkcs12_file>. This file is created when the master CA is
installed; it can also be generated using PKCS12Export. The file needs
to be readable by the user the Certificate Server runs as (by default,
pkiuser) and be given the SELinux context pki_tomcat_cert_t.
Installing a KRA, OCSP, or TKS clone
pkispawn-s <subsystem> -f myconfig.txt
where subsystem is KRA, OCSP, or TKS, and myconfig.txt contains the
following text:
[DEFAULT]
pki_admin_password=password123
pki_client_pkcs12_password=password123
pki_ds_password=password123
pki_security_domain_password=password123
pki_security_domain_hostname=<master_ca_hostname>
pki_security_domain_https_port=<master_ca_https_port>
pki_security_domain_user=caadmin
[KRA]
pki_clone=True
pki_clone_pkcs12_password=password123
pki_clone_pkcs12_path=<path_to_pkcs12_file>
pki_clone_replicate_schema=True
pki_clone_uri=https://<master_kra_host>:<master_kra_https_port>
pki_issuing_ca=https://<ca_hostname>:<ca_https_port>
As with a CA clone, a KRA, OCSP, or TKS clone uses the same certifi‐
cates and basic configuration as the original subsystem. The configura‐
tion points to the original subsystem to copy its configuration. This
example also assumes that the CA is on a remote machine and specifies
the CA and security domain information.
The subsystem section is [KRA], [OCSP], or [TKS].
Installing a subordinate CA
pkispawn-s CA -f myconfig.txt
where myconfig.txt contains the following text:
[DEFAULT]
pki_admin_password=password123
pki_client_pkcs12_password=password123
pki_ds_password=password123
pki_security_domain_password=password123
pki_security_domain_hostname=<security_domain_ca_hostname>
pki_security_domain_https_port=<security_domain_ca_https_port>
pki_security_domain_user=caadmin
[CA]
pki_subordinate=True
pki_issuing_ca=https://<master_ca_hostname>:<master_ca_https_port>
pki_ca_signing_subject_dn=cn=CA Subordinate Signing ,o=example.com
A sub-CA derives its certificate configuration -- such as allowed
extensions and validity periods -- from a superior or root CA. Other‐
wise, the configuration of the CA is independent of the root CA, so it
is its own instance rather than a clone. A sub-CA is configured using
the pki_subordinate parameter and a pointer to the CA which issues the
sub-CA's certificates.
Note: The value of pki_ca_signing_subject_dn of a subordinate CA should
be different from the root CA's signing subject DN.
Installing an externally signed CA
pkispawn-s CA -f myconfig.txt
This is a two step process.
In the first step, a certificate signing request (CSR) is generated for
the signing certificate and myconfig.txt contains the following text:
[DEFAULT]
pki_admin_password=password123
pki_client_pkcs12_password=password123
pki_ds_password=password123
pki_security_domain_password=password123
[CA]
pki_external=True
pki_external_csr_path=/tmp/ca_signing.csr
pki_ca_signing_subject_dn=cn=CA Signing,ou=External,o=example.com
The CSR is written to pki_external_csr_path. The pki_ca_signing_sub‐
ject_dn should be different from the subject DN of the external CA that
is signing the request. The pki_ca_signing_subject_dn parameter can be
used to specify the signing certificate's subject DN.
The CSR is then submitted to the external CA, and the resulting cer‐
tificate and certificate chain are saved to files on the system.
In the second step, the configuration file has been modified to install
the issued certificates. In place of the original CSR, the configura‐
tion file now points to the issued CA certificate and certificate
chain. There is also a flag to indicate that this completes the instal‐
lation process (pki_external_step_two).
[DEFAULT]
pki_admin_password=password123
pki_client_pkcs12_password=password123
pki_ds_password=password123
pki_security_domain_password=password123
[CA]
pki_external=True
pki_external_ca_cert_chain_path=/tmp/ca_cert_chain.cert
pki_external_ca_cert_path=/tmp/ca_signing.cert
pki_external_step_two=True
pki_ca_signing_subject_dn=cn=CA Signing Certificate,ou=External,o=example.com
Then, the pkispawn command is run again:
pkispawn-s CA -f myconfig.txt
Execution management of a PKI instance (start, stop, status, etc.)
To start all 389 instances (local PKI databases):
systemctl start dirsrv.target
To stop all 389 instances (local PKI databases):
systemctl stop dirsrv.target
To restart all 389 instances (local PKI databases):
systemctl restart dirsrv.target
To obtain the status of all 389 instances (local PKI databases):
systemctl status dirsrv.target
To start a PKI instance named <pki_instance_name>:
systemctl start pki-tomcatd@<pki_instance_name>.service
To stop a PKI instance named <pki_instance_name>:
systemctl stop pki-tomcatd@<pki_instance_name>.service
To restart a PKI instance named <pki_instance_name>:
systemctl restart pki-tomcatd@<pki_instance_name>.service
To obtain the status of a PKI instance named <pki_instance_name>:
systemctl status pki-tomcatd@<pki_instance_name>.service
To obtain a detailed status of a Tomcat PKI instance named
<pki_instance_name>:
pkidaemon status tomcat <pki_instance_name>
To obtain a detailed status of all Tomcat PKI instances:
pkidaemon status tomcat
To enable a PKI instance named <pki_instance_name> to be started auto‐
matically upon system reboot:
systemctl enable pki-tomcatd@<pki_instance_name>.service
BUGS
Report bugs to http://bugzilla.redhat.com.
AUTHORS
Ade Lee <alee@redhat.com>. pkispawn was written by the Certificate
Server project.
COPYRIGHT
Copyright (c) 2012 Red Hat, Inc. This is licensed under the GNU General
Public License, version 2 (GPLv2). A copy of this license is available
at http://www.gnu.org/licenses/old-licenses/gpl-2.0.txt.
SEE ALSOpkidestroy(8), pki_default.cfg(5), pki(1), setup-ds.pl(8)version 1.0 December 13, 2012 pkispawn(8)
