[Pki-devel] [PATCH] 633 Updated man page for configuring secure LDAP connection.

Fri Jul 17 00:48:54 UTC 2015

The instruction to setup secure LDAP connection in the pkispawn
man page has been updated. The sample deployment configuration
file has been made more generic. The setup-ds.pl has been removed
from the instruction since generating a self-signed certificate
requires a DS admin server. The URL to download setupssl2.sh has
been changed with a more direct link. The sample LDAP password
has been changed to match the current deployment configuration
examples. Some paragraphs have been line wrapped to simplify man
page development.

-- 
Endi S. Dewata
-------------- next part --------------
From 81ba547550b58c4ce8577839f39a137b1c4b1cac Mon Sep 17 00:00:00 2001
From: "Endi S. Dewata" <edewata at redhat.com>
Date: Thu, 16 Jul 2015 20:18:21 -0400
Subject: [PATCH] Updated man page for configuring secure LDAP connection.

The instruction to setup secure LDAP connection in the pkispawn
man page has been updated. The sample deployment configuration
file has been made more generic. The setup-ds.pl has been removed
from the instruction since generating a self-signed certificate
requires a DS admin server. The URL to download setupssl2.sh has
been changed with a more direct link. The sample LDAP password
has been changed to match the current deployment configuration
examples. Some paragraphs have been line wrapped to simplify man
page development.
---
 base/server/man/man8/pkispawn.8 | 80 ++++++++++++++++++++++++++++-------------
 1 file changed, 56 insertions(+), 24 deletions(-)

diff --git a/base/server/man/man8/pkispawn.8 b/base/server/man/man8/pkispawn.8
index c2ab93ed252d40038126db22a6079178d22e0448..9517b527c848f7e57f536a13696cb29095a0a4f7 100644
--- a/base/server/man/man8/pkispawn.8
+++ b/base/server/man/man8/pkispawn.8
@@ -687,54 +687,86 @@ Then, the \fBpkispawn\fP command is run again:
 
 .IP
 .B pkispawn -s CA -f myconfig.txt
-.SS Installing a CA connecting securely to a Directory Server via LDAPS
-\x'-1'\fBpkispawn \-s CA \-f myconfig.txt\fR
+
+.SS Installing a PKI subsystem with a secure LDAP connection
+.BR
 .PP
-where \fImyconfig.txt\fP contains the following text:
+To install a PKI subsystem with a Directory Server connected via LDAPS
+add the following parameters into the [DEFAULT] section:
+
 .IP
 .nf
-[DEFAULT]
-pki_admin_password=\fIpassword123\fP
-pki_client_database_password=\fIpassword123\fP
-pki_client_pkcs12_password=\fIpassword123\fP
-pki_ds_password=\fIpassword123\fP
 pki_ds_secure_connection=True
 pki_ds_secure_connection_ca_pem_file=\fI/root/dscacert.pem\fP
-
-[CA]
-pki_base_dn=\fIdc=example, dc=com\fP
 .fi
-.TP
-\fBImportant:\fP
-Although this example is specifically for a CA, the \fB[CA]\fP section may be replaced by the appropriate PKI subsystem (i. e. - \fb[KRA]\fP, \fb[OCSP]\fP, \fb[TKS]\fP, or \fb[TPS]\fP) being installed.  Additionally, if a KRA, OCSP, TKS, or TPS subsystem is being installed, they must also include the name/value pair \fBpki_security_domain_password=\fIpassword123\fP in the \fB[DEFAULT]\fP section.
+
 .PP
-Prior to running this command, a Directory Server instance must be configured to run securely over LDAPS using a self-signed certificate, and its self-signed CA certificate exported to a file so that it may be utilized by a PKI instance:
+Prior to installing the subsystem, a Directory Server instance must be
+configured to run securely over LDAPS using a self-signed certificate, and its
+self-signed CA certificate exported to a file so that it may be utilized by a
+PKI instance:
+
 .IP
-* \fBsetup-ds.pl\fP or \fBsetup-ds-admin.pl\fP
+* \fBsetup-ds-admin.pl\fP
+
 .IP
-* \fB/usr/sbin/setupssl2.sh /etc/dirsrv/\fIslapd-pki\fP 389 636 \fIpassword123\fP
+* \fB/usr/sbin/setupssl2.sh /etc/dirsrv/\fIslapd-pki\fP 389 636 \fISecret123\fP
+
 .TP
 \fBNote:\fP
-The \fBsetupssl2.sh\fP script may be downloaded from \fBhttps://github.com/richm/scripts/blob/master/setupssl2.sh\fP.
+The \fBsetupssl2.sh\fP script may be downloaded from \fBhttps://raw.githubusercontent.com/richm/scripts/master/setupssl2.sh\fP.
+
 .IP
 * \fBsystemctl restart dirsrv.target\fP
+
 .IP
 * \fBcd /etc/dirsrv/\fIslapd-pki\fP
+
 .IP
-* \fB/usr/lib64/mozldap/ldapsearch -Z -h \fIpki.example.com\fP -p 636 -D 'cn=Directory Manager' -w \fIpassword123\fP -b \fI"dc=example, dc=com"\fP "objectclass=*"\fP
+* \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
+
 .TP
 \fBNote:\fP
-The \fBmozldap ldapsearch\fP utility may be downloaded via running \fByum install mozldap-tools\fP.
+The \fBmozldap ldapsearch\fP utility is available from the \fBmozldap-tools\fP package.
+
 .IP
 * \fBcertutil -L -d /etc/dirsrv/\fIslapd-pki\fP -n "CA certificate" -a > \fI/root/dscacert.pem\fP
+
 .PP
-It should be noted that there are basically three scenarios in which a PKI subsystem (e. g. - a CA) needs to communicate securely via LDAPS with a directory server:
+It should be noted that there are basically 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 during \fBpkispawn\fP installation/configuration such that the CA may be installed and configured to communicate with this directory server using LDAPS.
+* 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 during \fBpkispawn\fP
+installation/configuration such that the 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.
+* 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/configuration.  For this to succeed, the directory server must generate a temporary self-signed certificate for use during \fBpkispawn\fP installation/creation.  Once the CA has been created, swap things out to reconfigure the CA and directory server to utilize LDAPS through the desired certificates.  This example demonstrates the \fBpkispawn\fP portion of this particular scenario.
+* 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 for use during \fBpkispawn\fP
+installation/creation. Once the CA has been created, swap things out to
+reconfigure the CA and directory server to utilize LDAPS through the
+desired certificates. This example demonstrates the \fBpkispawn\fP
+portion of this particular scenario.
 
 .SS Managing PKI instance
 .BR
-- 
1.9.3

