diff --git a/docs/rolereference.rst b/docs/rolereference.rst index e25f8c2a4c9e4895686d2be9cd40af6be13b0892..3f4ab8d18680e8544582d71c50a53570cddecf08 100644 --- a/docs/rolereference.rst +++ b/docs/rolereference.rst @@ -285,7 +285,7 @@ LDAP Client The ``ldap_client`` role can be used for setting-up an OpenLDAP client on destination machine. -The role implements the followings: +The role implements the following: * Installs OpenLDAP client tools. * Sets-up global configuration file for OpenLDAP clients at /etc/ldap/ldap.conf. @@ -334,3 +334,141 @@ Here is an example configuration for setting some common LDAP client options: - comment: Disable CRL checks for server certificate option: TLS_CRLCHECK value: none + + +LDAP Server +----------- + +The ``ldap_server`` role can be used for setting-up an OpenLDAP server on +destination machine. + +The role implements the following: + +* Installs OpenLDAP server (package ``slapd``). +* Configures OpenLDAP server (base DN - domain, organisation, TLS, SSF, log levels). +* Sets-up separate log file for OpenLDAP server at ``/var/log/slapd.log`` (with + log rotation included). +* Configures permissions. +* Creates LDAP entries. + + +Parameters +~~~~~~~~~~ + +**ldap_server_config** (list, mandatory) + A dictionary of configuration options for OpenLDAP server. The following + configuration options are available: + + **domain** (string, mandatory) + Domain that should be used for constructing the base DN of default user LDAP + database. This should be a sub-domain dedicated to organisation. The base DN + will be constructed by putting all elements of the sub-domain as ``dc`` + entries (as per standard Debian convention). I.e. ``example.com`` would get + transformed into ``dc=example,dc=com``. + + **organization** (string, mandatory) + Organization that should be specified in the base DN entry. + + **log_level** (string, mandatory) + Log level to use for the server. This should be compatible with OpenLDAP + configuration option ``olcLogLevel``. See `OpenLDAP Administrator's Guide + ` for value + description and syntax. + + **tls_certificate** (string, mandatory) + Path to *X.509* certificate (on server itself) that should be used as server + certificate for TLS connections. The certificate file should be provided in + ``PEM`` format. If file does not exist, no TLS will be set-up. + + **tls_key** (string, mandatory) + Path to private key (on server itself) that should be used as server's + private key for TLS connections. The private key should correspond to + certificate listed in option ``tls_certificate``. The key file should be + provided in ``PEM`` format. If file does not exist, no TLS will be set-up. + + **ssf** (number, mandatory) + Minimum *Security Strength Factor* to require from all incoming + connections. This applies for both remote and local connections. + +**ldap_permissions** (list, mandatory) + List of LDAP access controls to apply to directories served by the LDAP + server. Each item is a dictionary with the following options describing the + permissions: + + **filter** (string, mandatory) + An LDAP filter that should be applied on base DN ``cn=config`` using + sub-tree scope to locate the LDAP database for which the access control + rules will be applied. For default user database this could be something in + the lines of ``(olcSuffix=dc=example,dc=com)``. + + **rules** (list, mandatory) + A list of access control rules that should be applied for the selected + database. The access control rules listed will *replace* all existing + rules, and will be added in the same order they are listed in. Each item is + a string that constitutes a single access control rule. The format should be + the same as described in `OpenLDAP Administrator's Guide + `. + +**ldap_entries** (list, mandatory) + List of entries that should be kept in the LDAP directory. Each item is a + dictionary describing a single LDAP entry, with all of its attributes + listed. The keys in this dictionary should be the attribute names. The values + should be either strings, for setting a single attribute value, or a list of + strings if it is necessary to set multiple values for the same attribute. + + +Examples +~~~~~~~~ + +Here is an example configuration for setting-up LDAP server: + +.. code-block:: yaml + + --- + + ldap_server_config: + domain: "example.com" + organization: "Example Corporation" + log_level: 256 + tls_certificate: /etc/ssl/certs/ldap.example.com.pem + tls_key: /etc/ssl/private/ldap.example.com.pem + ssf: 128 + + ldap_permissions: + - filter: '(olcSuffix=dc=example,dc=com)' + rules: + - > + to * + by dn.exact=gidNumber=0+uidNumber=0,cn=peercred,cn=external,cn=auth manage + by * break + - > + to attrs=userPassword,shadowLastChange + by self write + by anonymous auth + by dn="cn=admin,dc=example,dc=com" write + by * none + - > + to dn.base="" + by * read + - > + to * + by self write + by dn="cn=admin,dc=example,dc=com" write + by users read + by * none + + ldap_entries: + - dn: ou=people,dc=example,dc=com + objectClass: organizationalUnit + ou: people + - dn: ou=groups,dc=example,dc=com + objectClass: organizationalUnit + ou: groups + - dn: uid=john,dc=example,dc=com + objectClass: + - inetOrgPerson + - simpleSecurityObject + userPassword: somepassword + uid: john + cn: John Doe + sn: Doe