PowerShell Agentless monitoring via WinRM
Overview
An alternative method to monitor Microsoft Windows servers is to use agentless monitoring. This is where access is granted to run PowerShell scripts for specific users over a secure channel. The plugins used are stored within Opsview Monitor and sent to the Windows server for execution, with the results being returned. This allows for centrally managing the Windows plugins, and there is no need to keep agent software up-to-date on the target devices.
Installation
By default, Windows hosts will not allow PowerShell remote scripts to run, so it must be enabled. This can be configured manually by the Windows Host administrator or automatically using our recommended way, which is using the following PowerShell script on the Windows Host. You can download the script from the Opsview Downloads page.
Please take the following into account before running the script:
- You should have PowerShell 5.x for PowerShell Agentless monitoring.
- Check your PowerShell version by running
$PSVersionTable.PSVersionwithin a PowerShell terminal.
You must run the ConfigureRemoting.ps1 script with Administrator privileges using a PowerShell terminal. This configures firewall rules, self-signed SSL certificates, and authentication for PowerShell remote access.
PS C:\Users\admin\Downloads> .\ConfigureRemoting.ps1
Ok.
Then, make sure that the PowerShell has been configured successfully by running the command winrm quickconfig.
PS C:\Users\admin\Downloads> winrm quickconfig
WinRM service is already running on this machine.
WinRM is already set up for remote management on this computer.
By default, ports 5985 and 5986 must be opened from the Opsview monitoring server to the Windows host you want to check. WinRM utilizes the HTTP and HTTPS protocols, and they can be configured to use certificates to secure the data in transit.
Test to ensure the service is listening run:
- For HTTP:
netstat -an | findstr 5985 - For HTTPS:
netstat -an | findstr 5986
When using basic authentication with WinRM, the following commands must also be entered on the windows host:
winrm set winrm/config/service/auth '@{Basic="true"}'
winrm set winrm/config/service '@{AllowUnencrypted="true"}'
winrm set winrm/config/client/auth '@{Basic="true"}'
If you see a 500 error (which is a known issue on Windows Server 2016) you may need to install WinRM-IIS-Ext.
Run the following command: Add-WindowsFeature winrm-IIS-Ext.
Test connectivity from the orchestrator and collector to the Windows host. Substitute 0 means the connectivity is good.
- For HTTP:
nc -z -w1 <ip> 5985;echo $? - For HTTPS:
nc -z -w1 <ip> 5986;echo $?
Usage
Opsview 6.0 onwards will have the winrm package installed automatically and have the check_by_winrm.py plugin installed by default. This plugin is used by monitoring plugins to be run on the Windows Host.
check_by_winrm.py usage is as follows:
$ ./check_by_winrm.py
-H <HOST>: The IP address or resolvable name of the Windows host
-P <PORT>: The TCP port for connecting to the Windows host. Defaults to 5985 (HTTP) or 5986 (HTTPS)
-u <USER>: The Windows username; required unless using certificate transport
-p <PASS>: The Windows password; required unless using certificate transport or pre-authenticated kerberos transport
-t <TRANSPORT>: The authentication mechanism. One of: basic|certificate|kerberos|ntlm|credssp
-s <SCHEME>: Either HTTP or HTTPS
-i: Ignore certificate validation errors when using HTTPS
-C <CA_CERT_PATH>: The CA certificate (bundle) to be used for validating the HTTPS certificate on the server
-c <CERT_PATH>: The client certificate when using certificate transport
-k <CERT_KEY_PATH>: The client certificate key when using certificate transport
-D: Whether kerberos delegation should be used (default: False). This enables the PowerShell script to use your Kerberos ticket to jump to other hosts. Only useful when using Kerberos transport.
-r: The read timeout seconds when reading back from the WinRM connection
-o: The operation timeout seconds when waiting for a WinRM operation to complete
<SCRIPT>: The name of the powershell script to execute. This should be either relative to CWD, absolute, or relative to the plugins.d directory
<PARAMS>: The parameters to pass to the powershell script, if required.
Example usage:
$ check_by_winrm.py -H '192.168.16.230' -u 'windows_user' -p 'windows_password' -t 'basic' -s http check_windows_base.ps1 -m cpu_usage
WinRM Host Variables
check_by_winrm.py uses the WINRM_TRANSPORT variables. These variables are:
WINRM_TRANSPORT— authentication transport type. The possible values are: Basic, Certificate, Kerberos, NTLM, or CredSSP.WINRM_TRANSPORT:1— username for Windows user.WINRM_TRANSPORT:2— password for Windows userWINRM_TRANSPORT:3— either HTTP or HTTPS.WINRM_TRANSPORT:4— extra arguments which can be used for any additional arguments forcheck_by_winrm.py.
These should be set on each host that uses check_by_winrm.py
Reload to submit your changes. Any hosts configured with Opspacks that use check_by_winrm.py should now be able to remotely run their PowerShell monitoring plugins. For more information, see Opspacks.