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.


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({})) }}'


    - role: python
      tags: [ 'role::python', 'skip::python', 'role::ldap' ]
        - '{{ ldap__python__dependent_packages3 }}'
        - '{{ ldap__python__dependent_packages2 }}'

    - role: ldap
      tags: [ 'role::ldap', 'skip::ldap' ]

Ansible tags

You can use Ansible --tags or --skip-tags parameters to limit what tasks are performed during Ansible run. This can be used after host is first configured to speed up playbook execution, when you are sure that most of the configuration has not been changed.

Available role tags:

Main role tag, should be used in the playbook to execute all of the role tasks as well as role dependencies.
Run the LDAP tasks generated by the role in the LDAP directory.

Other resources

List of other useful resources related to the debops.ldap Ansible role:


[1]Well, not yet, but that's the planned direction that DebOps maintainers are looking into right now.