Initial editorial pass through config section of LDAP.

Another pass is needed as this section could benefit from either several
sub-headings or procedures.

Sponsored by:	iXsystems

en_US.ISO8859-1/books/handbook/network-servers/chapter.xml

@@ -2285,13 +2285,12 @@ result: 0 Success
       <para>The final part of the certificate generation process
 	is to generate and sign the client certificates:</para>
 
-      <screen>&prompt.root; <userinput>openssl req -days <replaceable>365</replaceable> -nodes -new -keyout client.key -out client.csr</userinput></screen>
+      <screen>&prompt.root; <userinput>openssl req -days <replaceable>365</replaceable> -nodes -new -keyout client.key -out client.csr</userinput>
+&prompt.root; <userinput>openssl x509 -req -days 3650 -in client.csr -out ../client.crt -CA ../ca.crt -CAkey ca.key</userinput></screen>
 
-      <screen>&prompt.root; <userinput>openssl x509 -req -days 3650 -in client.csr -out ../client.crt -CA ../ca.crt -CAkey ca.key</userinput></screen>
+      <para>Remember to use the same <literal>Common Name</literal>
-
+	attribute when prompted.
-      <para>Remember, again, to respect the common name attribute.
+	When finished, ensure
-	This is a common cause for confusion during the first attempt
-	to configure <acronym>LDAP</acronym>.  In addition, ensure
 	that a total of eight (8) new files have been generated
 	through the proceeding commands.  If so, the next step is to
 	edit <filename>/usr/local/etc/openldap/slapd.conf</filename>
@@ -2302,60 +2301,58 @@ TLSCertificateFile /usr/local/etc/openldap/server.crt
 TLSCertificateKeyFile /usr/local/etc/openldap/private/server.key
 TLSCACertificateFile /usr/local/etc/openldap/ca.crt</programlisting>
 
-      <para>In addition, edit
+      <para>Then, edit
 	<filename>/usr/local/etc/openldap/ldap.conf</filename> and
 	add the following lines:</para>
 
       <programlisting>TLS_CACERT /usr/local/etc/openldap/ca.crt
 TLS_CIPHER_SUITE HIGH:MEDIUM:+SSLv3</programlisting>
 
-      <para>While editing these this file, set the
+      <para>While editing this file, uncomment the following entries
-	<option>BASE</option> to the desired values, and uncomment all
+	and set them to the desired values:
-	three of the <option>URI</option>, <option>SIZELIMIT</option>
+	<option>BASE</option>,
-	and <option>TIMELIMIT</option> options.  In addition, set the
+	<option>URI</option>, <option>SIZELIMIT</option>
+	and <option>TIMELIMIT</option>.  Set the
 	<option>URI</option> to contain <option>ldap://</option> and
-	<option>ldaps://</option>.</para>
+	<option>ldaps://</option>.  Then, add two entries pointing to
-
+	the certificate authority.  When finished, the entries should
-      <para>The resulting file should look similar to the following
+	look similar to the following:</para>
-	shown here:</para>
 
       <programlisting>BASE    dc=example,dc=com
 URI     ldap:// ldaps://
 
 SIZELIMIT       12
 TIMELIMIT       15
-#DEREF          never
 
 TLS_CACERT /usr/local/etc/openldap/ca.crt
 TLS_CIPHER_SUITE HIGH:MEDIUM:+SSLv3</programlisting>
 
-      <para>A password for the server will need to be created as the
+      <para>The default password for the server should then be
-	default is extremely poor as is normal in this industry.  To
+	changed:</para>
-	do this, issue the following command, sending the output to
-	<filename>slapd.conf</filename>:</para>
 
       <screen>&prompt.root; <userinput>slappasswd -h "{SHA}" &gt;&gt; /usr/local/etc/openldap/slapd.conf</userinput></screen>
 
-      <para>There will be a prompt for entering the password and,
+      <para>This command will prompt for the password and,
 	if the process does not fail, a password hash will be added
 	to the end of <filename>slapd.conf</filename>.
-	<command>slappasswd</command> understands several hashing
+	Several hashing
-	formats, refer to its manual page for more information.</para>
+	formats are supported.  Refer to the manual page for
+	<command>slappasswd</command> for more information.</para>
 
-      <para>Edit
+      <para>Next, edit
 	<filename>/usr/local/etc/openldap/slapd.conf</filename> and
 	add the following lines:</para>
 
       <programlisting>password-hash {sha}
 allow bind_v2</programlisting>
 
-      <para>In addition, the <option>suffix</option> in this file must
+      <para>The <option>suffix</option> in this file must
-	be updated to match the <option>BASE</option> from the
+	be updated to match the <option>BASE</option> used in
-	previous configuration.  The <option>rootdn</option> option
+	<filename>/usr/local/etc/openldap/ldap.conf</filename> and <option>rootdn</option>
-	should also be set.  A good recommendation is something like
+	should also be set.  A recommended value for <option>rootdn</option> is something like
 	<option>cn=Manager</option>.  Before saving this file, place
-	the <option>rootpw</option> option in front of the password
+	the <option>rootpw</option> in front of the password
-	output from the <command>slappasswd</command> and delete the
+	output from <command>slappasswd</command> and delete the
 	old <option>rootpw</option> option above.  The end result
 	should look similar to this:</para>
 
@@ -2366,28 +2363,23 @@ TLSCACertificateFile /usr/local/etc/openldap/ca.crt
 rootpw  {SHA}W6ph5Mm5Pz8GgiULbPgzG37mj9g=</programlisting>
 
       <para>Finally, enable the <application>OpenLDAP</application>
-	service in <filename>rc.conf</filename>.  At this time,
+	service in <filename>/etc/rc.conf</filename> and set
-	setting up a <acronym>URI</acronym> and providing the group
+	the <acronym>URI</acronym>:</para>
-	and user to run as may be useful.  Edit
-	<filename>/etc/rc.conf</filename> and add the following
-	lines:</para>
 
       <programlisting>slapd_enable="YES"
 slapd_flags="-4 -h ldaps:///"</programlisting>
 
-      <para>At this point the server should be ready to be brought
+      <para>At this point the server can be started
-	up and tested.  To perform this task, issue the following
+	and tested:</para>
-	command:</para>
 
       <screen>&prompt.root; <userinput>service slapd start</userinput></screen>
 
-      <para>If everything was configured correctly, a search of the
+      <para>If everything is configured correctly, a search of the
 	directory should show a successful connection with a single
 	response as in this example:</para>
 
-      <screen>&prompt.root; <userinput>ldapsearch -Z</userinput></screen>
+      <screen>&prompt.root; <userinput>ldapsearch -Z</userinput>
-
+# extended LDIF
-      <programlisting># extended LDIF
 #
 # LDAPv3
 # base &lt;dc=example,dc=com&gt; (default) with scope subtree
@@ -2399,55 +2391,49 @@ slapd_flags="-4 -h ldaps:///"</programlisting>
 search: 3
 result: 32 No such object
 
-# numResponses: 1</programlisting>
+# numResponses: 1</screen>
-
-      <para>Considering the service should now be responding, as it
-	is above, the directory may be populated using the
-	<command>ldapadd</command> command.  In this example, there
-	is a file containing a list of users to be added to this
-	particular directory.  First, create a file to be imported
-	with the following dataset:</para>
-
-      <programlisting>dn: dc=example,dc=com
-objectclass: dcObject
-objectclass: organization
-o: Example
-dc: Example
-
-dn: cn=Manager,dc=example,dc=com
-objectclass: organizationalRole
-cn: Manager</programlisting>
 
       <note>
-	<para>To debug any of the following, stop the
+	<para>If the command fails and the configuration looks
-	  <command>slapd</command> service using the
+	  correct, stop the
-	  <command>service</command> command and start it using with
+	  <command>slapd</command> service and restart it with
-	  debugging options.  To accomplish this, issue the following
+	  debugging options:</para>
-	  command:</para>
 
-	<screen>&prompt.root; <userinput>/usr/local/libexec/slapd -d -1</userinput></screen>
+	<screen>&prompt.root; <userinput>service slapd stop</userinput>
+&prompt.root; <userinput>/usr/local/libexec/slapd -d -1</userinput></screen>
       </note>
 
-      <para>To import this datafile, issue the following command,
+      <para>Once the service is responding,
-	assuming the file is <filename>import.ldif</filename>:</para>
+	the directory can be populated using
+	<command>ldapadd</command>.  In this example,
+	a file containing this list of users is first created.  Each
+	user should use the following format:</para>
 
-      <screen>&prompt.root; <userinput>ldapadd -Z -D "cn=Manager,dc=example,dc=com" -W -f <replaceable>import.ldif</replaceable></userinput></screen>
+      <programlisting>dn: dc=<replaceable>example</replaceable>,dc=<replaceable>com</replaceable>
+objectclass: dcObject
+objectclass: organization
+o: <replaceable>Example</replaceable>
+dc: <replaceable>Example</replaceable>
 
-      <para>There will be a request for the password specified
+dn: cn=<replaceable>Manager</replaceable>,dc=<replaceable>example</replaceable>,dc=<replaceable>com</replaceable>
-	earlier, and the output should look like this:</para>
+objectclass: organizationalRole
+cn: <replaceable>Manager</replaceable></programlisting>
 
-      <screen>Enter LDAP Password:
+      <para>To import this file, specify the file name.
+	The following command will prompt for the password specified
+	earlier and the output should look something like this:</para>
+
+      <screen>&prompt.root; <userinput>ldapadd -Z -D "cn=<replaceable>Manager</replaceable>,dc=<replaceable>example</replaceable>,dc=<replaceable>com</replaceable>" -W -f <replaceable>import.ldif</replaceable></userinput>
+Enter LDAP Password:
 adding new entry "dc=example,dc=com"
 
 adding new entry "cn=Manager,dc=example,dc=com"</screen>
 
       <para>Verify the data was added by issuing a search on the
-	server using <command>ldapsearch</command>.  In this case
+	server using <command>ldapsearch</command>:</para>
-	the output should look like this:</para>
 
-      <screen>&prompt.user; <userinput>ldapsearch -Z</userinput></screen>
+      <screen>&prompt.user; <userinput>ldapsearch -Z</userinput>
-
+# extended LDIF
-      <screen># extended LDIF
 #
 # LDAPv3
 # base &lt;dc=example,dc=com&gt; (default) with scope subtree
@@ -2474,9 +2460,7 @@ result: 0 Success
 # numResponses: 3
 # numEntries: 2</screen>
 
-      <para>It is of course advisable to read about the structure of
+      <para>At this point, the server
-	<acronym>LDAP</acronym> directories and the various manual
-	pages mentioned in this section.  At this point, the server
 	should be configured and functioning properly.</para>
     </sect2>
   </sect1>