debops.ldap default variables
Sections
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 [] }}'