Add new windows module: win_hosts (#46450)

* Add win_hosts module

added win_hosts module for easier manipulation of hosts entries in "%windir%\system32\drivers\etc\hosts" for windows systems

* Update win_hosts.py

* Add alias support to win_hosts module (#1)

* win_hosts supports aliases

added support for adding / removing aliases from a host entry, rather than adding a new entry

added ability for win_hosts to detect aliases:
`192.168.1.1 alias1 alias2 alias3`
```
win_hosts:
  host_name: alias2
  ip_address: 192.168.1.1
```
will result in `192.168.1.1 alias1 alias3`

also includes `replace` and `add` as options for `ip_action` (`replace` is default)

for example:
```
192.168.1.1 my_reused_alias
192.168.1.2 my_reused_alias
```
with
```
win_hosts:
  host_name: my_reused_alias
  ip_address: 192.168.1.3
  ip_action: add
```
the result will be
```
192.168.1.1 my_reused_alias
192.168.1.2 my_reused_alias
```
but with `ip_action=replace` the result would be
```
192.168.1.3 my_reused_alias
```

* fixed metadata version and version added

* fix line endings

* upload fixed line endings

try to upload the file with the fixed line endings

* aliases and canonical names are separate entities. added IPv4 and IPv6 validation

* only makes changes if "check_mode" is false

* improved behavior for duplicate aliases/entries.

* adding tests

* missing aliases file

* fix trailing whitespace and uses explicit paths

* Tweak tests to copy and restore original hosts file

test/integration/targets/win_hosts/aliases

@@ -0,0 +1 @@
+shippable/windows/group3

test/integration/targets/win_hosts/defaults/main.yml

@@ -0,0 +1,13 @@
+---
+test_win_hosts_cname: testhost
+test_win_hosts_ip: 192.168.168.1
+
+test_win_hosts_aliases_set:
+  - alias1
+  - alias2
+  - alias3
+  - alias4
+
+test_win_hosts_aliases_remove:
+  - alias3
+  - alias4

test/integration/targets/win_hosts/meta/main.yml

@@ -0,0 +1,2 @@
+dependencies:
+- setup_remote_tmp_dir

test/integration/targets/win_hosts/tasks/main.yml

@@ -0,0 +1,17 @@
+---
+- name: take a copy of the original hosts file
+  win_copy:
+    src: C:\Windows\System32\drivers\etc\hosts
+    dest: '{{ remote_tmp_dir }}\hosts'
+    remote_src: yes
+
+- block:
+  - name: run tests
+    include_tasks: tests.yml
+
+  always:
+  - name: restore hosts file
+    win_copy:
+      src: '{{ remote_tmp_dir }}\hosts'
+      dest: C:\Windows\System32\drivers\etc\hosts
+      remote_src: yes

test/integration/targets/win_hosts/tasks/tests.yml

@@ -0,0 +1,189 @@
+---
+
+- name: add a simple host with address
+  win_hosts:
+    state: present
+    ip_address: "{{ test_win_hosts_ip }}"
+    canonical_name: "{{ test_win_hosts_cname }}"
+  register: add_ip
+
+- assert:
+    that:
+      - "add_ip.changed == true"
+
+- name: get actual dns result
+  win_shell: "try{ [array]$t = [Net.DNS]::GetHostEntry('{{ test_win_hosts_cname }}') } catch { return 'false' } if ($t[0].HostName -eq '{{ test_win_hosts_cname }}' -and $t[0].AddressList[0].toString() -eq '{{ test_win_hosts_ip }}'){ return 'true' } else { return 'false' }"
+  register: add_ip_actual
+
+- assert:
+    that:
+      - "add_ip_actual.stdout_lines[0]|lower == 'true'"
+
+- name: add a simple host with ipv4 address (idempotent)
+  win_hosts:
+    state: present
+    ip_address: "{{ test_win_hosts_ip }}"
+    canonical_name: "{{ test_win_hosts_cname }}"
+  register: add_ip
+
+- assert:
+    that:
+      - "add_ip.changed == false"
+
+- name: remove simple host
+  win_hosts:
+    state: absent
+    ip_address: "{{ test_win_hosts_ip }}"
+    canonical_name: "{{ test_win_hosts_cname }}"
+  register: remove_ip
+
+- assert:
+    that:
+      - "remove_ip.changed == true"
+
+- name: get actual dns result
+  win_shell: "try{ [array]$t = [Net.DNS]::GetHostEntry('{{ test_win_hosts_cname}}') } catch { return 'false' } if ($t[0].HostName -eq '{{ test_win_hosts_cname }}' -and $t[0].AddressList[0].toString() -eq '{{ test_win_hosts_ip }}'){ return 'true' } else { return 'false' }"
+  register: remove_ip_actual
+  failed_when: "remove_ip_actual.rc == 0"
+
+- assert:
+    that:
+      - "remove_ip_actual.stdout_lines[0]|lower == 'false'"
+
+- name: remove simple host (idempotent)
+  win_hosts:
+    state: absent
+    ip_address: "{{ test_win_hosts_ip }}"
+    canonical_name: "{{ test_win_hosts_cname }}"
+  register: remove_ip
+
+- assert:
+    that:
+      - "remove_ip.changed == false"
+
+- name: add host and set aliases
+  win_hosts:
+    state: present
+    ip_address: "{{ test_win_hosts_ip }}"
+    canonical_name: "{{ test_win_hosts_cname }}"
+    aliases: "{{ test_win_hosts_aliases_set | union(test_win_hosts_aliases_remove) }}"
+    action: set
+  register: set_aliases
+
+- assert:
+    that:
+      - "set_aliases.changed == true"
+
+- name: get actual dns result for host
+  win_shell: "try{ [array]$t = [Net.DNS]::GetHostEntry('{{ test_win_hosts_cname }}') } catch { return 'false' } if ($t[0].HostName -eq '{{ test_win_hosts_cname }}' -and $t[0].AddressList[0].toString() -eq '{{ test_win_hosts_ip }}'){ return 'true' } else { return 'false' }"
+  register: set_aliases_actual_host
+
+- assert:
+    that:
+      - "set_aliases_actual_host.stdout_lines[0]|lower == 'true'"
+
+- name: get actual dns results for aliases
+  win_shell: "try{ [array]$t = [Net.DNS]::GetHostEntry('{{ item }}') } catch { return 'false' } if ($t[0].HostName -eq '{{ test_win_hosts_cname }}' -and $t[0].AddressList[0].toString() -eq '{{ test_win_hosts_ip }}'){ return 'true' } else { return 'false' }"
+  register: set_aliases_actual
+  with_items: "{{ test_win_hosts_aliases_set | union(test_win_hosts_aliases_remove) }}"
+
+- assert:
+    that:
+      - "item.stdout_lines[0]|lower == 'true'"
+  with_items: "{{ set_aliases_actual.results }}"
+
+- name: add host and set aliases (idempotent)
+  win_hosts:
+    state: present
+    ip_address: "{{ test_win_hosts_ip }}"
+    canonical_name: "{{ test_win_hosts_cname }}"
+    aliases: "{{ test_win_hosts_aliases_set | union(test_win_hosts_aliases_remove) }}"
+    action: set
+  register: set_aliases
+
+- assert:
+    that:
+      - "set_aliases.changed == false"
+
+- name: remove aliases from the list
+  win_hosts:
+    state: present
+    ip_address: "{{ test_win_hosts_ip }}"
+    canonical_name: "{{ test_win_hosts_cname }}"
+    aliases: "{{ test_win_hosts_aliases_remove }}"
+    action: remove
+  register: remove_aliases
+
+- assert:
+    that:
+      - "remove_aliases.changed == true"
+
+- name: get actual dns result for removed aliases
+  win_shell: "try{ [array]$t = [Net.DNS]::GetHostEntry('{{ item }}') } catch { return 'false' } if ($t[0].HostName -eq '{{ test_win_hosts_cname }}' -and $t[0].AddressList[0].toString() -eq '{{ test_win_hosts_ip }}'){ return 'true' } else { return 'false' }"
+  register: remove_aliases_removed_actual
+  failed_when: "remove_aliases_removed_actual.rc == 0"
+  with_items: "{{ test_win_hosts_aliases_remove }}"
+
+- assert:
+    that:
+      - "item.stdout_lines[0]|lower == 'false'"
+  with_items: "{{ remove_aliases_removed_actual.results }}"
+
+- name: get actual dns result for remaining aliases
+  win_shell: "try{ [array]$t = [Net.DNS]::GetHostEntry('{{ item }}') } catch { return 'false' } if ($t[0].HostName -eq '{{ test_win_hosts_cname }}' -and $t[0].AddressList[0].toString() -eq '{{ test_win_hosts_ip }}'){ return 'true' } else { return 'false' }"
+  register: remove_aliases_remain_actual
+  with_items: "{{ test_win_hosts_aliases_set | difference(test_win_hosts_aliases_remove) }}"
+
+- assert:
+    that:
+      - "item.stdout_lines[0]|lower == 'true'"
+  with_items: "{{ remove_aliases_remain_actual.results }}"
+
+- name: remove aliases from the list (idempotent)
+  win_hosts:
+    state: present
+    ip_address: "{{ test_win_hosts_ip }}"
+    canonical_name: "{{ test_win_hosts_cname }}"
+    aliases: "{{ test_win_hosts_aliases_remove }}"
+    action: remove
+  register: remove_aliases
+
+- assert:
+    that:
+      - "remove_aliases.changed == false"
+
+- name: add aliases back
+  win_hosts:
+    state: present
+    ip_address: "{{ test_win_hosts_ip }}"
+    canonical_name: "{{ test_win_hosts_cname }}"
+    aliases: "{{ test_win_hosts_aliases_remove }}"
+    action: add
+  register: add_aliases
+
+- assert:
+    that:
+      - "add_aliases.changed == true"
+
+- name: get actual dns results for aliases
+  win_shell: "try{ [array]$t = [Net.DNS]::GetHostEntry('{{ item }}') } catch { return 'false' } if ($t[0].HostName -eq '{{ test_win_hosts_cname }}' -and $t[0].AddressList[0].toString() -eq '{{ test_win_hosts_ip }}'){ return 'true' } else { return 'false' }"
+  register: add_aliases_actual
+  with_items: "{{ test_win_hosts_aliases_set | union(test_win_hosts_aliases_remove) }}"
+
+- assert:
+    that:
+      - "item.stdout_lines[0]|lower == 'true'"
+  with_items: "{{ add_aliases_actual.results }}"
+
+- name: add aliases back (idempotent)
+  win_hosts:
+    state: present
+    ip_address: "{{ test_win_hosts_ip }}"
+    canonical_name: "{{ test_win_hosts_cname }}"
+    aliases: "{{ test_win_hosts_aliases_remove }}"
+    action: add
+  register: add_aliases
+
+- assert:
+    that:
+      - "add_aliases.changed == false"