New host management module

There is a new user management module placed in the plugins folder:

  plugins/modules/ipauser.py

The host module allows to add, remove and disable hosts.

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

Here is the documentation for the module:

  README-host.md

New example playbooks have been added:

  playbooks/host/add-host.yml
  playbooks/host/delete-host.yml
  playbooks/host/disable-host.yml

README-host.md

+Host module
+===========
+
+Description
+-----------
+
+The host module allows to add, remove, and disable hosts.
+
+The host module is as compatible as possible to the Ansible upstream `ipa_host` module, but addtionally 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
+
+```ini
+[ipaserver]
+ipaserver.test.local
+```
+
+
+Example playbook to add hosts:
+
+```yaml
+---
+- name: Playbook to handle hosts
+  hosts: ipaserver
+  become: true
+
+  tasks:
+  # Ensure host is present
+  - ipahost:
+      ipaadmin_password: MyPassword123
+      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
+```
+
+
+Example playbook to create host without DNS:
+
+```yaml
+---
+- name: Playbook to handle hosts
+  hosts: ipaserver
+  become: true
+
+  tasks:
+  # Ensure host is present without DNS
+  - ipahost:
+      ipaadmin_password: MyPassword123
+      name: host02.example.com
+      description: Example host
+      force: yes
+```
+
+
+Example playbook to initiate the generation of a random password to be used in bulk enrollment:
+
+```yaml
+---
+- name: Playbook to handle hosts
+  hosts: ipaserver
+  become: true
+
+  tasks:
+  # Generate a random password for bulk enrolment
+  - ipahost:
+      ipaadmin_password: MyPassword123
+      name: host01.example.com
+      description: Example host
+      ip_address: 192.168.0.123
+      random: yes
+```
+
+
+Example playbook to disable a host:
+
+```yaml
+---
+- name: Playbook to handle hosts
+  hosts: ipaserver
+  become: true
+
+  tasks:
+  # Ensure host is disabled
+  - ipahost:
+      ipaadmin_password: MyPassword123
+      name: host01.example.com
+      update_dns: yes
+      state: disabled
+```
+`update_dns` controls if the DNS entries will be updated.
+
+
+Example playbook to ensure a host is absent:
+
+```yaml
+---
+- 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. | yes
+`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. | no
+`random` \| `random_password` |  Initiate the generation of a random password to be used in bulk enrollment. | no
+`mac_address` \| `macaddress` | List of hardware MAC addresses. | no
+`force` | Force host name even if not in DNS. | no
+`reverse` | Reverse DNS detection. | no
+`ip_address` \| `ipaddress` | The host IP address. | no
+`update_dns` | Update DNS entries. | 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
+`state` | The state to ensure. It can be one of `present`, `absent` or `disabled`, default: `present`. | yes
+
+
+Authors
+=======
+
+Thomas Woerner

README.md

 FreeIPA Ansible collection
 ==========================
 
-This repository contains [Ansible](https://www.ansible.com/) roles and playbooks to install and uninstall [FreeIPA](https://www.freeipa.org/) `servers`, `replicas` and `clients`. Also modules for group, topology and user management.
+This repository contains [Ansible](https://www.ansible.com/) roles and playbooks to install and uninstall [FreeIPA](https://www.freeipa.org/) `servers`, `replicas` and `clients`. Also modules for group, host, topology and user management.
 
 **Note**: The ansible playbooks and roles 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.
 
@@ -12,6 +12,7 @@ Features
 * One-time-password (OTP) support for client installation
 * Repair mode for clients
 * Modules for group management
+* Modules for host management
 * Modules for topology management
 * Modules for user management
 
@@ -387,6 +388,7 @@ Modules in plugin/modules
 =========================
 
 * [ipagroup](README-group.md)
+* [ipahost](README-host.md)
 * [ipatopologysegment](README-topology.md)
 * [ipatopologysuffix](README-topology.md)
 * [ipauser](README-user.md)

playbooks/host/add-host.yml

+---
+- name: Playbook to handle hosts
+  hosts: ipaserver
+  become: true
+
+  tasks:
+  - name: Ensure host is present
+    ipahost:
+      ipaadmin_password: MyPassword123
+      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

playbooks/host/delete-host.yml

+---
+- name: Playbook to handle hosts
+  hosts: ipaserver
+  become: true
+
+  tasks:
+  - name: Ensure host host01.example.com is absent
+    ipahost:
+      ipaadmin_password: MyPassword123
+      name: host01.example.com
+      state: absent

playbooks/host/disable-host.yml

+---
+- name: Playbook to handle hosts
+  hosts: ipaserver
+  become: true
+
+  tasks:
+  - name: Disable host host01.example.com
+    ipahost:
+      ipaadmin_password: MyPassword123
+      name: host01.example.com
+      state: disabled

plugins/modules/ipahost.py

+#!/usr/bin/python
+# -*- coding: utf-8 -*-
+
+# Authors:
+#   Thomas Woerner <twoerner@redhat.com>
+#
+# Copyright (C) 2019 Red Hat
+# see file 'COPYING' for use and warranty information
+#
+# This program is free software; you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with this program.  If not, see <http://www.gnu.org/licenses/>.
+
+ANSIBLE_METADATA = {
+    "metadata_version": "1.0",
+    "supported_by": "community",
+    "status": ["preview"],
+}
+
+DOCUMENTATION = """
+---
+module: ipahost
+short description: Manage FreeIPA hosts
+description: Manage FreeIPA hosts
+options:
+  ipaadmin_principal:
+    description: The admin principal
+    default: admin
+  ipaadmin_password:
+    description: The admin password
+    required: false
+  name:
+    description: The full qualified domain name.
+    aliases: ["fqdn"]
+    required: true
+  description:
+    description: The host description
+    required: false
+  locality:
+    description: Host locality (e.g. "Baltimore, MD")
+    required: false
+  location:
+    description: Host location (e.g. "Lab 2")
+    aliases: ["ns_host_location"]
+    required: false
+  platform:
+    description: Host hardware platform (e.g. "Lenovo T61")
+    aliases: ["ns_hardware_platform"]
+    required: false
+  os:
+    description: Host operating system and version (e.g. "Fedora 9")
+    aliases: ["ns_os_version"]
+    required: false
+  password:
+    description: Password used in bulk enrollment
+    aliases: ["user_password", "userpassword"]
+    required: false
+  random:
+    description:
+      Initiate the generation of a random password to be used in bulk
+      enrollment
+    aliases: ["random_password"]
+    required: false
+  mac_address:
+    description: List of hardware MAC addresses.
+    type: list
+    aliases: ["macaddress"]
+    required: false
+  force:
+    description: Force host name even if not in DNS
+    required: false
+  reverse:
+    description: Reverse DNS detection
+    default: true
+    required: false
+  ip_address:
+    description: The host IP address
+    aliases: ["ipaddress"]
+    required: false
+  update_dns:
+    description: Update DNS entries
+    required: false
+  update_password:
+    description:
+      Set password for a host in present state only on creation or always
+    default: 'always'
+    choices: ["always", "on_create"]
+  state:
+    description: State to ensure
+    default: present
+    choices: ["present", "absent",
+              "disabled"]
+author:
+    - Thomas Woerner
+"""
+
+EXAMPLES = """
+# Ensure host is present
+- ipahost:
+    ipaadmin_password: MyPassword123
+    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
+
+# Ensure host is present without DNS
+- ipahost:
+    ipaadmin_password: MyPassword123
+    name: host02.example.com
+    description: Example host
+    force: yes
+
+# Initiate generation of a random password for the host
+- ipahost:
+    ipaadmin_password: MyPassword123
+    name: host01.example.com
+    description: Example host
+    ip_address: 192.168.0.123
+    random: yes
+
+# Ensure host is disabled
+- ipahost:
+    ipaadmin_password: MyPassword123
+    name: host01.example.com
+    update_dns: yes
+    state: disabled
+
+# Ensure host is absent
+- ipahost:
+    ipaadmin_password: password1
+    name: host01.example.com
+    state: absent
+"""
+
+RETURN = """
+"""
+
+from ansible.module_utils.basic import AnsibleModule
+from ansible.module_utils._text import to_text
+from ansible.module_utils.ansible_freeipa_module import temp_kinit, \
+    temp_kdestroy, valid_creds, api_connect, api_command, compare_args_ipa
+
+
+def find_host(module, name):
+    _args = {
+        "all": True,
+        "fqdn": to_text(name),
+    }
+
+    _result = api_command(module, "host_find", to_text(name), _args)
+
+    if len(_result["result"]) > 1:
+        module.fail_json(
+            msg="There is more than one host '%s'" % (name))
+    elif len(_result["result"]) == 1:
+        return _result["result"][0]
+    else:
+        return None
+
+
+def show_host(module, name):
+    _result = api_command(module, "host_show", to_text(name), {})
+    return _result["result"]
+
+
+def gen_args(description, force, locality, location, platform, os, password,
+             random, mac_address, ip_address, update_dns, reverse):
+    _args = {}
+    if description is not None:
+        _args["description"] = description
+    if force is not None:
+        _args["force"] = force
+    if locality is not None:
+        _args["l"] = locality
+    if location is not None:
+        _args["nshostlocation"] = location
+    if platform is not None:
+        _args["nshardwareplatform"] = platform
+    if os is not None:
+        _args["nsosversion"] = os
+    if password is not None:
+        _args["userpassword"] = password
+    if random is not None:
+        _args["random"] = random
+    if mac_address is not None:
+        _args["macaddress"] = mac_address
+    if ip_address is not None:
+        _args["ip_address"] = ip_address
+    if update_dns is not None:
+        _args["updatedns"] = update_dns
+    if reverse is not None:
+        _args["no_reverse"] = not reverse
+
+    return _args
+
+
+def main():
+    ansible_module = AnsibleModule(
+        argument_spec=dict(
+            # general
+            ipaadmin_principal=dict(type="str", default="admin"),
+            ipaadmin_password=dict(type="str", no_log=True),
+
+            name=dict(type="list", aliases=["fqdn"], default=None,
+                      required=True),
+            # present
+            description=dict(type="str", default=None),
+            locality=dict(type="str", default=None),
+            location=dict(type="str", aliases=["ns_host_location"],
+                          default=None),
+            platform=dict(type="str", aliases=["ns_hardware_platform"],
+                          default=None),
+            os=dict(type="str", aliases=["ns_os_version"], default=None),
+            password=dict(type="str",
+                          aliases=["user_password", "userpassword"],
+                          default=None, no_log=True),
+            random=dict(type="bool", aliases=["random_password"],
+                        default=None),
+            # certificate (usercertificate)
+            mac_address=dict(type="list", aliases=["macaddress"],
+                             default=None),
+            # sshpubkey=dict(type="str", aliases=["ipasshpubkey"],
+            #                default=None),
+            # class
+            # auth_ind
+            # requires_pre_auth
+            # ok_as_delegate
+            # ok_to_auth_as_delegate
+            force=dict(type='bool', default=None),
+            reverse=dict(type='bool', default=True),
+            ip_address=dict(type="str", aliases=["ipaddress"],
+                            default=None),
+            # no_members
+
+            # for update:
+            # krbprincipalname
+            update_dns=dict(type="bool", aliases=["updatedns"],
+                            default=None),
+            update_password=dict(type='str', default=None,
+                                 choices=['always', 'on_create']),
+            # absent
+            # continue
+
+            # disabled
+
+            # state
+            state=dict(type="str", default="present",
+                       choices=["present", "absent", "disabled"]),
+        ),
+        supports_check_mode=True,
+    )
+
+    ansible_module._ansible_debug = True
+
+    # Get parameters
+
+    # general
+    ipaadmin_principal = ansible_module.params.get("ipaadmin_principal")
+    ipaadmin_password = ansible_module.params.get("ipaadmin_password")
+    names = ansible_module.params.get("name")
+
+    # present
+    description = ansible_module.params.get("description")
+    locality = ansible_module.params.get("locality")
+    location = ansible_module.params.get("location")
+    platform = ansible_module.params.get("platform")
+    os = ansible_module.params.get("os")
+    password = ansible_module.params.get("password")
+    random = ansible_module.params.get("random")
+    mac_address = ansible_module.params.get("mac_address")
+    force = ansible_module.params.get("force")
+    reverse = ansible_module.params.get("reverse")
+    ip_address = ansible_module.params.get("ip_address")
+    update_dns = ansible_module.params.get("update_dns")
+    update_password = ansible_module.params.get("update_password")
+    # absent
+    # disabled
+    # state
+    state = ansible_module.params.get("state")
+
+    # Check parameters
+
+    if state == "present":
+        if len(names) != 1:
+            ansible_module.fail_json(
+                msg="Only one host can be added at a time.")
+
+    if state == "absent":
+        if len(names) < 1:
+            ansible_module.fail_json(
+                msg="No name given.")
+        for x in ["description", "password", "random", "mac_address",
+                  "force", "ip_address", "update_password"]:
+            if vars()[x] is not None:
+                ansible_module.fail_json(
+                    msg="Argument '%s' can not be used with state '%s'" %
+                    (x, state))
+
+    if update_password is None:
+        update_password = "always"
+
+    # Init
+
+    changed = False
+    exit_args = {}
+    ccache_dir = None
+    ccache_name = None
+    try:
+        if not valid_creds(ansible_module, ipaadmin_principal):
+            ccache_dir, ccache_name = temp_kinit(ipaadmin_principal,
+                                                 ipaadmin_password)
+        api_connect()
+
+        commands = []
+
+        for name in names:
+            # Make sure host exists
+            res_find = find_host(ansible_module, name)
+
+            # Create command
+            if state == "present":
+                # Generate args
+                args = gen_args(
+                    description, force, locality, location, platform, os,
+                    password, random, mac_address, ip_address, update_dns,
+                    reverse)
+
+                # Found the host
+                if res_find is not None:
+                    # Ignore password with update_password == on_create
+                    if update_password == "on_create" and \
+                       "userpassword" in args:
+                        del args["userpassword"]
+
+                    # Ignore force, ip_address and no_reverse for mod
+                    for x in ["force", "ip_address", "no_reverse"]:
+                        if x in args:
+                            del args[x]
+
+                    # For all settings is args, check if there are
+                    # different settings in the find result.
+                    # If yes: modify
+                    if not compare_args_ipa(ansible_module, args, res_find):
+                        commands.append([name, "host_mod", args])
+                else:
+                    commands.append([name, "host_add", args])
+
+            elif state == "absent":
+                if res_find is not None:
+                    commands.append([name, "host_del", {}])
+
+            elif state == "disabled":
+                if res_find is not None:
+                    res_show = show_host(ansible_module, name)
+                    if res_show["has_keytab"]:
+                        commands.append([name, "host_disable", {}])
+                else:
+                    raise ValueError("No host '%s'" % name)
+
+            else:
+                ansible_module.fail_json(msg="Unkown state '%s'" % state)
+
+        # Execute commands
+        for name, command, args in commands:
+            try:
+                api_command(ansible_module, command, to_text(name), args)
+                changed = True
+            except Exception as e:
+                ansible_module.fail_json(msg="%s: %s: %s" % (command, name,
+                                                             str(e)))
+
+    except Exception as e:
+        ansible_module.fail_json(msg=str(e))
+
+    finally:
+        temp_kdestroy(ccache_dir, ccache_name)
+
+    # Done
+
+    ansible_module.exit_json(changed=changed, **exit_args)
+
+
+if __name__ == "__main__":
+    main()