Ansible Modules for the Automation of UCS-Specific Tasks

As a long-term Univention partner, we at Adfinis Sygroup operate UCS environments for many of our customers. We employ Ansible for automation when running different Linux distributions as it standardizes the roll-out of UCS among other things.

Up until now there weren’t any Ansible modules available for UCS-specific tasks. To remedy this, we developed modules based on the standard script interface of Univention Directory Manager for recurring tasks in the maintenance of the directory service with the goal of simplifying the process. These currently include the following:

udm_group
udm_user
udm_dns_zone
udm_dns_record
udm_share

These modules are included in the Ansible extra modules as of Ansible Version 2.2 and can be used accordingly with Ansible, as can other modules. If additional Ansible modules are developed in the future (and not yet included in Ansible itself), it will be possible to add them to individual projects. The following offers a brief explanation of how these additional Ansible modules can be installed and then provides a brief introduction to the modules listed above.

Installation

Additional Ansible modules can either be installed on an individual project basis or installed in the Ansible source code. For it to be possible to install additional modules for individual projects, they need to be copied into the “library” folder below the top directories of the project. This looks something like this:

$ ls
|- ansible.cfg
|- group_vars/
| |- all/
|- inventory
|- library/
| |- README.md
| |- ucr.py
| |- udm_dns_record.py
| |- udm_dns_zone.py
| |- udm_group.py
| |- udm_share.py
| |- udm_user.py
|- README.md
|- site.yml

If the modules are installed in the Ansible source code, the entire Ansible source code needs to be cloned:

$ git clone https://github.com/ansible/ansible.git
$ cd ansible/
$ git submodule update --init --recursive

Ansible can then be installed with the help of pip:

$ virtualenv -p /usr/bin/python2 venv
$ . venv/bin/activate
$ pip install -e ansible/

The additional Ansible modules then simply need to be copied into the ansible/lib/ansible/modules/extras/ or a subfolder. The Univention modules, for example, still belong in the subfolder univention.

udm_group

To create a group with the name employee and the LDAP DN cn=employee,cn=groups,ou=company,dc=example,dc=org, you need to run the following Ansible task:

- udm_group: name=employee
description=Employee
ou=company
subpath=‘cn=groups‘

If only the attribute name is specified, the group is created with the DN cn=<name>,cn=groups,<LDAP Base DN>.

udm_user

A user object spans a great number of possible attributes, as such only a few are displayed below as an example. All the available attributes are documented directly in the Ansible module.

For example, to create a user Hans Muster with the user name hans.muster and the password secure_password, you need to run the following task:

- udm_user: name=hans.muster
firstname=Hans
lastname=Muster
password=secure_password

It is also possible to specify the complete LDAP path as for udm_group. If no further data is entered, the user will be created with the LDAP DN uid=hans.muster,cn=users,dc=example,dc=com.

udm_dns_zone

DNS zones do not have many possible attributes. One special aspect is that the interfaces, NS records, and MX records are defined in the zone. The interfaces are comparable with BIND 9 Views. These define where the responses to the corresponding DNS queries come from. The NS and MX records are treated specially in UCS and for this reason are configured via udm_dns_zone and not udm_dns_record.

For example, the forward zone example.com with the responsible name server ucs.example.com, which responds to DNS queries on the IP address 192.168.1.1,would be set up as follows:

- udm_dns_zone: zone=example.com
type=forward_zone
nameserver=['ucs.example.com']
interfaces=['192.168.1.1']

udm_dns_record

Individual DNS records can be created with udm_dns_record. Possible entries are:

• host_record (A und AAAA Records)
• alias (CNAME Records)
• ptr_record
• srv_record
• txt_record

To add the entry www.example.com IN A 192.168.1.1 to the zone example.com, you need to run the following task:

- udm_dns_zone: name=www
zone=example.com
type=host_record
data=['a': '192.168.1.1']

udm_share

The module udm_share can be used to handle Samba and NFS shares. A share object contains a variety of attributes, all of which are documented in the Ansible module.

To create the share homes on the Ansible target system, you need to run the following task.

- udm_share: name=homes
host='{{ ansible_fqdn }}'
path=/home
owner=root
group=root
directorymode='00755'
samba_name=homes

Further links

Univention Common Code
Module udm_group
Module udm_user
Module udm_dns_zone
Module udm_dns_record
Module udm_share