Installation

Intended Audience: System administrators

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

Prerequisites

  1. Make yourself familiar with the system architecture.
  2. Currently the Ansible playbooks support fully automated installation/configuration on…
  3. 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)
  4. Install on your admin workstation (the so-called ansible control node): Simple approach for install ansible in a Python virtual environment: 
    python3 -m venv /opt/ansible
/opt/ansible/bin/pip install ansible aedir dnspython netaddr
  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. 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).
  8. Prepare to have SSH access to all Æ-DIR servers as user root (via su or sudo)
  9. Check whether you can access the hosts via SSH with: 
    /opt/ansible/bin/ansible all -i 'hostname.example.com,' -m setup
    The trailing comma after the FQDN is needed when using a single hostname!
  10. Make yourself familiar with how to use command-line options for ansible privilege escalation with become .
  11. 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

  1. 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
  2. Edit ansible inventory file myenv/hosts to match your hosts/VMs/containers of your installation environment.
  3. Edit the files in directory group_vars/ to match your environment.

See also:

Æ-DIR servers

  1. Invoke ansible play in sub-directory ansible/ (here using command su): 
    /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 directory ae-dir/ansible/myenv/files/.
    • Invoke ansible-playbook command above again to proceed with installation.
  2. 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).
  3. Check the systems' health by invoking the monitoring script on all Æ-DIR servers as user root. By default it is installed to: 
    /opt/ae-dir/sbin/slapdcheck.sh

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 su): 

/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

Support

Copyright & License

© 2015-2022 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: