Install and configure
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 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.
Install and configure the WEM agent
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:
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.”
Cached data 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.
Agent proxy configuration. The WEM 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 the WEM settings specific to the agent’s configuration set
Optionally, you can choose to configure an HTTPS proxy to define how the agent communicates with the service. To do so, double-click the Agent proxy configuration policy and then type a proxy server address. For example,
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
Although the .NET Framework can be automatically installed during agent installation, we recommend that you install it manually before you install the agent. Otherwise, you need to restart your machine to continue with the agent installation, and it might take a long time to complete.
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:
- Run Citrix Workspace Environment Management Agent Setup.exe on your machine.
- Select “I agree to the license terms and conditions” and then click Install.
On the Welcome page, click Next.
The Welcome page can take some time to appear. This happens when the required software is missing and is being installed in the background.
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.
On the Deployment Type page, select the applicable type of deployment and then click Next. In this case, select Cloud Service Deployment.
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.
Type the FQDN or IP address of each Citrix Cloud Connector. Make sure to separate the FQDNs or IP addresses with commas (,).
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.
The value you type for the extra sync delay interval must be an integer greater than or equal to zero.
- On the Ready to install page, click Install.
- 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 Workspace Environment Management Agent Setup.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.
See below for the WEM agent settings.
AgentLocation. Lets you specify the agent installation location. 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.
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 the SyncForegroundPolicy registry value during agent installation. This policy setting determines whether Group Policy processing is synchronous. Accepted values: 0, 1. If the value is not set or you set the value to 0, Citrix WEM Agent User Logon Service does not delay logons, and user Group Policy settings are processed in the background. If you set the value to 1, Citrix WEM Agent User Logon Service delays logons until the processing of user Group Policy settings completes. By default, the value does not change during installation.
If Group Policy settings are processed in the background, Windows Shell (Windows Explorer) might start before all policy settings are processed. Therefore, some settings might not take effect the first time a user logs on. If you want all policy settings to be processed the first time a user logs on, set the value to 1.
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.
If the settings above are not configured using the command line, they are not processed by the WEM agent installer during installation.
You can also configure the settings using the following command-line format:
"Citrix Workspace Environment Management Agent Setup.exe" <key=value>
- Specify the agent installation location and Citrix Cloud Connectors
"Citrix Workspace Environment Management Agent Setup.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 Workspace Environment Management Agent Setup.exe" WaitForNetwork=60