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

lib/ansible/modules/windows/win_snmp.ps1

@@ -0,0 +1,126 @@
+#!powershell
+
+# Copyright: (c) 2017, Ansible Project
+# GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
+
+#Requires -Module Ansible.ModuleUtils.Legacy
+
+$params      = Parse-Args -arguments $args -supports_check_mode $true;
+$check_mode  = Get-AnsibleParam -obj $params -name "_ansible_check_mode" -type "bool" -default $false
+$managers    = Get-AnsibleParam -obj $params -name "permitted_managers"  -type "list" -default $null
+$communities = Get-AnsibleParam -obj $params -name "community_strings"   -type "list" -default $null
+$action_in   = Get-AnsibleParam -obj $params -name "action"              -type "str"  -default "set" -ValidateSet @("set", "add", "remove")
+$action      = $action_in.ToLower()
+
+$result = @{
+  failed = $False
+  changed = $False
+  community_strings = [System.Collections.ArrayList]@()
+  permitted_managers = [System.Collections.ArrayList]@()
+}
+
+# Make sure lists are modifyable
+[System.Collections.ArrayList]$managers    = $managers
+[System.Collections.ArrayList]$communities = $communities
+[System.Collections.ArrayList]$indexes     = @()
+
+# Type checking
+# You would think that "$managers -ne $null" would work, but it doesn't.
+# A proper type check is required. If a user provides an empty list then $managers
+# is still of the correct type. If a user provides no option then $managers is $null.
+If ($managers -Is [System.Collections.ArrayList] -And $managers.Count -gt 0 -And $managers[0] -IsNot [String]) {
+  Fail-Json $result "Permitted managers must be an array of strings"
+}
+
+If ($communities -Is [System.Collections.ArrayList] -And $communities.Count -gt 0 -And $communities[0] -IsNot [String]) {
+  Fail-Json $result "SNMP communities must be an array of strings"
+}
+
+$Managers_reg_key    = "HKLM:\System\CurrentControlSet\services\SNMP\Parameters\PermittedManagers"
+$Communities_reg_key = "HKLM:\System\CurrentControlSet\services\SNMP\Parameters\ValidCommunities"
+
+ForEach ($idx in (Get-Item $Managers_reg_key).Property) {
+  $manager = (Get-ItemProperty $Managers_reg_key).$idx
+  If ($idx.ToLower() -eq '(default)') {
+    continue
+  }
+
+  $remove = $False
+  If ($managers -Is [System.Collections.ArrayList] -And $managers.Contains($manager)) {
+    If ($action -eq "remove") {
+      $remove = $True
+    } Else {
+      # Remove manager from list to add since it already exists
+      $managers.Remove($manager)
+    }
+  } ElseIf ($action -eq "set" -And $managers -Is [System.Collections.ArrayList]) {
+    # Will remove this manager since it is not in the set list
+    $remove = $True
+  }
+
+  If ($remove) {
+    $result.changed = $True
+    Remove-ItemProperty -Path $Managers_reg_key -Name $idx -WhatIf:$check_mode
+  } Else {
+    # Remember that this index is in use
+    $indexes.Add([int]$idx) | Out-Null
+    $result.permitted_managers.Add($manager) | Out-Null
+  }
+}
+
+ForEach ($community in (Get-Item $Communities_reg_key).Property) {
+  If ($community.ToLower() -eq '(default)') {
+    continue
+  }
+
+  $remove = $False
+  If ($communities -Is [System.Collections.ArrayList] -And $communities.Contains($community)) {
+    If ($action -eq "remove") {
+      $remove = $True
+    } Else {
+      # Remove community from list to add since it already exists
+      $communities.Remove($community)
+    }
+  } ElseIf ($action -eq "set" -And $communities -Is [System.Collections.ArrayList]) {
+    # Will remove this community since it is not in the set list
+    $remove = $True
+  }
+
+  If ($remove) {
+    $result.changed = $True
+    Remove-ItemProperty -Path $Communities_reg_key -Name $community -WhatIf:$check_mode
+  } Else {
+    $result.community_strings.Add($community) | Out-Null
+  }
+}
+
+If ($action -eq "remove") {
+  Exit-Json $result
+}
+
+# Add managers that don't already exist
+$next_index = 0
+If ($managers -Is [System.Collections.ArrayList]) {
+  ForEach ($manager in $managers) {
+    While ($True) {
+      $next_index = $next_index + 1
+      If (-Not $indexes.Contains($next_index)) {
+        $result.changed = $True
+        New-ItemProperty -Path $Managers_reg_key -Name $next_index -Value "$manager" -WhatIf:$check_mode | Out-Null
+        $result.permitted_managers.Add($manager) | Out-Null
+        break
+      }
+    }
+  }
+}
+
+# Add communities that don't already exist
+If ($communities -Is [System.Collections.ArrayList]) {
+  ForEach ($community in $communities) {
+    $result.changed = $True
+    New-ItemProperty -Path $Communities_reg_key -Name $community -PropertyType DWord -Value 4 -WhatIf:$check_mode | Out-Null
+    $result.community_strings.Add($community) | Out-Null
+  }
+}
+
+Exit-Json $result

lib/ansible/modules/windows/win_snmp.py

@@ -0,0 +1,79 @@
+#!/usr/bin/python
+# -*- coding: utf-8 -*-
+
+# Copyright: (c) 2018, Ansible, inc
+# GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
+
+ANSIBLE_METADATA = {
+    'metadata_version': '1.1',
+    'status': ['preview'],
+    'supported_by': 'community'
+}
+
+DOCUMENTATION = '''
+---
+module: win_snmp
+version_added: '2.8'
+short_description: Configures the Windows SNMP service
+author:
+    - Michael Cassaniti (@mcassaniti)
+description:
+    - This module configures the Windows SNMP service.
+options:
+    permitted_managers:
+        description:
+        - The list of permitted SNMP managers.
+        type: list
+    community_strings:
+        description:
+        - The list of read-only SNMP community strings.
+        type: list
+    action:
+        description:
+        - C(add) will add new SNMP community strings and/or SNMP managers
+        - C(set) will replace SNMP community strings and/or SNMP managers. An
+          empty list for either C(community_strings) or C(permitted_managers)
+          will result in the respective lists being removed entirely.
+        - C(remove) will remove SNMP community strings and/or SNMP managers
+        default: set
+        choices: [ add, set, remove ]
+'''
+
+EXAMPLES = '''
+---
+  - hosts: Windows
+    tasks:
+      - name: Replace SNMP communities and managers
+        win_snmp:
+          communities:
+            - public
+          managers:
+            - 192.168.1.2
+          action: set
+
+  - hosts: Windows
+    tasks:
+      - name: Replace SNMP communities and clear managers
+        win_snmp:
+          communities:
+            - public
+          managers: []
+          action: set
+'''
+
+RETURN = '''
+community_strings:
+    description: The list of community strings for this machine
+    type: list
+    returned: always
+    sample:
+      - public
+      - snmp-ro
+permitted_managers:
+    description: The list of permitted managers for this machine
+    type: list
+    returned: always
+    sample:
+      - 192.168.1.1
+      - 192.168.1.2
+'''