Host module

Description

The host module allows to ensure presence, absence and disablement of hosts.

The host module is as compatible as possible to the Ansible upstream ipa_host module, but additionally offers to disable hosts.

Features

Host management

Supported FreeIPA Versions

FreeIPA versions 4.4.0 and up are supported by the ipahost module.

Requirements

Controller

Ansible version: 2.8+

Node

Supported FreeIPA version (see above)

Usage

Example inventory file

[ipaserver]
ipaserver.test.local

Example playbook to ensure host presence:

---
- name: Playbook to handle hosts
  hosts: ipaserver
  become: true

  tasks:
  # Ensure host is present
  - ipahost:
      ipaadmin_password: SomeADMINpassword
      name: host01.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

Compared to ipa host-add command no IP address conflict check is done as the ipahost module supports to have several IPv4 and IPv6 addresses for a host.

Example playbook to ensure host presence with several IP addresses:

---
- name: Playbook to handle hosts
  hosts: ipaserver
  become: true

  tasks:
  # Ensure host is present
  - ipahost:
      ipaadmin_password: SomeADMINpassword
      name: host01.example.com
      description: Example host
      ip_address:
      - 192.168.0.123
      - 192.168.0.124
      - fe80::20c:29ff:fe02:a1b3
      - fe80::20c:29ff:fe02:a1b4
      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

Example playbook to ensure IP addresses are present for a host:

---
- name: Playbook to handle hosts
  hosts: ipaserver
  become: true

  tasks:
  # Ensure host is present
  - ipahost:
      ipaadmin_password: SomeADMINpassword
      name: host01.example.com
      ip_address:
      - 192.168.0.124
      - fe80::20c:29ff:fe02:a1b4
      action: member
      state: present

Example playbook to ensure IP addresses are absent for a host:

---
- name: Playbook to handle hosts
  hosts: ipaserver
  become: true

  tasks:
  # Ensure host is present
  - ipahost:
      ipaadmin_password: SomeADMINpassword
      name: host01.example.com
      ip_address:
      - 192.168.0.124
      - fe80::20c:29ff:fe02:a1b4
      action: member
      state: absent

Example playbook to ensure host presence without DNS:

---
- name: Playbook to handle hosts
  hosts: ipaserver
  become: true

  tasks:
  # Ensure host is present without DNS
  - ipahost:
      ipaadmin_password: SomeADMINpassword
      name: host02.example.com
      description: Example host
      force: yes

Example playbook to ensure host presence with a random password:

---
- name: Ensure host with random password
  hosts: ipaserver
  become: true

  tasks:
  - name: Host host01.example.com present with random password
    ipahost:
      ipaadmin_password: SomeADMINpassword
      name: host01.example.com
      random: yes
      force: yes
      update_password: on_create
    register: ipahost

  - name: Print generated random password
    debug:
      var: ipahost.host.randompassword

Please remember that a new random password will be generated for an existing but not enrolled host if update_password is not limited to on_create. For an already enrolled host the task will fail with update_password default setting always.

Example playbook to ensure presence of several hosts with a random password:

---
- name: Ensure hosts with random password
  hosts: ipaserver
  become: true

  tasks:
  - name: Hosts host01.example.com and host01.example.com present with random passwords
    ipahost:
      ipaadmin_password: SomeADMINpassword
      hosts:
      - name: host01.example.com
        random: yes
        force: yes
        update_password: on_create
      - name: host02.example.com
        random: yes
        force: yes
        update_password: on_create
    register: ipahost

  - name: Print generated random password for host01.example.com
    debug:
      var: ipahost.host["host01.example.com"].randompassword

  - name: Print generated random password for host02.example.com
    debug:
      var: ipahost.host["host02.example.com"].randompassword

Please remember that a new random password will be generated for an existing but not enrolled host if update_password is not limited to on_create. For an already enrolled host the task will fail with update_password default setting always.

Example playbook to ensure presence of host member principal:

---
- name: Host present with principal
  hosts: ipaserver
  become: true

  tasks:
  - name: Host host01.example.com present with principals host/testhost01.example.com and host/myhost01.example.com
    ipahost:
      ipaadmin_password: SomeADMINpassword
      name: host01.example.com
      principal:
      - host/testhost01.example.com
      - host/myhost01.example.com
      action: member

Example playbook to ensure presence of host member certificate:

- name: Host present with certificate
  hosts: ipaserver
  become: true

  tasks:
  - name: Host host01.example.com present with certificate
    ipahost:
      ipaadmin_password: SomeADMINpassword
      name: host01.example.com
      certificate:
      - MIIC/zCCAeegAwIBAg...
      action: member

Example playbook to ensure presence of member managedby_host for serveral hosts:

---
- name: Host present with managedby_host
  hosts: ipaserver
  become: true

  tasks:
    ipahost:
      ipaadmin_password: SomeADMINpassword
      hosts:
      - name: host01.example.com
        managedby_host: server.example.com
      - name: host02.example.com
        managedby_host: server.example.com
      action: member

Example playbook to disable a host:

---
- name: Playbook to handle hosts
  hosts: ipaserver
  become: true

  tasks:
  # Ensure host is disabled
  - ipahost:
      ipaadmin_password: SomeADMINpassword
      name: host01.example.com
      update_dns: yes
      state: disabled

update_dns controls if the DNS entries will be updated in this case. For state present it is controlling the update of the DNS SSHFP records, but not the the other DNS records.

Example playbook to ensure a host is absent:

---
- name: Playbook to handle hosts
  hosts: ipaserver
  become: true

  tasks:
  # Ensure host is absent
  - ipahost:
      ipaadmin_password: password1
      name: host01.example.com
      state: absent

Variables

Variable	Description	Required
`ipaadmin_principal`	The admin principal is a string and defaults to `admin`	no
`ipaadmin_password`	The admin password is a string and is required if there is no admin ticket available on the node	no
`ipaapi_context`	The context in which the module will execute. Executing in a server context is preferred. If not provided context will be determined by the execution environment. Valid values are `server` and `client`.	no
`ipaapi_ldap_cache`	Use LDAP cache for IPA connection. The bool setting defaults to yes. (bool)	no
`name` \| `fqdn`	The list of host name strings. `name` with host variables or `hosts` containing host variables need to be used.	no
Host variables	Only used with `name` variable in the first level.	no
`hosts`	The list of host dicts. Each `hosts` dict entry can contain host variables. There is one required option in the `hosts` dict:	no
	`name` \| `fqdn` - The user name string of the entry.	yes
	Host variables	no
`update_password`	Set password for a host in present state only on creation or always. It can be one of `always` or `on_create` and defaults to `always`.	no
`action`	Work on host or member level. It can be on of `member` or `host` and defaults to `host`.	no
`state`	The state to ensure. It can be one of `present`, `absent` or `disabled`, default: `present`.	yes

Host Variables:

Variable	Description	Required
`description`	The host description.	no
`locality`	Host locality (e.g. "Baltimore, MD").	no
`location` \| `ns_host_location`	Host location (e.g. "Lab 2").	no
`platform` \| `ns_hardware_platform`	Host hardware platform (e.g. "Lenovo T61").	no
`os` \| `ns_os_version`	Host operating system and version (e.g. "Fedora 9").	no
`password` \| `user_password` \| `userpassword`	Password used in bulk enrollment for absent or not enrolled hosts.	no
`random` \| `random_password`	Initiate the generation of a random password to be used in bulk enrollment for absent or not enrolled hosts.	no
`certificate` \| `usercertificate`	List of base-64 encoded host certificates	no
`managedby` \| `principalname` \| `krbprincipalname`	List of hosts that can manage this host	no
`principal` \| `principalname` \| `krbprincipalname`	List of principal aliases for this host	no
`allow_create_keytab_user` \| `ipaallowedtoperform_write_keys_user`	Users allowed to create a keytab of this host.	no
`allow_create_keytab_group` \| `ipaallowedtoperform_write_keys_group`	Groups allowed to create a keytab of this host.	no
`allow_create_keytab_host` \| `ipaallowedtoperform_write_keys_host`	Hosts allowed to create a keytab of this host.	no
`allow_create_keytab_hostgroup` \| `ipaallowedtoperform_write_keys_hostgroup`	Host groups allowed to create a keytab of this host.	no
`allow_retrieve_keytab_user` \| `ipaallowedtoperform_read_keys_user`	Users allowed to retieve a keytab of this host.	no
`allow_retrieve_keytab_group` \| `ipaallowedtoperform_read_keys_group`	Groups allowed to retieve a keytab of this host.	no
`allow_retrieve_keytab_host` \| `ipaallowedtoperform_read_keys_host`	Hosts allowed to retieve a keytab of this host.	no
`allow_retrieve_keytab_hostgroup` \| `ipaallowedtoperform_read_keys_hostgroup`	Host groups allowed to retieve a keytab of this host.	no
`mac_address` \| `macaddress`	List of hardware MAC addresses.	no
`sshpubkey` \| `ipasshpubkey`	List of SSH public keys	no
`userclass` \| `class`	Host category (semantics placed on this attribute are for local interpretation)	no
`auth_ind` \| `krbprincipalauthind`	Defines an allow list for Authentication Indicators. Use 'otp' to allow OTP-based 2FA authentications. Use 'radius' to allow RADIUS-based 2FA authentications. Use empty string to reset auth_ind to the initial value. Other values may be used for custom configurations. choices: ["radius", "otp", "pkinit", "hardened", ""]	no
`requires_pre_auth` \| `ipakrbrequirespreauth`	Pre-authentication is required for the service (bool)	no
`ok_as_delegate` \| `ipakrbokasdelegate`	Client credentials may be delegated to the service (bool)	no
`ok_to_auth_as_delegate` \| `ipakrboktoauthasdelegate`	The service is allowed to authenticate on behalf of a client (bool)	no
`force`	Force host name even if not in DNS.	no
`reverse`	Reverse DNS detection.	no
`ip_address` \| `ipaddress`	The host IP address list. It can contain IPv4 and IPv6 addresses. No conflict check for IP addresses is done.	no
`update_dns`	For existing hosts: DNS SSHFP records are updated with `state` present and all DNS entries for a host removed with `state` absent.	no

Return Values

There are only return values if one or more random passwords have been generated.

Variable	Description	Returned When
`host`	Host dict with random password. (dict) Options:	If random is yes and host did not exist or update_password is yes
	`randompassword` - The generated random password	If only one host is handled by the module
	`name` - The host name of the host that got a new random password. (dict) Options: `randompassword` - The generated random password	If several hosts are handled by the module

Authors

Thomas Woerner

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

README-host.md

README-host.md

Host module

Description

Features

Supported FreeIPA Versions

Requirements

Usage

Variables

Return Values

Authors

Files

README-host.md

Latest commit

History

README-host.md

File metadata and controls

Host module

Description

Features

Supported FreeIPA Versions

Requirements

Usage

Variables

Return Values

Authors