Installation
Intended Audience: System administrators
Support
- Subscribe to ae-dir-users and get informed about news.
- If you need more help please consider commercial support.
Prerequisites
- Make yourself familiar with the system architecture.
-
Install Æ-DIR servers with one of the supported operating
systems. Currently the ansible playbooks support fully automated
installation/configuration on…
- openSUSE Tumbleweed
- openSUSE Leap 15.0+
- SUSE Linux Enterprise Server 15 (to be tested)
- Debian Stretch using OpenLDAP packages from Debian APT repository of LTB project
- CentOS 7.4+ using OpenLDAP packages from YUM repository of LTB project
-
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)
-
Install on your admin workstation (the ansible controller):
- ansible 2.4+ (Use Jinja2 2.8.x! ansible has some issues with 2.9+!, see issue 20063)
- git
- dnspython
# virtualenv-2.7 /opt/ansible # /opt/ansible/bin/pip2 install --upgrade ansible Jinja2==2.8.1 dnspython paramiko
- Create DNS entries for all your Æ-DIR servers following best practices for hostnames.
- Configure time synchronisation (NTP) required for reliable replication.
-
Prepare to have SSH access to all Æ-DIR servers as user
root (via
su
orsudo
) - Make yourself familiar with how to use command-line options for ansible become.
-
Check whether you can access the hosts with
ansible setup:
/opt/ansible/bin/ansible all -i 'hostname.example.com,' -m setup
The trailing comma after the FQDN is needed when using a hostname! -
Get the ansible playbooks and roles:
git clone --recurse-submodules https://gitlab.com/ae-dir/ansible-example-site myenv
-
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 intools/pki-scripts/
.
Installation
- Edit ansible inventory file myenv/hosts to match your hosts/VMs/containers of your installation environment.
-
Read comments in file
myenv/roles/ae-dir-server/defaults/main.yml
and adjust ansible group and host vars to match your environment. -
Invoke ansible play in sub-directory
ansible/
(here using commandsu
):/opt/ansible/bin/ansible-playbook ae-dir-servers.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.
-
Log into one provider system become user root and run the
following commands to fully initialize your directory:
-
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
-
On SUSE / openSUSE:
-
Set the user password of an initial Æ admin (here msin):
/opt/ae-dir/bin/ae-passwd.py msin
-
Add the basic Æ-DIR entries with OpenLDAP command-line tool:
-
Check the systems' health by invoking as root the monitoring
script on all Æ-DIR servers. By default it is installed to:
/opt/ae-dir/sbin/slapd_checkmk.sh
NSS/PAM self-integration
For PAM/NSS client self-integration invoke ansible play in sub-directory ansible/
(here using command su
):
/opt/ansible/bin/ansible-playbook ae-dir-clients.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/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
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 http://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: