# ansible-freeipa installs a FreeIPA domain and manages its objects as Ansible modules > The FreeIPA Ansible collection provides roles that install and uninstall FreeIPA servers, replicas and clients, plus a long list of modules for users, groups, hosts, DNS, certificates, sudo rules and trust management. It suits an infrastructure team that wants the identity domain to be declarative, and the inventory format and password handling in the docs are the first things to read. **freeipa/ansible-freeipa** — Ansible roles and modules for FreeIPA - Repository: https://github.com/freeipa/ansible-freeipa - Stars: 573 · Forks: 245 - Language: Python - License: GPL-3.0 - Published: 2026-10-22 · Updated: 2026-10-22 · Language: en - Canonical page: https://hysenlabs.com/projects/freeipa-ansible-freeipa ## Roles for the domain, modules for everything inside it The FreeIPA Ansible collection contains Ansible roles and playbooks to install and uninstall FreeIPA servers, replicas and clients, and also modules for group, host, topology and user management. That split is the shape of the whole project. The roles deal with the lifecycle of the domain itself, and the modules deal with the objects that live in it once it exists. In practice most of the module list is the FreeIPA data model expressed as Ansible tasks. The feature list starts with deployment: server, replica and client deployment, and cluster deployments with server, replicas and clients in one playbook. Then there are operational features, one-time-password support for client installation, a repair mode for clients, backup and restore also to and from the controller, and smartcard setup for servers and clients. The module list is long, and it is essentially an index of the FreeIPA API. Automembership rule, automount key, automount location and automount map management, certificate management, config management, delegation management, then a run of DNS modules for config, forwarders, records and zones, then group management, hbacrule, hbacsvc and hbacsvcgroup, host and hostgroup, the two idoverride modules, idp, idrange, idview, location, netgroup, passkeyconfig, permission, privilege, pwpolicy, role, self service, server, service and the two service delegation modules, sudocmd, sudocmdgroup and sudorule, sysaccount, topology, trust, user and vault management. There is also an inventory plugin, freeipa, listed separately from the modules, and a dedicated README for it. So there are two ways to consume this: the roles to build a domain, and the modules to manage one that already exists. ## Getting the collection onto the controller The usage section names three methods, and the choice is mostly about how you want the roles and plugins found by Ansible. 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. ```bash git clone https://github.com/freeipa/ansible-freeipa.git cd ansible-freeipa ``` From there 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. Adapting ansible.cfg means pointing four paths at the clone. ``` roles_path = /my/dir/ansible-freeipa/roles library = /my/dir/ansible-freeipa/plugins/modules module_utils = /my/dir/ansible-freeipa/plugins/module_utils inventory_plugins = /my/dir/ansible-freeipa/plugins/inventory ``` Or you can link the directories instead. ``` ansible-freeipa/roles to ~/.ansible/ ansible-freeipa/plugins/modules to ~/.ansible/plugins/ ansible-freeipa/plugins/module_utils to ~/.ansible/plugins/ ``` The third method is the one most teams will end up with, and it comes with a naming quirk worth knowing. The command will get the whole collection from galaxy. ```bash ansible-galaxy collection 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`, and the collection is placed under `~/.ansible/collections/ansible_collections/freeipa/ansible_freeipa` where it will be automatically found for this user. There is also an RPM route: packages are available for Fedora, installing the roles and modules into the global Ansible directories for `roles`, `plugins/modules` and `plugins/module_utils` in `/usr/share/ansible`, so the roles and modules can be used without adapting the names as in the example playbooks. ## The inventory file holds the domain definition and the passwords The inventory is where the deployment is actually described, and the documentation is clear that it is the most important part of the file: the definition of the nodes, settings and the management modules. The master server is defined within the `[ipaserver]` group. ```yaml [ipaserver] ipaserver.test.local ``` Then there are variables that need to be set like domain, realm, admin password and dm password, and those go in the `[ipaserver:vars]` section. ```yaml [ipaserver:vars] ipaadmin_password=ADMPassword1 ipadm_password=DMPassword1 ipaserver_domain=test.local ipaserver_realm=TEST.LOCAL ``` The admin principal is `admin` by default, and you set `ipaadmin_principal` if you need to change it. The same group carries the switches for the optional parts of a deployment, and this is where the firewalld detail bites. ```yaml [ipaserver:vars] ipaserver_setup_dns=yes ipaserver_auto_forwarders=yes ``` To skip package installation or the firewall configuration. ```yaml [ipaserver:vars] ipaserver_install_packages=no ipaserver_setup_firewalld=no ``` The installation of packages and also the configuration of the firewall are by default enabled, and the note is that it is not enough to mask the systemd firewalld service to skip the firewalld configuration: you need to set the variable to `no`. Masking the unit and setting the variable are different operations, and a playbook that masks firewalld and leaves the variable at its default will still configure the firewall. The security point is the one the documentation underlines. Please remember to use Ansible Vault for passwords, and the examples here are not using vault for better readability. The examples in the README do exactly that, with the admin and directory manager passwords in plain text. ## Replicas, clusters and the supported version matrix Replicas are defined in their own group, the `[ipareplicas]` group. ```yaml [ipareplicas] ipareplica1.test.local ipareplica2.test.local ``` The documentation notes that if the master server is already deployed, there are DNS txt records that let the replica find it, which is the detail that matters: replication in FreeIPA depends on the DNS records that let a replica find the existing domain, so the inventory and the DNS zone have to agree. The support matrix is spelled out, and it has edges. 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, and the replica role is currently only working with versions 4.6 and up. The supported distributions are RHEL/CentOS 7.4+, Fedora 40+, Ubuntu, and Debian 10+ with a parenthetical that says ipaclient only, no server or replica. So a Debian shop can enrol clients but cannot run the domain from this collection. The requirements are Ansible version 2.14+ on the controller, a supported FreeIPA version on the node, and a supported distribution needed for package installation only. The README also states a general precondition: 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. That last point is not obvious from the name. These are not agentless roles in the usual sense; the target has to be reachable and able to install packages. ## The known limitation is the external signed CA There is one limitation section in the documentation, and it is worth reading before you plan a deployment rather than after it fails. 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. In practice that means a deployment that uses your organisation's existing certificate authority, rather than the self signed one FreeIPA generates for itself, cannot be expressed as a single playbook run. The certificate signing request has to be handled in a step of its own, and the server installation happens after. The documentation says as much and points at a planned change. The second operational note is the smartcard setup, which is listed as a feature for servers and clients and is a separate concern from the CA question, since a smartcard setup involves hardware and per device configuration that a first playbook will not fully cover. For a team evaluating this, the CA question is the one to answer first. If your environment already has a PKI and policy forbids the self signed route, the two step process is a fact of life with this collection, and you should design the playbook around it rather than discover it halfway through an install. ## The repository is mostly documentation, one file per module The tree tells you how this project is maintained, and the answer is: with a README per module. There is a README for each module area, named after it. README-automember.md, README-automountkey.md, README-automountlocation.md, README-automountmap.md, README-cert.md, README-config.md, README-delegation.md, README-dnsconfig.md, README-dnsforwardzone.md, README-dnsrecord.md, README-dnszone.md, README-group.md, README-hbacrule.md, README-hbacsvc.md, README-hbacsvcgroup.md, README-host.md, README-hostgroup.md, README-idoverridegroup.md, README-idoverrideuser.md, README-idp.md, README-idrange.md, README-idview.md, README-inventory-plugin-freeipa.md, README-location.md, README-netgroup.md, README-passkeyconfig.md, README-permission.md, README-privilege.md, README-pwpolicy.md, README-role.md, README-selfservice.md, README-server.md, README-service.md, README-servicedelegationrule.md, README-servicedelegationtarget.md, README-sudocmd.md, README-sudocmdgroup.md, README-sudorule.md, README-sysaccount.md, README-topology.md, README-trust.md, README-user.md and README-vault.md. That is the documentation strategy in one line: each module has a page explaining its parameters, and the collection's main README is the entry point for deployment and inventory. The rest of the tree is the usual Ansible collection layout. There are roles/, plugins/ for the modules and the inventory plugin, playbooks/, inventory/ for example inventories, meta/, a top-level galaxy.yml, and infra/ for the CI infrastructure. The tooling is visible too: an.ansible-lint configuration, a.yamllint configuration, a.pre-commit-config.yaml, a pytest.ini, and a requirements-dev.txt. There is also a setup.py using pbr, which is the older Python packaging path that predates pyproject.toml for this project, and a COPYING file for the licence. The release cadence is steady, with v1.17.0 on 2026-07-23, v1.16.0 on 2026-01-12 and v1.15.1 on 2025-07-31, and the last push on 2026-10-19. The project is licensed GPL-3.0, with the licence terms in the COPYING file. ## Conclusion ansible-freeipa fits an infrastructure team that already runs FreeIPA and wants the domain's own objects, users, groups, DNS and certificate policy to live in version control as Ansible tasks rather than in a set of imperative ipa commands. It does not fit a team that is choosing an identity provider, since the roles deploy FreeIPA itself rather than integrating with one. Before running it, read the inventory section and put the admin and directory manager passwords behind Ansible Vault, because the examples ship them in plain text for readability, and check the supported distribution and FreeIPA version matrix, since Debian is listed as ipaclient only with no server or replica. ## FAQ ### How do I install the FreeIPA Ansible collection? You can clone the repository and adapt ansible.cfg or link the role and plugin directories, install RPM packages for Fedora, or run ansible-galaxy collection install freeipa.ansible_freeipa, which is spelled with an underscore because Galaxy does not support dashes in names. ### Which FreeIPA versions and distributions does ansible-freeipa support? FreeIPA 4.6 and up are supported by all roles, the client role supports 4.4 and up, the server role 4.5 and up, and the replica role only 4.6 and up. The supported distributions are RHEL/CentOS 7.4+, Fedora 40+, Ubuntu, and Debian 10+ for ipaclient only, with no server or replica. ### How should I handle the FreeIPA admin passwords in the inventory? The documentation asks you to use Ansible Vault for passwords and notes that the examples do not use vault for better readability, showing ipaadmin_password and ipadm_password in plain text under the ipaserver:vars group. ### What is the known limitation of ansible-freeipa? External signed CA is supported, but the currently needed two step process is an issue for processing in a simple playbook, and work is planned to handle CSR for external signed CAs in a separate step before the server installation. ## Sources - [freeipa/ansible-freeipa on GitHub](https://github.com/freeipa/ansible-freeipa) - [Issues](https://github.com/freeipa/ansible-freeipa/issues) - [License: GPL-3.0](https://github.com/freeipa/ansible-freeipa/blob/master/LICENSE) - [README](https://github.com/freeipa/ansible-freeipa/blob/master/README.md) - [Releases](https://github.com/freeipa/ansible-freeipa/releases) --- Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/freeipa-ansible-freeipa