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

You can use the ansible/playbooks/ldap/init-directory.yml Ansible playbook to initialize new LDAP directory. This playbook is designed to be used with the LDAP Access Control List configuration and will be updated on any changes, if needed. 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. The default cn=admin LDAP object created during OpenLDAP installation will be removed.

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' ]

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:

role::ldap
Main role tag, should be used in the playbook to execute all of the role tasks as well as role dependencies.
role::ldap:tasks
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:

Footnotes

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