Product Documentation

Installing and Removing the Virtual Desktop Agent

Oct 09, 2015

The Virtual Desktop Agent has to be present on the virtual machines (VMs) and physical machines to which your users will be connecting. It enables the machines to register with controllers and manages the HDX connection between the machines and the user devices.

If you are using XenDesktop or Provisioning Services to provision VMs, you need to install and configure the Virtual Desktop Agent only once, but if you are using separate stand-alone virtual or physical machines you must install it on each of the machines so they can register with the controller to allow user connections.

You can install the Virtual Desktop Agent from a console session or from an RDP session, but installing from an ICA session is not supported.

To install the Virtual Desktop Agent components from the command line, see XenDesktopVdaSetup.exe in the XenDesktop 5 product documentation in the Citrix eDocs Archive.

The AutoSelect.exe file performs a wizard-based installation of the Virtual Desktop Agent:

  1. Run AutoSelect.exe.
  2. On the Installation page, select Install Virtual Desktop Agent.
  3. Associate this desktop with the VM hosted app site.
  4. Configure the agent as follows:
    • Reconfigure the firewall. If the Windows firewall is detected, the necessary ports can be opened automatically for you. If another firewall is detected, you are told which ports you need to open manually. You can also request to have the necessary ports opened for desktop shadowing and Windows Remote Management.
    • If this installation is running in a VM on a hypervisor, select Optimize XenDesktop Performance to have the VM automatically optimized for use with VM hosted apps. Optimization involves actions such as disabling offline files, disabling background defragmentation, and reducing the event log size. For full information on the optimization tool, see the Citrix Knowledge Center.

    A summary of what is going to be installed appears.

  5. When installation is complete the default is to restart the machine; you must do this for the changes to take effect.
Note: When you install the Virtual Desktop Agent, a new local user group for authorized RDP users is automatically created. The group is called Direct RDP Access Administrators. For further information on using protocols other than ICA, see the Citrix Knowledge Center.

VM hosted apps requires desktops and controllers to have synchronized system clocks. This is required by the underlying Kerberos infrastructure that secures the communication between the machines. You can use normal Windows domain infrastructure to ensure that the system time on all machines is correctly synchronized.

To add or remove components, use the Windows control panel. Select Citrix Virtual Desktop Agent. You can then select to add, remove, or reconfigure components, or to remove the Virtual Desktop Agent completely.

The Reconfigure Components option enables you to update the site and port numbers.

To configure firewalls manually

To enable users to connect to virtual desktops, you must configure your virtual desktop firewall as follows:

For communication between user devices and virtual desktops:

  • %Program Files%\Citrix\ICAService\picaSvc.exe requires inbound TCP on port 1494. Because this connection uses a kernel driver, you may need to configure this setting as a port exception rather than a program exception, depending on your firewall software. If you are running Windows Firewall, you must configure this setting as a port exception.
  • %Program Files%\Citrix\ICAService\CitrixCGPServer.exe requires inbound TCP on port 2598.
Note: Citrix recommends that you do not use TCP ports 1494 and 2598 for anything other than ICA and CGP, to avoid the possibility of inadvertently leaving administrative interfaces open to attack. Ports 1494 and 2598 are correctly registered with the Internet Assigned Number Authority (see http://www.iana.org/).

For communication between controllers and virtual desktops:

%Program Files%\Citrix\XenDesktop\WorkstationAgent.exe requires inbound HTTP (http.sys) on the TCP/IP port you configured at installation time. The default port is 80. Because this connection uses a kernel driver, you may need to configure this setting as a port exception rather than a program exception, depending on your firewall software. If you are running Windows Firewall, you must configure this setting as a port exception.

Windows Remote Assistance requires ports TCP/135, TCP/3389, and DCOM. On Windows Vista and Windows 7 desktops you can configure these exceptions by enabling the built-in Remote Assistance exception. On Windows XP you must set additional exceptions:
  1. Enable the Remote Assistance exception.
  2. Add and enable the TCP 135 exception.
  3. Add and enable the "%systemroot%\PCHEALTH\HELPCTR\Binaries\helpsvc.exe" exception.
  4. See http://support.microsoft.com/kb/555179.
Windows Remote Management requires the following ports:
  • TCP/80 for Windows Remote Management 1.1
  • TCP/5985 for Windows Remote Management 2.0

To deploy the Virtual Desktop Agent using Active Directory Group Policy Objects

If you are using Active Directory in your environment, you can deploy the Virtual Desktop Agent to all machines in a domain or Organizational Unit (OU) using Group Policy Objects(GPO).

  1. Create a network share and copy the XDSAgent.msi file from the XenDesktop installation media to that share. Note that you must set permissions on that share to allow read access to the .msi file.
  2. Create a new GPO for the Organizational Unit containing the computers on which you want to deploy the Virtual Desktop Agent.
  3. Edit the GPO you created in Step 2 to add the XDSAgent.msi file, using the following guidelines:
    • Enter the full Universal Naming Convention (UNC) path of the .msi file. For example, \\x-desktop-svr6\SoftwareInstall\XDSAgent.ms
    • Choose Assigned as the deployment method

After you save the new GPO, the Virtual Desktop Agent is installed on computers within the specified OU next time they are restarted.

You can restart computers in the OU remotely by running the #shutdown -r -m command.

For more information about using Active Directory, see the Microsoft Active Directory documentation.

Note: If you deploy the Virtual Desktop Agent using GPO, you must also set the Site GUID using GPO. For more information, see How to Use Group Policy Objects with XenDesktop.