Configuring WinRM on Hyper-V hosts

Configure Windows™ Remote Management to allow the BigFix Inventory server to gather data about virtualization topology of virtual machines installed in your infrastructure.

Before you begin

To retrieve the data that is required to properly calculate PVU, you must be logged in as a local administrator on the Hyper-V host. It is necessary because the Windows Management Instrumentation call that accesses MsCluster namespace requires an administrative account.
Hardcoded and select-only statements are run over WinRM. The obtained data is stored in a database schema. BigFix Inventory does not modify the Hyper-V settings and does not affect it any other way.

About this task

The WinRM service is an implementation of WS-Management specification that enables cooperation between hardware and operating systems that come from different vendors. The BigFix Inventory server connects to this service defined as a VM manager and collects data regarding virtualization hierarchy. Therefore, you must perform the following procedure on each Hyper-V host in your infrastructure, including those that are part of a cluster, to ensure the WinRM service is running and configured to enable communication with the server.

Procedure

Defining HTTP and HTTPS listeners. By default, communication with the WinRM service is disabled because there are no listeners defined. To check whether there are any listeners that are currently defined, type the following command: winrm enumerate winrm/config/listener. If there is no output returned, there are no listeners defined.
1. To define a default HTTP listener, type:
```
winrm quickconfig
```
  The command starts the WinRM service and sets it to start automatically with the system start. It also creates an HTTP listener on the default port (accepting requests from any IP), it defines Internet Connection Firewall exceptions for the service, and it opens the HTTP port. Depending on the version of the WinRM service, the default HTTP port might be 80 or 5985. For more information, see Installation and Configuration for Windows™ Remote Management.
2. To define a listener for secure connection (HTTPS), you must have a valid certificate on the Hyper-V host with a CN that matches the host name that you are using to connect to Hyper-V. You must also create a listener with the CertificateThumbprint of that certificate. For more information, see the Microsoft documentation: http://support.microsoft.com/kb/2019527.. You might be able to create a self-signed certificate for testing purposes, however, you should consult your certificate administrator.
  Note: If an appropriate certificate was not found on the machine, the above command will not work and the following output will be returned The certificate must have a CN matching the host name, be appropriate for Server Authentication, and not be expired, revoked, or self-signed. If there is a need to use a self-signed certificate, you can manually generate it and create the listener by starting the following command:
```
winrm create winrm/config/listener?Address=*+Transport=HTTPS 
@{Hostname=”<the name of your server>”;CertificateThumbprint=”<certificate thumbprint>”}
```
  In this case you have to configure the firewall settings manually.
Enabling WinRM Negotiate authentication scheme. The WinRM service offers several authentication schemes to be used to authenticate the client side. The BigFix Inventory server uses Negotiate authentication scheme, which is enabled by default.
1. To check the current setting of this property, type:
```
winrm get winrm/config/service/auth
```
2. To set the required value of this property, enter:
```
winrm set winrm/config/service/auth @{Negotiate="true"}
```
Setting WinRM AllowUnencrypted property. The server requires the property to be set to "true".
1. To check the current settings, type:
```
winrm get winrm/config/service
```
2. To set the required value of this property, type:
```
winrm set winrm/config/service @{AllowUnencrypted="true"}
```
  Note: Setting this value to "true" does not mean that the sensitive data, such as user names or passwords, will be passed in an unencrypted form over the network. Only the content of the SOAP messages will be sent as a plain text. If this cannot be accepted because of security reasons, define the HTTPS listener and use the secured transport (HTTPS) while defining a VM manager in the BigFix Inventory server so that the TLS protocol will be used to encrypt all the network traffic.
Verifying the listener. After you define the HTTP or HTTPS listener, verify that you can remotely connect to the Hyper-V server.
1. On the Hyper-V server, determine the port on which the Windows Remote Management client for the HTTP or HTTPS transport listens. Type the following command in the Windows command line:
```
winrm enumerate winrm/config/listener
```
  - If the port number is listed in the Port line, the listener was properly created.
  - If you receive an error or there is no information for the transport, the listener was not created properly. Go back to step one, and define the listener again.
2. To verify the listener, type:
```
winrm enumerate winrm/config/listener /r:<transport>://
<Hyper-V_server_name>:<port>/wsman /u:<user_id> /p:<password> /a:Negotiate
```
  Where
  
  <transport>
  
  Is either HTTP or HTTPS.
  
  <Hyper-V_server_name>
  
  Is the host name of the Hyper-V server. If you are using HTTPS, the host name must match the CN in the certificate.
  
  <port>
  
  Is the port number that you obtained in the previous step.
  
  <user_id>
  
  Is the user ID that is used to connect to the Hyper-V server.
  
  <password>
  
  Is the password that is used to connect to the Hyper-V server.
  For example:
```
winrm enumerate winrm/config/listener /r:https://
myhyperv.ibm.com:5986/wsman /u:administrator /p:abc /a:Negotiate
```
Verifying whether the Virtual System Management service is running. To verify that the service that provides Hyper-V management is running, go to Administrator Tools > Services on the Hyper-V server. Look for the service called Hyper-V Virtual Machine Management
- If the service exists, but is not running, start the service.
- If the service does not exist, the Hyper-V host was not configured properly.
Verifying the MsCluster resource. If the server is clustered, verify that you can access the MsCluster namespace. On the Hyper-V server, type the following command into the Windows command line:
```
winrm enumerate wmi/root/MsCluster/* 
-dialect:"http://schemas.microsoft.com/wbem/wsman/1/WQL"
-filter:"SELECT PrivateProperties, Type FROM MsCluster_Resource WHERE Type='Network Name' AND Flags='1'"
```
If this command fails, refer to Microsoft documentation about WMI for MsCluster.
Verifying remote connectivity and the server certificate. To verify remote connectivity and the server certificate, type the following command into the Windows command line:
Restriction: Enter the following command on the Windows command line of the BigFix Inventory server. If the server is not installed on a computer that runs on a Windows operating system, use a computer that is not the Hyper-V host and runs on Windows 2008 or higher.
```
winrm set winrm/config/client @{TrustedHosts="<Hyper-V_server_name>"} 
winrm get winrm/config/client /r:<transport>://
<Hyper-V_server_name>:<port>/wsman /u:<user_id> /p:<password> /a:Negotiate
```
Where

<transport>

Is either HTTP or HTTPS.

<Hyper-V_server_name>

Is the host name of the Hyper-V server. If you are using HTTPS, the host name must match the CN in the certificate.

<port>

Is the port number on which the Windows Remote Management client for the HTTP or HTTPS transport listens.

<user_id>

Is the user ID that is used to connect to the Hyper-V server.

<password>

Is the password that is used to connect to the Hyper-V server.
For example:
```
winrm set winrm/config/client @{TrustedHosts="myhyperv.ibm.com"}
winrm get winrm/config/client /r:https://
myhyperv.ibm.com:5986/wsman /u:administrator /p:abc /a:Negotiate
```
The following error is often returned when a self-signed certificate is used is:
```
WSManFault
Message = The server certificate on the destination computer (myhyperv.ibm.com:5986)
has the following errors: The SSL certificate is signed by an unknown certificate authority.
```
If you receive this error, export the self-signed certificate from the Hyper-V host, and import it on the BigFix Inventory host. For other errors, refer to Microsoft documentation for the returned error code.
Tip: For more information about Hyper-V configuration, see the following document: Hyper-V connection fails CODVM0005E.