New Module: Write Windows event log entries (win_eventlog_entry) (#27828)

* initial commit for win_eventlog_entry module

* added test module for integration tests and minor documentation fixes

lib/ansible/modules/windows/win_eventlog_entry.ps1

@@ -0,0 +1,106 @@
+#!powershell
+
+# (c) 2017, Andrew Saraceni <andrew.saraceni@gmail.com>
+# GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
+
+#Requires -Module Ansible.ModuleUtils.Legacy.psm1
+
+$ErrorActionPreference = "Stop"
+
+function Test-LogExistence {
+    <#
+    .SYNOPSIS
+    Get information on a log's existence.
+    #>
+    param(
+        [String]$LogName
+    )
+
+    $log_exists = $false
+    $log = Get-EventLog -List | Where-Object {$_.Log -eq $LogName}
+    if ($log) {
+        $log_exists = $true
+    }
+    return $log_exists
+}
+
+function Test-SourceExistence {
+    <#
+    .SYNOPSIS
+    Get information on a source's existence.
+    #>
+    param(
+        [String]$LogName,
+        [String]$SourceName
+    )
+
+    $source_exists = [System.Diagnostics.EventLog]::SourceExists($SourceName)
+
+    if ($source_exists) {
+        $source_log = [System.Diagnostics.EventLog]::LogNameFromSourceName($SourceName, ".")
+        if ($source_log -ne $LogName) {
+            Fail-Json -obj $result -message "Source $SourceName does not belong to log $LogName and cannot be written to"
+        }
+    }
+
+    return $source_exists
+}
+
+$params = Parse-Args $args -supports_check_mode $true
+$check_mode = Get-AnsibleParam -obj $params -name "_ansible_check_mode" -type "bool" -default $false
+
+$log = Get-AnsibleParam -obj $params -name "log" -type "str" -failifempty $true
+$source = Get-AnsibleParam -obj $params -name "source" -type "str" -failifempty $true
+$event_id = Get-AnsibleParam -obj $params -name "event_id" -type "int" -failifempty $true
+$message = Get-AnsibleParam -obj $params -name "message" -type "str" -failifempty $true
+$entry_type = Get-AnsibleParam -obj $params -name "entry_type" -type "str" -validateset "Error","FailureAudit","Information","SuccessAudit","Warning"
+$category = Get-AnsibleParam -obj $params -name "category" -type "int"
+$raw_data = Get-AnsibleParam -obj $params -name "raw_data" -type "str"
+
+$result = @{
+    changed = $false
+}
+
+$log_exists = Test-LogExistence -LogName $log
+if (!$log_exists) {
+    Fail-Json -obj $result -message "Log $log does not exist and cannot be written to"
+}
+
+$source_exists = Test-SourceExistence -LogName $log -SourceName $source
+if (!$source_exists) {
+    Fail-Json -obj $result -message "Source $source does not exist"
+}
+
+if ($event_id -lt 0 -or $event_id -gt 65535) {
+    Fail-Json -obj $result -message "Event ID must be between 0 and 65535"
+}
+
+$write_params = @{
+    LogName = $log
+    Source = $source
+    EventId = $event_id
+    Message = $message
+}
+
+try {
+    if ($entry_type) {
+        $write_params.EntryType = $entry_type
+    }
+    if ($category) {
+        $write_params.Category = $category
+    }
+    if ($raw_data) {
+        $write_params.RawData = [Byte[]]($raw_data -split ",")
+    }
+
+    if (!$check_mode) {
+        Write-EventLog @write_params
+    }
+    $result.changed = $true
+    $result.msg = "Entry added to log $log from source $source"
+}
+catch {
+    Fail-Json -obj $result -message $_.Exception.Message
+}
+
+Exit-Json -obj $result

lib/ansible/modules/windows/win_eventlog_entry.py

@@ -0,0 +1,78 @@
+#!/usr/bin/python
+
+# (c) 2017, Andrew Saraceni <andrew.saraceni@gmail.com>
+# GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
+
+ANSIBLE_METADATA = {'metadata_version': '1.0',
+                    'status': ['preview'],
+                    'supported_by': 'community'}
+
+DOCUMENTATION = r'''
+---
+module: win_eventlog_entry
+version_added: "2.4"
+short_description: Write entries to Windows event logs
+description:
+     - Write log entries to a given event log from a specified source.
+options:
+  log:
+    description:
+      - Name of the event log to write an entry to.
+    required: true
+  source:
+    description:
+      - Name of the log source to indicate where the entry is from.
+    required: true
+  event_id:
+    description:
+      - The numeric event identifier for the entry.
+      - Value must be between 0 and 65535.
+    required: true
+  message:
+    description:
+      - The message for the given log entry.
+    required: true
+  entry_type:
+    description:
+      - Indicates the entry being written to the log is of a specific type.
+    choices:
+      - Error
+      - FailureAudit
+      - Information
+      - SuccessAudit
+      - Warning
+  category:
+    description:
+      - A numeric task category associated with the category message file for the log source.
+  raw_data:
+    description:
+      - Binary data associated with the log entry.
+      - Value must be a comma-separated array of 8-bit unsigned integers (0 to 255).
+notes:
+    - This module will always report a change when writing an event entry.
+author:
+    - Andrew Saraceni (@andrewsaraceni)
+'''
+
+EXAMPLES = r'''
+- name: Write an entry to a Windows event log
+  win_eventlog_entry:
+    log: MyNewLog
+    source: NewLogSource1
+    event_id: 1234
+    message: This is a test log entry.
+
+- name: Write another entry to a different Windows event log
+  win_eventlog_entry:
+    log: AnotherLog
+    source: MyAppSource
+    event_id: 5000
+    message: An error has occurred.
+    entry_type: Error
+    category: 5
+    raw_data: 10,20
+'''
+
+RETURN = r'''
+# Default return values
+'''