win_snmp: Initial commit (#45710)

* win_snmp: Initial commit

* win_snmp: Better handling of lists

* win_snmp: Documentation fixes

* win_snmp: Updated documentation to match parameters

* win_snmp: Added integration tests

* win_snmp: Fixed typo in test

* win_snmp: Adjusted parameter checks to match documentation

* win_snmp: Updated option descriptions to be full sentences

* win_snmp: Better type checking and output suppression

* win_snmp: Fixed unset managers and communities

* win_snmp: Fixed skipping default registry keys

* win_snmp: Migrated to using add/set/remove action from replace

* win_snmp: Fixed check mode

* win_snmp: Fixed setting action and documentation. Expanded tests.

* win_snmp: Efficiency changes and documentation cleanup
  * Added example of explicitly setting an empty set of managers to
documentation
  * Made sure set will only remove items if there is a list of items
provided. This list can be of length 0
  * Improved efficiency in selecting next index for SNMP manager
  * Updated tests

* win_snmp: Added output of permitted managers and community strings

* win_snmp: Documentation fix

test/integration/targets/win_snmp/aliases

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

test/integration/targets/win_snmp/tasks/cleanup.yml

@@ -0,0 +1,16 @@
+---
+  - name: Make sure there are no existing SNMP configuration settings
+    win_regedit:
+      path: "{{ item }}"
+      state: absent
+    loop:
+      - "{{ permitted_managers_key }}"
+      - "{{ valid_communities_key }}"
+
+  - name: Create skeleton registry keys for SNMP
+    win_regedit:
+      path: "{{ item }}"
+      state: present
+    loop:
+      - "{{ permitted_managers_key }}"
+      - "{{ valid_communities_key }}"

test/integration/targets/win_snmp/tasks/cleanup_using_module.yml

@@ -0,0 +1,26 @@
+---
+  - name: Set no SNMP community or SNMP manager
+    register: snmp_cleanup
+    win_snmp:
+      action: set
+      community_strings: []
+      permitted_managers: []
+
+  - name: Check registry for no SNMP community
+    register: snmp_cleanup_reg_community
+    win_reg_stat:
+      path: "{{ valid_communities_key }}"
+      name: snmp-cleanup
+
+  - name: Check registry for no SNMP manager
+    register: snmp_cleanup_reg_manager
+    win_reg_stat:
+      path: "{{ permitted_managers_key }}"
+      name: 1
+
+  - name: Asset SNMP set operation results in no remaining SNMP details
+    assert:
+      that:
+        - snmp_cleanup.changed
+        - snmp_cleanup_reg_community.exists == false
+        - snmp_cleanup_reg_manager.exists == false

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

@@ -0,0 +1,8 @@
+---
+  - include_tasks: cleanup.yml
+  - include_tasks: snmp_community.yml
+  - include_tasks: cleanup.yml
+  - include_tasks: snmp_managers.yml
+  - include_tasks: output_only.yml
+  - include_tasks: cleanup_using_module.yml
+  - include_tasks: cleanup.yml

test/integration/targets/win_snmp/tasks/output_only.yml

@@ -0,0 +1,24 @@
+---
+  # Already tested
+  - name: Add an SNMP manager and an SNMP community
+    win_snmp:
+      action: add
+      community_strings:
+        - snmp-cleanup
+      permitted_managers:
+        - 192.168.1.1
+
+  - name: Run without options
+    register: snmp_no_options
+    win_snmp:
+
+  - name: Assert no changes occurred when no options provided
+    assert:
+      that:
+        - not snmp_no_options.changed
+
+  - name: Assert community strings and permitted managers are correctly returned
+    assert:
+      that:
+        - "'snmp-cleanup' in snmp_no_options.community_strings"
+        - "'192.168.1.1' in snmp_no_options.permitted_managers"

test/integration/targets/win_snmp/tasks/snmp_community.yml

@@ -0,0 +1,165 @@
+---
+  - name: Add initial SNMP community
+    register: snmp_community
+    win_snmp:
+      action: add
+      community_strings:
+        - ansible-ro-test
+
+  - name: Check initial SNMP community exists in registry
+    register: snmp_community_reg
+    win_reg_stat:
+      path: "{{ valid_communities_key }}"
+      name: ansible-ro-test
+
+  - name: Assert initial SNMP community is correct
+    assert:
+      that:
+        - snmp_community is changed
+        - snmp_community_reg.exists
+        - snmp_community_reg.type == 'REG_DWORD'
+        - snmp_community_reg.value == 4
+
+  - name: Add initial SNMP community again
+    register: snmp_community_again
+    win_snmp:
+      action: add
+      community_strings:
+        - ansible-ro-test
+
+  - name: Check no change occurred when adding SNMP community again
+    assert:
+      that:
+        - snmp_community_again is not changed
+
+  - name: Add next SNMP community
+    register: snmp_community_next
+    win_snmp:
+      action: add
+      community_strings:
+        - ansible-ro-test-next
+
+  - name: Check initial SNMP community still exists in registry
+    register: snmp_community_reg_orig
+    win_reg_stat:
+      path: "{{ valid_communities_key }}"
+      name: ansible-ro-test
+
+  - name: Check next SNMP community exists in registry
+    register: snmp_community_reg_next
+    win_reg_stat:
+      path: "{{ valid_communities_key }}"
+      name: ansible-ro-test-next
+
+  - name: Assert initial SNMP community still exists
+    assert:
+      that:
+        - snmp_community_reg_orig.exists
+        - snmp_community_reg_orig.type == 'REG_DWORD'
+        - snmp_community_reg_orig.value == 4
+
+  - name: Assert next SNMP community exists
+    assert:
+      that:
+        - snmp_community_next is changed
+        - snmp_community_reg_next.exists
+        - snmp_community_reg_next.type == 'REG_DWORD'
+        - snmp_community_reg_next.value == 4
+
+  - name: Replace SNMP community
+    register: snmp_community_replace
+    win_snmp:
+      action: set
+      community_strings:
+        - ansible-ro-test-replace
+
+  - name: Check initial SNMP community does not exist in registry
+    register: snmp_community_reg_orig_replace
+    win_reg_stat:
+      path: "{{ valid_communities_key }}"
+      name: ansible-ro-test
+
+  - name: Check next SNMP community does not exist in registry
+    register: snmp_community_reg_next_replace
+    win_reg_stat:
+      path: "{{ valid_communities_key }}"
+      name: ansible-ro-test-next
+
+  - name: Check replace SNMP community exists in registry
+    register: snmp_community_reg_replace
+    win_reg_stat:
+      path: "{{ valid_communities_key }}"
+      name: ansible-ro-test-replace
+
+  - name: Assert replace SNMP community exists and others are replaced
+    assert:
+      that:
+        - snmp_community_replace is changed
+        - snmp_community_reg_orig_replace.exists == false
+        - snmp_community_reg_next_replace.exists == false
+        - snmp_community_reg_replace.exists
+        - snmp_community_reg_replace.type == 'REG_DWORD'
+        - snmp_community_reg_replace.value == 4
+
+  # This task has already been tested
+  - name: Add another SNMP community before testing removal
+    win_snmp:
+      action: add
+      community_strings:
+        - ansible-ro-remove-add
+
+  - name: Remove the replaced SNMP community
+    register: snmp_community_remove
+    win_snmp:
+      action: remove
+      community_strings:
+        - ansible-ro-test-replace
+
+  - name: Check replace SNMP community is removed in registry
+    register: snmp_community_reg_remove
+    win_reg_stat:
+      path: "{{ valid_communities_key }}"
+      name: ansible-ro-test-replace
+
+  - name: Check SNMP community that was added for testing removal exists in registry
+    register: snmp_community_reg_remove_add
+    win_reg_stat:
+      path: "{{ valid_communities_key }}"
+      name: ansible-ro-remove-add
+
+  - name: Assert removal of SNMP community succeeded and next SNMP community remains
+    assert:
+      that:
+        - snmp_community_remove is changed
+        - snmp_community_reg_remove.exists == false
+        - snmp_community_reg_remove_add.exists
+        - snmp_community_reg_remove_add.type == 'REG_DWORD'
+        - snmp_community_reg_remove_add.value == 4
+
+  - name: Remove the replaced SNMP community (again)
+    register: snmp_community_remove
+    win_snmp:
+      action: remove
+      community_strings:
+        - ansible-ro-test-replace
+
+  - name: Check replace SNMP community is removed in registry (again)
+    register: snmp_community_reg_remove
+    win_reg_stat:
+      path: "{{ valid_communities_key }}"
+      name: ansible-ro-test-replace
+
+  - name: Check SNMP community that was added for testing removal exists in registry (again)
+    register: snmp_community_reg_remove_add
+    win_reg_stat:
+      path: "{{ valid_communities_key }}"
+      name: ansible-ro-remove-add
+
+  - name: Assert removal of SNMP community succeeded and next SNMP community remains (again)
+    assert:
+      that:
+        - snmp_community_remove is not changed
+        - snmp_community_reg_remove.exists == false
+        - snmp_community_reg_remove_add.exists
+        - snmp_community_reg_remove_add.type == 'REG_DWORD'
+        - snmp_community_reg_remove_add.value == 4

test/integration/targets/win_snmp/tasks/snmp_managers.yml

@@ -0,0 +1,158 @@
+---
+  - name: Add initial SNMP manager
+    register: snmp_manager
+    win_snmp:
+      action: add
+      permitted_managers:
+        - 192.168.1.1
+
+  - name: Check initial SNMP manager exists in registry
+    register: snmp_manager_reg
+    win_reg_stat:
+      path: "{{ permitted_managers_key }}"
+      name: 1
+
+  - name: Assert initial SNMP manager is correct
+    assert:
+      that:
+        - snmp_manager is changed
+        - snmp_manager_reg.exists
+        - snmp_manager_reg.type == 'REG_SZ'
+        - snmp_manager_reg.value == '192.168.1.1'
+
+  - name: Add initial SNMP manager again
+    register: snmp_manager_again
+    win_snmp:
+      action: add
+      permitted_managers:
+        - 192.168.1.1
+
+  - name: Check no change occurred when adding SNMP manager again
+    assert:
+      that:
+        - snmp_manager_again is not changed
+
+  - name: Add next SNMP manager
+    register: snmp_manager_next
+    win_snmp:
+      action: add
+      permitted_managers:
+        - 192.168.1.2
+
+  - name: Check initial SNMP manager still exists in registry
+    register: snmp_manager_reg_orig
+    win_reg_stat:
+      path: "{{ permitted_managers_key }}"
+      name: 1
+
+  - name: Check next SNMP manager exists in registry
+    register: snmp_manager_reg_next
+    win_reg_stat:
+      path: "{{ permitted_managers_key }}"
+      name: 2
+
+  - name: Assert initial SNMP manager still exists
+    assert:
+      that:
+        - snmp_manager_reg_orig.exists
+        - snmp_manager_reg_orig.type == 'REG_SZ'
+        - snmp_manager_reg_orig.value == '192.168.1.1'
+
+  - name: Assert next SNMP manager exists
+    assert:
+      that:
+        - snmp_manager_next is changed
+        - snmp_manager_reg_next.exists
+        - snmp_manager_reg_next.type == 'REG_SZ'
+        - snmp_manager_reg_next.value == '192.168.1.2'
+
+  - name: Replace SNMP manager
+    register: snmp_manager_replace
+    win_snmp:
+      action: set
+      permitted_managers:
+        - 192.168.1.10
+
+  - name: Check next SNMP manager does not exist in registry
+    register: snmp_manager_reg_next_replace
+    win_reg_stat:
+      path: "{{ permitted_managers_key }}"
+      name: 2
+
+  - name: Check replace SNMP manager exists in registry (overrides original slot)
+    register: snmp_manager_reg_replace
+    win_reg_stat:
+      path: "{{ permitted_managers_key }}"
+      name: 1
+
+  - name: Assert replace SNMP manager exists and others are replaced
+    assert:
+      that:
+        - snmp_manager_replace is changed
+        - snmp_manager_reg_next_replace.exists == false
+        - snmp_manager_reg_replace.exists
+        - snmp_manager_reg_replace.type == 'REG_SZ'
+        - snmp_manager_reg_replace.value == '192.168.1.10'
+
+  # This task has already been tested
+  - name: Add another SNMP manager before testing removal
+    win_snmp:
+      action: add
+      permitted_managers:
+        - 192.168.1.20
+
+  - name: Remove the replaced SNMP manager
+    register: snmp_manager_remove
+    win_snmp:
+      action: remove
+      permitted_managers:
+        - 192.168.1.10
+
+  - name: Check replace SNMP manager is removed in registry
+    register: snmp_manager_reg_remove
+    win_reg_stat:
+      path: "{{ permitted_managers_key }}"
+      name: 1
+
+  - name: Check SNMP manager that was added for testing removal exists in registry
+    register: snmp_manager_reg_remove_add
+    win_reg_stat:
+      path: "{{ permitted_managers_key }}"
+      name: 2
+
+  - name: Assert removal of SNMP manager succeeded and next SNMP manager remains
+    assert:
+      that:
+        - snmp_manager_remove is changed
+        - snmp_manager_reg_remove.exists == false
+        - snmp_manager_reg_remove_add.exists
+        - snmp_manager_reg_remove_add.type == 'REG_SZ'
+        - snmp_manager_reg_remove_add.value == '192.168.1.20'
+
+  - name: Remove the replaced SNMP manager (again)
+    register: snmp_manager_remove
+    win_snmp:
+      action: remove
+      permitted_managers:
+        - 192.168.1.10
+
+  - name: Check replace SNMP manager is removed in registry (again)
+    register: snmp_manager_reg_remove
+    win_reg_stat:
+      path: "{{ permitted_managers_key }}"
+      name: 1
+
+  - name: Check SNMP manager that was added for testing removal exists in registry (again)
+    register: snmp_manager_reg_remove_add
+    win_reg_stat:
+      path: "{{ permitted_managers_key }}"
+      name: 2
+
+  - name: Assert removal of SNMP manager succeeded and next SNMP manager remains (again)
+    assert:
+      that:
+        - snmp_manager_remove is not changed
+        - snmp_manager_reg_remove.exists == false
+        - snmp_manager_reg_remove_add.exists
+        - snmp_manager_reg_remove_add.type == 'REG_SZ'
+        - snmp_manager_reg_remove_add.value == '192.168.1.20'

test/integration/targets/win_snmp/vars/main.yml

@@ -0,0 +1,3 @@
+---
+  permitted_managers_key: 'HKLM:\System\CurrentControlSet\services\SNMP\Parameters\PermittedManagers'
+  valid_communities_key: 'HKLM:\System\CurrentControlSet\services\SNMP\Parameters\ValidCommunities'