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 the group policies (optional)

Optionally, you can choose to configure the group policies for the agent using the Citrix Workspace Environment Management Agent Host Configuration 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:

Group Policy management Editor

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.

Cache synchronization port. The port on which the agent cache synchronization process connects to the infrastructure service to synchronize the agent cache with the infrastructure server. The cache synchronization port must be the same as the port you configured for the cache synchronization port during the infrastructure services configuration. If unspecified, the port defaults to 8285.

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 how long the agent application launcher (VUEMAppCmd.exe) waits before the Citrix Virtual Apps and Desktops published resources start. This setting ensures that the necessary agent work completes first. If unspecified, the delay interval defaults to 0.

Step 2: Install the agent

You can run Citrix Workspace Environment Management Agent Setup 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 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 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.

    WEM agent installation 01

  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.
    • Cache synchronization port. By default, the value is 8285.

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

    WEM agent installation 03

  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 Setup.exe /quiet Cloud=0

Tip:

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: 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. Doing so 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 the command line. The executable accepts these command-line arguments:

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

Step 4: Restart the machine to complete the installation

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

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 Setup.exe <key=value>

For example:

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