From owner-svn-doc-head@freebsd.org Thu Dec 20 21:54:06 2018 Return-Path: Delivered-To: svn-doc-head@mailman.ysv.freebsd.org Received: from mx1.freebsd.org (mx1.freebsd.org [IPv6:2610:1c1:1:606c::19:1]) by mailman.ysv.freebsd.org (Postfix) with ESMTP id 3E9DA1355577; Thu, 20 Dec 2018 21:54:06 +0000 (UTC) (envelope-from bcr@FreeBSD.org) Received: from mxrelay.nyi.freebsd.org (mxrelay.nyi.freebsd.org [IPv6:2610:1c1:1:606c::19:3]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits) server-signature RSA-PSS (4096 bits) client-signature RSA-PSS (4096 bits) client-digest SHA256) (Client CN "mxrelay.nyi.freebsd.org", Issuer "Let's Encrypt Authority X3" (verified OK)) by mx1.freebsd.org (Postfix) with ESMTPS id E58AF6FA71; Thu, 20 Dec 2018 21:54:05 +0000 (UTC) (envelope-from bcr@FreeBSD.org) Received: from repo.freebsd.org (repo.freebsd.org [IPv6:2610:1c1:1:6068::e6a:0]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (Client did not present a certificate) by mxrelay.nyi.freebsd.org (Postfix) with ESMTPS id D91DD3EDC; Thu, 20 Dec 2018 21:54:05 +0000 (UTC) (envelope-from bcr@FreeBSD.org) Received: from repo.freebsd.org ([127.0.1.37]) by repo.freebsd.org (8.15.2/8.15.2) with ESMTP id wBKLs5x2089724; Thu, 20 Dec 2018 21:54:05 GMT (envelope-from bcr@FreeBSD.org) Received: (from bcr@localhost) by repo.freebsd.org (8.15.2/8.15.2/Submit) id wBKLs59E089723; Thu, 20 Dec 2018 21:54:05 GMT (envelope-from bcr@FreeBSD.org) Message-Id: <201812202154.wBKLs59E089723@repo.freebsd.org> X-Authentication-Warning: repo.freebsd.org: bcr set sender to bcr@FreeBSD.org using -f From: Benedict Reuschling Date: Thu, 20 Dec 2018 21:54:05 +0000 (UTC) To: doc-committers@freebsd.org, svn-doc-all@freebsd.org, svn-doc-head@freebsd.org Subject: svn commit: r52704 - head/en_US.ISO8859-1/books/handbook/network-servers X-SVN-Group: doc-head X-SVN-Commit-Author: bcr X-SVN-Commit-Paths: head/en_US.ISO8859-1/books/handbook/network-servers X-SVN-Commit-Revision: 52704 X-SVN-Commit-Repository: doc MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit X-Rspamd-Queue-Id: E58AF6FA71 X-Spamd-Bar: -- Authentication-Results: mx1.freebsd.org X-Spamd-Result: default: False [-2.96 / 15.00]; local_wl_from(0.00)[FreeBSD.org]; NEURAL_HAM_MEDIUM(-1.00)[-0.999,0]; NEURAL_HAM_LONG(-1.00)[-0.999,0]; NEURAL_HAM_SHORT(-0.96)[-0.963,0]; ASN(0.00)[asn:11403, ipnet:2610:1c1:1::/48, country:US] X-BeenThere: svn-doc-head@freebsd.org X-Mailman-Version: 2.1.29 Precedence: list List-Id: SVN commit messages for the doc tree for head List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Thu, 20 Dec 2018 21:54:06 -0000 Author: bcr Date: Thu Dec 20 21:54:05 2018 New Revision: 52704 URL: https://svnweb.freebsd.org/changeset/doc/52704 Log: Rewrite the LDAP server section of the handbook. The Lightweight Directory Access Protocol (LDAP) section of the handbook contains several errors (typos, wrong steps) and was in need of updates to reflect current versions of the software. Rocky Hotas provided a patch for review that fixes many of those bugs and extends the instructions in the first part. The second part received a complete rewrite, providing working example configuration files and steps to get the server running. I made only a few cleanups and corrections to the patch to fit our documentation guidelines. Most of the work was done by the submitter, big thanks for his work and patience! PR: 219142 Submitted by: rockyhotas@post.com Reviewed by: remko, wollman, wblock, myself, others Approved by: bcr Differential Revision: https://reviews.freebsd.org/D10600 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 Thu Dec 20 16:21:52 2018 (r52703) +++ head/en_US.ISO8859-1/books/handbook/network-servers/chapter.xml Thu Dec 20 21:54:05 2018 (r52704) @@ -1000,7 +1000,7 @@ Exports list on foobar: The &man.autofs.5; map format is the same as in other operating systems. Information about this format from other - sources can be useful, like the Mac OS X document. @@ -2248,9 +2248,18 @@ TWO (,hotel,test-domain) Tom Rhodes - Written by + Originally contributed by + + + + Rocky + Hotas + + Updates by + + LDAP @@ -2340,32 +2349,35 @@ result: 0 Success LDAP Server &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 - . + server. Begin the configuration by installing net/openldap-server package or + port: - Next, create the directories to hold the data and to store - the certificates: + &prompt.root; pkg install openldap-server - &prompt.root; mkdir /var/db/openldap-data -&prompt.root; mkdir /usr/local/etc/openldap/private + There is a large set of default options enabled in the + + package. Review them by running + pkg info openldap-server. If they are not + sufficient (for example if SQL support is needed), please + consider recompiling the port using the appropriate framework. - Copy over the database configuration file: + The installation creates the directory + /var/db/openldap-data to hold the data. + The directory to store the certificates must be + created: - &prompt.root; cp /usr/local/etc/openldap/DB_CONFIG.example /var/db/openldap-data/DB_CONFIG + &prompt.root; mkdir /usr/local/etc/openldap/private - The next phase is to configure the certificate authority. + 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. To create the - certificate authority, start with this command and follow the + users should not have access to these files. More detailed + information about certificates and their parameters can be + found in . 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 @@ -2375,7 +2387,7 @@ result: 0 Success 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. + with CA for Certificate Authority. The next task is to create a certificate signing request and a private key. Input this command and follow the @@ -2385,7 +2397,9 @@ result: 0 Success During the certificate generation process, be sure to correctly set the Common Name attribute. - Once complete, sign the key: + The Certificate Signing Request must be signed with the + Certificate Authority in order to be used as a valid + certificate: &prompt.root; openssl x509 -req -days 365 -in server.csr -out ../server.crt -CA ../ca.crt -CAkey ca.key -CAcreateserial @@ -2398,172 +2412,351 @@ result: 0 Success Remember to use the same Common Name attribute when prompted. When finished, ensure that a total of eight (8) new files have been generated through the - proceeding commands. If so, the next step is to edit - /usr/local/etc/openldap/slapd.conf and - add the following options: + proceeding commands. - TLSCipherSuite HIGH:MEDIUM:+SSLv3 -TLSCertificateFile /usr/local/etc/openldap/server.crt -TLSCertificateKeyFile /usr/local/etc/openldap/private/server.key -TLSCACertificateFile /usr/local/etc/openldap/ca.crt + The daemon running the OpenLDAP server is + slapd. Its configuration is performed + through slapd.ldif: the old + slapd.conf has been deprecated by + OpenLDAP. - Then, edit - /usr/local/etc/openldap/ldap.conf and add - the following lines: + Configuration + examples for slapd.ldif are + available and can also be found in + /usr/local/etc/openldap/slapd.ldif.sample. + Options are documented in slapd-config(5). Each section + of slapd.ldif, like all the other LDAP + attribute sets, is uniquely identified through a DN. Be sure + that no blank lines are left between the + dn: statement and the desired end of the + section. In the following example, TLS will be used to + implement a secure channel. The first section represents the + global configuration: - TLS_CACERT /usr/local/etc/openldap/ca.crt -TLS_CIPHER_SUITE HIGH:MEDIUM:+SSLv3 + # +# See slapd-config(5) for details on configuration options. +# This file should NOT be world readable. +# +dn: cn=config +objectClass: olcGlobal +cn: config +# +# +# Define global ACLs to disable default read access. +# +olcArgsFile: /var/run/openldap/slapd.args +olcPidFile: /var/run/openldap/slapd.pid +olcTLSCertificateFile: /usr/local/etc/openldap/server.crt +olcTLSCertificateKeyFile: /usr/local/etc/openldap/private/server.key +olcTLSCACertificateFile: /usr/local/etc/openldap/ca.crt +#olcTLSCipherSuite: HIGH +olcTLSProtocolMin: 3.1 +olcTLSVerifyClient: never - While editing this file, uncomment the following entries - and set them to the desired values: , - , and - . Set the to - contain and - . Then, add two entries pointing to - the certificate authority. When finished, the entries should - look similar to the following: + The Certificate Authority, server certificate and server + private key files must be specified here. It is recommended + to let the clients choose the security cipher and omit option + olcTLSCipherSuite (incompatible with TLS + clients other than openssl). Option + olcTLSProtocolMin lets the server require a + minimum security level: it is recommended. While + verification is mandatory for the server, it is not for the + client: olcTLSVerifyClient: never. - BASE dc=example,dc=com -URI ldap:// ldaps:// + The second section is about the backend modules and can be + configured as follows: -SIZELIMIT 12 -TIMELIMIT 15 + # +# Load dynamic backend modules: +# +dn: cn=module,cn=config +objectClass: olcModuleList +cn: module +olcModulepath: /usr/local/libexec/openldap +olcModuleload: back_mdb.la +#olcModuleload: back_bdb.la +#olcModuleload: back_hdb.la +#olcModuleload: back_ldap.la +#olcModuleload: back_passwd.la +#olcModuleload: back_shell.la -TLS_CACERT /usr/local/etc/openldap/ca.crt -TLS_CIPHER_SUITE HIGH:MEDIUM:+SSLv3 + The third section is devoted to load the needed + ldif schemas to be used by the databases: + they are essential. - The default password for the server should then be - changed: + dn: cn=schema,cn=config +objectClass: olcSchemaConfig +cn: schema - &prompt.root; slappasswd -h "{SHA}" >> /usr/local/etc/openldap/slapd.conf +include: file:///usr/local/etc/openldap/schema/core.ldif +include: file:///usr/local/etc/openldap/schema/cosine.ldif +include: file:///usr/local/etc/openldap/schema/inetorgperson.ldif +include: file:///usr/local/etc/openldap/schema/nis.ldif - This command will prompt for the password and, if the - process does not fail, a password hash will be added to the - end of slapd.conf. Several hashing - formats are supported. Refer to the manual page for - slappasswd for more information. + Next, the frontend configuration section: - Next, edit - /usr/local/etc/openldap/slapd.conf and - add the following lines: + # Frontend settings +# +dn: olcDatabase={-1}frontend,cn=config +objectClass: olcDatabaseConfig +objectClass: olcFrontendConfig +olcDatabase: {-1}frontend +olcAccess: to * by * read +# +# Sample global access control policy: +# Root DSE: allow anyone to read it +# Subschema (sub)entry DSE: allow anyone to read it +# Other DSEs: +# Allow self write access +# Allow authenticated users read access +# Allow anonymous users to authenticate +# +#olcAccess: to dn.base="" by * read +#olcAccess: to dn.base="cn=Subschema" by * read +#olcAccess: to * +# by self write +# by users read +# by anonymous auth +# +# if no access controls are present, the default policy +# allows anyone and everyone to read anything but restricts +# updates to rootdn. (e.g., "access to * by * read") +# +# rootdn can always read and write EVERYTHING! +# +olcPasswordHash: {SSHA} +# {SSHA} is already the default for olcPasswordHash - password-hash {sha} -allow bind_v2 + Another section is devoted to the configuration + backend, the only way to later access the + OpenLDAP server configuration is as a global + super-user. - The in this file must be updated - to match the used in - /usr/local/etc/openldap/ldap.conf and - should also be set. A recommended - value for is something like - . Before saving this file, place - the in front of the password output - from slappasswd and delete the old - . The end result should - look similar to this: + dn: olcDatabase={0}config,cn=config +objectClass: olcDatabaseConfig +olcDatabase: {0}config +olcAccess: to * by * none +olcRootPW: {SSHA}iae+lrQZILpiUdf16Z9KmDmSwT77Dj4U - TLSCipherSuite HIGH:MEDIUM:+SSLv3 -TLSCertificateFile /usr/local/etc/openldap/server.crt -TLSCertificateKeyFile /usr/local/etc/openldap/private/server.key -TLSCACertificateFile /usr/local/etc/openldap/ca.crt -rootpw {SHA}W6ph5Mm5Pz8GgiULbPgzG37mj9g= + The default administrator username is + cn=config. Type + slappasswd in a shell, choose a password + and use its hash in olcRootPW. If this + option is not specified now, before + slapd.ldif is imported, no one will be + later able to modify the + global configuration section. - Finally, enable the OpenLDAP - service in /etc/rc.conf and set the - URI: + The last section is about the database backend: - slapd_enable="YES" -slapd_flags="-4 -h ldaps:///" + ####################################################################### +# LMDB database definitions +####################################################################### +# +dn: olcDatabase=mdb,cn=config +objectClass: olcDatabaseConfig +objectClass: olcMdbConfig +olcDatabase: mdb +olcDbMaxSize: 1073741824 +olcSuffix: dc=domain,dc=example +olcRootDN: cn=mdbadmin,dc=domain,dc=example +# Cleartext passwords, especially for the rootdn, should +# be avoided. See slappasswd(8) and slapd-config(5) for details. +# Use of strong authentication encouraged. +olcRootPW: {SSHA}X2wHvIWDk6G76CQyCMS1vDCvtICWgn0+ +# The database directory MUST exist prior to running slapd AND +# should only be accessible by the slapd and slap tools. +# Mode 700 recommended. +olcDbDirectory: /var/db/openldap-data +# Indices to maintain +olcDbIndex: objectClass eq - At this point the server can be started and tested: + This database hosts the actual + contents of the LDAP + directory. Types other than mdb are + available. Its super-user, not to be confused with the global + one, is configured here: a (possibly custom) username in + olcRootDN and the password hash in + olcRootPW; slappasswd + can be used as before. - &prompt.root; service slapd start + This repository + contains four examples of slapd.ldif. To + convert an existing slapd.conf into + slapd.ldif, refer to this + page (please note that this may introduce some + unuseful options). - If everything is configured correctly, a search of the - directory should show a successful connection with a single - response as in this example: + When the configuration is completed, + slapd.ldif must be placed in an empty + directory. It is recommended to create it as: - &prompt.root; ldapsearch -Z + &prompt.root; mkdir /usr/local/etc/openldap/slapd.d/ + + Import the configuration database: + + &prompt.root; /usr/local/sbin/slapadd -n0 -F /usr/local/etc/openldap/slapd.d/ -l /usr/local/etc/openldap/slapd.ldif + + Start the slapd daemon: + + &prompt.root; /usr/local/libexec/slapd -F /usr/local/etc/openldap/slapd.d/ + + Option -d can be used for debugging, + as specified in slapd(8). To verify that the server is + running and working: + + &prompt.root; ldapsearch -x -b '' -s base '(objectclass=*)' namingContexts # extended LDIF # # LDAPv3 -# base <dc=example,dc=com> (default) with scope subtree +# base <> with scope baseObject # filter: (objectclass=*) -# requesting: ALL +# requesting: namingContexts # +# +dn: +namingContexts: dc=domain,dc=example + # search result -search: 3 -result: 32 No such object +search: 2 +result: 0 Success -# numResponses: 1 +# numResponses: 2 +# numEntries: 1 - - If the command fails and the configuration looks - correct, stop the slapd service and - restart it with debugging options: + The server must still be trusted. If that has never been + done before, follow these instructions. Install the OpenSSL + package or port: - &prompt.root; service slapd stop -&prompt.root; /usr/local/libexec/slapd -d -1 - + &prompt.root; pkg install openssl - Once the service is responding, the directory can be - populated using ldapadd. In this example, - a file containing this list of users is first created. Each - user should use the following format: + From the directory where ca.crt is + stored (in this example, + /usr/local/etc/openldap), run: - dn: dc=example,dc=com -objectclass: dcObject -objectclass: organization -o: Example -dc: Example + &prompt.root; c_rehash . -dn: cn=Manager,dc=example,dc=com -objectclass: organizationalRole -cn: Manager + Both the CA and the server certificate are now correctly + recognized in their respective roles. To verify this, run + this command from the server.crt + directory: - 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: + &prompt.root; openssl verify -verbose -CApath . server.crt - &prompt.root; ldapadd -Z -D "cn=Manager,dc=example,dc=com" -W -f import.ldif -Enter LDAP Password: -adding new entry "dc=example,dc=com" + If slapd was running, restart it. As + stated in /usr/local/etc/rc.d/slapd, to + properly run slapd at boot the + following lines must be added to + /etc/rc.conf: -adding new entry "cn=Manager,dc=example,dc=com" + lapd_enable="YES" +slapd_flags='-h "ldapi://%2fvar%2frun%2fopenldap%2fldapi/ +ldap://0.0.0.0/"' +slapd_sockets="/var/run/openldap/ldapi" +slapd_cn_config="YES" - Verify the data was added by issuing a search on the - server using ldapsearch: + slapd does not provide debugging at + boot. Check /var/log/debug.log, + dmesg -a and + /var/log/messages for this + purpose. - &prompt.user; ldapsearch -Z -# extended LDIF -# -# LDAPv3 -# base <dc=example,dc=com> (default) with scope subtree -# filter: (objectclass=*) -# requesting: ALL -# + The following example adds the group + team and the user john + to the domain.example + LDAP database, which is still empty. + First, create the file + domain.ldif: -# example.com -dn: dc=example,dc=com + &prompt.root; cat domain.ldif +dn: dc=domain,dc=example objectClass: dcObject objectClass: organization -o: Example -dc: Example +o: domain.example +dc: domain -# Manager, example.com -dn: cn=Manager,dc=example,dc=com -objectClass: organizationalRole -cn: Manager +dn: ou=groups,dc=domain,dc=example +objectClass: top +objectClass: organizationalunit +ou: groups -# search result -search: 3 -result: 0 Success +dn: ou=users,dc=domain,dc=example +objectClass: top +objectClass: organizationalunit +ou: users -# numResponses: 3 -# numEntries: 2 +dn: cn=team,ou=groups,dc=domain,dc=example +objectClass: top +objectClass: posixGroup +cn: team +gidNumber: 10001 - At this point, the server should be configured and - functioning properly. +dn: uid=john,ou=users,dc=domain,dc=example +objectClass: top +objectClass: account +objectClass: posixAccount +objectClass: shadowAccount +cn: John McUser +uid: john +uidNumber: 10001 +gidNumber: 10001 +homeDirectory: /home/john/ +loginShell: /usr/bin/bash +userPassword: secret + + See the OpenLDAP documentation for more details. Use + slappasswd to replace the plain text + password secret with a hash in + userPassword. The path specified as + loginShell must exist in all the systems + where john is allowed to login. Finally, + use the mdb administrator to modify the + database: + + &prompt.root; ldapadd -W -D "cn=mdbadmin,dc=domain,dc=example" -f domain.ldif + + Modifications to the global + configuration section can only be performed by + the global super-user. For example, assume that the option + olcTLSCipherSuite: HIGH:MEDIUM:SSLv3 was + initially specified and must now be deleted. First, create a + file that contains the following: + + &prompt.root; cat global_mod +dn: cn=config +changetype: modify +delete: olcTLSCipherSuite + + Then, apply the modifications: + + &prompt.root; ldapmodify -f global_mod -x -D "cn=config" -W + + When asked, provide the password chosen in the + configuration backend section. The + username is not required: here, cn=config + represents the DN of the database section to be modified. + Alternatively, use ldapmodify to delete a + single line of the database, ldapdelete to + delete a whole entry. + + If something goes wrong, or if the global super-user + cannot access the configuration backend, it is possible to + delete and re-write the whole configuration: + + &prompt.root; rm -rf /usr/local/etc/openldap/slapd.d/ + + slapd.ldif can then be edited and + imported again. Please, follow this procedure only when no + other solution is available. + + This is the configuration of the server only. The same + machine can also host an LDAP client, with its own separate + configuration. @@ -2810,7 +3003,7 @@ host fantasia { The default lease expiry time in seconds. A client - can be configured to override this value. + can be configured to override this value. @@ -4088,7 +4281,7 @@ Starting smbd. /etc/ntp.conf: - Sample <filename>/etc/ntp.conf</filename> + Sample <filename>/etc/ntp.conf</filename> server ntplocal.example.com prefer server timeserver.example.org @@ -4177,7 +4370,7 @@ driftfile /var/db/ntp.drift directives in /etc/ppp/ppp.conf. For example: - set filter dial 0 deny udp src eq 123 + set filter dial 0 deny udp src eq 123 # Prevent NTP traffic from initiating dial out set filter dial 1 permit 0 0 set filter alive 0 deny udp src eq 123