From owner-svn-doc-all@FreeBSD.ORG Tue Apr 15 20:08:59 2014 Return-Path: Delivered-To: svn-doc-all@freebsd.org Received: from mx1.freebsd.org (mx1.freebsd.org [8.8.178.115]) (using TLSv1 with cipher ADH-AES256-SHA (256/256 bits)) (No client certificate requested) by hub.freebsd.org (Postfix) with ESMTPS id EF422150; Tue, 15 Apr 2014 20:08:59 +0000 (UTC) Received: from svn.freebsd.org (svn.freebsd.org [IPv6:2001:1900:2254:2068::e6a:0]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (Client did not present a certificate) by mx1.freebsd.org (Postfix) with ESMTPS id DA539171C; Tue, 15 Apr 2014 20:08:59 +0000 (UTC) Received: from svn.freebsd.org ([127.0.1.70]) by svn.freebsd.org (8.14.8/8.14.8) with ESMTP id s3FK8xIA010093; Tue, 15 Apr 2014 20:08:59 GMT (envelope-from dru@svn.freebsd.org) Received: (from dru@localhost) by svn.freebsd.org (8.14.8/8.14.8/Submit) id s3FK8x8t010092; Tue, 15 Apr 2014 20:08:59 GMT (envelope-from dru@svn.freebsd.org) Message-Id: <201404152008.s3FK8x8t010092@svn.freebsd.org> From: Dru Lavigne Date: Tue, 15 Apr 2014 20:08:59 +0000 (UTC) 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 X-SVN-Group: doc-head MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit X-BeenThere: svn-doc-all@freebsd.org X-Mailman-Version: 2.1.17 Precedence: list List-Id: "SVN commit messages for the entire doc trees \(except for " user" , " projects" , and " translations" \)" List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Tue, 15 Apr 2014 20:09:00 -0000 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) - - &os; and <acronym>LDAP</acronym> + LDAP - LDAP, the Lightweight Directory Access - Protocol, is an application layer protocol used to access, - modify, and authenticate (bind) using a distributed directory + The Lightweight Directory Access + Protocol (LDAP) 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 + OpenLDAP 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 LDAP server's record base. - This section will not provide a history or the - implementation details of the protocol. These sections were - authored to get an LDAP server and/or client - configured both quickly and securely; however, any information - base requires planning and this is no exception. - - 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. + This section provides a quick start guide for configuring + an LDAP 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. <acronym>LDAP</acronym> Terminology and Structure - Before continuing, several parts of - LDAP must be explained to prevent - confusion. And confusion with this configuration is - relatively simple. To begin, all directory entries consist of - a group of attributes. Each of these - attribute sets contain a name, a unique identifier known as a - DN or distinguished name normally built - from several other attributes such as the - RDN. The RDN or - relative distinguished name, is a more common name for the - attribute. Like directories have absolute and relative paths, + LDAP uses several terms which should be + understood before starting the configuration. + All directory entries consist of + a group of attributes. Each of these + attribute sets contains a unique identifier known as a + Distinguished Name (DN) + which is normally built + from several other attributes such as the common or + Relative Distinguished Name + (RDN). + Similar to how directories have absolute and relative paths, consider a DN as an absolute path and the RDN as the relative path. - As an example, an entry might look like the - following: + An example LDAP entry looks like the + following. This example searches for the entry for the specified user + account (uid), organizational unit + (ou), and organization + (o): - &prompt.user; ldapsearch -xb "uid=trhodes,ou=users,o=example.com" - - # extended LDIF + &prompt.user; ldapsearch -xb "uid=trhodes,ou=users,o=example.com" +# 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 +# numEntries: 1 - In this example, it is very obvious what the various - attributes are; however, the cn attribute - should be noticed. This is the RDN - 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. + This example entry shows the values for the + dn, mail, + cn, uid, and + telephoneNumber + attributes. The cn attribute + is the RDN. + + More information about LDAP and its + terminology can be found at http://www.openldap.org/doc/admin24/intro.html. @@ -2223,72 +2229,63 @@ result: 0 Success LDAP Server - To configure &os; to act as an LDAP - server, the OpenLDAP port needs installed. This may be - accomplished using the pkg_add command - or by installing the - net/openldap24-server - 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. - - 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: + &os; does not provide a built-in LDAP + server. Begin the configuration by installing the + net/openldap24-server 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 . + + Next, create the directories to hold the + data and to store the + certificates: - &prompt.root; mkdir /var/db/openldap-data - - &prompt.root; mkdir /usr/local/etc/openldap/private + &prompt.root; mkdir /var/db/openldap-data +&prompt.root; mkdir /usr/local/etc/openldap/private Copy over the database configuration file: &prompt.root; cp /usr/local/etc/openldap/DB_CONFIG.example /var/db/openldap-data/DB_CONFIG - The next phase is to configure the SSL - certificates. While creating certificates is discussed in - the OpenSSL 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. - - The following commands must be executed in the - /usr/local/etc/openldap/private - directory. This is important as the file permissions will + The next phase is to configure the certificate authority. + The following commands must be executed from + /usr/local/etc/openldap/private. + 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. + these files. To create the certificate authority, + start with this command and follow the prompts: - &prompt.root; openssl req -days 365 -nodes -new -x509 -keyout ca.key -out ../ca.crt + &prompt.root; openssl req -days 365 -nodes -new -x509 -keyout ca.key -out ../ca.crt - The entries for these may be completely generic + The entries for the prompts may be generic except for the - Common Name 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 - CA for certificate authority. + Common Name. This entry must be + different than the system hostname. + If this will be a self signed certificate, + prefix the hostname with + CA for certificate authority. The next task is to create a certificate signing request - and a private key. To do this, issue the following - commands: + and a private key. Input this command and follow the + prompts: - &prompt.root; openssl req -days 365 -nodes -new -keyout server.key -out server.csr + &prompt.root; openssl req -days 365 -nodes -new -keyout server.key -out server.csr During the certificate generation process, be sure to - correctly set the common name attribute. After this has - been completed, the key will need signed: + correctly set the Common Name attribute. Once + complete, sign the key: - &prompt.root; openssl x509 -req -days 365 -in server.csr -out ../server.crt -CA ../ca.crt -CAkey ca.key -CAcreateserial + &prompt.root; openssl x509 -req -days 365 -in server.csr -out ../server.crt -CA ../ca.crt -CAkey ca.key -CAcreateserial The final part of the certificate generation process is to generate and sign the client certificates: - &prompt.root; openssl req -days 365 -nodes -new -keyout client.key -out client.csr + &prompt.root; openssl req -days 365 -nodes -new -keyout client.key -out client.csr &prompt.root; openssl x509 -req -days 3650 -in client.csr -out ../client.crt -CA ../ca.crt -CAkey ca.key