Agent

Install and configure the agent

Note:

• Do not install the Workspace Environment Management (WEM) agent on the infrastructure server.
• Do not install the WEM agent and administration console on the same machine.
• If you intend to assign resources published in Citrix StoreFront stores as application shortcuts in WEM from the administration console, ensure that Citrix Workspace app for Windows is installed on the administration console and the agent host machines. For more information, see System requirements.

Step 1: Configure group policies (optional)

Optionally, you can choose to configure the group policies for the agent using the Agent Group Policies administrative template. The WEM installation package contains this template. The template files are divided into .admx files and language-specific .adml files. We recommend that you configure the group policies on the domain controller.

To add the Agent Host Configuration policy, complete these steps:

1. Copy the Agent Group Policies folder provided with the WEM installation package to your WEM domain controller.

2. Add the .admx files.

   1. Go to the Agent Group Policies > ADMX folder.
   2. Copy the two files (Citrix Workspace Environment Management Agent Host Configuration.admx and CitrixBase.admx).
   3. Go to the <C:\Windows>\PolicyDefinitions folder and then paste the files.

3. Add the .adml files.

   1. Go to the Agent Group Policies > ADMX > en-US folder.
   2. Copy the two files (Citrix Workspace Environment Management Agent Host Configuration.adml and CitrixBase.adml).
   3. Go to the <C:\Windows>\PolicyDefinitions\en-US folder and then paste the files.

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

Infrastructure server. The address of the WEM infrastructure server. Type the name or IP address of the machine where the infrastructure service is installed.

Agent service port. The port on which the agent connects to the infrastructure server. The agent service port must be the same as the port you configured for the agent service port during the infrastructure services configuration. If unspecified, the port defaults to 8286.

Cached data synchronization port. (Applicable to Workspace Environment Management 1912 and later; replaces Cache synchronization port of Workspace Environment Management 1909 and earlier.) The port on which the agent cache synchronization process connects to the infrastructure service to synchronize the agent cache with the infrastructure server. The cached data synchronization port must be the same as the port you configured for the cached data synchronization port (WEM Infrastructure Service Configuration > Network Settings) during the infrastructure services configuration. The port defaults to 8288 and corresponds to the CachedDataSyncPort command-line argument. Alternatively, you can specify the port using a command-line option in the silent installation of the WEM agent. For example:

• citrix_wem_agent_bundle.exe /quiet CachedDataSyncPort=9000

Citrix Cloud Connectors. Not applicable to the on-premises versions of WEM. Leave the state Not Configured.

Agent proxy configuration. Not applicable to the on-premises versions of WEM. Leave the 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 2: Install the agent

Important:

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.

You can run Citrix Workspace Environment Management Agent in your user environment. You can also choose to install the agent using the command line. By default, the agent installs into one of the following folders, depending on your operating system:

• 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 these steps:

1. Run Citrix Workspace Environment Management Agent.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 delay 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 you already installed the WEM agent, the destination folder field automatically populates 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 On-premises Deployment.

   

6. On the Infrastructure Service Configuration page, specify the infrastructure service 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 the Infrastructure Service. Lets you configure the infrastructure service by typing the FQDN or IP address of the infrastructure service.
   • Agent service port. By default, the value is 8286.
   • Cached data synchronization port. By default, the value is 8288.

   

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. Alternatively, you can do that through the registry. To do that, first stop the Citrix WEM Agent Host Service and then modify the following registry key.

     HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\Norskale\Agent Host

     Name: AgentCacheAlternateLocation

     Type: REG_SZ

     Value: Empty

     By default, the value is empty. The default folder is: <WEM agent installation folder path>\Local Databases Set. Specify a different folder path if necessary. For the changes to take effect, restart the Citrix WEM Agent Host Service. If the change takes effect, the following files appear in the folder: LocalAgentCache.db and LocalAgentDatabase.db.

     Caution:

     Editing the registry incorrectly can cause serious problems that might require you to reinstall your operating system. Citrix cannot guarantee that problems resulting from the incorrect use of Registry Editor can be solved. Use Registry Editor at your own risk. Be sure to back up the registry before you edit it.

   • VUEMAppCmd Extra Sync Delay (Optional). Lets you specify how long the agent application launcher (VUEMAppCmd.exe) waits before published resources start. Setting this delay 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.

   

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

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

• "Citrix Workspace Environment Management Agent.exe" /quiet Cloud=0

Tip:

• For agents running in an on-premises WEM deployment, enter Cloud=0. For agents running in a WEM service deployment, enter Cloud=1.
• You might want to consult the log files to troubleshoot the agent installation. By default, log files recording all actions that occur during installation are created in %TEMP%. You can use the /log log.txt command to designate a specific location for the log files to be saved.

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

After installation, the agent runs as Citrix WEM Agent Host Service (formerly Norskale Agent Host Service) and Citrix WEM Agent User Logon Service. The agent runs as account LocalSystem. We do not support changing this account. The service requires the log on as a local system permission.

Step 3: Restart the machine to complete the installation

Prerequisites and recommendations

To ensure that the WEM agent works properly, be aware of the following prerequisites and recommendations:

Prerequisites

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.

Recommendations

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: LocalAgentCache.db and 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.
• -RefreshCache or -r: Triggers a cache build or refresh.
• -RefreshSettings or -S: Refreshes agent host settings.
• -Reinitialize or -I: Reinitializes the agent cache when used together with the -RefreshCache option.

See the following examples for details about how to use the command line:

• Refresh agent host settings:
  • AgentCacheUtility.exe -RefreshSettings
• 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 in the Agent settings and the System settings sections.

Agent settings

The WEM agent settings include:

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

• 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.

• AgentCacheSyncPort. Lets you specify the port on which the agent cache synchronization process connects to the infrastructure service to synchronize the agent cache with the infrastructure server.

• AgentServicePort. Lets you specify the port on which the agent connects to the infrastructure server.

• InfrastructureServer. Lets you specify the FQDN or IP address of the infrastructure server where the infrastructure service is running.

• VUEMAppCmdDelay. Lets you specify how long the agent application launcher (VUEMAppCmd.exe) waits before the Citrix Virtual Apps and Desktops published resources start. 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.

Be aware of the following:

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

• If you don’t configure the settings through the command line and there are previously configured settings, the installer uses the settings that were previously configured.

• If you don’t configure the settings through the command line and there are no previously configured settings, the installer uses the default settings.

System settings

The system settings associated with the agent host machine include:

• 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.

  Important:

  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.

The previous three keys ensure that the WEM agent service starts before the Windows logon screen appears. All three keys are created under HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows NT\CurrentVersion\Winlogon during installation. The keys also 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, extra processing time before the logon screen appears might result. We recommend that you set the value of the GpNetworkStartTimeoutPolicyValue key to a minimum of 30 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 you don’t configure the preceding settings using the command line, the WEM agent installer does not process them during installation.

Examples

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

• "Citrix Workspace Environment Management Agent.exe" <key=value>

For example:

• Choose a silent installation or upgrade of the WEM agent
  • "Citrix Workspace Environment Management Agent.exe" /quiet Cloud=0
• Set user logon network wait time to 60 seconds
  • "Citrix Workspace Environment Management Agent.exe" WaitForNetwork=60