This Ansible role allows to join hosts as clients to an IPA domain. This can be done in different ways using auto-discovery of the servers, domain and other settings or by specifying them.
Note: The ansible playbooks and role 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.
FreeIPA versions 4.5 and up are supported by the client role. There is also limited support for version 4.4.
Controller Ansible version: 2.8+ /usr/bin/kinit is required on the controller if a one time password (OTP) is used * python3-gssapi is required on the controller if a one time password (OTP) is used with keytab
Node Supported FreeIPA version (see above) Supported distribution (needed for package installation only, see above)
Example inventory file with fixed principal using auto-discovery with DNS records:
[ipaclients] ipaclient1.example.com ipaclient2.example.com [ipaclients:vars] ipaadmin_principal=admin
Example playbook to setup the IPA client(s) using principal from inventory file and password from an Ansible Vault file:
- name: Playbook to configure IPA clients with username/password hosts: ipaclients become: true vars_files: - playbook_sensitive_data.yml roles: - role: ipaclient state: present
Example playbook to unconfigure the IPA client(s) using principal and password from inventory file:
- name: Playbook to unconfigure IPA clients hosts: ipaclients become: true roles: - role: ipaclient state: absent
Example inventory file with fixed servers, principal, password and domain:
[ipaclients] ipaclient1.example.com ipaclient2.example.com [ipaservers] ipaserver.example.com [ipaclients:vars] ipaclient_domain=example.com ipaadmin_principal=admin ipaadmin_password=MySecretPassword123
Example playbook to setup the IPA client(s) using principal and password from inventory file:
- name: Playbook to configure IPA clients with username/password hosts: ipaclients become: true roles: - role: ipaclient state: present
The playbooks needed to deploy or undeploy a client are part of the repository in the playbooks folder. There are also playbooks to deploy and undeploy clusters.
install-client.yml uninstall-client.yml
Please remember to link or copy the playbooks to the base directory of ansible-freeipa if you want to use the roles within the source archive.
ansible-playbook -v -i inventory/hosts install-client.yml
This will deploy the clients defined in the inventory file.
| Variable | Description | Required |
|---|---|---|
ipaclients |
This group is a list of the names of the IPA clients in FQDN form. All these clients will be installed or configured using the playbook. | yes |
ipaclient_domain |
This string value sets the DNS domain that will be used for client installation. Usually the DNS domain is a lower-cased name of the Kerberos realm. If the role is for example used in a cluster inventory and ipaserver_domain is set, then it will be used. |
no |
ipaclient_realm |
This string value sets the Kerberos realm that will be used for client installation. Usually the Kerberos realm is an upper-cased name of the DNS domain. If the role is for example used in a cluster inventory and ipaserver_realm is set, then it will be used. If ipaclient_realm is not set, then it will be generated from ipaclient_domain if this is set. |
no |
ipaclient_mkhomedir |
This bool value defines if PAM will be configured to create a users home directory if it does not exist. ipaclient_mkhomedir defaults to no. |
no |
ipaclient_force_join |
This bool value defines if an already enrolled host can join again. ipaclient_force_join defaults to no. |
no |
ipaclient_kinit_attempts |
The int value defines the number of tries to repeat the request for a failed host Kerberos ticket. ipaclient_kinit_attempts defaults to 5. |
no |
ipaclient_ntp_servers |
The list defines the NTP servers to be used. | no |
ipaclient_ntp_pool |
The string value defines the ntp server pool to be used. | no |
ipaclient_no_ntp |
The bool value defines if NTP will not be configured and enabled. ipaclient_no_ntp defaults to no. |
no |
ipaclient_ssh_trust_dns |
The bool value defines if OpenSSH client will be configured to trust DNS SSHFP records. ipaclient_ssh_trust_dns defaults to no. |
no |
ipaclient_no_ssh |
The bool value defines if OpenSSH client will be configured. ipaclient_no_ssh defaults to no. |
no |
ipaclient_no_sshd |
The bool value defines if OpenSSH server will be configured. ipaclient_no_sshd defaults to no. |
no |
ipaclient_no_sudo |
The bool value defines if SSSD will be configured as a data source for sudo. ipaclient_no_sudo defaults to no. |
no |
ipaclient_no_dns_sshfp |
The bool value defines if DNS SSHFP records will not be created automatically. ipaclient_no_dns_sshfp defaults to no. |
no |
ipaclient_force |
The bool value defines if settings will be forced even in the error case. ipaclient_force defaults to no. |
no |
ipaclient_force_ntpd |
The bool value defines if ntpd usage will be forced. This is not supported anymore and leads to a warning. ipaclient_force_ntpd defaults to no. |
no |
ipaclient_nisdomain |
This string value defines the NIS domain name. | no |
ipaclient_no_nisdomain |
The bool value defines if the NIS domain name will not be configured. ipaclient_no_nisdomain defaults to no. |
no |
ipaclient_configure_firefox |
The bool value defines if Firefox will be configured to use IPA domain credentials. ipaclient_configure_firefox defaults to no. |
no |
ipaclient_firefox_dir |
The string value defines the Firefox installation directory. For example: '/usr/lib/firefox'. | no |
ipaclient_all_ip_addresses |
The bool value defines if DNS A/AAAA records for each IP address on the client will be created. ipaclient_all_ip_addresses defaults to no. |
no |
ipasssd_fixed_primary |
The bool value defines if SSSD will be configured to use a fixed server as the primary IPA server. ipasssd_fixed_primary defaults to no. |
no |
ipasssd_permit |
The bool value defines if SSSD will be configured to permit all access. Otherwise the machine will be controlled by the Host-based Access Controls (HBAC) on the IPA server. ipasssd_permit defaults to no. |
no |
ipasssd_enable_dns_updates |
The bool value tells SSSD to automatically update DNS with the IP address of this client. ipasssd_enable_dns_updates defaults to no. |
no |
ipasssd_no_krb5_offline_passwords |
The bool value defines if SSSD will be configured not to store user password when the server is offline . ipasssd_no_krb5_offline_passwords defaults to no. |
no |
ipasssd_preserve_sssd |
The bool value defines if the old SSSD configuration will be preserved if it is not possible to merge it with a new one. ipasssd_preserve_sssd defaults to no. |
no |
ipaclient_request_cert |
The bool value defines if the certificate for the machine wil be requested. The certificate will be stored in /etc/ipa/nssdb under the nickname "Local IPA host". . ipaclient_request_cert defaults to no. The option is deprecated and will be removed in a future release. |
no |
ipaclient_keytab |
The string value contains the path on the node of a backup host keytab from a previous enrollment. | no |
| Variable | Description | Required |
|---|---|---|
ipaservers |
This group is a list of the IPA server full qualified host names. In a topology with a chain of servers and replicas, it is important to use the right server or replica as the server for the client. If there is a need to overwrite the setting for a client in the ipaclients group, please use the list ipaclient_servers explained below. If no ipaservers group is defined than the installation preparation step will try to use DNS autodiscovery to identify the the IPA server using DNS txt records. |
mostly |
ipaadmin_keytab |
The string variable enables the use of an admin keytab as an alternative authentication method. The variable needs to contain the local path to the keytab file. If ipaadmin_keytab is used, then ipaadmin_password does not need to be set. If ipaadmin_keytab is used with ipaclient_use_otp: yes then the keytab needs to be available on the controller, else on the client node. The use of full path names is recommended. |
no |
ipaadmin_principal |
The string variable only needs to be set if the name of the Kerberos admin principal is not "admin". If ipaadmin_principal is not set it will be set internally to "admin". |
no |
ipaadmin_password |
The string variable contains the Kerberos password of the Kerberos admin principal. If ipaadmin_keytab is used, then ipaadmin_password does not need to be set. |
mostly |
These variables can be used to define or change how clients are arranged within a cluster for example.
| Variable | Description | Required |
|---|---|---|
ipaclient_no_dns_lookup |
The bool value defines if the ipaservers group will be used as servers for the clients automatically. If enabled this deactivates DNS lookup in Kerberos in client installations. ipaclient_no_dns_lookup defaults to no. |
no |
ipaclient_servers |
The optional list can be used to manually override list of servers on a per client basis. The list of servers is normally taken from from ipaservers group. |
no |
| Variable | Description | Required |
|---|---|---|
ipaclient_use_otp |
The bool value defines if a one-time password will be generated to join a new or existing host. ipaclient_use_otp defaults to no. The enforcement on an existing host is not done if there is a working krb5.keytab on the host. If the generation of an otp is enforced for an existing host entry, then the host gets disabled and the containing keytab gets removed. |
no |
ipaclient_otp |
The string value sets an already generated one-time password for the host. The role will use it and not try to generate a new one. Do not enable ipaclient_use_otp additionally. |
no |
ipaclient_allow_repair |
The bool value defines if an already joined or partly set-up client can be repaired. ipaclient_allow_repair defaults to no. Contrary to ipaclient_force_join=yes the host entry will not be changed on the server. |
no |
ipaclient_install_packages |
The bool value defines if the needed packages are installed on the node. ipaclient_install_packages defaults to yes. |
no |
ipaclient_on_master |
The bool value is only used in the server and replica installation process to install the client part. It should not be set otherwise. ipaclient_on_master defaults to no. |
no |
Florence Blanc-Renaud
Thomas Woerner