Getting started
Ansible Controller requirements
If you plan to use this role to perform LDAP tasks in the default
configuration, you need to install the python-ldap
Python package in the
Ansible environment on the Controller host.
By default the role uses pass (Password Store) as a password manager to store LDAP user credentials securely using GnuPG. As a fallback, you can also provide the required password using an environment variable on the Ansible Controller, or configure your own password lookup method.
LDAP directory initialization
The base directory structure used by DebOps roles is defined and managed by the
debops.slapd Ansible role. The slapd__structure_tasks
variable
contains a list of LDAP objects which will be created on server installation,
which conform to the LDAP Access Control List configuration.
The ansible/playbooks/ldap/init-directory.yml
Ansible playbooks
contains additional configuration which can be used to create an admin account
inside of the LDAP directory and grant it "LDAP Administrator" and "UNIX
Administrator" roles. To use it with the new OpenLDAP servers, run the command:
debops ldap/init-directory -l <slapd-server>
The playbook will use the current UNIX account information on the Ansible
Controller (passwd
database, SSH public keys from ssh-agent) to
create a new user account in the LDAP directory with administrator privileges.
The user will be asked for a new password used to bind to the directory; this password will be stored on the Ansible Controller using Password Store, and used for LDAP tasks and administrative operations.
The playbook will not make any changes to existing LDAP objects.
Note
For the LDAP access to work, Ansible Controller needs to trust the Certificate Authority which is used by the OpenLDAP service. If you rely on the debops.pki internal CA, you will have to add the Root CA certificate managed by the role to the operating system certificate store.
Example inventory
The debops.ldap role is included in the DebOps common playbook, therefore you don't need to do anything special to enable it on a host. However it is deactivated by default.
To enable the role, define in the Ansible inventory, for example in
ansible/inventory/group_vars/all/ldap.yml
file:
ldap__enabled: True
The debops.ldap role is used by many other DebOps roles 1, and enabling it will affect the environment and configuration of multiple services, including basic things like UNIX system groups used to manage the host. It's best to either not enable LDAP support in a given environment, or enable it at the beginning of a new deployment.
The POSIX integration with the LDAP directory can be controlled using the
ldap__posix_enabled
variable. If it's set to False
, services that
are specific to a POSIX environment (nslcd, sshd,
sudo and others) will not be configured with LDAP support. In such
case only higher-level applications like nullmailer, Postfix,
GitLab, etc. will be configured for use with LDAP.
You can of course enable LDAP support in an existing environment, but you should first learn about changes required by other Ansible roles for successful migration. Check the documentation of other DebOps roles for more details.
Example playbook
If you are using this role without DebOps, here's an example Ansible playbook
that uses the debops.ldap
role:
---
- name: Manage LDAP basic configuration
collections: [ 'debops.debops', 'debops.roles01',
'debops.roles02', 'debops.roles03' ]
hosts: [ 'debops_all_hosts', 'debops_service_ldap' ]
become: True
environment: '{{ inventory__environment | d({})
| combine(inventory__group_environment | d({}))
| combine(inventory__host_environment | d({})) }}'
roles:
- role: python
tags: [ 'role::python', 'skip::python', 'role::ldap' ]
python__dependent_packages3:
- '{{ ldap__python__dependent_packages3 }}'
python__dependent_packages2:
- '{{ ldap__python__dependent_packages2 }}'
- role: ldap
tags: [ 'role::ldap', 'skip::ldap' ]
Other resources
List of other useful resources related to the debops.ldap
Ansible role:
Manual pages: ldap.conf(5), ldif(5)
LDAP for Rocket Scientists, an excellent book about LDAP and OpenLDAP
Debian LDAP Portal page in the Debian Wiki
Ansible community.general.ldap_entry module, used to manage LDAP entries.
The role does not rely on the Ansible
ldap_attr
module, instead it uses theldap_attrs
module included in thedebops.ansible_plugins
role to manage LDAP attributes of an entry.
Footnotes
- 1
Well, not yet, but that's the planned direction that DebOps maintainers are looking into right now.