debops.ldap default variables

Sections

Role behaviour
APT packages
DNS and network configuration
LDAP directory structure
LDAP device object configuration
POSIX environment
Host-based access control
System-wide LDAP configuration
LDAP administrative access
LDAP tasks and operations
Configuration variables for other Ansible roles

Role behaviour 

ldap__enabled

Enable or disable support for system-wide LDAP configuration. By default LDAP configuration is disabled, but once enabled on a host, the role will keep it that way.

In a custom playbook that uses the debops.ldap role, you can set this variable to True to strictly enable LDAP support (for example during initial deployment), or to False, to omit making any changes on a host related to LDAP (for example if you want to interact only with the LDAP directory itself).

ldap__enabled: '{{ ansible_local.ldap.enabled
                   if (ansible_local | d() and ansible_local.ldap | d() and
                       (ansible_local.ldap.enabled | d()) | bool)
                   else False }}'

ldap__posix_enabled

Enable or disable support for LDAP-POSIX environment integration. If this variable is disabled, this will instruct other Ansible roles to not configure POSIX subsystems like PAM, sshd service, sudo and similar to use LDAP directory on a paritcular host. Only higher level applications will integrate with the directory.

ldap__posix_enabled: '{{ ansible_local.ldap.posix_enabled | d(ldap__enabled) }}'

ldap__configured

This variable is used to detect if the role already applied its default configuration on a host. If it did (or this variable is True) and the role is used as a dependency, the role will skip executing LDAP tasks defined by default and those defined in the Ansible inventory to avoid creating long lists of tasks. The state is tracked using a fact during runtime.

ldap__configured: '{{ ansible_local.ldap.configured
                      if (ansible_local | d() and ansible_local.ldap | d() and
                          ansible_local.ldap.configured is defined)
                      else False }}'

ldap__dependent_play

This variable checks if the role is used as a dependent role. If it is (or this variable is True), the role will skip most of its normal tasks and only run the LDAP tasks defined via the dependent variables.

ldap__dependent_play: '{{ True
                          if (ldap__configured | bool and
                              ldap__dependent_tasks | d())
                          else False }}'

APT packages 

ldap__base_packages

List of default APT packages to install for LDAP client support.

ldap__base_packages: [ 'libldap-common', 'ldap-utils', 'libsasl2-modules' ]

ldap__packages

List of additional APT packages to install with LDAP client support.

ldap__packages: []

DNS and network configuration 

ldap__domain

The DNS domain used to look for the LDAP servers and to create the LDAP Base Distinguished Name (BaseDN) variables.

ldap__domain: '{{ ansible_domain }}'

ldap__servers_srv_rr

List which contains the result of the DNS query for LDAP server SRV resource records in the host's domain.

ldap__servers_srv_rr: '{{ q("debops.debops.dig_srv", "_ldap._tcp." + ldap__domain,
                            "ldap." + ldap__domain, 389) }}'

ldap__servers

List of LDAP directory server hostnames which should be used to manage directory entries. The first server listed here will be used for administrative access.

The role tries to detect LDAP servers to use via published _ldap._tcp SRV resource records, and if there aren't any, will fallback to the ldap.* Fully Qualified Domain Name.

ldap__servers: '{{ ldap__servers_srv_rr | map(attribute="target") }}'

ldap__servers_protocol

The <protocol>:// name to use in the configured LDAP URIs, based on the presence of configured debops.pki environment. Role assumes that all detected LDAP servers use the same connection configuration.

ldap__servers_protocol: '{{ "ldap" if ldap__start_tls | bool else "ldaps" }}'

ldap__servers_uri

The list of LDAP URIs to configure in the /etc/ldap/ldap.conf configuration file which will be used as a default configuration system-wide.

ldap__servers_uri: '{{ ldap__servers
                       | map("regex_replace", "^(.*)$",
                             ldap__servers_protocol + "://\1/")
                       | list }}'

ldap__start_tls

If True, the role will use STARTTLS command by default on connections to plain ldap (389) TCP port. This requires configured X.509 PKI environment, managed by the debops.pki role.

ldap__start_tls: '{{ True
                     if (ansible_local | d() and ansible_local.pki | d() and
                         (ansible_local.pki.enabled | d()) | bool)
                     else False }}'

LDAP directory structure 

These variables define the LDAP directory structure used by the debops.ldap Ansible role. Check the LDAP Directory Information Tree for more details.

ldap__base_dn

The Base Distinguished Name (BaseDN) used in the LDAP directory, defined in a YAML list format. By default, OpenLDAP service in Debian uses the host DNS domain to create the directory BaseDN, that's why this role uses the DNS domain to construct the BaseDN on the client side.

This variable can be used in Ansible playbooks that include the debops.ldap role to join other YAML list-based RDNs together.

ldap__base_dn: '{{ ldap__domain.split(".")
                   | map("regex_replace", "^(.*)$", "dc=\1")
                   | list }}'

ldap__basedn

The Base Distinguished Name (BaseDN) used in the LDAP directory, defined as a comma-delimited string.

This variable can be used in Ansible playbooks that include the debops.ldap role to join other string-based RDNs together.

ldap__basedn: '{{ ldap__base_dn | join(",") }}'

ldap__people_rdn

The RDN added to the BaseDN that contains the personal LDAP objects, for example inetOrgPerson.

ldap__people_rdn: 'ou=People'

ldap__system_groups_rdn

The RDN added to the BaseDN that contains LDAP System Group objects, for example groupOfNames or groupOfUniqueNames. This group is used for internal LDAP administration.

This variable is obsolete and will be removed in the future.

ldap__system_groups_rdn: 'ou=System Groups'

ldap__groups_rdn

The RDN added to the BaseDN that contains LDAP Group objects, for example groupOfNames or groupOfUniqueNames.

ldap__groups_rdn: 'ou=Groups'

ldap__hosts_rdn

The RDN added to the BaseDN that contains LDAP Host objects, for example device, that allow different devices access to the LDAP directory. This branch is meant to be used for servers and devices managed by the IT department.

ldap__hosts_rdn: 'ou=Hosts'

ldap__machines_rdn

The RDN added to the BaseDN that contains LDAP Machine objects, for example device, that allow different devices access to the LDAP directory. This branch is meant to be used for client machines that require access to the LDAP directory.

ldap__machines_rdn: 'ou=Machines'

ldap__roles_rdn

The RDN added to the BaseDN that contains LDAP Role objects, for example organizationalRole.

ldap__roles_rdn: 'ou=Roles'

ldap__services_rdn

The RDN added to the BaseDN that contains LDAP Service objects, for example account, that belong to the cluster-wide services, as opposed to a service that exists on a specific machine.

ldap__services_rdn: 'ou=Services'

LDAP device object configuration 

These variables define the "LDAP device object" the debops.ldap role will create in the LDAP directory for a given host it is executed against. This object will be used as a base DN to create additional LDAP objects required by other DebOps roles, for example bind accounts.

ldap__device_enabled

Enable or disable management of the "LDAP device object" in the LDAP directory. Disabling this functionality might make some of the DebOps roles that depend on access to the LDAP directory unusable.

ldap__device_enabled: True

ldap__device_separate_domains

By default, hosts managed by DebOps will be put in an additional directory level based on their DNS domain, to make the management of large environments easier. If you have small number of hosts in the LDAP directory, you can disable this variable to not create additional level in the directory structure.

ldap__device_separate_domains: True

ldap__device_domain

The DNS domain used to create an LDAP dNSDomain object to hold hosts in the same domain together.

ldap__device_domain: '{{ ldap__domain }}'

ldap__device_fqdn

The Fully Qualified Domain Name of a given remote host. This value will be used to build the Distinguished Name of the LDAP object that represents this device.

ldap__device_fqdn: '{{ ansible_fqdn }}'

ldap__device_aliases

List of additional DNS names for a given device. They will be added as cn attributes in the LDAP device object.

ldap__device_aliases: [ '{{ ansible_hostname }}' ]

ldap__device_ip_addresses

List of IPv6/IPv4 addresses of the remote host which will be included in the LDAP device object ipHostNumber attributes.

Only the externally accessible addresses will be added, any internal bridges or other network interfaces not reachable directly from outside the host will be skipped. The RFC 1918 addresses will also be added in the attributes, if they are configured to be reachable from outside of the host.

ldap__device_ip_addresses: '{{ lookup("template", "lookup/ldap__device_ip_addresses.j2",
                                      convert_data=False) | from_yaml }}'

ldap__device_ip_iface_regex

Regex used to determine which network interfaces to consider for inclusion in the LDAP device object ipHostNumber attributes.

ldap__device_ip_iface_regex: '^(bond|en|eth|vlan|mv-|host)'

ldap__device_mac_addresses

List of Media Access Control (MAC) addresses of the remote host which will be included in the LDAP device object macAddress attributes.

Only the Ethernet network interfaces, or their equivalents in the virtual machines or containers, will be included in the list. Any other types of network devices will be skipped.

The 'unique' filter is used here to prevent adding duplicate MAC addresses to the device object. This could otherwise cause problems when the host employs network bonding (where the MAC addresses of the physical interfaces can become the same).

ldap__device_mac_addresses: '{{ lookup("template", "lookup/ldap__device_mac_addresses.j2",
                                       convert_data=False) | from_yaml }}'

ldap__device_mac_iface_regex

Regex used to determine which network interfaces to consider for inclusion in the LDAP device object macAddress attributes.

ldap__device_mac_iface_regex: '^(en|eth|mv-)'

ldap__device_self_rdn

The Relative Distinguished Name of the remote host LDAP object managed by DebOps.

ldap__device_self_rdn: 'cn={{ ldap__device_fqdn }}'

ldap__device_domain_rdn

The Relative Distinguished Name of the domain LDAP object which will contain all device objects in that domain, if enabled.

ldap__device_domain_rdn: 'dc={{ ldap__device_domain }}'

ldap__device_branch_rdn

The Relative Distinguished Name of the main LDAP directory branch where the remote hosts managed by DebOps will be added, along with the separate domain LDAP objects.

ldap__device_branch_rdn: '{{ ldap__hosts_rdn }}'

ldap__device_dn

The Distinguished Name of the LDAP object that will represent the host managed by DebOps in the LDAP directory, defined as a YAML list. This value will be available using the ansible_local.ldap.device_dn Ansible local fact, from where other Ansible roles can use it to construct Distinguished Names relative to the hosts' own LDAP object.

ldap__device_dn: '{{ q("flattened", [ldap__device_self_rdn]
                                    + ([ldap__device_domain_rdn]
                                       if ldap__device_separate_domains | bool
                                       else [])
                                    + [ldap__device_branch_rdn]
                                    + ldap__base_dn) }}'

ldap__device_managers

The list of Distinguished Names of the host managers (system administrators or other people responsible for a given host), stored in the LDAP device object in the manager attribute. By default the current Ansible user will be set as a manager; any other Ansible users who apply the debops.ldap role against the same host will be automatically added as managers as well.

ldap__device_managers: [ '{{ ldap__admin_dn | join(",") }}' ]

ldap__device_domain_object_classes

List of LDAP objectClass names which will be used to create the domain LDAP object, when enabled.

ldap__device_domain_object_classes: [ 'domain' ]

ldap__device_domain_attributes

YAML dictionary which contains the LDAP object attributes which are required to create the domain LDAP object.

ldap__device_domain_attributes:
  dc: '{{ ldap__device_domain_rdn.split("=")[1] }}'

ldap__device_object_classes

List of LDAP objectClass names which will be used to create the LDAP device object.

ldap__device_object_classes: '{{ ["device", "ieee802Device", "ipHost"]
                                 + ([]
                                    if (ansible_virtualization_role == "guest" and
                                        ansible_virtualization_type in ["lxc", "docker", "openvz"])
                                    else ["bootableDevice"]) }}'

ldap__device_attributes

YAML dictionary which contains the LDAP object attributes of the device object. Some of these attributes (cn, ipHostNumber) are required for the object creation by the LDAP schema, others are included as a convenience.

These attributes will be used to update the existing LDAP device object as well on any changes.

ldap__device_attributes:
  cn: '{{ ([ldap__device_self_rdn.split("=")[1]] + ldap__device_aliases) | unique }}'
  ipHostNumber: '{{ ldap__device_ip_addresses }}'
  macAddress:   '{{ ldap__device_mac_addresses }}'
  manager:      '{{ ldap__device_managers }}'

POSIX environment 

These variables define default parameters of the POSIX environment expected by the LDAP directory. See LDAP - POSIX environment integration for more details.

Ref: https://github.com/systemd/systemd/blob/master/docs/UIDS-GIDS.md

Note

When the values of the variables are updated here, rmember to update the corresponding variables in the debops.slapd role for consistency.

ldap__uid_gid_min

First UID/GID which is considered to be managed by the LDAP directory and not by the local NSS database.

ldap__uid_gid_min: '2000000000'

ldap__groupid_min

First UID/GID reserved for shared groups in the LDAP directory. Default: the same as the start of the LDAP directory UID/GID range.

ldap__groupid_min: '{{ ldap__uid_gid_min }}'

ldap__groupid_max

Last UID/GID reserved for shared groups in the LDAP directory. Higher UID/GID numbers are meant to be used for people, machine or service accounts with matching User Private Groups. Default: 2001999999

Ref: https://wiki.debian.org/UserPrivateGroups

ldap__groupid_max: '{{ ldap__uid_gid_min | int + 1999999 }}'

ldap__uid_gid_max

Last UID/GID which is considered to be managed by the LDAP directory and not by the local NSS database. Default: 2099999999

ldap__uid_gid_max: '{{ ldap__uid_gid_min | int + 99999999 }}'

ldap__home

Specify the base path of the home directories managed in LDAP using the homeDirectory attribute.

ldap__home: '/home'

ldap__shell

Specify the default shell for accounts managed in LDAP using the loginShell attribute.

ldap__shell: '/bin/bash'

Host-based access control 

Lists below define URN-like patterns which can be used by other Ansible roles to implement host-based access control. The list of URN patterns defined on a given host is available via Ansible local facts. See Host-based access control for more details.

The lists are flattened in the fact script, you can use an empty list to enable or disable an URN pattern conditionally.

ldap__default_urn_patterns

List of the URN-like patterns defined by the role.

ldap__default_urn_patterns:

  - '{{ ("deploy:" + ansible_local.machine.deployment)
        if (ansible_local.machine.deployment | d())
        else [] }}'

ldap__urn_patterns

List of the URN-like patterns defined on all hosts in the Ansible inventory.

ldap__urn_patterns: []

ldap__group_urn_patterns

List of the URN-like patterns defined on hosts in a specific Ansible inventory group.

ldap__group_urn_patterns: []

ldap__host_urn_patterns

List of the URN-like patterns defined on specific hosts in the Ansible inventory.

ldap__host_urn_patterns: []

ldap__combined_urn_patterns

Variable which combines all other URN pattern lists and is used in role templates.

ldap__combined_urn_patterns: '{{ ldap__default_urn_patterns
                                 + ldap__urn_patterns
                                 + ldap__group_urn_patterns
                                 + ldap__host_urn_patterns }}'

System-wide LDAP configuration 

These variables define contents of the /etc/ldap/ldap.conf configuration file. See ldap__configuration for more details.

ldap__default_configuration

List of the default configuration options for system-wide LDAP support, defined by the role.

ldap__default_configuration:

  - name: 'base'
    value: '{{ ldap__basedn }}'

  - name: 'uri'
    value: '{{ ldap__servers_uri }}'

  - name: 'sizelimit'
    value: '12'
    state: 'comment'
    separator: True

  - name: 'timelimit'
    value: '15'
    state: 'comment'

  - name: 'deref'
    value: 'never'
    state: 'comment'

  - name: 'tls_cacert'
    comment: 'TLS certificates (needed for GnuTLS)'
    value: '/etc/ssl/certs/ca-certificates.crt'

  - name: 'tls_reqcert'
    value: 'demand'

ldap__configuration

List of the configuration options for system-wide LDAP support, defined on all hosts in the Ansible inventory.

ldap__configuration: []

ldap__group_configuration

List of the configuration options for system-wide LDAP support, defined on hosts in a specific Ansible inventory group.

ldap__group_configuration: []

ldap__host_configuration

List of the configuration options for system-wide LDAP support, defined on specific hosts in the Ansible inventory.

ldap__host_configuration: []

ldap__combined_configuration

The variable which combines all other system-wide configuration variables and is used in the Ansible tasks and templates.

ldap__combined_configuration: '{{ ldap__default_configuration
                                  + ldap__configuration
                                  + ldap__group_configuration
                                  + ldap__host_configuration }}'

LDAP administrative access 

These variables define configuration of the administrative access to the LDAP directory, required to perform LDAP tasks by Ansible on behalf of the system administrator. See LDAP tasks and administrative operations for more details.

ldap__admin_enabled

Enable or disable support for performing LDAP tasks on behalf of the LDAP Administrator. This feature will be enabled if the password is available to allow binding to the LDAP directory.

ldap__admin_enabled: '{{ True if ldap__fact_admin_bindpw | d() else False }}'

ldap__admin_passwordstore_path

The relative path in the pass password database, where personal LDAP credentials can be found by the role. See Secure handling of LDAP admin credentials for more details. This variable can be used in Ansible playbooks that use the debops.ldap role to create and update admin credentials.

ldap__admin_passwordstore_path: 'debops/ldap/credentials'

ldap__admin_rdn

The Relative Distinguished Name of the personal account of the person who uses the Ansible playbooks. By default derived from the local UNIX account name which is assumed to be the same in the LDAP directory. This account should have sufficient privileges to manage the LDAP directory objects operated on by the playbooks.

ldap__admin_rdn: '{{ "uid=" + lookup("env", "USER") }}'

ldap__admin_dn

The Distinguished Name of the system administrator account, defined as a YAML list.

ldap__admin_dn: '{{ [ldap__admin_rdn, ldap__people_rdn] + ldap__base_dn }}'

ldap__admin_binddn

The LDAP BindDN value which will be used to bind to the LDAP directory for administrative tasks. It can be overridden on the Ansible Controller through use of the environment variables.

ldap__admin_binddn: '{{ lookup("env", "DEBOPS_LDAP_ADMIN_BINDDN")
                        | d(ldap__admin_dn | join(","), True) }}'

ldap__admin_bindpw

The LDAP BindPW value which will be used to bind to the LDAP directory for administrative tasks. It can be overridden on the Ansible Controller through use of the environment variables. See Secure handling of LDAP admin credentials for more details.

ldap__admin_bindpw: '{{ (lookup("env", "DEBOPS_LDAP_ADMIN_BINDPW")
                         if lookup("env", "DEBOPS_LDAP_ADMIN_BINDPW") | d()
                         else (lookup("file", secret + "/ldap/credentials/"
                                              + ldap__admin_binddn | to_uuid
                                              + ".password")
                               if lookup("first_found",
                                         [secret + "/ldap/credentials/"
                                          + ldap__admin_binddn | to_uuid
                                          + ".password"],
                                         skip=True, errors="ignore")
                               else lookup("passwordstore",
                                           ldap__admin_passwordstore_path + "/"
                                           + ldap__admin_binddn | to_uuid
                                           + " create=false", errors="ignore")))
                        if ldap__enabled | bool else "" }}'

ldap__admin_server_uri

The LDAP URI that defines the connection to use for LDAP tasks performed by Ansible on behalf of the system administrator.

ldap__admin_server_uri: '{{ ldap__servers_uri | first }}'

ldap__admin_delegate_to

By default all LDAP tasks are delegated to the Ansible Controller to allow access to credentials stored locally by the current Ansible user. This variable allows to delegate to another host than the Ansible Controller to perform the LDAP tasks there.

ldap__admin_delegate_to: 'localhost'

ldap__admin_become

By default the LDAP tasks delegated to the Ansible Controller will be executed without performing privilege escalation on the Controller host. If you need to to escalate privileges on a remote host to which the LDAP tasks have been delegated, you can enable this here.

ldap__admin_become: False

ldap__admin_become_user

Specify the UNIX account to which perform the privilege escalation, if enabled in the previous variable.

ldap__admin_become_user: 'root'

LDAP tasks and operations 

These variables define a list of LDAP tasks to perform in the LDAP directory, when the administrative access is available. See ldap__tasks for more details.

ldap__default_tasks

List of LDAP tasks to perform in the LDAP directory, defined by the role.

ldap__default_tasks:

  - name: 'Ensure that {{ ldap__hosts_rdn }} object exists in LDAP directory'
    dn: '{{ [ldap__hosts_rdn] + ldap__base_dn }}'
    objectClass: [ 'organizationalStructure' ]
    attributes:
      ou: '{{ ldap__hosts_rdn.split("=")[1] }}'
      description: 'Servers and other data center equipment'

  - name: 'Create domain object for {{ ldap__device_dn | join(",") }}'
    dn: '{{ [ldap__device_domain_rdn, ldap__device_branch_rdn]
            + ldap__base_dn }}'
    objectClass: '{{ ldap__device_domain_object_classes }}'
    attributes: '{{ ldap__device_domain_attributes }}'
    state: '{{ "present"
               if (ldap__device_enabled | bool and
                   ldap__device_separate_domains | bool)
               else "ignore" }}'

  - name: 'Create device object for {{ ldap__device_dn | join(",") }}'
    dn: '{{ ldap__device_dn }}'
    objectClass: '{{ ldap__device_object_classes }}'
    attributes: '{{ ldap__device_attributes }}'
    state: '{{ "present"
               if (ldap__device_enabled | bool)
               else "ignore" }}'

  - name: 'Update device object for {{ ldap__device_dn | join(",") }}'
    dn: '{{ ldap__device_dn }}'
    attributes: '{{ ldap__device_attributes }}'
    state: '{{ "present"
               if (ldap__fact_configured | bool and
                   ldap__device_enabled | bool)
               else ("exact"
                     if (ldap__device_enabled | bool)
                     else "ignore") }}'

ldap__tasks

List of LDAP tasks to perform in the LDAP directory, defined on all hosts in the Ansible inventory.

ldap__tasks: []

ldap__group_tasks

List of LDAP tasks to perform in the LDAP directory, defined on hosts in specific Ansible inventory group.

ldap__group_tasks: []

ldap__host_tasks

List of LDAP tasks to perform in the LDAP directory, defined on specific hosts in the Ansible inventory.

ldap__host_tasks: []

ldap__dependent_tasks

List of the LDAP tasks to perform in the LDAP directory, defined by other Ansible roles or playbooks.

ldap__dependent_tasks: []

ldap__combined_tasks

The variable that combines the lists of LDAP tasks in other variables and is used in role tasks. By default debops.ldap role will execute LDAP tasks defined in Ansible inventory when run standalone, and will skip them if it detects the usage as a dependency by another role.

ldap__combined_tasks: '{{ ldap__dependent_tasks
                          if (ldap__fact_configured | bool and
                              ldap__dependent_tasks | d())
                          else (ldap__default_tasks
                                + ldap__tasks
                                + ldap__group_tasks
                                + ldap__host_tasks
                                + ldap__dependent_tasks) }}'

Configuration variables for other Ansible roles 

ldap__python__dependent_packages3

Configuration for the debops.python Ansible role.

ldap__python__dependent_packages3:

  - '{{ ([]
         if (ansible_distribution_release in
             (["stretch", "trusty", "xenial"]))
         else "python3-ldap")
        if ldap__enabled | bool
        else [] }}'

ldap__python__dependent_packages2

Configuration for the debops.python Ansible role.

ldap__python__dependent_packages2:

  - '{{ "python-ldap" if ldap__enabled | bool else [] }}'