Configuring WinRM for Windows Collector

WinRM is Microsoft’s implementation of WS-Management Protocol, a standard SOAP-based firewall friendly protocol that allows hardware and operating systems from different vendors to interoperate. Thus, WinRM provides a way to get management data from a local computer or a remote computer using WS-Management protocol.

Prerequisites

You must meet the following prerequisites to configure and use WinRM to query data.

• You must install EA Collector 35.400 or a later version.
• You must create and enable an HTTPS listener on the Windows devices. See, Creating an HTTPS Listener (port 5986).

Creating Domain User

You can create a new domain user or use an existing domain user. However, ensure that the domain user is not a member of the Administrators group. If you are going to create a new domain user, it is recommended that you first create a domain user and then install the collector using that domain user.

1. Navigate to Server Manager > Tools > Active Directory Users and Computers. 
2. Go to the domain that you want to use for WinRM and right-click Users and select New.
3. Enter the new user details and select Next.
   
4. Enter a password and confirm it, and then select Next.
   
5. Check details and select Finish.
   

Creating an HTTPS Listener (port 5986)

An HTTPS listener must be created and/or enabled on the Windows devices. If you do not have an HTTPS listener created for WinRM, follow the steps given below:

1. Run the command WinRM e winrm/config/listener in cmd_prompt to check if port 5986 is already enabled on WinRM service.
2. Use a certificate signed by a trusted Certificate Authority (CA).

3. Copy the thumb print of the existing certificate and run the following command on PowerShell.
   winrm create winrm/config/Listener?Address=*+Transport=HTTPS '@{Hostname="<YOUR_DNS_NAME>"; CertificateThumbprint="<COPIED_CERTIFICATE_THUMBPRINT>"}‘
4. To verify if the listener is created, run the command WinRM e winrm/config/listener in cmd_prompt to print details of port 5985 and 5986.
5. To add a new firewall inbound rule to allow all connections for port 5986 (TCP), follow these steps:
   1. Search and select the Windows Firewall with Advanced Security option. The Windows Firewall with Advanced Security window is displayed.
   2. In the left navigation, right-click Inbound Rules and select New Rule. The New Inbound Rule Wizard window is displayed.
   3. Select the Port radio button and select Next.
   4. Select the TCP radio button.
   5. Select the Specific local ports radio button and enter 5986 in the blank field. Select Next. 
   6. Select the Allow the connection radio button and select Next.
   7. Select the Domain, Private, and Public checkboxes and select Next.
   8. Enter a rule name in the Name field and select Finish.

Setting Up WinRM Enabled Collector

To setup WinRM enabled collector, follow these steps:

1. Install Windows collector
2. Configure WinRM properties
3. Automate WinRM non-admin configuration
4. Create GPO policy
5. Add WinRM tasks to the GPO policy
6. Restart remote machine

Installing Windows Collector

Follow the instructions given in Installing Collectors to install Windows Collector. Ensure that you install EA Collector 35.400 or a later version.

Configuring WinRM Properties

To use the WinRM data collection feature using HTTP (port 5985), you must configure the following properties.

Restart the collector after you update the configuration files with the properties. 

Automating WinRM Non-admin Configuration

We have automated the WinRM non-admin configuration process by adding Windows_NonAdmin_Config.ps1. You must consider the following points about the scripts:

• The scripts are bundled with the Windows collector installer. 
• After installing collector, go to \LogicMonitor\Agent\bin and move the scripts to the netlogon folder. 
• All the machines in the domain must have access to the netlogon folder in order to access this script when executed through Group Policy (GPO).

In case of access issue, see Microsoft documentation.

Creating GPO Policy

1. Navigate to Server Manager > Tools > Group Policy Management.
2. Right-click the domain you want to use and select Create a GPO in this domain, and Link it here…
   
3. Enter a name for the new GPO policy (for example, WinRM Configuration) and then select OK. Note that the Source Starter GPO will remain (none).
   
4. Right-click the newly created GPO policy and select Edit to add WinRM tasks.
   

Adding WinRM Tasks to GPO Policy

1. In the Group Policy Management Editor, navigate to Computer Configuration > Policies > Windows Settings > Scripts (Startup / Shutdown) and select Startup.
   
   A Startup Properties dialogue box is displayed.
2. Under the Scripts tab select Add.
   
   An Add a Script dialogue is displayed.
3. On the Add a Script dialogue, enter the following details.
   1. In the Script Name field browse for the PowerShell.exe path. Typically, the path is C:\Windows\System32\WindowsPowerShell\v1.0\Powershell.exe
Note: If the path differs, browse for the specific folder where you have placed the Powershell.exe.
   2. In the Script Parameters field enter the following parameters for the script.
      -Noninteractive -ExecutionPolicy Bypass -Noprofile -file \\<IP_Address_of_DC>\netlogon\Windows_NonAdmin_Config.ps1 -add -UserName logicmonitor\DomainUser01
      
4. Select OK and then select Apply.

Restarting Domain Machine

1. Open PowerShell terminal and run gpupdate/force.
   
2. Once the user policy is successfully updated, restart the domain machines.

To manually perform the above setup, see Windows Server Monitoring and Principle of Least Privilege.

Using the Debug Command to Verify Configuration

When the configuration is complete, you can run the !winrm debug command to verify the WinRM setup. In addition, you can run !winrm for any query to get the output. When the debug command runs successfully, it prints the output of the query. The format of the debug command is as follows:

!winrm host=<Computer Name> [auth=<Auth Type>] [useSSL=true|false] [certCheck=true|false] [username=foo] [password=var] [query=winrmquery]

The properties in this debug command are described in the following table:

 The following is an example of a query input:

!winrm host=EC2AMAZ-93376C4.logicmonitor.com auth=Kerberos username=LOGICMONITOR\WinUser01 password=WinPass@123 useSSL=false certCheck=false

Rolling Back WinRM Configuration

You can revert the changes done by the Windows_NonAdmin_Config.ps1 script. Refer the following example:

• -Noninteractive -ExecutionPolicy Bypass -Noprofile -file \\<IP_Address_of_DC>\netlogon\Windows_NonAdmin_Config.ps1 -remove -UserName logicmonitor\ScriptTestUser01

Follow the steps given in Adding WinRM Tasks to GPO Policy section but run the scripts with remove flag to roll back WinRM configuration.

Troubleshooting

WQL filter issue for groovy scripts modules containing wmi.queryfirst() and wmi.queryAll()

WQL filter supports the following 2 formats:

• Format 1 – “select * from win32_bios where NAME LIKE ‘%’” – Double quotes surround the WQL and the clause value is enclosed with single quotes.
• Format 2 – ’select * from win32_bios where NAME LIKE “%” ’- Single quotes surround the WQL and the clause value is enclosed with double quotes.

WinRM (when you set wmi.winrm.enable= true) supports only the format 2. If you have enabled WinRM and if for custom datasource you use the format 1, then you will see errors on calling wmi.queryFirst() / wmi.queryAll() in the groovy script. To avoid the errors, we recommend you to use the format 2.

Intermittent issue – Network path not found

Due to issues with network or domain you may get the “Network path not found” message.

Error Message : Exception calling "Invoke" with "2" argument(s): "The network path was not found.".Exception.Messages

When you find this error message in the logs, to troubleshoot it, reapply the scripts as a fresh task.

To migrate service account to non-admin user separately, see Migrating Windows Collector from Admin to Non-admin User.