Intended Audience: System administrators
- Installation (ansible)
- Copyright & License
- Software / technology used
- Make yourself familiar with the system architecture.
Currently the Ansible playbooks support fully automated
- openSUSE Tumbleweed
- openSUSE Leap 15.4+ and SUSE Linux Enterprise Server 15SP4 using additional OBS repo home:stroeder:iam
- Debian bullseye (currently stable) and Debian bookworm (currently testing) using additional Æ-DIR Debian APT repository
- Ubuntu Server 20.04 LTS (Focal Fossa) and 22.04 LTS (Jammy Jellyfish) using additional Æ-DIR Ubuntu APT repository
CentOS 8.2+ (not recommended anymore) or
Rocky Linux 8.4+
Symas OpenLDAP 2.6
and with setting
- Arch Linux
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 so-called ansible control node):
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.
Firewall rules are properly setup
(see also system architecture):
- Your Ansible control node (e.g. admin workstation) has to be able to contact all Æ-DIR hosts via SSH (usually 22/tcp, see below for details).
- Your admin workstation has to be able to contact the Æ-DIR providers via HTTPS (443/tcp).
- The provider replicas have to be able to contact each other via LDAPS (port 636/tcp).
- The consumer replicas have to be able to contact the relevant provider replicas via LDAPS (port 636/tcp).
Prepare to have SSH access to all Æ-DIR servers as user
Check whether you can access the hosts via SSH with:
/opt/ansible/bin/ansible all -i 'hostname.example.com,' -m setupThe trailing comma after the FQDN is needed when using a single hostname!
- Make yourself familiar with how to use command-line options for ansible privilege escalation with become .
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://code.stroeder.com/AE-DIR/ansible-example-site.git 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 control node (e.g. admin workstation).
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: