path: root/base/server/man/man8/pkispawn.8

.\" First parameter, NAME, should be all caps
.\" Second parameter, SECTION, should be 1-8, maybe w/ subsection
.\" other parameters are allowed: see man(7), man(1)
.TH pkispawn 8 "December 13, 2012" "version 1.0" "PKI Instance Creation Utility" Ade Lee
.\" Please adjust this date whenever revising the man page.
.\"
.\" Some roff macros, for reference:
.\" .nh        disable hyphenation
.\" .hy        enable hyphenation
.\" .ad l      left justify
.\" .ad b      justify to both left and right margins
.\" .nf        disable filling
.\" .fi        enable filling
.\" .br        insert line break
.\" .sp <n>    insert n+1 empty lines
.\" for man page specific macros, see man(7)
.SH NAME
pkispawn \- Sets up an instance of Certificate Server.

.SH SYNOPSIS
pkispawn \-s <subsystem> \-f <config_file> [\-h] [\-v] [\-p <prefix>]

.SH DESCRIPTION
Sets up a Certificate Server subsystem (CA, KRA, OCSP, TKS, or TPS) in a
Tomcat instance.
.TP
\fBNote:\fP 
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
.B setup-ds.pl(8).
.PP
An instance can contain multiple subsystems, although it may contain at most one of each type of subsystem on a single machine.  So, for example, 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 
.I -s CA 
and 
.I -s KRA 
respectively.
.PP
The instances are created based on values for configuration parameters in the default configuration (/etc/pki/default.cfg) and the user-provided 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 different from the default configuration in their user-provided configuration file.
.PP
This configuration file contains parameters that are grouped into sections.
These sections are stacked, so that parameters defined in earlier sections can
be overwritten by parameters defined in later sections. The sections are read
in the following order: [DEFAULT], [Tomcat], and the subsystem section ([CA],
[KRA], [OCSP], [TKS], or [TPS]). This allows the ability to specify parameters
to be shared by all subsystems in [DEFAULT] or [Tomcat], and system-specific
customization.

.TP
\fBNote:\fP
Any non-password related parameter values in the configuration file that needs to contain a \fB%\fP character must be properly escaped.  For example, a value of \fBfoo%bar\fP would be specified as \fBfoo%%bar\fP in the configuration file.
.PP
At a minimum, the user-defined configuration file must provide some passwords needed for the install.  An example configuration file is provided in the 
.B EXAMPLES
section below.  For more information on the default configuration file and the parameters it contains (and can be customized), see
.B pki_default.cfg(5).
.PP
The \fBpkispawn\fP run creates several different installation files that can be referenced later, if need be:
.IP
* For Tomcat-based instances, a Tomcat instance is created at \fT/var/lib/pki/<pki_instance_name>\fP, where pki_instance_name is defined in the configuration file.  
.IP
* A log file of \fBpkispawn\fP operations is written to \fI/var/log/pki/pki-<subsystem>-spawn.<timestamp>.log\fP.  
.IP
* A .p12 (PKCS #12) file containing a certificate for a subsystem administrator is stored in pki_client_dir. 
.PP
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. 
.PP
The Certificate Server instance can also be accessed using the \fBpki\fP command line interface.  See 
\fBpki(1)\fP. For more extensive documentation on how to use Certificate Server features, see the Red Hat Certificate System Documentation at https://access.redhat.com/knowledge/docs/Red_Hat_Certificate_System/.
.PP
Instances created using \fBpkispawn\fP can be removed using \fBpkidestroy\fP.  See
.BR pkidestroy(8).
.PP
\fBpkispawn\fP supersedes and combines the functionality of \fBpkicreate\fP and \fBpkisilent\fP, which were available in earlier releases of Certificate Server.  It is now possible to completely create and configure the Certificate Server subsystem in a single step using \fBpkispawn\fP.
.TP
\fBNote:\fP 
Previously, as an alternative to using \fBpkisilent\fP to perform a non-interactive batch configuration, a PKI instance could be interactively configured by a GUI-based configuration wizard via a Firefox browser.  GUI-based configuration of a PKI instance is unavailable in this version of the product.
.SH OPTIONS
.TP
.B -s <subsystem>
Specifies the subsystem to be installed and configured, where <subsystem> is CA, KRA, OCSP, TKS, or TPS.
.TP
.B -f <config_file>
Specifies the path to the user-defined configuration file.  This file contains differences between the default configuration and the custom configuration.
.TP
.B --precheck
Execute pre-checks and exit.
.TP
.B -h, --help
Prints additional help information.
.TP
.B -v
Displays verbose information about the installation.  This flag can be provided multiple times to increase verbosity.  See
.B pkispawn -h 
for details.

.SH INTERACTIVE MODE
.PP
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 provided. This
includes root CA, KRA, OCSP, TKS, and TPS connecting to an existing
directory server. More advanced setups such as cloned subsystems,
subordinate or externally signed CA, 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.

.PP
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 \fB/etc/sysconfig/pki/tomcat/<instance name>/<subsystem>/deployment.cfg.\fP
.PP
The following parameters are queried interactively during the installation process:
.PP
\fBSubsystem Type\fP
.TP
\fISubsystem (CA/KRA/OCSP/TKS/TPS):\fP
the type of subsystem to be installed. Prompted when the \-s option is not specified.  The default value chosen is CA.
.PP
\fBInstance Specific Parameters\fP
.TP
\fIInstance name:\fP
the name of the tomcat instance in which the subsystem is to be installed. The default value is pki-tomcat.
.br
\fBNote:\fP Only one subsystem of a given type (CA, KRA, OCSP, TKS, TPS) can exist within a given instance.
.TP
\fIHTTP port:\fP
the HTTP port of the Tomcat instance. The default value is 8080.
.TP
\fISecure HTTP port:\fP
the HTTPS port of the Tomcat instance. The default value is 8443.
.TP
\fIAJP port:\fP
the AJP port of the Tomcat instance. The default value is 8009.
.TP
\fIManagement port:\fP
the management port of the Tomcat instance. The default value is 8005.
.TP
\fBNote:\fP When deploying a new subsystem into an existing instance, pkispawn will attempt to read the ports from \fBdeployment.cfg\fP files stored for previously installed subsystems for this instance.  If successful, the installer will not prompt for these ports. 
.PP
\fBAdministrative User Parameters\fP
.TP
\fIUsername:\fP
the username of the administrator of this subsystem. The default value is <ca/kra/ocsp/tks/tps>admin.
.TP
\fIPassword:\fP
password for the administrator user.
.TP
\fIImport certificate:\fP
An optional parameter that can be used to import an already available CA admin certificate into this instance.
.TP
\fIExport certificate:\fP
setup the path where the admin certificate of this <subsystem> should be stored. The default value is $HOME/.dogtag/pki-tomcat/<ca/kra/ocsp/tks/tps>_admin.cert.
.PP
\fBDirectory Server Parameters\fP
.TP
\fIHostname:\fP
Hostname of the directory server instance.  The default value is the hostname of the system.
.TP
\fIUse a secure LDAPS connection?\fP
Answering yes to this question will cause prompts for \fISecure LDAPS Port:\fP and \fIDirectory Server CA certificate pem file:\fP.  Answering no to this question will cause a prompt for \fILDAP Port\fP.  The initial default value for this question is no.
.TP
\fISecure LDAPS Port:\fP
Secure LDAPS port for the directory server instance. The default value is 636.
.TP
\fIDirectory Server CA certificate pem file:\fP
The fully-qualified path including the filename of the file which contains an exported copy of the Directory Server's CA certificate (e. g. - $HOME/dscacert.pem).  This file must exist prior to \fBpkispawn\fP being able to utilize it.  For details on creation of this file see the
.B EXAMPLES
section below entitled
.B Installing a CA connecting securely to a Directory Server via LDAPS.
.
.TP
\fILDAP Port:\fP
LDAP port for the directory server instance. The default value is 389.
.TP
\fIBase DN:\fP
the Base DN to be used for the internal database for this subsystem. The default value is o=pki-tomcat-<subsystem>.
.TP
\fIBind DN:\fP
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.
.TP
\fIPassword:\fP
password for the bind DN.
.PP
\fBSecurity Domain Parameters\fP
.TP
\fIName:\fP
the name of the security domain. Required only if installing a root CA. Default value: <DNS domain name> Security Domain.
.TP
\fIHostname:\fP
the hostname for the security domain CA. Required only for non-CA subsystems. The default value is the hostname of this system.
.TP
\fISecure HTTP port:\fP
the https port for the security domain. Required only for non-CA subsystems. The default value is 8443.
.TP
\fIUsername:\fP
the username of the security domain administrator of the CA. Required only for non-CA subsystems. The default value is caadmin.
.TP
\fIPassword:\fP
password for the security domain administrator. Required for all subsystems that are not root CAs.

.SH PRE-CHECK MODE
.PP
This option is only available when pkispawn is invoked in a non-interactive mode.
When the \fB--precheck\fP option is provided, a set of basic tests are performed to
ensure that the parameters provided to pkispawn are valid and consistent.

pkispawn will then exit with an exit code of 0 on success, or 1 on failure.  This
mode can be used to perform basic tests prior to doing any actual installation of
the Certificate Server instance.

Flags are available to disable specific tests.  For instance, one might want to
disable validation of the credentials for the internal database user if the
directory server instance has not yet been created.

See \fB pki_default.cfg(5) \fP for more details about available flags.

.SH EXAMPLES

.SS Installing a root CA
.BR
.PP
To install a root CA in a new instance execute the following command:

.IP
\x'-1'\fBpkispawn \-s CA \-f myconfig.txt\fR

.PP
where \fImyconfig.txt\fP contains the following text:

.IP
.nf
[DEFAULT]
pki_admin_password=\fISecret123\fP
pki_client_pkcs12_password=\fISecret123\fP
pki_ds_password=\fISecret123\fP
.fi

.PP
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:

.IP
* Installed on the local machine

.IP
* Listening on port 389 

.IP
* The user is cn=Directory Manager, with the password specified in pki_ds_password

.PP
This invocation of \fBpkispawn\fP 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.

.PP
The instance name (defined by pki_instance_name) is pki-tomcat, and it is
located at \fI/var/lib/pki/pki-tomcat\fP. Logs for the instance are located
at \fI/var/log/pki/pki-tomcat\fP, and an installation log is written to
\fI/var/log/pki/pki-<subsystem>-spawn.<timestamp>.log\fP.

.PP
A PKCS #12 file containing the administrator certificate is created in
\fI$HOME/.dogtag/pki-tomcat\fP. This PKCS #12 file uses the password
designated by pki_client_pkcs12_password in the configuration file.

.PP
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.

.SS Installing a root CA using ECC
.BR
.PP
To install a root CA in a new instance using ECC execute the following command:

.IP
\x'-1'\fBpkispawn \-s CA \-f myconfig.txt\fR

.PP
where \fImyconfig.txt\fP contains the following text:

.IP
.nf
[DEFAULT]
pki_admin_password=\fISecret123\fP
pki_admin_keysize=nistp256
pki_admin_key_type=ecc
pki_client_pkcs12_password=\fISecret123\fP
pki_ds_password=\fISecret123\fP
pki_ssl_server_key_algorithm=SHA256withEC
pki_ssl_server_key_size=nistp256
pki_ssl_server_key_type=ecc
pki_subsystem_key_algorithm=SHA256withEC
pki_subsystem_key_size=nistp256
pki_subsystem_key_type=ecc

[CA]
pki_ca_signing_key_algorithm=SHA256withEC
pki_ca_signing_key_size=nistp256
pki_ca_signing_key_type=ecc
pki_ca_signing_signing_algorithm=SHA256withEC
pki_ocsp_signing_key_algorithm=SHA256withEC
pki_ocsp_signing_key_size=nistp256
pki_ocsp_signing_key_type=ecc
pki_ocsp_signing_signing_algorithm=SHA256withEC
.fi

.PP
In order to utilize ECC, the SSL Server and Subsystem key algorithm, key size, and key type should be changed from SHA256withRSA --> SHA256withEC, 2048 --> nistp256, and rsa --> ecc, respectively.  To use an ECC admin key size and key type, the values should also be changed from 2048 --> nistp256, and rsa --> ecc.

.PP
Additionally, for a CA subsystem, both the CA and OCSP Signing key algorithm, key size, key type, and signing algorithm should be changed from SHA256withRSA --> SHA256withEC, 2048 --> nistp256, rsa --> ecc, and SHA256withRSA --> SHA256withEC,respectively.

.TP
\fBNote:\fP
For all PKI subsystems including the CA, ECC is not supported for the corresponding Audit Signing parameters.  Similarly, for KRA subsystems, ECC is not supported for either of the corresponding Storage or Transport parameters.

.SS Installing a KRA, OCSP, TKS, or TPS in a shared instance
.BR
.PP
To install a KRA, OCSP, TKS, or TPS in the same instance used by the CA execute

the following command:

.IP
\x'-1'\fBpkispawn \-s <subsystem> \-f myconfig.txt\fR

.PP
where subsystem is KRA, OCSP, TKS, or TPS, and \fImyconfig.txt\fP contains the
following text:

.IP
.nf
[DEFAULT]
pki_admin_password=\fISecret123\fP
pki_client_database_password=\fISecret123\fP
pki_client_pkcs12_password=\fISecret123\fP
pki_ds_password=\fISecret123\fP
pki_security_domain_password=\fISecret123\fP
.fi

.PP
The \fBpki_security_domain_password\fP is the admin password of the CA
installed in the same instance. This command should be run after a CA is
installed. This installs another subsystem within the same instance using the
certificate generated for the CA administrator for the subsystem's
administrator. This allows a user to access both subsystems on the browser
with a single administrator certificate. To access the new subsystem's
functionality, simply point the browser to https://<hostname>:8443 and click
the relevant top-level links.

.PP
To install TPS in a shared instance the following section must be added to
\fImyconfig.txt\fP:

.IP
.nf
[TPS]
pki_authdb_basedn=\fIdc=example,dc=com\fP
.fi

.PP
TPS requires an authentication database. The \fBpki_authdb_basedn\fP
specifies the base DN of the authentication database.

.PP
TPS also requires that a CA and a TKS subsystems are already installed
in the same instance. Since they are in the same instance, a shared
secret key will automatically be generated in TKS and imported into TPS.

.PP
Optionally, server-side key generation can be enabled in TPS by adding the
following parameter in [TPS]:

.IP
.nf
pki_enable_server_side_keygen=\fITrue\fP
.fi

.PP
Enabling server-side key generation requires that a KRA subsystem is already
installed in the same instance.

.SS Installing a KRA, OCSP, TKS, or TPS in a separate instance
.BR
.PP
To install a KRA, OCSP, TKS, or TPS with a remote a CA execute the following
command:

.IP
\x'-1'\fBpkispawn \-s <subsystem> \-f myconfig.txt\fR

.PP
where subsystem is KRA, OCSP, TKS, or TPS, and \fImyconfig.txt\fP contains the
following text:

.IP
.nf
[DEFAULT]
pki_admin_password=\fISecret123\fP
pki_client_database_password=\fISecret123\fP
pki_client_pkcs12_password=\fISecret123\fP
pki_ds_password=\fISecret123\fP
pki_security_domain_password=\fISecret123\fP
pki_security_domain_hostname=<ca_hostname>
pki_security_domain_https_port=<ca_https_port>
pki_security_domain_user=caadmin
pki_issuing_ca=https://<ca_hostname>:<ca_https_port>

[KRA/OCSP/TKS/TPS]
pki_import_admin_cert=False
.fi

.PP
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,
\fImyconfig.txt\fP must specify the connection information for the remote CA
and the information about the security domain (the trusted collection of
subsystems within an instance).

.PP
The subsystem section is [KRA], [OCSP], [TKS], or [TPS].  This example assumes
that the specified CA hosts the security domain.  The CA must be running and
accessible.

.PP 
A new administrator certificate is generated for the new subsystem and stored
in a PKCS #12 file in \fI$HOME/.dogtag/pki-tomcat\fP.

.PP
As in a shared instance, to install TPS in a separate instance the
authentication database must be specified in the [TPS] section, and optionally
the server-side key generation can be enabled. If the CA, KRA, or TKS
subsystems required by TPS are running on a remote instance the following
parameters must be added into the [TPS] section to specify their locations:

.IP
.nf
pki_ca_uri=\fIhttps://<ca_hostname>:<ca_https_port>\fP
pki_kra_uri=\fIhttps://<kra_hostname>:<kra_https_port>\fP
pki_tks_uri=\fIhttps://<tks_hostname>:<tks_https_port>\fP
.fi

.PP
If TPS and TKS are installed on separate instances the shared secret key needs
to be generated manually in TKS, then manually imported into TPS.

Generate the shared secret key in TKS with the following command:

.IP
tkstool -T -d /var/lib/pki/pki-tomcat/alias -n sharedSecret

.PP
Verify the shared secret key in TKS with the following command:

.IP
tkstool -L -d /var/lib/pki/pki-tomcat/alias

.PP
Once TPS is installed, shutdown TPS instance, then import the shared secret
key into TPS with the following command:

.IP
tkstool -I -d /var/lib/pki/pki-tomcat/alias -n sharedSecret

.PP
Verify the shared secret key in TPS with the following command:

.IP
tkstool -L -d /var/lib/pki/pki-tomcat/alias

.PP
The shared secret key nickname should be stored in the following property
in the TPS's CS.cfg:

.IP
conn.tks1.tksSharedSymKeyName=sharedSecret

.PP
Finally, restart the TPS instance.

.SS Installing a CA clone
.BR
.PP
To install a CA clone execute the following command:

.IP
\x'-1'\fBpkispawn \-s CA \-f myconfig.txt\fR

.PP 
where \fImyconfig.txt\fP contains the following text:

.IP
.nf
[DEFAULT]
pki_admin_password=\fISecret123\fP
pki_client_database_password=\fISecret123\fP
pki_client_pkcs12_password=\fISecret123\fP
pki_ds_password=\fISecret123\fP
pki_security_domain_password=\fISecret123\fP
pki_security_domain_hostname=<master_ca_hostname>
pki_security_domain_https_port=<master_ca_https_port>
pki_security_domain_user=caadmin

[Tomcat]
pki_clone=True
pki_clone_pkcs12_password=\fISecret123\fP
pki_clone_pkcs12_path=<path_to_pkcs12_file>
pki_clone_replicate_schema=True
pki_clone_uri=https://<master_ca_hostname>:<master_ca_https_port>
.fi

.PP
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 database -- separate
from the master CA database -- but using the same base DN, that keeps in sync
with the master CA through replication agreements between the databases. This
is very useful for load sharing and disaster recovery. To create a clone, the
\fImyconfig.txt\fP uses pki_clone-* parameters in its [Tomcat] 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.

.PP
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.

.PP
In addition, since this example does not utilize an HSM, the master'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
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.

.PP
The master's system certificates can be exported to a PKCS#12 file when the
master is installed if the parameter \fBpki_backup_keys\fP is set to \fBTrue\fP
and the \fBpki_backup_password\fP is set.  The PKCS#12 file is then found under
\fB/var/lib/pki/<instance_name>/alias\fP.  Alternatively, the PKCS#12 file can
be generated at any time post-installation using \fBPKCS12Export\fP.

.PP
An example invocation showing the export of the system certificates and keys,
copying the keys to the replica subsystem, and setting the relevant SELinux and
file permissions is shown below.  \fBpwfile\fP is a text file containing the
password for the master NSS DB (found in \fB/etc/pki/<instance_name>/password.conf\fP).
\fB pkcs12_password_file\fP is a text file containing the password selected for
the generated PKCS12 file.

.IP
.nf
\fBmaster# PKCS12Export -d /etc/pki/pki-tomcat/alias -p pwfile \\
        -w pkcs12_password_file -o backup_keys.p12
master# scp backup_keys.p12 clone:/backup_keys.p12

clone# chown pkiuser: /backup_keys.p12
clone# semanage -a -t pki_tomcat_cert_t /backup_keys.p12\fP
.fi

.PP
\fBNote:\fP From Dogtag 10.3, a slightly different mechanism has been provided to
create and specify the required PKCS#12 file to the clone subsystem.  This new
method is provided in addition to the method above, but will become the preferred
method in future releases.

This method can be used if both master and clone are 10.3 or above.

.PP
To export the required keys from the master, use the \fBpki-server\fP command
line tool.

.IP
.nf
\fB
master# pki-server ca-clone-prepare -i pki-tomcat \\
        --pkcs12-file backup_keys.p12 \\
        --pkcs12-password Secret123

master# scp backup_keys.p12 clone:/backup_keys.p12
master# scp /etc/pki/pki-tomcat/external_certs.conf \\
         clone:/external_certs.conf
.fi

.PP
The \fBexternal_certs.conf\fP file contains information about third party certificates
that were added to the master's certificate database using the \fBpki-server\fP
command.  The certificates themselves are stored in the backup_keys.p12 file. If
there are no third-party certifcates that have been added, then the
\fBexternal_certs.conf\fP file may not exist and should be ignored.

The two files (\fBbackup_keys.p12\fP and \fBexternal_certs.conf\fP) are specified
to pkispawn as below.

.IP
.nf
[DEFAULT]
pki_admin_password=\fISecret123\fP
pki_client_database_password=\fISecret123\fP
pki_client_pkcs12_password=\fISecret123\fP
pki_ds_password=\fISecret123\fP
pki_security_domain_password=\fISecret123\fP
pki_security_domain_hostname=<master_ca_hostname>
pki_security_domain_https_port=<master_ca_https_port>
pki_security_domain_user=caadmin

[Tomcat]
pki_clone=True
pki_server_pkcs12_password=\fISecret123\fP
pki_server_pkcs12_path=<path_to_pkcs12_file>
pki_server_external_cert_path=<path to external_certs.conf file>
pki_clone_replicate_schema=True
pki_clone_uri=https://<master_ca_hostname>:<master_ca_https_port>
.fi

.PP
Note that the previous p12 parameters (pki_clone_pkcs12_*) are no longer
needed, and will be ignored.

.nf
Note: One current cloning anomaly to mention is the following scenario:

1. Create a clone of a CA or of any other subsystem.
2. Remove that just created clone.
3. Immediately attempt the exact same clone again, in place of
   the recently destroyed instance. Before recreating this clone,
   make sure the "pki_ds_remove_data=True" is used in the clone's
   deployment config file. This will remove the old data from the previous
   clone.

Here the Director Server instance may have worked itself in into a state
where it no longer accepts connections, aborting the clone configuration quickly.

The fix to this is to simply restart the Directory Server instance before
creating the clone for the second time. After restarting the Directory Server
it should be possible to create the mentioned clone instance.
.fi

.SS Installing a KRA or TKS clone
.BR
.PP
To install a KRA or TKS (OCSP and TPS unsupported as of now) execute the following command:

.IP
\x'-1'\fBpkispawn \-s <subsystem> \-f myconfig.txt\fR

.PP
where subsystem is KRA or TKS and \fImyconfig.txt\fP contains the following text:

.IP
.nf
[DEFAULT]
pki_admin_password=\fISecret123\fP
pki_client_database_password=\fISecret123\fP
pki_client_pkcs12_password=\fISecret123\fP
pki_ds_password=\fISecret123\fP
pki_security_domain_password=\fISecret123\fP
pki_security_domain_hostname=<master_ca_hostname>
pki_security_domain_https_port=<master_ca_https_port>
pki_security_domain_user=caadmin

[Tomcat]
pki_clone=True
pki_clone_pkcs12_password=\fISecret123\fP
pki_clone_pkcs12_path=<path_to_pkcs12_file>
pki_clone_replicate_schema=True
pki_clone_uri=https://<master_subsystem_host>:<master_subsystem_https_port>
pki_issuing_ca=https://<ca_hostname>:<ca_https_port>
.fi

.PP
As with a CA clone, a KRA or TKS clone uses the same certificates and basic
configuration as the original subsystem. The configuration 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.

.PP
The parameter \fBpki_clone_uri\fP should be modified to point to the required
master (KRA or TKS).

As of 10.3, a slightly different mechanism has been introduced to generate and
specify the PKCS#12 file and any third-party certificates.  See the
\fBInstalling a CA clone\fP section for details.

.SS Installing a CA clone on the same host
.BR
.PP
For testing purposes, it is useful to configure cloned CAs which exist (with
their internal databases) on the same host as the master CA. To configure
the cloned CA execute the following command:

.IP
\x'-1'\fBpkispawn \-s CA \-f myconfig.txt\fR

.PP
where \fImyconfig.txt\fP contains the following text:

.IP
.nf
[DEFAULT]
pki_admin_password=Secret123
pki_client_database_password=Secret123
pki_client_pkcs12_password=Secret123
pki_ds_password=Secret123
pki_ds_ldap_port=<unique port different from master>
pki_ds_ldaps_port=<unique port different from master>
pki_http_port=<unique port different from master>
pki_https_port=<unique port different from master>
pki_instance_name=<unique name different from master>
pki_security_domain_hostname=<master_ca_hostname>
pki_security_domain_https_port=<master_ca_https_port>
pki_security_domain_password=Secret123

[Tomcat]
pki_ajp_port=<unique port different from master>
pki_clone=True
pki_clone_pkcs12_password=Secret123
pki_clone_pkcs12_path=<path_to_pkcs12_file>
pki_clone_uri=https://<master_ca_hostname>:<master_ca_https_port>
pki_tomcat_server_port=<unique port different from master>

[CA]
pki_ds_base_dn=<identical value as master>
pki_ds_database=<identical value as master>
.fi

.PP
In this case, because both CA Tomcat instances are on the same host, they must
have distinct ports.  Similarly, each CA must use a distinct directory server
instance for its internal database.  Like the Tomcat instances, these are
distinguished by distinct ports. The suffix being replicated
(\fBpki_ds_base\fP), however, must be the same for both master and clone.

.SS Installing a subordinate CA in existing security domain
.BR
.PP
To install a subordinate CA in an existing security domain execute the
following command:

.IP
\x'-1'\fBpkispawn \-s CA \-f myconfig.txt\fR

.PP
where \fImyconfig.txt\fP contains the following text:

.IP
.nf
[DEFAULT]
pki_admin_password=\fISecret123\fP
pki_client_database_password=\fISecret123\fP
pki_client_pkcs12_password=\fISecret123\fP
pki_ds_password=\fISecret123\fP
pki_security_domain_password=\fISecret123\fP
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
.fi

.PP
A sub-CA derives its certificate configuration -- such as allowed extensions
and validity periods -- from a superior or root CA. Otherwise, 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.

.PP
\fBNote:\fP The value of \fBpki_ca_signing_subject_dn\fP of a subordinate CA
should be different from the root CA's signing subject DN.

.SS Installing a subordinate CA in new security domain
.BR
.PP
To install a subordinate CA in a new security domain execute the following
command:

.IP
\x'-1'\fBpkispawn \-s CA \-f myconfig.txt\fR

.PP
where \fImyconfig.txt\fP contains the following text:

.IP
.nf
[DEFAULT]
pki_admin_password=\fISecret123\fP
pki_client_database_password=\fISecret123\fP
pki_client_pkcs12_password=\fISecret123\fP
pki_ds_password=\fISecret123\fP
pki_security_domain_password=\fISecret123\fP
pki_security_domain_hostname=<master CA security domain hostname>
pki_security_domain_https_port=<master CA security domain 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=\fIcn=CA Subordinate Signing,o=example.com\fP
pki_subordinate_create_new_security_domain=True
pki_subordinate_security_domain_name=\fISubordinate CA Security Domain\fP
.fi

.PP
In this section, the subordinate CA logs onto and registers with the security
domain CA (using parameters \fBpki_security_domain_hostname\fP,
\fBpki_security_domain_user\fP and \fBpki_security_domain_password\fP) as in
the previous section, but also creates and hosts a new security domain. To do
this, \fBpki_subordinate_create_new_security_domain\fP must be set to
\fBTrue\fP. The subordinate CA security domain name can also be specified by
specifying a value for \fBpki_subordinate_security_domain_name\fP.

.PP
\fBNote:\fP The value of \fBpki_ca_signing_subject_dn\fP of a subordinate CA
should be different from the root CA's signing subject DN.

.SS Installing an externally signed CA
.BR
.PP
To install an externally signed CA execute the following command:

.IP
\x'-1'\fBpkispawn \-s CA \-f myconfig.txt\fR

.PP
This is a two step process.

.PP
In the first step, a certificate signing request (CSR) is generated for the
signing certificate and \fImyconfig.txt\fP contains the following text:

.IP
.nf
[DEFAULT]
pki_admin_password=\fISecret123\fP
pki_client_database_password=\fISecret123\fP
pki_client_pkcs12_password=\fISecret123\fP
pki_ds_password=\fISecret123\fP
pki_security_domain_password=\fISecret123\fP

[CA]
pki_external=True
pki_external_csr_path=\fI/tmp/ca_signing.csr\fP
pki_ca_signing_subject_dn=\fIcn=CA Signing,ou=External,o=example.com\fP
.fi

.PP
The CSR is written to pki_external_csr_path. The pki_ca_signing_subject_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.

.PP
The CSR is then submitted to the external CA, and the resulting certificate
and certificate chain are saved to files on the system.

.PP
In the second step, the configuration file has been modified to install the
issued certificates. In place of the original CSR, the configuration file now
points to the issued CA certificate and certificate chain. There is also a
flag to indicate that this completes the installation process
(pki_external_step_two).

.IP
.nf
[DEFAULT]
pki_admin_password=\fISecret123\fP
pki_client_database_password=\fISecret123\fP
pki_client_pkcs12_password=\fISecret123\fP
pki_ds_password=\fISecret123\fP
pki_security_domain_password=\fISecret123\fP

[CA]
pki_external=True
pki_external_ca_cert_chain_path=\fI/tmp/ca_cert_chain.cert\fP
pki_external_ca_cert_path=\fI/tmp/ca_signing.cert\fP
pki_external_step_two=True
pki_ca_signing_subject_dn=\fIcn=CA Signing Certificate,ou=External,o=example.com\fP
.fi

.PP
Then, the \fBpkispawn\fP command is run again:

.IP
.B pkispawn -s CA -f myconfig.txt

.SS Installing a PKI subsystem with a secure LDAP connection
.BR
.PP
There are three scenarios in which a PKI subsystem (e.g. a CA) needs to
communicate securely via LDAPS with a directory server:

.IP
* A directory server exists which is already running LDAPS using a CA
certificate that has been issued by some other CA. For this scenario, the CA
certificate must be made available via a PEM file (e.g. $HOME/dscacert.pem)
prior to running \fBpkispawn\fP such that the new CA may be installed and
configured to communicate with this directory server using LDAPS.

.IP
* A directory server exists which is currently running LDAP. Once a CA has
been created, there is a desire to use its CA certificate to issue an SSL
certificate for this directory server so that this CA and this directory
server can communicate via LDAPS.  For this scenario, since there is no need
to communicate securely during the \fBpkispawn\fP installation/configuration,
simply use \fBpkispawn\fP to install and configure the CA using the LDAP port
of the directory server, issue an SSL certificate from this CA for the
directory server, and then reconfigure the CA and directory server to
communicate with each other via LDAPS.

.IP
* Similar to the previous scenario, a directory server exists which is
currently running LDAP, and the desire is to create a CA and use it to
establish LDAPS communications between this CA and this directory server.
However, for this scenario, there is a need for the CA and the directory
server to communicate securely during \fBpkispawn\fP installation and
configuration. For this to succeed, the directory server must generate a
temporary self-signed certificate which then must be made available via
a PEM file (e.g. $HOME/dscacert.pem) prior to running \fBpkispawn\fP. Once
the CA has been created, swap things out to reconfigure the CA and directory
server to utilize LDAPS through the desired certificates.

.PP
The following example demonstrates the steps to generate a temporary
self-signed certificate in the Directory Server which requires an Admin Server.
Directory Server and Admin Server instances can be created with the following
command:

.IP
\fBsetup-ds-admin.pl\fP

.PP
Enable LDAPS in the Directory Server with the following command:

.IP
\fB/usr/sbin/setupssl2.sh /etc/dirsrv/\fIslapd-pki\fP 389 636 \fISecret123\fP

.PP
\fBNote:\fP
The \fBsetupssl2.sh\fP script may be downloaded from \fBhttps://raw.githubusercontent.com/richm/scripts/master/setupssl2.sh\fP.

Restart the Directory Server with the following command:

.IP
\fBsystemctl restart dirsrv.target\fP

.PP
Verify that a client can connect securely over LDAPS with the following
command:

.IP
\fB/usr/lib64/mozldap/ldapsearch -Z -h \fIpki.example.com\fP -p 636 -D 'cn=Directory Manager' -w \fISecret123\fP -b \fI"dc=example, dc=com"\fP "objectclass=*"\fP

.PP
\fBNote:\fP
The \fBmozldap ldapsearch\fP utility is available from the \fBmozldap-tools\fP package.

.PP
Export the self-signed CA certificate with the following command:

.IP
\fBcertutil -L -d /etc/dirsrv/\fIslapd-pki\fP -n "CA certificate" -a > \fI$HOME/dscacert.pem\fP

.PP
Once the self-signed CA certificate is obtained, add the following parameters
into the [DEFAULT] section in \fImyconfig.txt\fP:

.IP
.nf
pki_ds_secure_connection=True
pki_ds_secure_connection_ca_pem_file=\fI$HOME/dscacert.pem\fP
.fi

.PP
Then execute \fBpkispawn\fP to create the CA subsystem.

.SS Managing PKI instance
.BR
.PP
To start all 389 instances (local PKI databases):
.IP
.nf
\fBsystemctl start dirsrv.target\fR
.fi
.PP
To stop all 389 instances (local PKI databases):
.IP
.nf
\fBsystemctl stop dirsrv.target\fR
.fi
.PP
To restart all 389 instances (local PKI databases):
.IP
.nf
\fBsystemctl restart dirsrv.target\fR
.fi
.PP
To obtain the status of all 389 instances (local PKI databases):
.IP
.nf
\fBsystemctl status dirsrv.target\fR
.fi
.PP
To start a PKI instance named <pki_instance_name>:
.IP
.nf
\fBsystemctl start pki-tomcatd@<pki_instance_name>.service\fR
.fi
.PP
To stop a PKI instance named <pki_instance_name>:
.IP
.nf
\fBsystemctl stop pki-tomcatd@<pki_instance_name>.service\fR
.fi
.PP
To restart a PKI instance named <pki_instance_name>:
.IP
.nf
\fBsystemctl restart pki-tomcatd@<pki_instance_name>.service\fR
.fi
.PP
To obtain the status of a PKI instance named <pki_instance_name>:
.IP
.nf
\fBsystemctl status pki-tomcatd@<pki_instance_name>.service\fR
.fi
.PP
To obtain a detailed status of a Tomcat PKI instance named <pki_instance_name>:
.IP
.nf
\fBpkidaemon status tomcat <pki_instance_name>\fR
.fi
.PP
To obtain a detailed status of all Tomcat PKI instances:
.IP
.nf
\fBpkidaemon status tomcat\fR
.fi

.SH BUGS
Report bugs to http://bugzilla.redhat.com.

.SH AUTHORS
Ade Lee <alee@redhat.com>.  \fBpkispawn\fP was written by the Certificate Server project.

.SH 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.

.SH SEE ALSO
.BR pkidestroy(8),
.BR pki_default.cfg(5),
.BR pki(1),
.BR setup-ds.pl(8)