Date: Tue, 15 Apr 2014 20:08:59 +0000 (UTC) From: Dru Lavigne <dru@FreeBSD.org> To: doc-committers@freebsd.org, svn-doc-all@freebsd.org, svn-doc-head@freebsd.org Subject: svn commit: r44566 - head/en_US.ISO8859-1/books/handbook/network-servers Message-ID: <201404152008.s3FK8x8t010092@svn.freebsd.org>
next in thread | raw e-mail | index | archive | help
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@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>
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?201404152008.s3FK8x8t010092>