Install and configure

Note:

Learn about product name changes here.

Use the following sequence to set up your Workspace Environment Management (WEM) service deployment. Review the entire process before starting the deployment, so you know what to expect. Links are provided to product documentation and videos.

If you are not familiar with the components and terminology used in a WEM service deployment, see Workspace Environment Management service.

Get started

Get started by signing up for a Citrix account and requesting a WEM service trial.

Set up resource locations and install Cloud Connectors

Resource locations contain infrastructure servers (such as Active Directory and Citrix Cloud Connectors), and the machines that deliver apps and desktops to users.

Before you install the WEM agent, you must set up resource locations and install at least one Citrix Cloud Connector in each. For high availability, Citrix recommends that you install two Cloud Connectors in each resource location.

See Resource locations and Cloud Connector Installation.

Install and configure the WEM agent

Note:

  • To configure the WEM agent, you need administrative access to your Active Directory (AD).
  • To access resources published in Citrix StoreFront stores as application shortcuts from the administration console, ensure that Citrix Workspace app for Windows is installed on the agent host machine. For more information, see System requirements.

Step 1: Join agent host machines to AD

Agent host machines must belong to the same AD domain as the configured Cloud Connectors. Ensure that the agent host machines in each resource location are joined correctly.

Step 2: Download the agent

Download the WEM agent package (Citrix-Workspace-Environment-Management-Agent-Setup.zip) from the WEM service Downloads tab and save a copy on each agent host.

Step 3: Configure group policies (optional)

Optionally, you can choose to configure the group policies. The Citrix Workspace Environment Management Agent Host Configuration.admx administrative template, provided in the agent package, adds the Agent Host Configuration policy.

Use the Group Policy Management Editor to configure a GPO with the following settings:

Group Policy management Editor

  • Infrastructure server. Not required for WEM service. Leave state “Not configured.”
  • Agent service port. Not required for WEM service. Leave state “Not configured.”
  • Cache synchronization port. Not required for WEM service. Leave state “Not configured.”
  • Citrix Cloud Connectors. Configure at least one Citrix Cloud Connector. Agent host machines must be in the same AD domain as the configured Cloud Connector machines.
  • VUEMAppCmd extra sync delay. Specifies how long the agent application launcher (VUEMAppCmd.exe) waits before Citrix Virtual Apps and Desktops published resources are started. This ensures that the necessary agent work completes first. The default value is 0.

Step 4: Install the agent

The agent setup program Citrix Workspace Environment Management Agent Setup is provided in the agent download. You can choose to install the agent interactively or using the command line. By default, the agent installs into one of the following folders, depending on your operating system (OS):

  • C:\Program Files (x86)\Citrix\Workspace Environment Management Agent (on 64-bit OS)
  • C:\Program Files\ Citrix\Workspace Environment Management Agent (on 32-bit OS)

To install the agent interactively, complete the following steps:

  1. Run Citrix Workspace Environment Management Agent Setup.exe on your machine.
  2. Select “I agree to the license terms and conditions” and then click Install.
  3. On the Welcome page, click Next.

    Note:

    The Welcome page can take some time to appear. This happens when the required software is missing and is being installed in the background.

  4. On the Destination Folder page, click Next.

    • By default, the destination folder field is automatically populated with the default folder path. If you want to install the agent to another folder, click Change to navigate to the folder and then click Next.
    • If the WEM agent is already installed, the destination folder field is automatically populated with the existing installation folder path.
  5. On the Deployment Type page, select the applicable type of deployment and then click Next. In this case, select Cloud Service Deployment.

    WEM agent installation 01

  6. On the Cloud Service Configuration page, specify the Citrix Cloud Connectors to which the agent connects and then click Next.

    • Skip Configuration. Select this option if you have already configured the setting using Group Policy.
    • Configure Citrix Cloud Connectors. Lets you configure the Citrix Cloud Connectors by typing a comma-separated list of FQDNs or IP addresses of the Cloud Connectors.

    Note:

    Type the FQDN or IP address of each Citrix Cloud Connector. Make sure to separate the FQDNs or IP addresses with commas (,).

    WEM agent installation 02

  7. On the Advanced Settings page, configure advanced settings for the agent and then click Next.

    • Alternative Cache Location (Optional). Lets you specify an alternative location for the agent cache. Click Browse to navigate to the applicable folder.
    • VUEMAppCmd Extra Sync Delay (Optional). Lets you specify how long the agent application launcher (VUEMAppCmd.exe) waits before published resources are started. This ensures that the necessary agent work completes first. The default value is 0.

    Note:

    The value you type for the extra sync delay interval must be an integer greater than or equal to zero.

    WEM agent installation 03

  8. On the Ready to install page, click Install.
  9. Click Finish to exit the install wizard.

Alternatively, you can choose a silent installation of the WEM agent using the command line. To do so, use the following command line:

  • citrix_wem_agent_bundle.exe /quiet Cloud=1

You can also use command-line options to specify custom arguments. Doing so lets you customize agent and system settings during the installation process. For more information, see Good to know.

After installation, the agent runs as the following services: Citrix WEM Agent Host Service and Citrix WEM Agent User Logon Service. The agent runs as account LocalSystem. Changing this account is not supported. The agent services require the “log on as a local system” permission.

Step 5: Build the agent service cache (optional)

By default, the agent service cache is built the first time the agent runs. You can choose to build the agent service cache before the agent runs. This is useful if you want to build an image that includes the WEM agent host as pre-installed software.

To build or rebuild the agent service cache, run AgentCacheUtility.exe in the agent installation folder using command line. The executable accepts the following command-line arguments:

  • -help: displays a list of allowed arguments
  • -refreshcache or -r: triggers a cache build or refresh

Step 6: Restart the machine to complete the installation

Good to know

The agent executable accepts custom arguments as described below.

Agent settings

See below for the WEM agent settings.

  • AgentLocation. Lets you specify the agent installation location. You must specify a valid folder path.

  • CloudConnectorList. Lets you specify the FQDN or IP address of each Citrix Cloud Connector. Make sure to separate FQDNs or IP addresses with commas (,).

  • VUEMAppCmdDelay. Lets you specify how long the agent application launcher (VUEMAppCmd.exe) waits before Citrix Virtual Apps and Desktops published resources are started. The default value is 0 (milliseconds). The value you type for the extra sync delay interval must be an integer greater than or equal to zero.

  • AgentCacheLocation. Lets you specify an alternative location for the agent cache. If configured, the agent local cache file is saved in the designated location instead of in the agent installation folder.

Be aware of the following:

  • If the settings are configured through the command line, the WEM agent installer uses the configured settings.

  • If the settings are not configured through the command line and there are previously configured settings, the installer uses the settings that were previously configured.

  • If the settings are not configured through the command line and there are no previously configured settings, the installer uses the default settings.

System settings

See below for the system settings associated with the agent host machine.

  • GpNetworkStartTimeoutPolicyValue. Lets you configure the value, in seconds, of the GpNetworkStartTimeoutPolicyValue registry key created during installation. This argument specifies how long Group Policy waits for network availability notifications during policy processing on logon. The argument accepts any whole number in the range of 1 (minimum) to 600 (maximum). By default, this value is 120.

  • SyncForegroundPolicy. Lets you configure whether the SyncForegroundPolicy registry key created during installation is active. This argument configures the agent host to wait for a complete network initialization before allowing a user to log on. Accepted values: 0, 1. If not specified, the key is not created during installation.

  • WaitForNetwork. Lets you configure the value, in seconds, of the WaitForNetwork registry key created during installation. This argument specifies how long the agent host waits for the network to be completely initialized and available. The argument accepts any whole number in the range of 0 (minimum) to 300 (maximum). By default, this value is 30.

All three keys above are created under HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows NT\CurrentVersion\Winlogon during installation. The keys serve to ensure that the user environment receives the infrastructure server address GPOs before logon. In network environments where the Active Directory or Domain Controller servers are slow to respond, this might result in extra processing time before the logon screen appears. Citrix recommends that you set the value of the GpNetworkStartTimeoutPolicyValue key to a minimum of 30 in order for it to have an impact.

  • ServicesPipeTimeout. Lets you configure the value of the ServicesPipeTimeout registry key. The key is created during installation under HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control. This registry key adds a delay before the service control manager is allowed to report on the state of the WEM agent service. The delay prevents the agent from failing by keeping the agent service from launching before the network is initialized. This argument accepts any value, in milliseconds. If not specified, a default value of 60000 (60 seconds) is used.

    Note:

    If the settings above are not configured using the command line, they are not processed by the WEM agent installer during installation.

Examples

You can also configure the settings using the following command-line format:

  • citrix_wem_agent_bundle.exe <key=value>

For example:

  • Specify the agent installation location and Citrix Cloud Connectors
    • citrix_wem_agent_bundle.exe /quiet AgentLocation=”L:\WEM Agent” Cloud=1 CloudConnectorList=cc1.qa.local,cc2.qa.local
  • Set “user logon network wait time” to 60 seconds
    • citrix_wem_agent_bundle.exe WaitForNetwork=60

Configure HTTPS proxy for the agent

The WEM service agent relies on internet connections to connect to the WEM service in Citrix Cloud. The communication between the agent and the service serves the following purposes:

  • Uploading statistics and status to the WEM service
  • Keeping the agent cache in sync with the WEM service database
  • Retrieving the agent settings and WEM settings specific to the agent’s configuration set

You can optionally choose to configure an HTTPS proxy to define how the agent communicates with the service. To do so, complete the following steps:

  1. On the agent host, locate the C:\Program Files (x86)\Norskale\Norskale Agent Host\Norskale Agent Host Service.exe.config file.
  2. Open the file in Notepad, customize it to reflect your specifics, and then add it to all applicable sections as in the example below:
    <netHttpBinding>
     <binding name="Cloud_IAgentBrokerService" sendTimeout="00:10:00"
      allowCookies="true" maxBufferPoolSize="2147483647" maxBufferSize="2147483647"
      maxReceivedMessageSize="2147483647" proxyAddress="http://10.108.125.51:8080" useDefaultWebProxy="false">
      <readerQuotas maxDepth="2147483647" maxStringContentLength="2147483647"
       maxArrayLength="2147483647" maxBytesPerRead="2147483647" maxNameTableCharCount="2147483647" />
      <reliableSession enabled="true" />
      <security mode="Transport" />
     </binding>
     <binding name="Cloud_IAgentLocalCacheSyncContract" sendTimeout="00:10:00"
      allowCookies="true" maxBufferPoolSize="2147483647" maxBufferSize="2147483647"
      maxReceivedMessageSize="2147483647" proxyAddress="http://10.108.125.51:8080" useDefaultWebProxy="false">
      <readerQuotas maxDepth="2147483647" maxStringContentLength="2147483647"
       maxArrayLength="2147483647" maxBytesPerRead="2147483647" maxNameTableCharCount="2147483647" />
      <reliableSession enabled="true" />
      <security mode="Transport" />
     </binding>
    </netHttpBinding>