CLIENT.md

ipaclient role

Description

This role allows to join hosts as clients to an IPA domain. This can be done in differnt ways using auto-discovery of the servers, domain and other settings or by specifying them.

Usage

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

Variables

ipaclients

The mandatory ipaclients 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.

ipaclient_domain

The optional ipaclient_domain variable 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 ipaclient_domain is not set, then it will be generated from the domain part of the first entry from the ipaservers FQDN group if the group is defined and contains at least one entry. If ipaservers is not defined, then the domain will be tried to gather using DNS autodiscovery. ipaclient_domain needs to be set if the primary DNS domain is different from domain part of the server FQDN.

ipaclient_realm

The optional ipaclient_realm 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 ipaclient_realm is not set, then it will be generated from ipaclient_domain if this is set. If both are not set, then this

ipaclient_keytab

The optional ipaclient_keytab contains the path of a backup host keytab from a previous enrollment.

ipaclient_force_join

The ipaclient_force_join bool value defines if an already enrolled host can join again. ipaclient_force_join defaults to no.

ipaclient_use_otp

The ipaclient_use_otp 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 diabled and the containing keytab gets removed.

ipaclient_allow_repair

The ipaclient_allow_repair 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.

ipaclient_kinit_attempts

The optional ipaclient_kinit_attempts defines the number of tries to repeat the request for a failed host Kerberos ticket. ipaclient_kinit_attempts defaults to 3.

ipaclient_no_ntp

The ipaclient_no_ntp bool value defines if NTP will not be configured and enabled. ipaclient_no_ntp defaults to no.

ipaclient_mkhomedir

The ipaclient_mkhomedir bool value defines if PAM will be configured to create a users home directory if it does not exist. ipaclient_mkhomedir defaults to no.

Server Variables

ipaservers

The optional ipaservers 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.

ipaadmin_keytab

The ipaadmin_keytab variable enables the use of an admin keytab as an alternativce 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.

ipaadmin_principal

The optional ipaadmin_principal 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".

ipaadmin_password

The ipaadmin_password variable contains the Kerberos password of the Kerberos admin principal. If ipaadmin_keytab is used, then ipaadmin_password does not need to be set.

Topology Variables

These variables can be used to define or change how clients are arranged within a cluster for example.

ipaclient_no_dns_lookup

The ipaclient_no_dns_lookup 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 defauults to no.

ipaclient_servers

The optional ipaclient_servers varaible 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.

Requirements

freeipa-client v4.4 or later

Authors

Florence Blanc-Renaud

Thomas Woerner