Intended Audience: System administrators

  1. Prerequisites
  2. Installation (ansible)
    1. NSS/PAM self-integration
    2. Two-factor authentication (OATH-LDAP)
  3. Support
  4. Copyright & License
  5. Software / technology used


  1. Make yourself familiar with the system architecture.
  2. Install Æ-DIR servers with one of the supported operating systems. Currently the ansible playbooks support fully automated installation/configuration on… If you want to tweak the ansible roles to install on another OS make sure a recent OpenLDAP 2.4.44+ with overlay slapo-deref is available for your OS platform. Older releases are explicitly not recommended!
  3. The ansible roles needs the following software packages on all target machines to be installed:
    • Python 2.x
    • python-xml
    • lsb_release command (package lsb-release)
  4. Install on your admin workstation (the ansible controller): Simple approach:
          # virtualenv-2.7 /opt/ansible
          # /opt/ansible/bin/pip2 install --upgrade ansible Jinja2==2.8.1 dnspython paramiko
  5. Create DNS entries for all your Æ-DIR servers following best practices for hostnames. Don't forget to add correct reverse DNS entries (PTR RRs) required for correctly creating LDIF data for initial load.
  6. Configure time synchronisation (NTP) required for reliable replication.
  7. Prepare to have SSH access to all Æ-DIR servers as user root (via su or sudo)
  8. Make yourself familiar with how to use command-line options for ansible become.
  9. Check whether you can access the hosts with ansible setup:
    /opt/ansible/bin/ansible all -i ',' -m setup
    The trailing comma after the FQDN is needed when using a hostname!
  10. You have to issue X.509 TLS server certificates with appropriate CN and subjectAltName values for all replicas with your existing PKI's certificate authority.
    The anti-security concept of wild-card certificates is not compatible with Æ-DIR's security concept! Therefore these cannot be used!
    If you don't have a PKI yet you can setup a test certificate authority (CA) with shell scripts found in pki-scripts/.

Installation with ansible

Note that there is no official way to install Æ-DIR manually.

  1. Get the ansible playbooks and roles:
    git clone --recurse-submodules myenv
  2. Edit ansible inventory file myenv/hosts to match your hosts/VMs/containers of your installation environment.
  3. Read comments in file myenv/roles/ae-dir-server/defaults/main.yml and adjust ansible group and host vars to match your environment.
  4. Invoke ansible play in sub-directory ansible/ (here using command su):
    /opt/ansible/bin/ansible-playbook ae-dir-server.yml -i myenv/hosts --become -K --become-method=su --extra-vars='{"aedir_init":True, "openldap_keygen":True}'
    • At first run this will generate TLS server key and signed CSR file and stops with a message where to find the CSR files on your local ansible controller.
    • After signing the CSRs with your CA place the server certificate file(s) into directory ae-dir/ansible/myenv/files/.
    • Invoke ansible-playbook command above again to proceed with installation.
  5. Log into one provider system become user root and run the following commands to fully initialize your directory:
    1. Add the basic Æ-DIR entries with OpenLDAP command-line tool:
      • On SUSE / openSUSE:
        ldapmodify -f /opt/ae-dir/etc/ae-dir-base.ldif
      • On Debian and CentOS:
        /usr/local/openldap/bin/ldapmodify -f /opt/ae-dir/etc/ae-dir-base.ldif
    2. Set the user password of an initial Æ admin (here msin):
      /opt/ae-dir/bin/ae-dir-passwd msin
  6. Check the systems' health by invoking as root the monitoring script on all Æ-DIR servers. By default it is installed to:

NSS/PAM self-integration

For PAM/NSS client self-integration invoke this ansible play to install and configure aehostd (here using command su):

/opt/ansible/bin/ansible-playbook aehostd.yml -i myenv/hosts --become -K --become-method=su -l ae-dir-servers

Two-factor authentication (OATH-LDAP)

You can easily use the built-in two-factor authentication based on OATH-LDAP.

This is enabled by setting ansible variable oath_ldap_enabled: True and then play the complete configuration to the Æ-DIR servers. Of course you set this flag also before the first run. This installs an additional web app and the so-called bind listeners on providers and consumers.

Afterwards you have to generate at least one master key pair for protecting the token shared secrets (OTP seeds):

# oathldap-tool genkey --key-path /opt/ae-dir/etc/oath-master-keys/
Generating RSA-2048 key pair...

wrote /opt/ae-dir/etc/oath-master-keys/oathldap_master_key_201806141818.priv
wrote /opt/ae-dir/etc/oath-master-keys/

Correct the permissions if needed which would also be done by next ansible play:

# chmod 640 /opt/ae-dir/etc/oath-master-keys/oathldap_master_key_201806141818.*

Then store the new public key in the OATH parameters entry:

# ldapmodify <<EOF
dn: cn=oath-policy-hotp-users,cn=ae,ou=ae-dir
changetype: modify
replace: oathEncKey
oathEncKey:< file:/opt/ae-dir/etc/oath-master-keys/



Copyright & License

© 2015-2017 by Michael Ströder

  Licensed under the Apache License, Version 2.0 (the "License"); you may
  not use files and content provided on this web site except in compliance
  with the License. You may obtain a copy of the License at

  Unless required by applicable law or agreed to in writing, software
  distributed under the License is distributed on an "AS IS" BASIS,
  See the License for the specific language governing permissions and
  limitations under the License.

Software / technology used

Æ-DIR serves as a good example for standing on the shoulders of giants:

Other upstream software components installed: