Index: chapter.xml
===================================================================
--- chapter.xml
+++ chapter.xml
@@ -2245,10 +2245,20 @@
+ Rocky
+ Hotas
+
+ Draft by
+
+
+
+
+
+ TomRhodes
- Written by
+ Originally contributed by
@@ -2340,31 +2350,36 @@
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
- .
-
- 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
+ server. Begin the configuration by installing net/openldap-server package or
+ port:
+
+ &prompt.root; pkg install openldap-server
+
+ There is a large set of default options enabled in
+ the
+ package. To review them:
+ 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.
+
+ The installation creates the directory
+ /var/db/openldap-data to hold the data.
+ The directory to store the certificates must be
+ created:
- Copy over the database configuration file:
-
- &prompt.root; cp /usr/local/etc/openldap/DB_CONFIG.example /var/db/openldap-data/DB_CONFIG
+ &prompt.root; mkdir /usr/local/etc/openldap/privateThe 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
+ 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:
@@ -2385,7 +2400,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 +2415,420 @@
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:
-
- 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
-
- Then, edit
- /usr/local/etc/openldap/ldap.conf and add
- the following lines:
-
- TLS_CACERT /usr/local/etc/openldap/ca.crt
-TLS_CIPHER_SUITE HIGH:MEDIUM:+SSLv3
-
- 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:
-
- BASE dc=example,dc=com
-URI ldap:// ldaps://
-
-SIZELIMIT 12
-TIMELIMIT 15
-
-TLS_CACERT /usr/local/etc/openldap/ca.crt
-TLS_CIPHER_SUITE HIGH:MEDIUM:+SSLv3
-
- The default password for the server should then be
- changed:
-
- &prompt.root; slappasswd -h "{SHA}" >> /usr/local/etc/openldap/slapd.conf
-
- 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, edit
- /usr/local/etc/openldap/slapd.conf and
- add the following lines:
-
- password-hash {sha}
-allow bind_v2
-
- 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:
-
- 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=
-
- Finally, enable the OpenLDAP
- service in /etc/rc.conf and set the
- URI:
-
- slapd_enable="YES"
-slapd_flags="-4 -h ldaps:///"
-
- At this point the server can be started and tested:
-
- &prompt.root; service slapd start
-
- If everything is configured correctly, a search of the
- directory should show a successful connection with a single
- response as in this example:
+ proceeding commands.
- &prompt.root; ldapsearch -Z
-# extended LDIF
+ The daemon running the OpenLDAP server is
+ slapd. Its configuration can be
+ performed through a slapd.conf
+ configuration file, or through a database file
+ slapd.ldif.
+ The former way is deprecated by OpenLDAP:
+
+
+ The use of slapd.ldif is
+ strongly recommended.
+
+
+ Configuration examples for
+ slapd.ldif can be found
+ here and in
+ /usr/local/etc/openldap/slapd.ldif.sample.
+ Each part of this file is uniquely identified through a
+ dn: (Distinguished Name), beginning with the
+ global configuration entry. Be sure that
+ no blank lines are between the dn: statement
+ and the desired end of the section. Options are documented in
+
+ slapd-config(5). In the following example, TLS will
+ be used to implement a secure channel.
+
+ #
+# See slapd-config(5) for details on configuration options.
+# This file should NOT be world readable.
#
-# LDAPv3
-# base <dc=example,dc=com> (default) with scope subtree
-# filter: (objectclass=*)
-# requesting: ALL
+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
+
+ 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.
-# search result
-search: 3
-result: 32 No such object
-
-# numResponses: 1
+ The second part is about the backend modules and can be
+ configured as follows:
-
- If the command fails and the configuration looks
- correct, stop the slapd service and
- restart it with debugging options:
-
- &prompt.root; service slapd stop
-&prompt.root; /usr/local/libexec/slapd -d -1
-
+ #
+# 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
+
+ The third part is devoted to load the needed
+ ldif schemas to be used by the databases: they
+ are essential.
+
+ dn: cn=schema,cn=config
+objectClass: olcSchemaConfig
+cn: schema
+
+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
- 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:
-
- dn: dc=example,dc=com
-objectclass: dcObject
-objectclass: organization
-o: Example
-dc: Example
-
-dn: cn=Manager,dc=example,dc=com
-objectclass: organizationalRole
-cn: Manager
-
- 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; ldapadd -Z -D "cn=Manager,dc=example,dc=com" -W -f import.ldif
-Enter LDAP Password:
-adding new entry "dc=example,dc=com"
+ Then, the frontend configuration follows:
-adding new entry "cn=Manager,dc=example,dc=com"
+ # 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
- Verify the data was added by issuing a search on the
- server using ldapsearch:
+ The following section describes the configuration
+ backend: this will be the only way to
+ access the global configuration for the system
+ administrator, once this procedure is completed. Thus, it
+ is extremely important that all the
+ needed options are specified here. In particular, a root
+ password must be chosen: together with the default
+ administrator username cn=config, it will
+ let the server administrator to later edit the configuration
+ as the super-user. Note that, without the specification of
+ a olcRootPW here, after this file is
+ imported as a configuration file for
+ slapd, no one will be able to modify this
+ global configuration. This is highly undesirable.
+ If anyway something is wrong with the actual configuration,
+ later will be shown a way to delete (and hopefully replace)
+ it.
+ A password can be generated using
+ slappasswd in a shell and its entire output must
+ be used as a value for olcRootPW.
+
+ dn: olcDatabase={0}config,cn=config
+objectClass: olcDatabaseConfig
+olcDatabase: {0}config
+olcAccess: to * by * none
+olcRootPW: {SSHA}iae+lrQZILpiUdf16Z9KmDmSwT77Dj4U
+
+ The last section showed here is about the database
+ backend, used for the actual contents
+ of the LDAP directory. This database can
+ be used to add new groups and users as regards the domain
+ domain.example. Here, the database type
+ mdb is used and another super-user is
+ specified: it will be only able to modify this database and
+ not the previous sections of
+ slapd.ldif. Here, a username
+ olcRootDN can be specified, being related to the
+ domain. A password can be generated as before.
+
+ #######################################################################
+# 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
+
+ In
+ this repository, four examples of
+ slapd.ldif files are available (they are used
+ as a 4-way multi master LDAP server). At
+ the bottom of
+ this page, section 5.4, also a way to convert an
+ existing slapd.conf into a valid
+ slapd.ldif is presented. Please note
+ that this may introduce some unuseful options.
+
+ Once the slapd.ldif configuration
+ is completed, this file must be imported in an empty
+ directory. It is recommended to create it with the
+ following name and location:
+
+ &prompt.root; mkdir /usr/local/etc/openldap/slapd.d/
+
+ The commands suggested at points 9 and 10 in the
+ OpenLDAP Quick Start guide (which can anyway be
+ considered as a reference for all the other operations) are
+ currently wrong: instead, it is advisable to use
+
+ &prompt.root; /usr/local/sbin/slapadd -n0 -F /usr/local/etc/openldap/slapd.d/ -l /usr/local/etc/openldap/slapd.ldif
+
+ This will import the configuration database. To 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.user; ldapsearch -Z
+ &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
#
-# example.com
-dn: dc=example,dc=com
-objectClass: dcObject
-objectClass: organization
-o: Example
-dc: Example
-
-# Manager, example.com
-dn: cn=Manager,dc=example,dc=com
-objectClass: organizationalRole
-cn: Manager
+#
+dn:
+namingContexts: dc=domain,dc=example
# search result
-search: 3
+search: 2
result: 0 Success
-# numResponses: 3
-# numEntries: 2
+# numResponses: 2
+# numEntries: 1
+
+ The server will not still be recognized by any client as
+ trusted, anyway.
+ The certificates were created in non-standard directories
+ from the point of view of openssl. In
+ order for openssl to work, the
+ directories where the certificates are stored must contain
+ symbolic links (whose names are composed by a hash) to the
+ certificates. Even if some openssl
+ commands are already available in a FreeBSD base system, it
+ is necessary now to explicitly install the package:
+
+ &prompt.root; pkg install openssl
+
+ This will provide the c_rehash(1)
+ tool. Now run
+
+ &prompt.root; c_rehash .
+
+ from the directory where the CA is stored (in this
+ example, /usr/local/etc/openldap,
+ which contains the file ca.crt). This
+ utility must create a symlink for each
+ .pem, .crt,
+ .crl or .cer file
+ in the directory. Only this way
+ server.crt can be recognized as a valid, trusted
+ and acceptable certificate. After having verified that
+ symlinks have been created, in order to verify if the server
+ certificate is trusted (and this is the operation each
+ LDAP client does before accessing the
+ server), run (from the server.crt
+ directory):
+
+ &prompt.root; openssl verify -verbose -CApath . server.crt
+
+ If slapd was running, it must now
+ be restarted before using the server.
+ Please, carefully read the comments included in
+ /usr/local/etc/rc.d/slapd, to make a
+ correct configuration to run slapd at
+ boot.
+ An additional option is needed if the
+ cn=config style (that is: the file
+ slapd.ldif) is used for configuration.
+ You could put in /etc/rc.conf the
+ following lines:
+
+ 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"
+
+ slapd does not provide debugging at
+ boot, but dmesg -a,
+ /var/log/messages and (in particular)
+ /var/log/debug.log can be checked.
+
+ The LDAP users database is still
+ empty. An example, which adds a group called
+ team and a user called
+ john to the
+ domain.example
+ database is here provided. Create a file
+ domain.ldif with the following contents:
+
+ &prompt.root; cat domain.ldif
+dn: dc=domain,dc=example
+objectClass: dcObject
+objectClass: organization
+o: domain.example
+dc: domain
+
+dn: ou=groups,dc=domain,dc=example
+objectClass: top
+objectClass: organizationalunit
+ou: groups
+
+dn: ou=users,dc=domain,dc=example
+objectClass: top
+objectClass: organizationalunit
+ou: users
+
+dn: cn=team,ou=groups,dc=domain,dc=example
+objectClass: top
+objectClass: posixGroup
+cn: team
+gidNumber: 10001
+
+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
+
+ Instead of being secret, the password
+ in the last line of domain.ldif for
+ john can be generated with
+ slappasswd. Be careful about the
+ default shell path:
+ if it does not exist in the system where the user tries to log
+ in, an error can be generated and the user could not be able
+ to actually log in. A symlink can be created, or a different
+ shell can be used to avoid this. For the structure of the
+ ldif files and the LDAP
+ directory, see the OpenLDAP documentation. Such data can be
+ added to the database using the mdb
+ administrator:
+
+ &prompt.root; ldapadd -W -D "cn=mdbadmin,dc=domain,dc=example" -f domain.ldif
+
+ If instead a global option is to be modified, a
+ different user must be considered: as
+ anticipated, it is the global
+ super-user. Let us assume that the option
+ olcTLSCipherSuite: HIGH:MEDIUM:SSLv3 was
+ specified before and now it must be deleted. The
+ instructions for the modification can be stored in the file
+ global_mod.
+ It must not contain the previous value of the option to be
+ deleted in the last line: this means that
+ olcTLSCipherSuite: HIGH:MEDIUM:SSLv3 must
+ not be included as last line.
+
+ &prompt.root; cat global_mod
+dn: cn=config
+changetype: modify
+delete: olcTLSCipherSuite
+
+ The modifications can be applied with
+
+ &prompt.root; ldapmodify -f global_mod -x -D "cn=config" -W
+
+ cn=config is the
+ dn (Distinguished Name) of the entry
+ (section) of the database to be modified.
+ Use ldapmodify to delete a single line
+ of the database; ldapdelete is used to
+ delete an entire entry (section) instead.
+ Each database section has its own administrator and it must
+ be specified while applying a modification.
+ The global super-user, whose name is by default
+ cn=config, should have a password set by
+ olcRootPW in the
+ dn: olcDatabase={0}config,cn=config
+ section. It is the one who must used here. If something
+ goes wrong, or if this root administrator cannot access the
+ configuration backend, it is possible to completeley delete
+ the current configuration. It can be done by removing the
+ directory that was previously created:
+
+ &prompt.root; rm -rf /usr/local/etc/openldap/slapd.d/
+
+ slapd.ldif can then be edited and
+ imported again. Please note that this procedure
+ is not to be considered as ordinary, nor normal:
+ it will not have side effects, but it should be followed
+ only when no other solution is
+ suitable.
+
+ This is the configuration of the server only. The
+ client, which can be the server itself, and/or another
+ machine, relies upon other configuration files: a dedicated
+ guide must be followed for them.
- At this point, the server should be configured and
- functioning properly.