Chapter 38. Managing hosts using Ansible playbooks

Ansible is an automation tool used to configure systems, deploy software, and perform rolling updates. Ansible includes support for Identity Management (IdM), and you can use Ansible modules to automate host management.

This chapter describes the following concepts and operations performed when managing hosts and host entries using Ansible playbooks:

38.1. Hosts in IdM

Identity Management (IdM) manages these identities:

  • Users
  • Services
  • Hosts

A host represents a machine. As an IdM identity, a host has an entry in the IdM LDAP, that is the 389 Directory Server instance of the IdM server.

The host entry in IdM LDAP is used to establish relationships between other hosts and even services within the domain. These relationships are part of delegating authorization and control to hosts within the domain. Any host can be used in host-based access control (HBAC) rules.

IdM domain establishes a commonality between machines, with common identity information, common policies, and shared services. Any machine that belongs to a domain functions as a client of the domain, which means it uses the services that the domain provides. IdM domain provides three main services specifically for machines:

  • DNS
  • Kerberos
  • Certificate management

Hosts in IdM are closely connected with the services running on them:

  • Service entries are associated with a host.
  • A host stores both the host and the service Kerberos principals.

38.2. Host enrollment

This section describes enrolling hosts as IdM clients and what happens during and after the enrollment. The section compares the enrollment of IdM hosts and IdM users. The section also outlines alternative types of authentication available to hosts.

Enrolling a host consists of:

  • Creating a host entry in IdM LDAP: possibly using the ipa host-add command in IdM CLI, or the equivalent IdM Web UI operation.
  • Configuring IdM services on the host, for example the System Security Services Daemon (SSSD), Kerberos, and certmonger, and joining the host to the IdM domain.

The two actions can be performed separately or together.

If performed separately, they allow for dividing the two tasks between two users with different levels of privilege. This is useful for bulk deployments.

The ipa-client-install command can perform the two actions together. The command creates a host entry in IdM LDAP if that entry does not exist yet, and configures both the Kerberos and SSSD services for the host. The command brings the host within the IdM domain and allows it to identify the IdM server it will connect with. If the host belongs to a DNS zone managed by IdM, ipa-client-install adds DNS records for the host too. The command must be run on the client.

38.2.1. User privileges required for host enrollment

The host enrollment operation requires authentication to prevent an unprivileged user from adding unwanted machines to the IdM domain. The privileges required depend on several factors, for example:

  • If a host entry is created separately from running ipa-client-install
  • If a one-time password (OTP) is used for enrollment
User privileges for optionally manually creating a host entry in IdM LDAP

The user privilege required for creating a host entry in IdM LDAP using the ipa host-add CLI command or the IdM Web UI is Host Administrators. The Host Administrators privilege can be obtained through the IT Specialist role.

User privileges for joining the client to the IdM domain

Hosts are configured as IdM clients during the execution of the ipa-client-install command. The level of credentials required for executing the ipa-client-install command depends on which of the following enrolling scenarios you find yourself in:

  • The host entry in IdM LDAP does not exist. For this scenario, you need a full administrator’s credentials or the Host Administrators role. A full administrator is a member of the admins group. The Host Administrators role provides privileges to add hosts and enroll hosts. For details about this scenario, see Installing a client using user credentials: interactive installation.
  • The host entry in IdM LDAP exists. For this scenario, you need a limited administrator’s credentials to execute ipa-client-install successfully. The limited administrator in this case has the Enrollment Administrator role, which provides the Host Enrollment privilege. For details, see Installing a client using user credentials: interactive installation.
  • The host entry in IdM LDAP exists, and an OTP has been generated for the host by a full or limited administrator. For this scenario, you can install an IdM client as an ordinary user if you run the ipa-client-install command with the --password option, supplying the correct OTP. For details, see Installing a client by using a one-time password: Interactive installation.

After enrollment, IdM hosts authenticate every new session to be able to access IdM resources. Machine authentication is required for the IdM server to trust the machine and to accept IdM connections from the client software installed on that machine. After authenticating the client, the IdM server can respond to its requests.

38.2.2. Enrollment and authentication of IdM hosts and users: comparison

There are many similarities between users and hosts in IdM. This section describes some of the similarities that can be observed during the enrollment stage as well as those that concern authentication during the deployment stage.

  • The enrollment stage (Table 38.1, “User and host enrollment”):

    • An administrator can create an LDAP entry for both a user and a host before the user or host actually join IdM: for the stage user, the command is ipa stageuser-add; for the host, the command is ipa host-add.
    • A file containing a key table or, abbreviated, keytab, a symmetric key resembling to some extent a user password, is created during the execution of the ipa-client-install command on the host, resulting in the host joining the IdM realm. Analogically, a user is asked to create a password when they activate their account, thus joining the IdM realm.
    • While the user password is the default authentication method for a user, the keytab is the default authentication method for a host. The keytab is stored in a file on the host.

    Table 38.1. User and host enrollment

    ActionUserHost

    Pre-enrollment

    $ ipa stageuser-add user_name [--password]

    $ ipa host-add host_name [--random]

    Activating the account

    $ ipa stageuser-activate user_name

    $ ipa-client install [--password] (must be run on the host itself)

  • The deployment stage (Table 38.2, “User and host session authentication”):

    • When a user starts a new session, the user authenticates using a password; similarly, every time it is switched on, the host authenticates by presenting its keytab file. The System Security Services Daemon (SSSD) manages this process in the background.
    • If the authentication is successful, the user or host obtains a Kerberos ticket granting ticket (TGT).
    • The TGT is then used to obtain specific tickets for specific services.

    Table 38.2. User and host session authentication

     UserHost

    Default means of authentication

    Password

    Keytabs

    Starting a session (ordinary user)

    $ kinit user_name

    [switch on the host]

    The result of successful authentication

    TGT to be used to obtain access to specific services

    TGT to be used to obtain access to specific services

TGTs and other Kerberos tickets are generated as part of the Kerberos services and policies defined by the server. The initial granting of a Kerberos ticket, the renewing of the Kerberos credentials, and even the destroying of the Kerberos session are all handled automatically by the IdM services.

38.2.3. Alternative authentication options for IdM hosts

Apart from keytabs, IdM supports two other types of machine authentication:

  • SSH keys. The SSH public key for the host is created and uploaded to the host entry. From there, the System Security Services Daemon (SSSD) uses IdM as an identity provider and can work in conjunction with OpenSSH and other services to reference the public keys located centrally in IdM.
  • Machine certificates. In this case, the machine uses an SSL certificate that is issued by the IdM server’s certificate authority and then stored in IdM’s Directory Server. The certificate is then sent to the machine to present when it authenticates to the server. On the client, certificates are managed by a service called certmonger.

38.3. Ensuring the presence of an IdM host entry with FQDN using Ansible playbooks

This section describes ensuring the presence of host entries in Identity Management (IdM) using Ansible playbooks. The host entries are only defined by their fully-qualified domain names (FQDNs).

Specifying the FQDN name of the host is enough if at least one of the following conditions applies:

  • The IdM server is not configured to manage DNS.
  • The host does not have a static IP address or the IP address is not known at the time the host is configured. Adding a host defined only by an FQDN essentially creates a placeholder entry in the IdM DNS service. For example, laptops may be preconfigured as IdM clients, but they do not have IP addresses at the time they are configured. When the DNS service dynamically updates its records, the host’s current IP address is detected and its DNS record is updated.
Note

Without Ansible, host entries are created in IdM using the ipa host-add command. The result of adding a host to IdM is the state of the host being present in IdM. Because of the Ansible reliance on idempotence, to add a host to IdM using Ansible, you must create a playbook in which you define the state of the host as present: state: present.

Prerequisites

  • You know the IdM administrator password.
  • The ansible-freeipa package is installed on the Ansible controller.

Procedure

  1. Create an inventory file, for example inventory.file, and define ipaserver in it:

    [ipaserver]
    server.idm.example.com
  2. Create an Ansible playbook file with the FQDN of the host whose presence in IdM you want to ensure. To simplify this step, you can copy and modify the example in the /usr/share/doc/ansible-freeipa/playbooks/host/add-host.yml file:

    ---
    - name: Host present
      hosts: ipaserver
      become: true
    
      tasks:
      - name: Host host01.idm.example.com present
        ipahost:
          ipaadmin_password: MySecret123
          name: host01.idm.example.com
          state: present
          force: yes
  3. Run the playbook:

    $ ansible-playbook -v -i path_to_inventory_directory/inventory.file path_to_playbooks_directory/ensure-host-is-present.yml
Note

The procedure results in a host entry in the IdM LDAP server being created but not in enrolling the host into the IdM Kerberos realm. For that, you must deploy the host as an IdM client. For details, see Installing an Identity Management client using an Ansible playbook.

Verification steps

  1. Log in to your IdM server as admin:

    $ ssh admin@server.idm.example.com
    Password:
  2. Enter the ipa host-show command and specify the name of the host:

    $ ipa host-show host01.idm.example.com
      Host name: host01.idm.example.com
      Principal name: host/host01.idm.example.com@IDM.EXAMPLE.COM
      Principal alias: host/host01.idm.example.com@IDM.EXAMPLE.COM
      Password: False
      Keytab: False
      Managed by: host01.idm.example.com

The output confirms that host01.idm.example.com exists in IdM.

38.4. Ensuring the presence of an IdM host entry with DNS information using Ansible playbooks

This section describes ensuring the presence of host entries in Identity Management (IdM) using Ansible playbooks. The host entries are defined by their fully-qualified domain names (FQDNs) and their IP addresses.

Note

Without Ansible, host entries are created in IdM using the ipa host-add command. The result of adding a host to IdM is the state of the host being present in IdM. Because of the Ansible reliance on idempotence, to add a host to IdM using Ansible, you must create a playbook in which you define the state of the host as present: state: present.

Prerequisites

  • You know the IdM administrator password.
  • The ansible-freeipa package is installed on the Ansible controller.

Procedure

  1. Create an inventory file, for example inventory.file, and define ipaserver in it:

    [ipaserver]
    server.idm.example.com
  2. Create an Ansible playbook file with the fully-qualified domain name (FQDN) of the host whose presence in IdM you want to ensure. In addition, if the IdM server is configured to manage DNS and you know the IP address of the host, specify a value for the ip_address parameter. The IP address is necessary for the host to exist in the DNS resource records. To simplify this step, you can copy and modify the example in the /usr/share/doc/ansible-freeipa/playbooks/host/host-present.yml file. You can also include other, additional information:

    ---
    - name: Host present
      hosts: ipaserver
      become: true
    
      tasks:
      - name: Ensure host01.idm.example.com is present
        ipahost:
          ipaadmin_password: MySecret123
          name: host01.idm.example.com
          description: Example host
          ip_address: 192.168.0.123
          locality: Lab
          ns_host_location: Lab
          ns_os_version: CentOS 7
          ns_hardware_platform: Lenovo T61
          mac_address:
          - "08:00:27:E3:B1:2D"
          - "52:54:00:BD:97:1E"
          state: present
  3. Run the playbook:

    $ ansible-playbook -v -i path_to_inventory_directory/inventory.file path_to_playbooks_directory/ensure-host-is-present.yml
Note

The procedure results in a host entry in the IdM LDAP server being created but not in enrolling the host into the IdM Kerberos realm. For that, you must deploy the host as an IdM client. For details, see Installing an Identity Management client using an Ansible playbook.

Verification steps

  1. Log in to your IdM server as admin:

    $ ssh admin@server.idm.example.com
    Password:
  2. Enter the ipa host-show command and specify the name of the host:

    $ ipa host-show host01.idm.example.com
      Host name: host01.idm.example.com
      Description: Example host
      Locality: Lab
      Location: Lab
      Platform: Lenovo T61
      Operating system: CentOS 7
      Principal name: host/host01.idm.example.com@IDM.EXAMPLE.COM
      Principal alias: host/host01.idm.example.com@IDM.EXAMPLE.COM
      MAC address: 08:00:27:E3:B1:2D, 52:54:00:BD:97:1E
      Password: False
      Keytab: False
      Managed by: host01.idm.example.com

The output confirms host01.idm.example.com exists in IdM.

38.5. Ensuring the presence of multiple IdM host entries with random passwords using Ansible playbooks

The ipahost module allows the system administrator to ensure the presence or absence of multiple host entries in IdM using just one Ansible task. This section describes how to ensure the presence of multiple host entries that are only defined by their fully-qualified domain names (FQDNs). Running the Ansible playbook generates random passwords for the hosts.

Note

Without Ansible, host entries are created in IdM using the ipa host-add command. The result of adding a host to IdM is the state of the host being present in IdM. Because of the Ansible reliance on idempotence, to add a host to IdM using Ansible, you must create a playbook in which you define the state of the host as present: state: present.

Prerequisites

  • You know the IdM administrator password.
  • The ansible-freeipa package is installed on the Ansible controller.

Procedure

  1. Create an inventory file, for example inventory.file, and define ipaserver in it:

    [ipaserver]
    server.idm.example.com
  2. Create an Ansible playbook file with the fully-qualified domain name (FQDN) of the hosts whose presence in IdM you want to ensure. To make the Ansible playbook generate a random password for each host even when the host already exists in IdM and update_password is limited to on_create, add the random: yes and force: yes options. To simplify this step, you can copy and modify the example from the /usr/share/doc/ansible-freeipa/README-host.md Markdown file:

    ---
    - name: Ensure hosts with random password
      hosts: ipaserver
      become: true
    
      tasks:
      - name: Hosts host01.idm.example.com and host02.idm.example.com present with random passwords
        ipahost:
          ipaadmin_password: MySecret123
          hosts:
          - name: host01.idm.example.com
            random: yes
            force: yes
          - name: host02.idm.example.com
            random: yes
            force: yes
        register: ipahost
  3. Run the playbook:

    $ ansible-playbook -v -i path_to_inventory_directory/inventory.file path_to_playbooks_directory/ensure-hosts-are-present.yml
    [...]
    TASK [Hosts host01.idm.example.com and host02.idm.example.com present with random passwords]
    changed: [r8server.idm.example.com] => {"changed": true, "host": {"host01.idm.example.com": {"randompassword": "0HoIRvjUdH0Ycbf6uYdWTxH"}, "host02.idm.example.com": {"randompassword": "5VdLgrf3wvojmACdHC3uA3s"}}}

Verification steps

  1. Log in to your IdM server as admin:

    $ ssh admin@server.idm.example.com
    Password:
  2. Enter the ipa host-show command and specify the name of one of the hosts:

    $ ipa host-show host01.idm.example.com
      Host name: host01.idm.example.com
      Password: True
      Keytab: False
      Managed by: host01.idm.example.com

The output confirms host01.idm.example.com exists in IdM with a random password.

38.6. Ensuring the presence of an IdM host entry with multiple IP addresses using Ansible playbooks

This section describes how to ensure the presence of a host entry in Identity Management (IdM) using Ansible playbooks. The host entry is defined by its fully-qualified domain name (FQDN) and its multiple IP addresses.

Note

In contrast to the ipa host utility, the Ansible ipahost module can ensure the presence or absence of several IPv4 and IPv6 addresses for a host. The ipa host-mod command cannot handle IP addresses.

Prerequisites

  • You know the IdM administrator password.
  • The ansible-freeipa package is installed on the Ansible controller.

Procedure

  1. Create an inventory file, for example inventory.file, and define ipaserver in it:

    [ipaserver]
    server.idm.example.com
  2. Create an Ansible playbook file. Specify, as the name of the ipahost variable, the fully-qualified domain name (FQDN) of the host whose presence in IdM you want to ensure. Specify each of the multiple IPv4 and IPv6 ip_address values on a separate line by using the - ip_address syntax. To simplify this step, you can copy and modify the example in the /usr/share/doc/ansible-freeipa/playbooks/host/host-member-ipaddresses-present.yml file. You can also include additional information:

    ---
    - name: Host member IP addresses present
      hosts: ipaserver
      become: true
    
      tasks:
      - name: Ensure host101.example.com IP addresses present
        ipahost:
          ipaadmin_password: MySecret123
          name: host01.idm.example.com
          ip_address:
          - 192.168.0.123
          - fe80::20c:29ff:fe02:a1b3
          - 192.168.0.124
          - fe80::20c:29ff:fe02:a1b4
          force: yes
  3. Run the playbook:

    $ ansible-playbook -v -i path_to_inventory_directory/inventory.file path_to_playbooks_directory/ensure-host-with-multiple-IP-addreses-is-present.yml
Note

The procedure creates a host entry in the IdM LDAP server but does not enroll the host into the IdM Kerberos realm. For that, you must deploy the host as an IdM client. For details, see Installing an Identity Management client using an Ansible playbook.

Verification steps

  1. Log in to your IdM server as admin:

    $ ssh admin@server.idm.example.com
    Password:
  2. Enter the ipa host-show command and specify the name of the host:

    $ ipa host-show host01.idm.example.com
      Principal name: host/host01.idm.example.com@IDM.EXAMPLE.COM
      Principal alias: host/host01.idm.example.com@IDM.EXAMPLE.COM
      Password: False
      Keytab: False
      Managed by: host01.idm.example.com

    The output confirms that host01.idm.example.com exists in IdM.

  3. To verify that the multiple IP addresses of the host exist in the IdM DNS records, enter the ipa dnsrecord-show command and specify the following information:

    • The name of the IdM domain
    • The name of the host

      $ ipa dnsrecord-show idm.example.com host01
      [...]
        Record name: host01
        A record: 192.168.0.123, 192.168.0.124
        AAAA record: fe80::20c:29ff:fe02:a1b3, fe80::20c:29ff:fe02:a1b4

    The output confirms that all the IPv4 and IPv6 addresses specified in the playbook are correctly associated with the host01.idm.example.com host entry.

38.7. Ensuring the absence of an IdM host entry using Ansible playbooks

This section describes how to ensure the absence of host entries in Identity Management (IdM) using Ansible playbooks.

Prerequisites

  • IdM administrator credentials

Procedure

  1. Create an inventory file, for example inventory.file, and define ipaserver in it:

    [ipaserver]
    server.idm.example.com
  2. Create an Ansible playbook file with the fully-qualified domain name (FQDN) of the host whose absence from IdM you want to ensure. If your IdM domain has integrated DNS, use the updatedns: yes option to remove the associated records of any kind for the host from the DNS.

    To simplify this step, you can copy and modify the example in the /usr/share/doc/ansible-freeipa/playbooks/host/delete-host.yml file:

    ---
    - name: Host absent
      hosts: ipaserver
      become: true
    
      tasks:
      - name: Host host01.idm.example.com absent
        ipahost:
          ipaadmin_password: MySecret123
          name: host01.idm.example.com
          updatedns: yes
          state: absent
  3. Run the playbook:

    $ ansible-playbook -v -i path_to_inventory_directory/inventory.file path_to_playbooks_directory/ensure-host-absent.yml
Note

The procedure results in:

  • The host not being present in the IdM Kerberos realm.
  • The host entry not being present in the IdM LDAP server.

To remove the specific IdM configuration of system services, such as System Security Services Daemon (SSSD), from the client host itself, you must run the ipa-client-install --uninstall command on the client. For details, see Uninstalling an IdM client.

Verification steps

  1. Log into ipaserver as admin:

    $ ssh admin@server.idm.example.com
    Password:
    [admin@server /]$
  2. Display information about host01.idm.example.com:

    $ ipa host-show host01.idm.example.com
    ipa: ERROR: host01.idm.example.com: host not found

The output confirms that the host does not exist in IdM.

Additional resources

  • You can see the definitions of the ipahost variables as well as sample Ansible playbooks for ensuring the presence, absence, and disablement of hosts in the /usr/share/doc/ansible-freeipa/README-host.md Markdown file.
  • Additional playbooks are in the /usr/share/doc/ansible-freeipa/playbooks/host directory.