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 Agent Group Policies administrative template, provided in the WEM agent package, adds the Agent Host Configuration policy.
Copy the Agent Group Policies folder provided with the WEM installation package to your WEM domain controller.
Add the .admx files.
- Go to the Agent Group Policies > ADMX folder.
- Copy the two files (Citrix Workspace Environment Management Agent Host Configuration.admx and CitrixBase.admx).
- Go to the
<C:\Windows>\PolicyDefinitionsfolder and then paste the files.
Add the .adml files.
- Go to the Agent Group Policies > ADMX > en-US folder.
- Copy the two files (Citrix Workspace Environment Management Agent Host Configuration.adml and CitrixBase.adml).
- Go to the
<C:\Windows>\PolicyDefinitions\en-USfolder and then paste the files.
In the Group Policy Management Editor window, go to Computer Configuration > Policies > Administrative Templates > Citrix Components > Workspace Environment Management > Agent Host Configuration and configure the following settings:
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,
WEM service does not support proxy servers that require authentication.
Agent service 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.
Discover Citrix Cloud Connector from CVAD service. Lets you control whether the agent discovers Cloud Connector information from the relevant Citrix Virtual Apps and Desktops (CVAD) service deployment if you have not yet configured Cloud Connectors for the agent. The agent then connects to the corresponding Cloud Connector machines.
- This setting is designed for scenarios where the WEM agent is running in a CVAD service deployment.
- This policy setting does not work if Cloud Connectors are configured during agent installation or the Citrix Cloud Connectors policy setting is enabled.
Infrastructure server. Not required for WEM service. Leave state “Not configured.”
VUEMAppCmd extra sync delay. Specifies, in milliseconds, 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 recommended value is 100 through 200. 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 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.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 (,).
- In scenarios where multiple Cloud Connectors are configured, the WEM agent randomly selects from the list a Cloud Connector that is reachable. This design intends to distribute traffic across all Cloud Connectors.
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.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: Restart the machine to complete the installations
Where to go next
If you want to migrate your existing on-premises WEM database into the WEM service, see Migrate.
To directly get started with the WEM service, start the administration console and configure settings there as needed. See Manage.
Prerequisites and recommendations
To ensure that the WEM agent works properly, be aware of the following prerequisites and recommendations:
Verify that the following requirements are met:
The Windows service System Event Notification Service is configured to start automatically on startup.
The WEM agent services Citrix WEM Agent Host Service and Citrix WEM User Logon Service are configured to start automatically on startup.
The agent cache resides in a persistent location whenever possible. Using a non-persistent cache location can cause potential cache sync issues, excessive network data usage, performance issues, and so on.
If the agent cache resides in a non-persistent location, take the following steps before sealing the base image:
- Stop Citrix WEM Agent Host Service.
- Delete the following agent local database files: LocalAgentCache.db and LocalAgentDatabase.db.
Follow the recommendations in this section for a successful agent deployment:
Do not manually operate Citrix WEM Agent Host Service, for example, using logon or startup scripts. Operations such as stopping or restarting Citrix WEM Agent Host Service can stop the Netlogon service from working, causing issues with other applications.
Do not use logon scripts to launch UI-mode or CMD-mode agents. Otherwise, some functionalities might fail to work.
Agent startup behaviors
Citrix WEM Agent Host Service automatically reloads Cloud Connector settings configured through Group Policy after the service starts.
Citrix WEM Agent User Logon Service automatically starts Citrix WEM Agent Host Service if the agent host service does not start during the first logon. This behavior ensures that user configuration is processed properly.
Citrix WEM Agent Host Service automatically performs checks on the following local database files on startup:
LocalAgentDatabase.db. If the virtual machine is provisioned and the local database files are from the base image, the database files are automatically purged.
When Citrix WEM Agent Host Service starts, it automatically verifies that the agent local cache has been recently updated. If the cache has not been updated for more than two configured cache synchronization time intervals, the cache is synchronized immediately. For example, suppose the default agent cache sync interval is 30 minutes. If the cache was not updated in the past 60 minutes, it is synchronized immediately after Citrix WEM Agent Host Service starts.
During installation, the WEM agent installer configures the Windows service System Event Notification Service to start automatically.
The WEM agent installer automatically starts the Netlogon service after the WEM agent upgrade completes.
Agent cache utility options
Citrix WEM Agent Host Service handles setting refresh and cache sync automatically. Use the agent cache utility only in scenarios where there is a need to immediately refresh the settings and synchronize the cache.
Use the command line to run AgentCacheUtility.exe in the agent installation folder. The executable accepts the following command-line arguments:
-help: Displays a list of allowed arguments.
-r: Triggers a cache build or refresh.
-S: Refreshes agent host settings.
-I: Reinitializes the agent cache when used together with the
See the following examples for details about how to use the command line:
- Refresh agent host settings:
- Refresh agent host settings and agent cache simultaneously:
AgentCacheUtility.exe -RefreshSettings -RefreshCache
- Reinitialize the agent cache:
AgentCacheUtility.exe -RefreshCache -Reinitialize
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.exe" <key=value>
- Specify the agent installation location and Citrix Cloud Connectors
"Citrix Workspace Environment Management Agent.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.exe" WaitForNetwork=60