Enabling WinRM for Desktop Director

Enabling WinRM for Desktop Director

book

Article ID: CTX125243

calendar_today

Updated On:

Description

This article contains information about the Desktop Director requirement for Windows Remote Management (WinRM) on the virtual desktop. It also describes how to install WinRM, configuration changes that XenDesktop installer makes, and how to configure WinRM manually. It also outlines the consequences of not installing WinRM.

Note: This article also applies to    Director to ensure that the Director can retrieve data, such as profiles and HDX data from Virtual Delivery Agents (VDAs) earlier than XenDesktop 7.

Background

Desktop Director is a Web-based helpdesk and operations console introduced in XenDesktop 5. When troubleshooting the user or the desktop, it displays real-time information from virtual desktop. It does this by connecting directly to the desktop machine using WinRM.

WinRM is the implementation of Microsoft of the WS-Management protocol and enables remote monitoring using a firewall friendly SOAP-based protocol.

Instructions

Installing WinRM

Desktop Director requires WinRM 1.1 or later installed and enabled on the desktop machine. Citrix strongly recommends upgrading to WinRM 2.0 if WinRM 1.1 is already installed for XP or Vista.

You might be required to install WinRM depending on the operating system as listed in the following table:

Operating System WinRM
Windows 7 WinRM 2.0 installed by default.
Vista WinRM 1.1 installed by default.
Windows XP WinRM not installed by default.

If WinRM is not installed, the XenDesktop installer notifies you. You might either install WinRM before continuing with the install or install WinRM later. If you decide to install WinRM later, you must also configure WinRM. Refer to the following Configuring WinRM section for details.

Configuring WinRM

The XenDesktop installer can automatically enable and configure WinRM for use by Desktop Director.
On the Virtual Desktop Configuration page, select Real Time Monitoring to automatically configure WinRM.
The following are the configuration changes made by the installer:
  • Enable and start the WinRM service.
  • Enable the Windows Firewall exceptions for WinRM, refer to the ports in the following steps.
  • Enable the default WinRM listener - port 80 on WinRM 1.1, port 5985 on WinRM 2.0.
  • On WinRM 2.0, enable the compatibility mode listener - port 80.
If you choose not to configure WinRM automatically using the XenDesktop installer, or install WinRM after running the XenDesktop installer, then these changes can be made manually by running the following commands from an elevated command prompt:
winrm quickconfig
and additionally for WinRM 2.0, run the following command:
winrm set winrm/config/Service @{EnableCompatibilityHttpListener="true"}
Alternatively, you can configure WinRM using Microsoft Group Policy.If WinRM 2.0 is installed for XP and Vista desktop machines, change the WinRM port configuration on Desktop Director in Application Settings to port 5985 only, by completing the following procedure:

  1. Open IIS Manager on the server.

  2. Browse to Sites > Default Web Site > DesktopDirector.

  3. Double-click the Application Settings icon.

  4. Edit the Connector.WinRM.Ports value to only 5985. Remove port 80.

Note: These steps are equivalent to editing the web.config file directly in c:\inetpub\wwwroot\DesktopDirector.

Configuring WinRM using Microsoft Group Policy

If running winrm quickconfig on every XenApp server is not efficient for your site, you can configure WinRM using Microsoft Group Policy.
Note: Settings configured by Group Policy overrides the configuration changes made by the installer or configuration changes made locally on the desktop.
 
Complete the following procedure to configure WinRM using Group Policy:

  1. Set the WinRM service to auto start:

    a.    In the Group Policy Editor, navigate to Computer Configuration> Policies > Windows Settings > Security Settings> System Services.
    b.    Double-click Windows Remote Management (WS-Management) and set it to Automatic.

     

  2.   Create the WinRM listener:

    a.    In the Group Policy Editor, navigate to Computer Configuration >Policies > Administrative Templates > Windows Components > Windows Remote Management (WinRM) > WinRM  Service.
    b.    Double-click Allow automatic configuration of listeners and configure the IPv4 filter to *.
     

  3. Create a firewall exception for WinRM:

    a.    In the Group Policy Editor, navigate to Computer Configuration> Policies > Windows Settings > Security Settings> Windows Firewall with Advanced Security.
    b.    Create an Inbound Rule for WinRM for port 5985.

  4. After configuring the preceding three group policies, restart the server to update the group policies and start the WinRM service.
     

  

Choosing Not to Install or Configure WinRM

If WinRM is not correctly installed and configured on Virtual Desktop, the following information is unavailable in the Desktop Director Machine Details page:
  • Machine: CPU, Memory, Disk, and Personal vDisk information
  • Session: Profile location and load time, Policies and ICA latency
  • HDX Panel
  • Activity: Real-time metrics
User-added image
 
Notes:
  • No other pages of Desktop Director are affected.
  • Desktop Studio is unaffected by WinRM.
     
The user of Desktop Director instead notices an error indicating that the desktop machine is unavailable, as displayed in the following screen shot:
“Failed to retrieve data: Machine unresponsive or reported an error (error code 105). View server event logs for further information.”

 User-added image

Log Name: Application
Source: Citrix Desktop Director Service
Date: 9/14/2011 5:39:23 PM         
Event ID:5
Task Category:None
Level:Error
Keywords:Classic
User: N/A
Computer: xxxxxx5.xxx.com
Description:
Failed to connect to data source 'virtual desktop via WinRM' ('xxxxagents.xxx.xxx.com:5985').

Verify that the data source is available.

User: 'CH2K8\Administrator'
Console operation: 'retrieving desktop performance metric'

Additional diagnostics information, the following error message is displayed:
“Unable to connect to WinRM on the virtual desktop. Verify that WinRM is configured on the desktop, and is listening on the correct port. Error code: -2144108526”

Troubleshooting WinRM

Citrix Support encountered an issue when installing WinRM 2.0 on Windows XP Service Pack 3 before the XenDesktop Virtual Agent was installed.
 
C:\Documents and Settings\administrator.CH2K8.000>winrm quickconfig

WinRM is not set up to receive requests on this machine.
 
The following changes must be made:

  1. Set the WinRM service type to auto start.

  2. Start the WinRM service.

 
Make these changes [y/n]? y

  1. WinRM has been updated to receive requests.

  2. WinRM service type changed successfully.

  3. WinRM service started.

  4. WSManFault

Message = The client cannot connect to the destination specified in the request. Verify that the service on the destination is running and is accepting requests. Consult the logs and documentation for the WS-Management service running on the destination, most commonly IIS or WinRM. If the destination is the WinRM service, run the following command on the destination to analyze and configure the WinRM service: "winrm quickconfig"
 
Error number:  -2144108526 0x80338012
The client cannot connect to the destination specified in the request. Verify that the service on the destination is running and is accepting requests. Consult the logs and documentation for the WS-Management service running on the destination, most commonly IIS or WinRM. If the destination is the WinRM service, run the following command on the destination to analyze and configure the WinRM service: "winrm quickconfig".

Event Type: Error
Event Source: WinRM
Event Category: None
Event ID:10119
Date: 9/22/2011
Time: 4:24:25 AM
User: N/A
Computer:xxxxxAGENTS
Description:
The WinRM service is unable to start because of a failure during initialization.

Additional Data
The error code is 1300.

For more information, see Help and Support Center at http://go.microsoft.com/fwlink/events.asp.
 
WinRM 2.0 was uninstalled from Windows XP Service Pack 3, the system restarted, and WinRM 1.1 was installed. While the WinRM listener created, the service would not start.
 
C:\Documents and Settings\administrator.CH2K8.000>winrm quickconfig
WinRM is not set up to allow remote access to this machine for management.
 

The following changes must be made:

  1. Set the WinRM service type to auto start.

  2. Start the WinRM service.

  3. Create a WinRM listener on HTTP://* to accept WS-Man requests to any IP on this machine.

  4. Enable the WinRM firewall exception.

Make these changes [y/n]? y

  1. WinRM has been updated for remote management.

  2. WinRM service type changed successfully.

  3. WinRM service started.

  4. Created a WinRM listener on HTTP://* to accept WS-Man requests to any IP on this machine.

  5. WinRM firewall exception enabled.
    User-added image


Event Type:Error
Event Source:Service Control Manager
Event Category:None
Event ID:7023
Date:9/22/2011
Time:4:37:19 AM
User:N/A
Computer:xxxxxxAGENTS
Description:
The Windows Remote Management (WS-Management) service terminated with the following error:
Not all privileges referenced are assigned to the caller.

For more information, see Help and Support Center at http://go.microsoft.com/fwlink/events.asp.
 
Fixing the Network Service account permissions allowed the WinRM 1.1 service to start on Windows XP Service Pack 3: See IIS and Built-in Accounts (IIS 6.0)
Citrix Support installed the XenDesktop Virtual Desktop Agent on Windows XP Service Pack 3 and verified that Desktop Director was able to retrieve the data.
Citrix Support then updated WinRM 1.1 to WinRM 2.0 on Windows XP Service Pack 3 without having to do any additional WinRM configuration.
 
In addition, the XenDesktop 5 DDC Event Viewer Application log advises on the DNS name being used by Desktop Director. It might be necessary to configure or modify a different Primary DNS suffix in the properties of the Virtual Desktop Agent.

User-added image

Environment

This software application is provided to you as is with no representations, warranties or conditions of any kind. You may use and distribute it at your own risk. CITRIX DISCLAIMS ALL WARRANTIES WHATSOEVER, EXPRESS, IMPLIED, WRITTEN, ORAL OR STATUTORY, INCLUDING WITHOUT LIMITATION WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, TITLE AND NONINFRINGEMENT. Without limiting the generality of the foregoing, you acknowledge and agree that: (a) the software application may exhibit errors, design flaws or other problems, possibly resulting in loss of data or damage to property; (b) it may not be possible to make the software application fully functional; and (c) Citrix may, without notice or liability to you, cease to make available the current version and/or any future versions of the software application. In no event should the software application be used to support ultra-hazardous activities, including but not limited to life support or blasting activities. NEITHER CITRIX NOR ITS AFFILIATES OR AGENTS WILL BE LIABLE, UNDER BREACH OF CONTRACT OR ANY OTHER THEORY OF LIABILITY, FOR ANY DAMAGES WHATSOEVER ARISING FROM USE OF THE SOFTWARE APPLICATION, INCLUDING WITHOUT LIMITATION DIRECT, SPECIAL, INCIDENTAL, PUNITIVE, CONSEQUENTIAL OR OTHER DAMAGES, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGES. You agree to indemnify and defend Citrix against any and all claims arising from your use, modification or distribution of the software application.

Issue/Introduction

This article describes the Desktop Director requirement for Windows Remote Management (WinRM) on the virtual desktop.
Powered by Wolken Software