Tech Blog.

Thoughts, stories, ideas.

UCS Ansible modules

24. March 2016

A Univention Corporate Server (UCS) is not particularly suited for configuration by Ansible, since many tasks have to be done either via the Web GUI or via special Bash commands. Examples of this are creating, modifying or deleting users and groups.
Since we still want to automatically install and configure UCS from the Adfinis SyGroup, we’ve written new Ansible modules for various tasks. These currently include the following:

  • udm_group
  • udm_user
  • udm_dns_zone
  • udm_dns_record
  • udm_share

These modules are shipped as part of Ansible Modules Extras with Ansible version 2.2. Meaning they can be used like every other Ansible module.

If other Ansible Modules should be developed in the future (and if they are not part of Ansible), they can be installed per project.
Afterwards, a brief explanation is given on how to install additional Ansible modules, and then the above-mentioned modules are briefly introduced.

Installation

Additional Ansible modules are installed either by project or in the Ansible source code. For additional modules to be installed by project, they need to be copied into the “library” folder under the top directories of the project. This looks roughly as follows:

$ 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 has to be cloned:

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

After that, Ansible can be installed using pip:

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

Finally, the additional Ansible modules need to be copied into the folder ansible/lib/ansible/modules/extras/ or a subfolder thereof. For example, the Univention modules 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 , the following Ansible task is required:

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

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

udm_user

A user object comprises a great deal of possible attributes, so the following is just a minimal example. All available attributes are documented directly in the Ansible module.

If a user Hans Muster with the user ID hans.muster and the password secure_password is created, the following task is required:

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

The exact LDAP path can also be indicated as with udm_group. If nothing further is indicated, the user is created with the LDAP DN uid=hans.muster,cn=users,dc=example,dc=com .

udm_dns_zone

DNS zones do not have very many possible attributes. One thing to note is that the interfaces, NS and MX records are defined in the zone.
The interfaces can be compared with BIND 9 Views. These define where the corresponding DNS queries are answered from.
The NS and MX records are handled differently in UCS and are therefore not configured with udm_dns_record but rather by udm_dns_zone.

For example, the forward zone example.com with the authoritative name server ucs.example.com, which answers DNS queries at the IP address 192.168.1.1 is 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

If the zone example.com has the entry www.example.com. IN A 192.168.1.1 added to it, the following task is required:

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

udm_share

Samba and NFS shares can be handled with the module udm_share. A share object comprises a large number of attributes, which are documented in the Ansible module.

For the share homes to be created on the Ansible target system, the following task is required:

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

Links