README.md

FreeIPA Ansible collection

This repository contains Ansible roles and playbooks to install and uninstall FreeIPA servers, replicas and clients. Also modules for group, host, topology and user management.

Note: The Ansible playbooks and roles require a configured Ansible environment where the Ansible nodes are reachable and are properly set up to have an IP address and a working package manager.

Features

• Server, replica and client deployment
• Cluster deployments: Server, replicas and clients in one playbook
• One-time-password (OTP) support for client installation
• Repair mode for clients
• Backup and restore, also to and from controller
• Modules for automembership rule management
• Modules for automount key management
• Modules for automount location management
• Modules for automount map management
• Modules for config management
• Modules for delegation management
• Modules for dns config management
• Modules for dns forwarder management
• Modules for dns record management
• Modules for dns zone management
• Modules for group management
• Modules for hbacrule management
• Modules for hbacsvc management
• Modules for hbacsvcgroup management
• Modules for host management
• Modules for hostgroup management
• Modules for location management
• Modules for permission management
• Modules for privilege management
• Modules for pwpolicy management
• Modules for role management
• Modules for self service management
• Modules for server management
• Modules for service management
• Modules for service delegation rule management
• Modules for service delegation target management
• Modules for sudocmd management
• Modules for sudocmdgroup management
• Modules for sudorule management
• Modules for topology management
• Modules for trust management
• Modules for user management
• Modules for vault management

Supported FreeIPA Versions

FreeIPA versions 4.6 and up are supported by all roles.

The client role supports versions 4.4 and up, the server role is working with versions 4.5 and up, the replica role is currently only working with versions 4.6 and up.

Supported Distributions

• RHEL/CentOS 7.4+
• Fedora 26+
• Ubuntu
• Debian 10+ (ipaclient only, no server or replica!)

Requirements

Controller

• Ansible version: 2.8+ (ansible-freeipa is an Ansible Collection)
• /usr/bin/kinit is required on the controller if a one time password (OTP) is used

Node

• Supported FreeIPA version (see above)
• Supported distribution (needed for package installation only, see above)

Limitations

External signed CA

External signed CA is now supported. But the currently needed two step process is an issue for the processing in a simple playbook.

Work is planned to have a new method to handle CSR for external signed CAs in a separate step before starting the server installation.

Usage

How to use ansible-freeipa

GIT repo

The simplest method for now is to clone this repository on the controller from github directly and to start the deployment from the ansible-freeipa directory:

git clone https://github.com/freeipa/ansible-freeipa.git
cd ansible-freeipa

You can use the roles directly within the top directory of the git repo, but to be able to use the management modules in the plugins subdirectory, you have to either adapt ansible.cfg or create links for the roles, modules or directories.

You can either adapt ansible.cfg:

roles_path   = /my/dir/ansible-freeipa/roles
library      = /my/dir/ansible-freeipa/plugins/modules
module_utils = /my/dir/ansible-freeipa/plugins/module_utils

Or you can link the directories:

ansible-freeipa/roles to ~/.ansible/
ansible-freeipa/plugins/modules to ~/.ansible/plugins/
ansible-freeipa/plugins/module_utils to ~/.ansible/plugins/

RPM package

There are RPM packages available for Fedora 29+. These are installing the roles and modules into the global Ansible directories for roles, plugins/modules and plugins/module_utils in the /usr/share/ansible directory. Therefore is it possible to use the roles and modules without adapting the names like it is done in the example playbooks.

Ansible Galaxy

This command will get the whole collection from galaxy:

ansible-galaxy collection install freeipa.ansible_freeipa

Installing collections using the ansible-galaxy command is only supported with ansible 2.9+.

The mazer tool can be used for to install the collection for ansible 2.8:

mazer install freeipa.ansible_freeipa

Ansible galaxy does not support the use of dash ('-') in a name and is automatically replacing this with an underscore ('_'). Therefore the name is ansible_freeipa. The ansible_freeipa collection will be placed in the directory ~/.ansible/collections/ansible_collections/freeipa/ansible_freeipa where it will be automatically be found for this user.

The needed adaptions of collection prefixes for modules and module_utils will be done with ansible-freeipa release 0.1.6 for galaxy.

Ansible inventory file