ipahost: Return generated random password

The random password is only returned if random is yes and the host did
not exist or update_password is yes.

If only one host is handled by the module, the returned dict is containing
this dict:

  { "randompassword": "<the host random password>" }

If several hosts are handled by the module (future feature):

  { "<host>": { "randompassword": "<the host random password>" } }

Fixes issue #134 (ipahost does not return the random password)

README-host.md

@@ -101,6 +101,11 @@ Example playbook to initiate the generation of a random password to be used in b
       description: Example host
       ip_address: 192.168.0.123
       random: yes
+    register: ipahost
+
+  - name: Print generated random password
+    debug:
+      var: ipahost.host.randompassword
 ```
 
 
@@ -167,6 +172,21 @@ Variable | Description | Required
 `state` | The state to ensure. It can be one of `present`, `absent` or `disabled`, default: `present`. | yes
 
 
+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) <br>Options: | If random is yes and host did not exist or update_password is yes
+&nbsp; | `randompassword` - The generated random password | If only one host is handled by the module
+&nbsp; | `name` - The host name of the host that got a new random password. (dict) <br> Options: <br> &nbsp; `randompassword` - The generated random password | If several hosts are handled by the module
+
+
 Authors
 =======
 

playbooks/host/ensure_host_with_randompassword.yml

@@ -0,0 +1,18 @@
+---
+- name: Ensure host with random password
+  hosts: ipaserver
+  become: true
+
+  tasks:
+  - name: Host "{{ 'host1.' + ipaserver_domain }}" present with random password
+    ipahost:
+      ipaadmin_password: MyPassword123
+      name: "{{ 'host1.' + ipaserver_domain }}"
+      random: yes
+      force: yes
+      update_password: on_create
+    register: ipahost
+
+  - name: Print generated random password
+    debug:
+      var: ipahost.host.randompassword

plugins/modules/ipahost.py

@@ -149,6 +149,22 @@ EXAMPLES = """
 """
 
 RETURN = """
+host:
+  description: Host dict with random password
+  returned: If random is yes and user did not exist or update_password is yes
+  type: dict
+  options:
+    randompassword:
+      description: The generated random password
+      returned: If only one user is handled by the module
+    name:
+      description: The user name of the user that got a new random password
+      returned: If several users are handled by the module
+      type: dict
+      options:
+        randompassword:
+          description: The generated random password
+          returned: always
 """
 
 from ansible.module_utils.basic import AnsibleModule
@@ -344,9 +360,11 @@ def main():
                 # 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"]
+                    if update_password == "on_create":
+                        if "userpassword" in args:
+                            del args["userpassword"]
+                        if "random" in args:
+                            del args["random"]
 
                     # Ignore force, ip_address and no_reverse for mod
                     for x in ["force", "ip_address", "no_reverse"]:
@@ -379,8 +397,19 @@ def main():
         # Execute commands
         for name, command, args in commands:
             try:
-                api_command(ansible_module, command, to_text(name), args)
+                result = api_command(ansible_module, command, to_text(name),
+                                     args)
                 changed = True
+
+                if "random" in args and command in ["host_add", "host_mod"] \
+                   and "randompassword" in result["result"]:
+                    if len(names) == 1:
+                        exit_args["randompassword"] = \
+                            result["result"]["randompassword"]
+                    else:
+                        exit_args.setdefault(name, {})["randompassword"] = \
+                            result["result"]["randompassword"]
+
             except Exception as e:
                 ansible_module.fail_json(msg="%s: %s: %s" % (command, name,
                                                              str(e)))
@@ -393,7 +422,7 @@ def main():
 
     # Done
 
-    ansible_module.exit_json(changed=changed, **exit_args)
+    ansible_module.exit_json(changed=changed, host=exit_args)
 
 
 if __name__ == "__main__":

tests/host/test_host_random.yml

@@ -0,0 +1,41 @@
+---
+- name: Test ipahost random password generation
+  hosts: ipaserver
+  become: true
+
+  tasks:
+  - name: Get Domain from server name
+    set_fact:
+      ipaserver_domain: "{{ groups.ipaserver[0].split('.')[1:] | join ('.') }}"
+    when: ipaserver_domain is not defined
+
+  - name: Test hosts absent
+    ipahost:
+      ipaadmin_password: MyPassword123
+      name:
+      - "{{ 'host1.' + ipaserver_domain }}"
+      - "{{ 'host2.' + ipaserver_domain }}"
+      update_dns: yes
+      state: absent
+
+  - name: Host "{{ 'host1.' + ipaserver_domain }}" present with random password
+    ipahost:
+      ipaadmin_password: MyPassword123
+      name: "{{ 'host1.' + ipaserver_domain }}"
+      random: yes
+      force: yes
+      update_password: on_create
+    register: ipahost
+    failed_when: not ipahost.changed or
+                 ipahost.host.randompassword is not defined
+
+  - name: Print generated random password
+    debug:
+      var: ipahost.host.randompassword
+
+  - name: Host "{{ 'host1.' + ipaserver_domain }}" absent
+    ipahost:
+      ipaadmin_password: MyPassword123
+      name:
+      - "{{ 'host1.' + ipaserver_domain }}"
+      state: absent