summaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
authorMatthew Harmsen <mharmsen@redhat.com>2012-12-06 22:03:17 -0800
committerMatthew Harmsen <mharmsen@redhat.com>2012-12-06 22:06:01 -0800
commite7b7d9846060c8eb0e57b0e59047995cfc854569 (patch)
treecad996483e21bd70d2db4b8e96134740ddf25bed
parentcbfdae84f511ae526f1e7e29f71e7f60eef96094 (diff)
downloadpki-e7b7d9846060c8eb0e57b0e59047995cfc854569.tar.gz
pki-e7b7d9846060c8eb0e57b0e59047995cfc854569.tar.xz
pki-e7b7d9846060c8eb0e57b0e59047995cfc854569.zip
Added man pages.
* TRAC Ticket #315 - Man pages for pkispawn/pkidestroy. * Added place-holders for 'pki.1' and 'pki_default.cfg.5' man pages.
-rw-r--r--base/deploy/CMakeLists.txt23
-rw-r--r--base/deploy/man/man5/pki_default.cfg.581
-rw-r--r--base/deploy/man/man8/pkidestroy.858
-rw-r--r--base/deploy/man/man8/pkispawn.8270
-rw-r--r--base/java-tools/CMakeLists.txt10
-rw-r--r--base/java-tools/man/man1/pki.195
-rw-r--r--specs/pki-core.spec9
7 files changed, 545 insertions, 1 deletions
diff --git a/base/deploy/CMakeLists.txt b/base/deploy/CMakeLists.txt
index 3b1d9f583..94abccdbc 100644
--- a/base/deploy/CMakeLists.txt
+++ b/base/deploy/CMakeLists.txt
@@ -23,6 +23,29 @@ set(APACHE_SUBSYSTEMS
install(
FILES
+ man/man5/pki_default.cfg.5
+ DESTINATION
+ ${MAN_INSTALL_DIR}/man5
+ PERMISSIONS
+ OWNER_EXECUTE OWNER_WRITE OWNER_READ
+ GROUP_EXECUTE GROUP_READ
+ WORLD_EXECUTE WORLD_READ
+)
+
+install(
+ FILES
+ man/man8/pkispawn.8
+ man/man8/pkidestroy.8
+ DESTINATION
+ ${MAN_INSTALL_DIR}/man8
+ PERMISSIONS
+ OWNER_EXECUTE OWNER_WRITE OWNER_READ
+ GROUP_EXECUTE GROUP_READ
+ WORLD_EXECUTE WORLD_READ
+)
+
+install(
+ FILES
src/pkispawn
src/pkidestroy
DESTINATION
diff --git a/base/deploy/man/man5/pki_default.cfg.5 b/base/deploy/man/man5/pki_default.cfg.5
new file mode 100644
index 000000000..96e26762e
--- /dev/null
+++ b/base/deploy/man/man5/pki_default.cfg.5
@@ -0,0 +1,81 @@
+.\" 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 5, 2012" "version 1.0" "PKI Default Instance Configuration" Ade Lee
+.\" Please adjust this date whenever revising the manpage.
+.\"
+.\" 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 manpage-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 Certifcate Server instance created using \fBpkispawn\fP. This file should not be edited, as it can be modified when the Certificate Server packages are udpated. 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
+.BR pkispawn(2)
+ 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 susbsystem 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 parameters values can be interpolated tokens rather than explicit values. For example,
+.PP
+\fBpki_ca_signing_nickname=caSigningCert cert-%(pki_instance_id)s CA\fP
+.PP
+substitutes the value of pki_instance_id 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_id should only be overridden in [DEFAULT]; otherwise, interpolations can fail.
+
+.SH PARAMETERS
+These parameters can be customized as part of a deployment, grouped by functionality. This list is not exhaustive.
+
+.SS GENERAL INSTANCE PARAMETERS
+.TP
+.B pki_instance_name
+Name of the instance. The instance is located at /var/lib/pki/<instance_name>. For Java subsystems, the default is pki-tomcat.
+.TP
+.B pki_https_port, pki_http_port
+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
+Ports for Tomcat subsystems. Defaults to standard Tocat ports of 8009 and 8005, respectively.
+.TP
+.B pki_proxy_http_port, pki_proxy_https_port, pki_enable_proxy
+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 Red Hat Certificate System documentation for details.
+
+.SS INTERNAL DATABASE PARAMETERS
+.TP
+.B pki_ds_hostname, pki_ds_ldap_port, pki_ds_ldaps_port
+Hostname and ports for the internal database. Defaults to localhost, 389, and 636.
+.TP
+.B pki_ds_bind_dn, pki_ds_password
+Credentials to connect to the database during installation. Directory manager level access if 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.
+.TP
+.B pki_ds_secure_connection
+Set to True to require connections to the Directory Server using LDAPS. Requires SSL to be set up on the Directory Server first. Defaults to false.
+.TP
+.B pki_ds_remove_data
+Set to True to remove any data from the base DN before starting the installation. Defaults to True.
+.TP
+.B pki_ds_base_dn
+blah blah
+.TP
+.B pki_ds_database
+blah blah
+
+.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/deploy/man/man8/pkidestroy.8 b/base/deploy/man/man8/pkidestroy.8
new file mode 100644
index 000000000..b4e012a06
--- /dev/null
+++ b/base/deploy/man/man8/pkidestroy.8
@@ -0,0 +1,58 @@
+.\" 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 5, 2012" "version 1.0" "PKI Instance Removal Utility" Ade Lee
+.\" Please adjust this date whenever revising the manpage.
+.\"
+.\" 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 manpage-specific macros, see man(7)
+.SH NAME
+pkidestroy \- Removes a subsytem from an instance of Certificate Server.
+
+.SH SYNOPSIS
+pkidestroy -s <subsystem> -i <instance> [-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 Apache-based 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.
+.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>.
+.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 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/deploy/man/man8/pkispawn.8 b/base/deploy/man/man8/pkispawn.8
new file mode 100644
index 000000000..87795a626
--- /dev/null
+++ b/base/deploy/man/man8/pkispawn.8
@@ -0,0 +1,270 @@
+.\" 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 5, 2012" "version 1.0" "PKI Instance Creation Utility" Ade Lee
+.\" Please adjust this date whenever revising the manpage.
+.\"
+.\" 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 manpage-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 the Certificate Server instance and its rich feature set, 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 supercedes 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 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_backup_password=\fIpassword123\fP
+pki_client_pkcs12_password=\fIpassword123\fP
+pki_ds_password=\fIpassword123\fP
+pki_security_domain_password=\fIpassword123\fP
+.fi
+.PP
+Prior to running this command, a Directory Server instance should be created and running on the local machine on port 389 with user cn=Directory Manager having the password specified in pki_ds_password above. 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. 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 is the same as the one used for the default CA example. 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_backup_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=https://<ca_hostname>:<ca_port>
+.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
+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_backup_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_backup_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_backup_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>
+.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.
+.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_backup_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 subjectDN.
+.PP
+The CSR is then submitted to the external CA, and the resulting certificate and certificate chain are copied to files on the system.
+.PP
+.B pkispawn -s CA -f myconfig.txt
+.PP
+In the second step, the \fBpkispawn\fP command is run again after the configuration file has been modified to contain the following text:
+.IP
+.nf
+[DEFAULT]
+pki_admin_password=\fIpassword123\fP
+pki_backup_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,ou=External,o=example.com
+.fi
+.PP
+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).
+
+.SH BUGS
+Report bugs to http://bugzilla.redhat.com.
+
+.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 pkidestroy(8),
+.BR pki_default.cfg(5),
+.BR pki(1),
+.BR setup-ds.pl(8)
diff --git a/base/java-tools/CMakeLists.txt b/base/java-tools/CMakeLists.txt
index e3024da86..430985d71 100644
--- a/base/java-tools/CMakeLists.txt
+++ b/base/java-tools/CMakeLists.txt
@@ -1,5 +1,15 @@
project(java-tools NONE)
+install(
+ FILES
+ man/man1/pki.1
+ DESTINATION
+ ${MAN_INSTALL_DIR}/man1
+ PERMISSIONS
+ OWNER_EXECUTE OWNER_WRITE OWNER_READ
+ GROUP_EXECUTE GROUP_READ
+ WORLD_EXECUTE WORLD_READ
+)
install(
FILES
diff --git a/base/java-tools/man/man1/pki.1 b/base/java-tools/man/man1/pki.1
new file mode 100644
index 000000000..30b8668f2
--- /dev/null
+++ b/base/java-tools/man/man1/pki.1
@@ -0,0 +1,95 @@
+.\" 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 1 "December 5, 2012" "version 1.0" "PKI Command-Line Interface (CLI) Tools" Ade Lee
+.\" Please adjust this date whenever revising the manpage.
+.\"
+.\" 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 manpage-specific macros, see man(7)
+.SH NAME
+pki \- Command-Line Interface (CLI) Tools.
+
+.SH LOCATION
+/usr/bin/pki
+
+.SH DESCRIPTION
+.PP
+The \fBpki\fR command-line interface tool allows an administrator the ability
+to manage certificates, groups, keys, security domains, and users from the
+command line.
+
+.SH OPTIONS
+.TP
+.B -d <database>
+Specifies the certificate database to be utilized.
+.TP
+.B -h <hostname>
+Specifies the hostname (default: localhost).
+.TP
+.B --help
+Prints additional help information.
+.TP
+.B -n <nickname>
+Specifies the certificate nickname.
+.TP
+.B -P <protocol>
+Specifies the protocol (default: http)
+.TP
+.B -p <port>
+Specifies the port (default: 8080)
+.TP
+.B -t <type>
+Specifies the type of subsystem (default: ca)
+.TP
+.B -U <uri>
+Specifies the server URI.
+.TP
+.B -u <username>
+Specifies the user name.
+.TP
+.B -v
+Displays verbose information.
+.TP
+.B --version
+Displays 'pki' CLI version information.
+.TP
+.B -w <password>
+Specifies the password.
+
+.SH COMMANDS
+.SS cert \- Certificate Management Commands
+.PP
+blah blah
+
+.SS group \- Group Management Commands
+.PP
+blah blah
+
+.SS key \- Key Management Commands
+.PP
+blah blah
+
+.SS securitydomain \- Security Domain Commands
+.PP
+blah blah
+
+.SS user \- User Management Commands
+.PP
+blah blah
+
+.SH AUTHORS
+Ade Lee <alee@redhat.com>. \fBpki\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
+blah blah
diff --git a/specs/pki-core.spec b/specs/pki-core.spec
index f7481548c..e78022f20 100644
--- a/specs/pki-core.spec
+++ b/specs/pki-core.spec
@@ -14,7 +14,7 @@ distutils.sysconfig import get_python_lib; print(get_python_lib(1))")}
Name: pki-core
Version: 10.0.0
-Release: %{?relprefix}55%{?prerel}%{?dist}
+Release: %{?relprefix}56%{?prerel}%{?dist}
Summary: Certificate System - PKI Core Components
URL: http://pki.fedoraproject.org/
License: GPLv2
@@ -808,6 +808,7 @@ fi
%{_bindir}/TokenInfo
%{_javadir}/pki/pki-tools.jar
%{_datadir}/pki/java-tools/
+%{_mandir}/man1/*
%files -n pki-server
@@ -846,6 +847,8 @@ fi
%{_bindir}/pkisilent
%{_datadir}/pki/silent/
%{_bindir}/pkicontrol
+%{_mandir}/man5/*
+%{_mandir}/man8/*
# Details:
#
@@ -960,6 +963,10 @@ fi
%changelog
+* Thu Dec 8 2012 Matthew Harmsen <mharmsen@redhat.com> 10.0.0-0.56.b3
+- TRAC Ticket #315 - Man pages for pkispawn/pkidestroy.
+- Added place-holders for 'pki.1' and 'pki_default.cfg.5' man pages.
+
* Thu Dec 6 2012 Endi S. Dewata <edewata@redhat.com> 10.0.0-0.55.b3
- Added system-wide configuration /etc/pki/pki.conf.
- Removed redundant lines in %files.