svn commit: r44566 - head/en_US.ISO8859-1/books/handbook/network-servers
Dru Lavigne
dru at FreeBSD.org
Tue Apr 15 20:09:00 UTC 2014
Author: dru
Date: Tue Apr 15 20:08:59 2014
New Revision: 44566
URL: http://svnweb.freebsd.org/changeset/doc/44566
Log:
Editorial review of first part of LDAP chapter.
Rename the chapter to be consistent with the format used in the rest of
this mega-chapter.
Need to verify the configuration commands before finishing editorial
review of rest of this section.
Sponsored by: iXsystems
Modified:
head/en_US.ISO8859-1/books/handbook/network-servers/chapter.xml
Modified: head/en_US.ISO8859-1/books/handbook/network-servers/chapter.xml
==============================================================================
--- head/en_US.ISO8859-1/books/handbook/network-servers/chapter.xml Tue Apr 15 17:45:54 2014 (r44565)
+++ head/en_US.ISO8859-1/books/handbook/network-servers/chapter.xml Tue Apr 15 20:08:59 2014 (r44566)
@@ -2128,67 +2128,69 @@ TWO (,hotel,test-domain)
</sect1>
<sect1 xml:id="network-ldap">
- <!--
- <sect1info>
+ <info>
+ <title>Lightweight Directory Access Protocol
+ (<acronym>LDAP</acronym>)</title>
+
<authorgroup>
<author>
+ <personname>
<firstname>Tom</firstname>
<surname>Rhodes</surname>
+ </personname>
<contrib>Written by </contrib>
</author>
</authorgroup>
- </sect1info>
- -->
- <title>&os; and <acronym>LDAP</acronym></title>
+ </info>
<indexterm><primary>LDAP</primary></indexterm>
- <para><acronym>LDAP</acronym>, the Lightweight Directory Access
- Protocol, is an application layer protocol used to access,
- modify, and authenticate (bind) using a distributed directory
+ <para>The Lightweight Directory Access
+ Protocol (<acronym>LDAP</acronym>) is an application layer protocol used to access,
+ modify, and authenticate objects using a distributed directory
information service. Think of it as a phone or record book
which stores several levels of hierarchical, homogeneous
- information. It is often used in networks where users often
- need access to several levels of internal information utilizing
+ information. It is used in Active Directory and
+ <application>OpenLDAP</application> networks and allows users to
+ access to several levels of internal information utilizing
a single account. For example, email authentication, pulling
employee contact information, and internal website
- authentication might all make use of a single user in the
+ authentication might all make use of a single user account in the
<acronym>LDAP</acronym> server's record base.</para>
- <para>This section will not provide a history or the
- implementation details of the protocol. These sections were
- authored to get an <acronym>LDAP</acronym> server and/or client
- configured both quickly and securely; however, any information
- base requires planning and this is no exception.</para>
-
- <para>Planning should include what type of information will be
- stored, what that information will be used for, whom should
- have access to said information, and how to secure this
- information from prying eyes.</para>
+ <para>This section provides a quick start guide for configuring
+ an <acronym>LDAP</acronym> server on a &os; system.
+ It assumes that the administrator already has a design plan
+ which includes the type of information to
+ store, what that information will be used for, which users should
+ have access to that information, and how to secure this
+ information from unauthorized access.</para>
<sect2>
<title><acronym>LDAP</acronym> Terminology and Structure</title>
- <para>Before continuing, several parts of
- <acronym>LDAP</acronym> must be explained to prevent
- confusion. And confusion with this configuration is
- relatively simple. To begin, all directory entries consist of
- a group of <emphasis>attributes</emphasis>. Each of these
- attribute sets contain a name, a unique identifier known as a
- <acronym>DN</acronym> or distinguished name normally built
- from several other attributes such as the
- <acronym>RDN</acronym>. The <acronym>RDN</acronym> or
- relative distinguished name, is a more common name for the
- attribute. Like directories have absolute and relative paths,
+ <para><acronym>LDAP</acronym> uses several terms which should be
+ understood before starting the configuration.
+ All directory entries consist of
+ a group of <firstterm>attributes</firstterm>. Each of these
+ attribute sets contains a unique identifier known as a
+ <firstterm>Distinguished Name</firstterm> (<acronym>DN</acronym>)
+ which is normally built
+ from several other attributes such as the common or
+ <firstterm>Relative Distinguished Name</firstterm>
+ (<acronym>RDN</acronym>).
+ Similar to how directories have absolute and relative paths,
consider a <acronym>DN</acronym> as an absolute path and the
<acronym>RDN</acronym> as the relative path.</para>
- <para>As an example, an entry might look like the
- following:</para>
+ <para>An example <acronym>LDAP</acronym> entry looks like the
+ following. This example searches for the entry for the specified user
+ account (<literal>uid</literal>), organizational unit
+ (<literal>ou</literal>), and organization
+ (<literal>o</literal>):</para>
- <screen>&prompt.user; ldapsearch -xb "uid=trhodes,ou=users,o=example.com"</screen>
-
- <programlisting># extended LDIF
+ <screen>&prompt.user; <userinput>ldapsearch -xb "uid=<replaceable>trhodes</replaceable>,ou=<replaceable>users</replaceable>,o=<replaceable>example.com</replaceable>"</userinput>
+# extended LDIF
#
# LDAPv3
# base <uid=trhodes,ou=users,o=example.com> with scope subtree
@@ -2201,21 +2203,25 @@ dn: uid=trhodes,ou=users,o=example.com
mail: trhodes at example.com
cn: Tom Rhodes
uid: trhodes
-telephoneNumber: (xxx) xxx-xxxx
+telephoneNumber: (123) 456-7890
# search result
search: 2
result: 0 Success
# numResponses: 2
-# numEntries: 1</programlisting>
+# numEntries: 1</screen>
- <para>In this example, it is very obvious what the various
- attributes are; however, the <acronym>cn</acronym> attribute
- should be noticed. This is the <acronym>RDN</acronym>
- discussed previously. In addition, there is a unique user id
- provided here. It is common practice to have specific uid or
- uuids for entries to ease in any future migration.</para>
+ <para>This example entry shows the values for the
+ <literal>dn</literal>, <literal>mail</literal>,
+ <literal>cn</literal>, <literal>uid</literal>, and
+ <literal>telephoneNumber</literal>
+ attributes. The <acronym>cn</acronym> attribute
+ is the <acronym>RDN</acronym>.</para>
+
+ <para>More information about <acronym>LDAP</acronym> and its
+ terminology can be found at <uri
+ xlink:href="http://www.openldap.org/doc/admin24/intro.html">http://www.openldap.org/doc/admin24/intro.html</uri>.</para>
</sect2>
<sect2>
@@ -2223,72 +2229,63 @@ result: 0 Success
<indexterm><primary>LDAP Server</primary></indexterm>
- <para>To configure &os; to act as an <acronym>LDAP</acronym>
- server, the OpenLDAP port needs installed. This may be
- accomplished using the <command>pkg_add</command> command
- or by installing the
- <package role="port">net/openldap24-server</package>
- port. Building the port is recommended as the administrator
- may select a great deal of options at this time and disable
- some options. In most cases, the defaults will be fine;
- however, this is the time to enable SQL support if
- needed.</para>
-
- <para>A few directories will be required from this point on,
- at minimal, a data directory and a directory to store the
- certificates in. Create them both with the following
- commands:</para>
+ <para>&os; does not provide a built-in <acronym>LDAP</acronym>
+ server. Begin the configuration by installing the
+ <package role="port">net/openldap24-server</package> package or
+ port. Since the port has many configurable
+ options, it is recommended that the default options are
+ reviewed to see if the package is sufficient, and to instead
+ compile the port if any options should be changed.
+ In most cases, the defaults are fine.
+ However, if SQL support is needed, this option must be
+ enabled and the port compiled using the instructions in <xref
+ linkend="ports-using"/>.</para>
+
+ <para>Next, create the directories to hold the
+ data and to store the
+ certificates:</para>
- <screen>&prompt.root; <userinput>mkdir /var/db/openldap-data</userinput></screen>
-
- <screen>&prompt.root; <userinput>mkdir /usr/local/etc/openldap/private</userinput></screen>
+ <screen>&prompt.root; <userinput>mkdir /var/db/openldap-data</userinput>
+&prompt.root; <userinput>mkdir /usr/local/etc/openldap/private</userinput></screen>
<para>Copy over the database configuration file:</para>
<screen>&prompt.root; <userinput>cp /usr/local/etc/openldap/DB_CONFIG.example /var/db/openldap-data/DB_CONFIG</userinput></screen>
- <para>The next phase is to configure the <acronym>SSL</acronym>
- certificates. While creating certificates is discussed in
- the <link linkend="openssl">OpenSSL</link> section in this
- book, a certificate authority is needed so a different method
- will be used. It is recommended that this section be reviewed
- prior to configuring to ensure correct information is entered
- during the certificate creation process below.</para>
-
- <para>The following commands must be executed in the
- <filename>/usr/local/etc/openldap/private</filename>
- directory. This is important as the file permissions will
+ <para>The next phase is to configure the certificate authority.
+ The following commands must be executed from
+ <filename>/usr/local/etc/openldap/private</filename>.
+ This is important as the file permissions
need to be restrictive and users should not have access to
- these files directly. To create the certificates, issues the
- following commands.</para>
+ these files. To create the certificate authority,
+ start with this command and follow the prompts:</para>
- <screen>&prompt.root; <userinput>openssl req -days 365 -nodes -new -x509 -keyout ca.key -out ../ca.crt</userinput></screen>
+ <screen>&prompt.root; <userinput>openssl req -days <replaceable>365</replaceable> -nodes -new -x509 -keyout ca.key -out ../ca.crt</userinput></screen>
- <para>The entries for these may be completely generic
+ <para>The entries for the prompts may be generic
<emphasis>except</emphasis> for the
- <emphasis>Common Name</emphasis> entry. This entry must have
- something different than the system hostname. If the entry
- is the hostname, it would be like the hostname is attempting
- to verify hostname. In cases with a self signed certificate
- like this example, just prefix the hostname with
- <acronym>CA</acronym> for certificate authority.</para>
+ <literal>Common Name</literal>. This entry must be
+ <emphasis>different</emphasis> than the system hostname.
+ If this will be a self signed certificate,
+ prefix the hostname with
+ <literal>CA</literal> for certificate authority.</para>
<para>The next task is to create a certificate signing request
- and a private key. To do this, issue the following
- commands:</para>
+ and a private key. Input this command and follow the
+ prompts:</para>
- <screen>&prompt.root; <userinput>openssl req -days 365 -nodes -new -keyout server.key -out server.csr</userinput></screen>
+ <screen>&prompt.root; <userinput>openssl req -days <replaceable>365</replaceable> -nodes -new -keyout server.key -out server.csr</userinput></screen>
<para>During the certificate generation process, be sure to
- correctly set the common name attribute. After this has
- been completed, the key will need signed:</para>
+ correctly set the <literal>Common Name</literal> attribute. Once
+ complete, sign the key:</para>
- <screen>&prompt.root; <userinput>openssl x509 -req -days 365 -in server.csr -out ../server.crt -CA ../ca.crt -CAkey ca.key -CAcreateserial</userinput></screen>
+ <screen>&prompt.root; <userinput>openssl x509 -req -days <replaceable>365</replaceable> -in server.csr -out ../server.crt -CA ../ca.crt -CAkey ca.key -CAcreateserial</userinput></screen>
<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 365 -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></screen>
<screen>&prompt.root; <userinput>openssl x509 -req -days 3650 -in client.csr -out ../client.crt -CA ../ca.crt -CAkey ca.key</userinput></screen>
More information about the svn-doc-all
mailing list