Index: head/en_US.ISO8859-1/books/handbook/network-servers/chapter.xml =================================================================== --- head/en_US.ISO8859-1/books/handbook/network-servers/chapter.xml +++ head/en_US.ISO8859-1/books/handbook/network-servers/chapter.xml @@ -1000,7 +1000,7 @@ 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 @@ Tom Rhodes - Written by + Originally contributed by + + + + Rocky + Hotas + + Updates by + + LDAP @@ -2340,32 +2349,35 @@ 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 @@ 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 @@ 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 @@ 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 @@ 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 @@ /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 @@ 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