Enable -Verbose and log to EventLog (#19909)

Instead of asking the user to type something prior to running the script, why not allow -Verbose on the command line directly.
Also log important events to EventLog, so that it can be traced e.g. when running via RunOnce mechanism.

The documentation is updated as well.

docs/docsite/rst/intro_windows.rst

@@ -211,15 +211,20 @@ To automate the setup of WinRM, you can run `this PowerShell script <https://git
 
 The example script accepts a few arguments which Admins may choose to use to modify the default setup slightly, which might be appropriate in some cases.
 
-Pass the -CertValidityDays option to customize the expiration date of the generated certificate.
+Pass the -CertValidityDays option to customize the expiration date of the generated certificate::
+
     powershell.exe -File ConfigureRemotingForAnsible.ps1 -CertValidityDays 100
 
-Pass the -SkipNetworkProfileCheck switch to configure winrm to listen on PUBLIC zone interfaces.  (Without this option, the script will fail if any network interface on device is in PUBLIC zone)
+Pass the -SkipNetworkProfileCheck switch to configure winrm to listen on PUBLIC zone interfaces.  (Without this option, the script will fail if any network interface on device is in PUBLIC zone)::
+
     powershell.exe -File ConfigureRemotingForAnsible.ps1 -SkipNetworkProfileCheck
 
-Pass the -ForceNewSSLCert switch to force a new SSL certificate to be attached to an already existing winrm listener. (Avoids SSL winrm errors on syspreped Windows images after the CN changes)
+Pass the -ForceNewSSLCert switch to force a new SSL certificate to be attached to an already existing winrm listener. (Avoids SSL winrm errors on syspreped Windows images after the CN changes)::
+
     powershell.exe -File ConfigureRemotingForAnsible.ps1 -ForceNewSSLCert
 
+To troubleshoot the ``ConfigureRemotingForAnsible.ps1`` writes every change it makes to the Windows EventLog (useful when run unattendedly). Additionally the ``-Verbose`` option can be used to get more information on screen about what it is doing.
+
 .. note::
    On Windows 7 and Server 2008 R2 machines, due to a bug in Windows
    Management Framework 3.0, it may be necessary to install this

examples/scripts/ConfigureRemotingForAnsible.ps1

@@ -5,26 +5,33 @@
 # necessary changes to allow Ansible to connect, authenticate and execute
 # PowerShell commands.
 #
-# Set $VerbosePreference = "Continue" before running the script in order to
-# see the output messages.
-# Set $SkipNetworkProfileCheck to skip the network profile check.  Without
-# specifying this the script will only run if the device's interfaces are in
-# DOMAIN or PRIVATE zones.  Provide this switch if you want to enable winrm on
-# a device with an interface in PUBLIC zone.
+# All events are logged to the Windows EventLog, useful for unattended runs.
 #
-# Set $ForceNewSSLCert if the system has been syspreped and a new SSL Cert
-# must be forced on the WinRM Listener when re-running this script. This
-# is necessary when a new SID and CN name is created.
+# Use option -Verbose in order to see the verbose output messages.
+#
+# Use option -SkipNetworkProfileCheck to skip the network profile check.
+# Without specifying this the script will only run if the device's interfaces
+# are in DOMAIN or PRIVATE zones.  Provide this switch if you want to enable
+# WinRM on a device with an interface in PUBLIC zone.
+#
+# Use option -ForceNewSSLCert if the system has been SysPreped and a new
+# SSL Certifcate must be forced on the WinRM Listener when re-running this
+# script. This is necessary when a new SID and CN name is created.
 #
 # Written by Trond Hindenes <trond@hindenes.com>
 # Updated by Chris Church <cchurch@ansible.com>
 # Updated by Michael Crilly <mike@autologic.cm>
 # Updated by Anton Ouzounov <Anton.Ouzounov@careerbuilder.com>
+# Updated by Dag Wieërs <dag@wieers.com>
 #
-# Version 1.0 - July 6th, 2014
-# Version 1.1 - November 11th, 2014
-# Version 1.2 - May 15th, 2015
-# Version 1.3 - April 4th, 2016
+# Version 1.0 - 2014-07-06
+# Version 1.1 - 2014-11-11
+# Version 1.2 - 2015-05-15
+# Version 1.3 - 2016-04-04
+# Version 1.4 - 2017-01-05
+
+# Support -Verbose option
+[CmdletBinding()]
 
 Param (
     [string]$SubjectName = $env:COMPUTERNAME,
@@ -34,6 +41,26 @@ Param (
     [switch]$ForceNewSSLCert
 )
 
+Function Write-Log
+{
+    $Message = $args[0]
+    Write-EventLog -LogName Application -Source $EventSource -EntryType Information -EventId 1 -Message $Message
+}
+
+Function Write-VerboseLog
+{
+    $Message = $args[0]
+    Write-Verbose $Message
+    Write-Log $Message
+}
+
+Function Write-HostLog
+{
+    $Message = $args[0]
+    Write-Host $Message
+    Write-Log $Message
+}
+
 Function New-LegacySelfSignedCert
 {
     Param (
@@ -86,10 +113,21 @@ Trap
     Exit 1
 }
 $ErrorActionPreference = "Stop"
+$EventSource = $MyInvocation.MyCommand.Name
+If ($EventSource -eq $Null)
+{
+    $EventSource = "Powershell CLI"
+}
+
+If ([System.Diagnostics.EventLog]::Exists('Application') -eq $False -or [System.Diagnostics.EventLog]::SourceExists($EventSource) -eq $False)
+{
+    New-EventLog -LogName Application -Source $EventSource
+}
 
 # Detect PowerShell version.
 If ($PSVersionTable.PSVersion.Major -lt 3)
 {
+    Write-Log "PowerShell version 3 or higher is required."
     Throw "PowerShell version 3 or higher is required."
 }
 
@@ -97,26 +135,32 @@ If ($PSVersionTable.PSVersion.Major -lt 3)
 Write-Verbose "Verifying WinRM service."
 If (!(Get-Service "WinRM"))
 {
+    Write-Log "Unable to find the WinRM service."
     Throw "Unable to find the WinRM service."
 }
 ElseIf ((Get-Service "WinRM").Status -ne "Running")
 {
     Write-Verbose "Starting WinRM service."
     Start-Service -Name "WinRM" -ErrorAction Stop
+    Write-Log "Started WinRM service."
     Write-Verbose "Setting WinRM service to start automatically on boot."
     Set-Service -Name "WinRM" -StartupType Automatic
+    Write-Log "Set WinRM service to start automatically on boot."
+
 }
 
 # WinRM should be running; check that we have a PS session config.
 If (!(Get-PSSessionConfiguration -Verbose:$false) -or (!(Get-ChildItem WSMan:\localhost\Listener)))
 {
-  if ($SkipNetworkProfileCheck) {
+  If ($SkipNetworkProfileCheck) {
     Write-Verbose "Enabling PS Remoting without checking Network profile."
     Enable-PSRemoting -SkipNetworkProfileCheck -Force -ErrorAction Stop
+    Write-Log "Enabled PS Remoting without checking Network profile."
   }
-  else {
-    Write-Verbose "Enabling PS Remoting"
+  Else {
+    Write-Verbose "Enabling PS Remoting."
     Enable-PSRemoting -Force -ErrorAction Stop
+    Write-Log "Enabled PS Remoting."
   }
 }
 Else
@@ -133,12 +177,12 @@ If (!($listeners | Where {$_.Keys -like "TRANSPORT=HTTPS"}))
     {
         $cert = New-SelfSignedCertificate -DnsName $SubjectName -CertStoreLocation "Cert:\LocalMachine\My"
         $thumbprint = $cert.Thumbprint
-        Write-Host "Self-signed SSL certificate generated; thumbprint: $thumbprint"
+        Write-HostLog "Self-signed SSL certificate generated; thumbprint: $thumbprint"
     }
     Else
     {
         $thumbprint = New-LegacySelfSignedCert -SubjectName $SubjectName
-        Write-Host "(Legacy) Self-signed SSL certificate generated; thumbprint: $thumbprint"
+        Write-HostLog "(Legacy) Self-signed SSL certificate generated; thumbprint: $thumbprint"
     }
 
     # Create the hashtables of settings to be used.
@@ -152,25 +196,27 @@ If (!($listeners | Where {$_.Keys -like "TRANSPORT=HTTPS"}))
 
     Write-Verbose "Enabling SSL listener."
     New-WSManInstance -ResourceURI 'winrm/config/Listener' -SelectorSet $selectorset -ValueSet $valueset
+    Write-Log "Enabled SSL listener."
 }
 Else
 {
     Write-Verbose "SSL listener is already active."
 
     # Force a new SSL cert on Listener if the $ForceNewSSLCert
-    if($ForceNewSSLCert){
+    If ($ForceNewSSLCert)
+    {
 
         # Create the new cert.
         If (Get-Command "New-SelfSignedCertificate" -ErrorAction SilentlyContinue)
         {
             $cert = New-SelfSignedCertificate -DnsName $SubjectName -CertStoreLocation "Cert:\LocalMachine\My"
             $thumbprint = $cert.Thumbprint
-            Write-Host "Self-signed SSL certificate generated; thumbprint: $thumbprint"
+            Write-HostLog "Self-signed SSL certificate generated; thumbprint: $thumbprint"
         }
         Else
         {
             $thumbprint = New-LegacySelfSignedCert -SubjectName $SubjectName
-            Write-Host "(Legacy) Self-signed SSL certificate generated; thumbprint: $thumbprint"
+            Write-HostLog "(Legacy) Self-signed SSL certificate generated; thumbprint: $thumbprint"
         }
 
         $valueset = @{}
@@ -194,6 +240,7 @@ If (($basicAuthSetting.Value) -eq $false)
 {
     Write-Verbose "Enabling basic auth support."
     Set-Item -Path "WSMan:\localhost\Service\Auth\Basic" -Value $true
+    Write-Log "Enabled basic auth support."
 }
 Else
 {
@@ -207,11 +254,13 @@ If ($fwtest1.count -lt 5)
 {
     Write-Verbose "Adding firewall rule to allow WinRM HTTPS."
     netsh advfirewall firewall add rule profile=any name="Allow WinRM HTTPS" dir=in localport=5986 protocol=TCP action=allow
+    Write-Log "Added firewall rule to allow WinRM HTTPS."
 }
 ElseIf (($fwtest1.count -ge 5) -and ($fwtest2.count -lt 5))
 {
     Write-Verbose "Updating firewall rule to allow WinRM HTTPS for any profile."
     netsh advfirewall firewall set rule name="Allow WinRM HTTPS" new profile=any
+    Write-Log "Updated firewall rule to allow WinRM HTTPS for any profile."
 }
 Else
 {
@@ -238,6 +287,7 @@ ElseIf ($httpResult -and !$httpsResult)
 }
 Else
 {
+    Write-Log "Unable to establish an HTTP or HTTPS remoting session."
     Throw "Unable to establish an HTTP or HTTPS remoting session."
 }
-Write-Verbose "PS Remoting has been successfully configured for Ansible."
+Write-VerboseLog "PS Remoting has been successfully configured for Ansible."