Renamed base/deploy to base/server.

The base/deploy folder has been renamed to base/server to match the
package name. The pki.conf has been moved into pki-base package.

Ticket #553, #564

3 files changed, 716 insertions, 0 deletions

diff --git a/base/server/man/man5/pki_default.cfg.5 b/base/server/man/man5/pki_default.cfg.5
new file mode 100644
index 000000000..ec2379a9f
--- /dev/null
+++ b/base/server/man/man5/pki_default.cfg.5
@@ -0,0 +1,275 @@
+.\" 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 pki_default.cfg 5 "December 13, 2012" "version 1.0" "PKI Default Instance Configuration" 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
+pki_default.cfg \- Certificate Server instance default config file.
+
+.SH LOCATION
+/etc/pki/default.cfg
+
+.SH DESCRIPTION
+This file contains the default settings for a Certificate Server instance created using \fBpkispawn\fP.  This file should not be edited, as it can be modified when the Certificate Server packages are updated.  Rather, when setting up a Certificate Server instance, a user-provided configuration file can provide overrides to the defaults in /etc/pki/default.cfg.  See \fBpkispawn(8)\fR for details.
+
+.SH SECTIONS
+\fIdefault.cfg\fP is divided into subsystem-based sections ([DEFAULT] for general configuration and subsystem-type sections such as [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], and [TKS] -- in that order.  This allows the ability to specify parameters to be shared by all subsystems in [DEFAULT] or [Tomcat], and subsystem-specific upgrades in the other sections.
+.PP
+There are a small number of bootstrap parameters which are passed in the configuration file by \fBpkispawn\fP. Other parameter's values can be interpolated tokens rather than explicit values. For example:
+.PP
+\fBpki_ca_signing_nickname=caSigningCert cert-%(pki_instance_name)s CA\fP
+.PP
+This substitutes the value of pki_instance_name into the parameter value.  It is possible to interpolate any parameter within a section or in [DEFAULT]. Any parameter used in interpolation can \fBONLY\fP be overridden within the same section.  So, for example, pki_instance_name should only be overridden in [DEFAULT]; otherwise, interpolations can fail.
+
+.SH GENERAL INSTANCE PARAMETERS
+The parameters described below, as well as the parameters located in the following sections, can be customized as part of a deployment.  This list is not exhaustive.
+.TP
+.B pki_instance_name
+.IP
+Name of the instance. The instance is located at /var/lib/pki/<instance_name>.  For Java subsystems, the default is specified as pki-tomcat.
+.TP
+.B pki_https_port, pki_http_port
+.IP
+Secure and unsecure ports.  Defaults to standard Tomcat ports 8443 and 8080, respectively, for Java subsystems, and 443 and 80 for Apache subsystems.
+.TP
+.B pki_ajp_port, pki_tomcat_server_port
+.IP
+Ports for Tomcat subsystems.  Defaults to standard Tomcat ports of 8009 and 8005, respectively.
+.TP
+.B pki_proxy_http_port, pki_proxy_https_port, pki_enable_proxy
+.IP
+Ports for an Apache proxy server. Certificate Server instances can be run behind an Apache proxy server, which will communicate with the Tomcat instance through the AJP port.  See the Red Hat Certificate System documentation at https://access.redhat.com/knowledge/docs/Red_Hat_Certificate_System/ for details.
+.TP
+.B pki_user, pki_group, pki_audit_group
+.IP
+Specifies the default administrative user, group, and auditor group identities for PKI instances.  The default user and group are both specified as \fBpkiuser\fR, and the default audit group is specified as \fBpkiaudit\fR.
+.TP
+.B pki_token_name, pki_token_password
+.IP
+The token and password where this instance's system certificate and keys are stored.  Defaults to the NSS internal software token.
+
+.SS SYSTEM CERTIFICATE PARAMETERS
+\fBpkispawn\fP sets up a number of system certificates for each subsystem.  The system certificates which are required differ between subsystems.  Each system certificate is denoted by a tag, as noted below.  The different system certificates are:
+.IP
+* signing certificate ("signing").  Used to sign other certificates.  Required for CA.
+.IP
+* OCSP signing certificate ("ocsp_signing" in CA, "signing" in OCSP).  Used to sign CRLs.  Required for OCSP and CA.
+.IP
+* storage certificate ("storage").  Used to encrypt keys for storage in KRA.  Required for KRA only.
+.IP
+* transport certificate ("transport").  Used to encrypt keys in transport to the KRA.  Required for KRA only.
+.IP
+* subsystem certificate ("subsystem").  Used to communicate between subsystems within the security domain.  Issued by the security domain CA.  Required for all subsystems.
+.IP
+* server certificate ("sslserver").  Used for communication with the server.  One server certificate is required for each Certificate Server instance.
+.IP
+* audit signing certificate ("audit_signing").  Used to sign audit logs.  Required for all subsystems except the RA.
+.PP
+Each system certificate can be customized using the parameters below:
+.TP
+.B pki_<tag>_key_type, pki_<type>_keysize, pki_<tag>_key_algorithm
+.IP
+Characteristics of the private key. See the Red Hat Certificate System documentation at https://access.redhat.com/knowledge/docs/Red_Hat_Certificate_System/ for possible options.  The defaults are RSA for the type, 2048 bits for the key size, and SHA256withRSA for the algorithm.
+.TP 
+.B pki_<tag>_signing_algorithm
+.IP
+For signing certificates, the algorithm used for signing.  Defaults to SHA256withRSA.
+.TP
+.B pki_<tag>_token
+.IP
+Location where the certificate and private key are stored.  Defaults to the internal software NSS token database.
+.TP
+.B pki_<tag>_nickname
+.IP
+Nickname for the certificate in the token database.
+.TP
+.B pki_<tag>_subject_dn
+.IP
+Subject DN for the certificate.  The subject DN for the SSL Server certificate must include CN=<hostname>.
+.SS ADMIN USER PARAMETERS
+\fBpkispawn\fP creates a bootstrap administrative user that is a member of all the necessary groups to administer the installed subsystem.  On a security domain CA, the CA administrative user is also a member of the groups required to register a new subsystem on the security domain.  The certificate and keys for this administrative user are stored in a PKCS #12 file in \fBpki_client_dir\fP, and can be imported into a browser to administer the system.
+.TP
+.B pki_admin_name, pki_admin_uid
+.IP
+Name and UID of this administrative user.  Defaults to caadmin for CA, kraadmin for KRA, etc.
+.TP
+.B pki_admin_password
+.IP
+Password for the admin user.  This password is used to log into the pki-console (unless client authentication is enabled), as well as log into the security domain CA.
+.TP
+.B pki_admin_email
+.IP
+Email address for the admin user.
+.TP
+.B pki_admin_dualkey, pki_admin_keysize, pki_admin_keytype
+.IP
+Settings for the administrator certificate and keys.
+.TP
+.B pki_admin_subject_dn
+.IP
+Subject DN for the administrator certificate.  Defaults to \fBcn=PKI Administrator, e=%(pki_admin_email)s, o=%(pki_security_domain_name)s\fP.
+.TP
+.B pki_admin_nickname
+Nickname for the administrator certificate.
+.TP
+.B pki_import_admin_cert
+.IP
+Set to True to import an existing admin certificate for the admin user, rather than generating a new one.  A subsystem-specific administrator will still be created within the subsystem's LDAP tree.  This is useful to allow multiple subsystems within the same instance to be more easily administered from the same browser by using a single certificate.
+
+By default, this is set to False for CA subsystems and true for KRA, OCSP, and TKS subsystems.  In this case, the admin certificate is read from the file ca_admin.cert in \fBpki_client_dir\fP.
+
+Note that cloned subsystems do not create a new administrative user.  The administrative user of the master subsystem is used instead, and the details of this master user are replicated during the install.
+.TP
+.B pki_client_admin_cert_p12
+.IP
+Location for the PKCS #12 file containing the administrative user's certificate and keys.  For a CA, this defaults to \fIca_admin_cert.p12\fP in the \fBpki_client_dir\fP directory.
+.SS BACKUP PARAMETERS
+.TP
+.B pki_backup_keys, pki_backup_password
+.IP
+Set to True to back up the subsystem certificates and keys to a PKCS #12 file.  This file will be located in \fI/var/lib/pki/<instance_name>/alias\fP.  pki_backup_password is the password of the PKCS#12 file.
+  
+.SS CLIENT DIRECTORY PARAMETERS
+.TP
+.B pki_client_dir
+.IP
+This is the location where all client data used during the installation is stored.  At the end of the invocation of \fBpkispawn\fP, the administrative user's certificate and keys are stored in a PKCS #12 file in this location.
+.TP
+.B pki_client_database_dir,  pki_client_database_password
+.IP
+Location where an NSS token database is created in order to generate a key for the administrative user.  Usually, the data in this location is removed at the end of the installation, as the keys and certificates are stored in a PKCS #12 file in \fBpki_client_dir\fP.
+.TP
+.B pki_client_database_purge
+.IP
+Set to True to remove \fBpki_client_database_dir\fP at the end of the installation.  Defaults to True.
+.SS INTERNAL DATABASE PARAMETERS
+\x'-1'\fBpki_ds_hostname, pki_ds_ldap_port, pki_ds_ldaps_port\fR
+.IP
+Hostname and ports for the internal database.  Defaults to localhost, 389, and 636, respectively.
+.PP
+.B pki_ds_bind_dn, pki_ds_password
+.IP
+Credentials to connect to the database during installation.  Directory Manager-level access is required during installation to set up the relevant schema and database.  During the installation, a more restricted Certificate Server user is set up to client authentication connections to the database.  Some additional configuration is required, including setting up the directory server to use SSL.  See the documentation for details. 
+.PP
+.B pki_ds_secure_connection
+.IP
+Sets whether to require connections to the Directory Server using LDAPS.  This requires SSL to be set up on the Directory Server first.  Defaults to false.
+.PP
+.B pki_ds_remove_data
+.IP
+Sets whether to remove any data from the base DN before starting the installation.  Defaults to True.
+.PP
+.B pki_ds_base_dn
+.IP
+The base DN for the internal database.  It is advised that the Certificate Server have its own base DN for its internal database.  If the base DN does not exist, it will be created during the running of \fBpkispawn\fP.  For a cloned subsystem, the base DN for the clone subsystem MUST be the same as for the master subsystem.
+.PP
+.B pki_ds_database
+.IP
+Name of the back-end database.  It is advised that the Certificate Server have its own base DN for its internal database.  If the back-end does not exist, it will be created during the running of \fBpkispawn\fP.
+.SS ISSUING CA PARAMETERS
+\x'-1'\fBpki_issuing_ca_hostname, pki_issuing_ca_https_port, pki_issuing_ca_uri\fR
+.IP
+Hostname and port, or URI of the issuing CA.  Required for installations of subordinate CA and non-CA subsystems.  This should point to the CA that will issue the relevant system certificates for the subsystem.  In a default install, this defaults to the CA subsystem within the same instance.  The URI has the format https://<ca_hostname>:<ca_https_port>.
+
+.SS MISCELLANEOUS PARAMETERS
+\x'-1'\fBpki_restart_configured_instance\fR
+.IP
+Sets whether to restart the instance after configuration is complete.  Defaults to True.
+.PP
+.B pki_skip_configuration
+.IP
+Sets whether to execute the configuration steps when running \fBpkispawn\fP.  If this is true, then the process is analogous to running \fBpkicreate\fP, when the configuration was performed separately from the instance creation.  A configuration URL will be provided.  This URL can be used as a starting point for the browser-based configuration panels.  Defaults to False.
+.PP
+.B pki_skip_installation
+.IP
+Sets whether to skip the installation steps.  With pki_skip_configuration set to False, this is analogous to running pkisilent.  Defaults to False.
+.PP
+.B pki_enable_java_debugger
+.IP
+Sets whether to attach a Java debugger such as Eclipse to the instance for troubleshooting.  Defaults to False.
+.PP
+.B pki_security_manager
+.IP
+Enables the Java security manager policies provided by the JDK to be used with the instance.  Defaults to True.
+.PP
+.SS SECURITY DOMAIN PARAMETERS
+The security domain is a component that facilitates communication between subsystems.  The first CA installed hosts this component and is used to register subsequent subsystems with the security domain.  These subsystems can communicate with each other using their subsystem certificate, which is issued by the security domain CA.  For more information about the security domain component, see the Red Hat Certificate System documentation at https://access.redhat.com/knowledge/docs/Red_Hat_Certificate_System/.
+.TP
+.B pki_security_domain_hostname, pki_security_domain_https_port
+.IP
+Location of the security domain.  Required for KRA, OCSP, and TKS subsystems and for CA subsystems joining a security domain.  Defaults to the location of the CA subsystem within the same instance.
+.TP
+.B pki_security_domain_user, pki_security_domain_password
+.IP
+Administrative user of the security domain.  Required for KRA, OCSP, and TKS subsystems, and for CA subsystems joining a security domain.  Defaults to the administrative user for the CA subsystem within the same instance (caadmin).
+.TP
+.B pki_security_domain_name
+.IP
+The name of the security domain. This is required for the security domain CA.
+
+.SS CLONE PARAMETERS
+.TP
+.B pki_clone
+.IP
+Installs a clone, rather than original, subsystem.
+.TP
+.B pki_clone_pkcs12_password, pki_clone_pkcs12_path
+.IP
+Location and password of the PKCS #12 file containing the system certificates for the master subsystem being cloned.  This file should be readable by the user that the Certificate Server is running as (default of pkiuser), and have the correct selinux context (pki_tomcat_cert_t).  This can be achieved by placing the file in \fI/var/lib/pki/<instance_name>/alias\fP.
+.TP
+.B pki_clone_replication_master_port, pki_clone_replication_clone_port
+.IP
+Ports on which replication occurs.  These are the ports on the master and clone databases respectively.  Defaults to the internal database port. 
+.TP
+.B pki_clone_repicate_schema
+.IP
+Replicate schema when the replication agreement is set up and the new instance (consumer) is initialized.  Otherwise, the schema must be installed in the clone as a separate step beforehand.  This does not usually have to be changed.  Defaults to True.
+.TP
+.B pki_clone_replication_security
+.IP
+The type of security used for the replication data.  This can be set to SSL (using LDAPS), TLS, or None.  Defaults to None.  For SSL and TLS, SSL must be set up for the database instances beforehand.
+.TP
+.B pki_clone_uri
+.IP
+A pointer to the subsystem being cloned.  The format is https://<master_hostname>:<master_https_port>.
+
+.SS EXTERNAL CA CERTIFICATE PARAMETERS
+\x'-1'\fBpki_external\fR
+.IP
+Sets whether the new CA will have a signing certificate that will be issued by an external CA.  This is a two step process.  In the first step, a CSR to be presented to the external CA is generated.  In the second step, the issued signing certificate and certificate chain are provided to the \fBpkispawn\fP utility to complete the installation.  Defaults to False.
+.PP
+.B pki_external_csr_path
+.IP
+Required in the first step of the external CA signing process.  The CSR will be printed to the screen and stored in this location.
+.PP
+.B pki_external_step_two
+.IP
+Specifies that this is the second step of the external CA process.  Defaults to False.
+.PP
+.B pki_external_cert_path, pki_external_cert_chain_path
+.IP
+Required for the second step of the external CA signing process.  This is the location of the CA signing cert (as issued by the external CA) and the external CA's certificate chain.
+.SS SUBORDINATE CA CERTIFICATE PARAMETERS
+\x'-1'\fBpki_subordinate\fR
+.IP
+Specifies whether the new CA which will be a subordinate of another CA.  The master CA is specified by \fBpki_issuing_ca\fP.  Defaults to False.
+
+.SH AUTHORS
+Ade Lee <alee@redhat.com>.  \fBpkispawn\fP was written by the Dogtag 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 pkispawn(8)
diff --git a/base/server/man/man8/pkidestroy.8 b/base/server/man/man8/pkidestroy.8
new file mode 100644
index 000000000..407a915aa
--- /dev/null
+++ b/base/server/man/man8/pkidestroy.8
@@ -0,0 +1,67 @@
+.\" 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 pkidestroy 8 "December 13, 2012" "version 1.0" "PKI Instance Removal 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
+pkidestroy \- Removes a subsystem from an instance of Certificate Server.
+
+.SH SYNOPSIS
+pkidestroy -s <subsystem> -i <instance> [-u <secutiry domain username>] [-W <security domain password file>] [-h] [-v] [-p <prefix>]
+
+.SH DESCRIPTION
+Removes a subsystem from an instance of Certificate Server.  This utility removes any of the Java-based Certificate Server subsystems (CA, KRA, OCSP, and TKS).
+.PP
+.TP
+\fBNote:\fP 
+This utility is only used for Java-based subsystems. The Apache-based Certificate Server subsystems (RA and TPS) are removed using \fBpkiremove\fP.
+.PP
+An instance can contain multiple subsystems, although it may contain at most one of each type of subsystem.  So, for example, an instance could contain CA and KRA subsystems,  but not two CA subsystems.  If \fBpkidestroy\fP is invoked on the last subsystem in the instance, then that instance is removed.  Typically, as subsystems need to contact the CA to update the security domain, the CA instance should be the last instance to be removed.
+
+.SH OPTIONS
+.TP
+.B -s <subsystem>
+Specifies the subsystem to be removed, where <subsystem> is CA, KRA, OCSP, or TKS. If this option is not specified, \fBpkidestroy\fP
+will prompt for its value.
+.TP
+.B -i <instance>
+Specifies the name of the instance from which the subsystem should be removed.  The instance is located at /var/log/pki/<instance>. If this option is not specified, \fBpkidestroy\fP
+will prompt for its value.
+.TP
+.B -u <security domain username> 
+Specifies the username of the security domain of the subsystem. This is an \fBoptional\fP parameter.
+.TP
+.B -W <security domain password file> 
+Specifies the file containing the password of the security domain of the subsystem. This is an \fBoptional\fP parameter. 
+.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 pkidestroy -h 
+for details.
+
+
+.SH BUGS
+Report bugs to http://bugzilla.redhat.com.
+
+.SH AUTHORS
+Ade Lee <alee@redhat.com>.  \fBpkidestroy\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 pkispawn(8)
diff --git a/base/server/man/man8/pkispawn.8 b/base/server/man/man8/pkispawn.8
new file mode 100644
index 000000000..d3e980302
--- /dev/null
+++ b/base/server/man/man8/pkispawn.8
@@ -0,0 +1,374 @@
+.\" 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] [-u] [-v] [-p <prefix>]
+
+.SH DESCRIPTION
+Sets up an instance of Certificate Server.  This utility creates any of the Java-based Certificate Server subsystems (CA, KRA, OCSP, and TKS). 
+.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).
+.TP
+\fBNote:\fP 
+This utility creates only Java-based subsystems. The Apache-based Certificate Server subsystems (RA and TPS) are created using \fBpkicreate\fP. 
+.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 directives that are divided into sections 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.
+.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-spawn-<pki_instance_name>-<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. To use the browser-based configuration panels with \fBpkispawn\fP instead, set the configuration parameter \fBpki_skip_configuration\fP to True.
+ 
+.SH OPTIONS
+.TP
+.B -s <subsystem>
+Specifies the subsystem to be installed and configured, where <subsystem> is CA, KRA, OCSP, or TKS.
+.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 -h, --help
+Prints additional help information.
+.TP
+.B -u
+Runs this script in upgrade mode, to update an existing instance.
+.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 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.
+.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):\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) 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.
+.PP
+\fBAdministrative User Parameters\f
+.TP
+\fIUsername:\fP
+the username of the administrator of this subsystem. The default value is <ca/kra/tks/ocsp>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 /root/.pki/pki-tomcat/<ca/kra/tks/ocsp>_admin.cert.
+.PP
+\fBDirectory Server Parameters\f
+.TP
+\fIHostname:\fP
+Hostname of the directory server instance.  The default value is the hostname of the system.
+.TP
+\fIPort:\fP
+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\f
+.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 EXAMPLES
+.SS CA using default configuration
+\x'-1'\fBpkispawn -s CA -f myconfig.txt\fR
+.PP
+where \fImyconfig.txt\fP contains the following text:
+.IP
+.nf
+[DEFAULT]
+pki_admin_password=\fIpassword123\fP
+pki_client_pkcs12_password=\fIpassword123\fP
+pki_ds_password=\fIpassword123\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
+
+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/pkispawn-pki-tomcat-<timestamp>.log\fP.
+.PP
+A PKCS #12 file containing the administrator certificate is created in \fI$HOME/.pki/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 KRA, OCSP, or TKS using default configuration
+\x'-1'\fBpkispawn -s <subsystem> -f myconfig.txt\fR
+.PP
+where subsystem is KRA, OCSP, or TKS, and \fImyconfig.txt\fP contains the following text: 
+.IP
+.nf
+[DEFAULT]
+pki_admin_password=\fIpassword123\fP
+pki_client_pkcs12_password=\fIpassword123\fP
+pki_ds_password=\fIpassword123\fP
+pki_security_domain_password=\fIpassword123\fP
+.fi
+.PP
+The \fBpki_security_domain_password\fP 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 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.
+.SS KRA, OCSP, or TKS connecting to a remote CA
+\x'-1'\fBpkispawn -s <subsystem> -f myconfig.txt\fR
+.PP
+where subsystem is KRA, OCSP, or TKS, and \fImyconfig.txt\fP contains the following text:
+.IP
+.nf
+[DEFAULT]
+pki_admin_password=\fIpassword123\fP
+pki_client_pkcs12_password=\fIpassword123\fP
+pki_ds_password=\fIpassword123\fP
+pki_security_domain_password=\fIpassword123\fP
+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
+.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], or [TKS].  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/.pki/pki-tomcat\fP. 
+.SS Installing a CA clone
+\x'-1'\fBpkispawn -s CA -f myconfig.txt\fR
+.PP 
+where \fImyconfig.txt\fP contains the following text:
+.IP
+.nf
+[DEFAULT]
+pki_admin_password=\fIpassword123\fP
+pki_client_pkcs12_password=\fIpassword123\fP
+pki_ds_password=\fIpassword123\fP
+pki_security_domain_password=\fIpassword123\fP
+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=\fIpassword123\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 [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.
+.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.  In addition, 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 is created when the master CA is installed; it can also be generated using \fBPKCS12Export\fP.  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.
+.PP
+.SS Installing a KRA, OCSP, or TKS clone
+\x'-1'\fBpkispawn -s <subsystem> -f myconfig.txt\fR
+.PP
+where subsystem is KRA, OCSP, or TKS, and \fImyconfig.txt\fP contains the following text:
+.IP
+.nf
+[DEFAULT]
+pki_admin_password=\fIpassword123\fP
+pki_client_pkcs12_password=\fIpassword123\fP
+pki_ds_password=\fIpassword123\fP
+pki_security_domain_password=\fIpassword123\fP
+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=\fIpassword123\fP
+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>
+.fi
+.PP
+As with a CA clone, a KRA, OCSP, 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 subsystem section is [KRA], [OCSP], or [TKS].
+.SS Installing a subordinate CA
+\x'-1'\fBpkispawn -s CA -f myconfig.txt\fR
+.PP
+where \fImyconfig.txt\fP contains the following text:
+.IP
+.nf
+[DEFAULT]
+pki_admin_password=\fIpassword123\fP
+pki_client_pkcs12_password=\fIpassword123\fP
+pki_ds_password=\fIpassword123\fP
+pki_security_domain_password=\fIpassword123\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 an externally signed CA
+\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=\fIpassword123\fP
+pki_client_pkcs12_password=\fIpassword123\fP
+pki_ds_password=\fIpassword123\fP
+pki_security_domain_password=\fIpassword123\fP
+
+[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
+.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=\fIpassword123\fP
+pki_client_pkcs12_password=\fIpassword123\fP
+pki_ds_password=\fIpassword123\fP
+pki_security_domain_password=\fIpassword123\fP
+
+[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
+.fi
+.PP
+Then, the \fBpkispawn\fP command is run again:
+.PP
+.B pkispawn -s CA -f myconfig.txt
+
+.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)