Skip to content

Latest commit

 

History

History
386 lines (305 loc) · 11.8 KB

README-host.md

File metadata and controls

386 lines (305 loc) · 11.8 KB

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.exmaple.com
        managedby_host: server.exmaple.com
      - name: host02.exmaple.com
        managedby_host: server.exmaple.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

ipahost

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
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

ipahost

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