Intended Audience: System administrators
- Installation (ansible)
- Copyright & License
- Software / technology used
- Make yourself familiar with the system architecture.
Install Æ-DIR servers with one of the supported operating
systems which support Python 3.6+ out-of-the-box.
Currently the ansible playbooks support fully automated
- openSUSE Tumbleweed
- openSUSE Leap 15.3+
- SUSE Linux Enterprise Server 15SP3
- Debian bullseye (stable) and Debian buster (oldstable) (deprecated!) using custom OpenLDAP packages from Æ-DIR's Debian APT repository
- Unbuntu 20.04 LTS using custom OpenLDAP packages from Æ-DIR's Ubuntu APT repository
CentOS 8.2+ (not recommended anymore) or
Rocky Linux 8.4+
OpenLDAP for Linux by Symas
and with setting
The ansible roles needs the following software packages on all target
machines to be installed:
- Python 3.6 or newer
- lsb_release command (package lsb-release)
Install on your admin workstation (the ansible controller):
python3 -m venv /opt/ansible /opt/ansible/bin/pip install ansible aedir dnspython netaddr
- 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.
- Configure time synchronisation (NTP) required for reliable replication.
Prepare to have SSH access to all Æ-DIR servers as user
- Make yourself familiar with how to use command-line options for ansible become.
Check whether you can access the hosts with
/opt/ansible/bin/ansible all -i 'hostname.example.com,' -m setupThe trailing comma after the FQDN is needed when using a hostname!
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.
Prepare ansible inventory
Get the ansible playbooks and roles:
git clone https://gitlab.com/ae-dir/ansible-example-site myenv cd myenv /opt/ansible/bin/ansible-galaxy install -r requirements.yml
- Edit ansible inventory file myenv/hosts to match your hosts/VMs/containers of your installation environment.
- Edit the files in directory group_vars/ to match your environment.
- Comments in file myenv/roles/ae-dir-server/defaults/main.yml describing the use of all variables you can override to adapt installation to your local environment.
- Ansible documentation about group and host vars to get a good understanding of how values are assigned to variables.
Invoke ansible play in sub-directory
ansible/(here using command
/opt/ansible/bin/ansible-playbook aedir_server.yml -i myenv/hosts --become -K --become-method=su -e aedir_init=1 -e aedir_keygen=1
- 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
- Invoke ansible-playbook command above again to proceed with installation.
- Loading the initial LDAP entries defined in file /opt/ae-dir/etc/ae-dir-base.ldif is done automatically during installation on the host referenced by ansible variable aedir_main_provider_hostname (default is first provider host).
Check the systems' health by invoking the monitoring
script on all Æ-DIR servers as user root.
By default it is installed to:
NSS/PAM integration of other hosts
For PAM/NSS client integration of arbitrary hosts invoke this ansible
play to install and configure aehostd
(here using command
/opt/ansible/bin/ansible-playbook aehostd.yml -i myenv/hosts --become -K --become-method=su -l some-other-host.example.com
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/oathldap_master_key_201806141818.pub
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/oathldap_master_key_201806141818.pub EOF
- Subscribe to ae-dir-announce and get informed about news.
- If you need more help please consider commercial support.
Copyright & License
© 2015-2021 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 https://www.apache.org/licenses/LICENSE-2.0 Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 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: