Man page updates for new cloning options

2 files changed, 88 insertions, 1 deletions

diff --git a/base/server/man/man8/pki-server-instance.8 b/base/server/man/man8/pki-server-instance.8
index 18518f618..4d0f52bd9 100644
--- a/base/server/man/man8/pki-server-instance.8
+++ b/base/server/man/man8/pki-server-instance.8
@@ -27,6 +27,10 @@ pki-server instance \- Command-Line Interface for managing Certificate System in
 \fBpki-server [CLI options] instance-migrate\fR --tomcat <version> <instance ID>
 \fBpki-server [CLI options] instance-nuxwdog-enable\fR <instance ID>
 \fBpki-server [CLI options] instance-nuxwdog-disable\fR <instance ID>
+\fBpki-server [CLI options] instance-externalcert-add\fR -i <instance ID>
+    --cert-file <path> --trust-args <args> --nickname <nickname> --token <token>
+\fBpki-server [CLI options] instance-externalcert-del\fR -i <instance ID>
+    --nickname <nickname> --token <token>
 .fi
 
 .SH DESCRIPTION
@@ -87,6 +91,24 @@ This command is to convert a CS instance to start with access to a
 password file, rather than using the \fBnuxwdog\fR daemon.  See \fBpki-server nuxwdog\fR(8)
 for further details.
 .RE
+.PP
+\fBpki-server [CLI options] instance-externalcert-add\fR -i <instance ID>
+    --cert-file <path> --trust-args <args> --nickname <nickname> --token <token>
+.RS 4
+This command is to add a certificate to the certificate database for a CS instance.
+The certificate will be kept track of in the configuration file \fBexternal_certs.conf\fP,
+and will automatically be exported when the system certificates are exported.  To
+update a certificate, the old one needs to be removed first using the delete command below.
+
+The trust arguments are those defined for NSS databases eg. "C,c,c".  See \fBcertutil(1)\fP
+for more details.  
+.RE
+.PP
+\fBpki-server [CLI options] instance-externalcert-del\fR -i <instance ID>
+    --nickname <nickname> --token <token>
+.RS 4
+This command is to remove a certificate from the certificate database for a CS instance.
+.RE
 
 .SH OPTIONS
 The CLI options are described in \fBpki-server\fR(8).
diff --git a/base/server/man/man8/pkispawn.8 b/base/server/man/man8/pkispawn.8
index 2a6b95084..92751d7d7 100644
--- a/base/server/man/man8/pkispawn.8
+++ b/base/server/man/man8/pkispawn.8
@@ -559,7 +559,66 @@ 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:
 
@@ -578,6 +637,7 @@ 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
@@ -618,7 +678,12 @@ 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).
+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