- Home
- /
- Article
Thanks for your feedback.
Deployment guide for Webex App for Virtual Desktop Infrastructure (VDI)
In this article
Feedback?New and changed information
New and changed information
This table covers content updates related to new features or functionality, changes to existing content, and any major errors that were fixed in the Deployment guide for Webex App for Virtual Desktop Infrastructure (VDI).
For more information about Webex App VDI updates, new features, added VDI support, and limitations, see the VDI release notes.
|
Date |
Changes made |
|---|---|
|
November 13, 2023 |
Prepare your environment:
|
|
August 23, 2023 |
Throughout document:
Prepare your environment:
Deploy Webex App for VDI:
Manage and troubleshoot Webex App for VDI:
|
|
May 18, 2023 |
Clarified the note about Azure Virtual Desktop in Full-featured meetings requirements. AVD does not support full-featured meetings. |
|
April 17, 2023 |
New content about disabling the VDI version compatibility check, in Manage and troubleshoot Webex App for VDI. Updated supported infrastructure and OS versions for the 43.4 (April 2023) release, in Hosted virtual desktop and thin client requirements. |
|
March 15, 2023 |
|
|
March 3, 2023 |
|
|
February 27, 2023 |
Added recommendation to synchronize some
|
|
January 11, 2023 |
Added latest tested infrastructure and thin client OS versions and supported hardware in the Hosted virtual desktop and thin client requirements. Includes Apple M2 chip, macOS Ventura, HP ThinPro 8, and Dell ThinOS 9.3. |
|
October 26, 2022 |
Updated |
|
August 25, 2022 |
Updated for Webex App VDI version 42.8:
Updated description for |
|
May 30, 2022 |
|
|
April 26, 2022 |
|
|
April 25, 2022 |
|
|
April 13, 2022 |
|
|
February 9, 2022 |
|
|
February 3, 2022 |
|
|
December 15, 2021 |
|
|
November 12, 2021 |
|
|
October 29, 2021 |
|
|
October 8, 2021 |
|
|
August 10, 2021 |
|
|
July 6, 2021 |
|
|
June 3, 2021 |
Updates for June (41.6) release, including the following:
Other general updates:
|
|
May 3, 2021 |
|
|
April 16, 2021 |
|
|
April 9, 2021 |
|
|
January 18, 2021 |
|
|
December 11, 2020 |
|
|
September 29, 2020 |
|
|
July 16, 2020 |
|
|
June 29, 2020 |
|
Overview
Webex App for VDI overview
Without optimization, Webex App messaging works as-is in a Virtual Desktop Infrastructure (VDI) environment. However, the full Webex App experience also includes calling and meetings, which require video and audio media processing.
Because of a limitation known as the hairpin effect, calling, meeting, and accompanying video capability are not supported without optimization. The additional bandwidth required for calls and video creates a bottleneck at the data center because the media flows from one user to the data center back to another user. As a result of this unoptimized media path and the lack of easy access to peripherals such as device speakers, microphone, and camera, the user experience is not ideal.
To fix the issue of the hairpin effect, the Webex App VDI plugin extends the Cisco collaboration experience to virtual deployments so that users can use the full messaging, meeting, and calling functionality that the Webex App provides.
To reduce latency and to enhance media quality, the VDI plugin optimizes the media workflows by streaming media directly between users on thin client endpoints and leverages the hardware of the thin client machines to handle media processing. This media path does not go through the hosted virtual desktops (HVDs). The result is a stable and full-featured calling and meeting experience for your VDI users.
In this architecture, the Webex App is installed on the HVD in your VDI environment and required VDI plugins are installed on the user's thin client (typically a lightweight system, like a repurposed laptop or desktop).
Using a supported Linux, Mac, or Windows-based thin client, users access the Webex App on the HVD from a remote virtual desktop environment. With supported versions of Webex App, users can use all of the built-in messaging, meetings, and calling on Webex App functionality on their thin client. Additionally, you can integrate Webex App VDI with a Unified CM or Webex Calling environment, so that users can use supported call features.
-
The Webex App on the virtual desktop still processes lightweight data such as call signaling and retrieving configuration from the cloud.
-
For Linux thin clients, you must install the Webex Meetings VDI plugin alongside the Webex App VDI plugin.
For new features for each release, see the release notes for more information.
VDI environment overview
VDI components
Using Webex App in an optimized virtual environment requires the following components.
-
Connection broker—The resource and connection manager (Citrix, VMware) that connects the virtualization provider to the thin client.
-
Hosted virtual desktop (HVD)—The Virtual Machine (VM) that runs the Webex App remotely.
-
Thin client—The endpoint (for example, low profile or repurposed desktop or laptop) that the user uses to sign in remotely to the virtual desktop. The connection broker and VDI plugin are installed on the thin client device so it can access the HVD environment.
-
Plugin—Software that is installed on the thin client used to offload media processing to the user device instead of HVD resources. The supported versions of the Webex App VDI plugin are linked from the Downloads tab of the Webex App VDI release notes.
For Linux thin clients, you must install the Webex Meetings VDI plugin alongside the Webex VDI plugin.
-
Webex App—The app that is installed and runs on the HVD. The supported versions for the HVD installer are available on the Downloads tab of the Webex App VDI release notes.
Environment types
-
Persistent mode—In a persistent environment, a user's local operating system changes are preserved after a user signs out.
All user preferences are in the roaming database (
spark_roaming_store.db). This database is much smaller than the main db (spark_persistent_store.db). -
Non-persistent mode—In a non-persistent environment, a user' local operating system changes are not preserved after a user signs out. The applicable user-specific information (user data, profile, and settings) is cached during the user session.
If you are a non-persistent VDI customer (a VDI environment that is deleted everytime the user logs out), you can quickly back up and restore
spark_roaming_store.dbso that VDI users won't lose preferences between sessions.The roaming database contains all user credentials and preferences, encrypted using AES256. As a VDI customer, you should always back up the roaming database, so that user credentials and preferences are maintained across VDI sessions.
Architecture
The architecture diagrams show the components, signaling, and optimized media flows that are involved in a typical Webex App VDI deployment with an existing supported call service deployment: either Unified CM, Webex Calling, or BroadWorks.
On the left of each diagram is your corporate network which contains the virtual environment. This virtual environment lightens the load on the user-side hardware by running the apps, the operating system, and user data the virtual data center. With that framework, you can manage the environment from a central location and users can access it remotely from supported thin clients.
The components in the corporate network consist of the Hosted Virtual Desktop (HVD), the central environment you manage where the Webex App is installed and runs, and a virtual channel connection (through the Cisco HVDAgent) to the user's thin client endpoint.
On the thin client, users install the Webex VDI plugin and sign into a connection broker (Citrix or VMware), a piece of software that creates connections to HVDs. A connection broker performs a number of tasks including the following:
-
Validating the username and providing a connection for the user.
-
Allowing the user to connect to a specific virtual desktop.
Once signed in, the thin client endpoint simulates interactions with applications and an operating system through peripherals such as a monitor, keyboard, mouse, USB devices, and so on, as if the software were installed on the thin client itself. Users use a thin client app on this endpoint to access Webex App on the remote server.
This architecture optimizes the direction of signaling and media. It communicates over HTTPS, WSS, and SIP for signaling with the Webex cloud or BroadWorks cloud (on the right side). Separate media streams for meetings (Webex App) and calling (Unified CM, Webex Calling, or BroadWorks) are established through SRTP.
You must update the Webex App on the HVD. New versions are released every two months and have backwards compatibility with previous thin client VDI plugins. New thin client VDI plugin builds are also made available every two months. Download the software and see the release notes for more information about version compatibility.
Webex VDI with Unified CM
Webex VDI with Unified CM and Expressways for MRA
The Expressways in the diagram are used to represent a Mobile and Remote Access (MRA) deployment. For MRA to work with Webex App VDI, the HVD must be able to send requests to the Expressway-E, which is typically configured in the DMZ.
Webex App VDI with Webex Calling
Webex VDI with Webex for BroadWorks
Webex App VDI with Meetings
Fallback mode
Webex App VDI fallback mode offers short-term support for basic audio and video calls when VDI can't establish the virtual channel. Fallback mode supports standard calls and call recording. The full feature set isn't supported. Call quality is lower because of the server or network issues that cause the switch to fallback mode.
Prepare Your Environment
Webex App VDI login flow
The Webex App VDI architecture consists of two primary components: the Webex App for VDI and the Webex VDI plugin for the thin client. The VDI plugin is installed on a thin client while the app is installed on the HVD.
When a user launches a virtual broker-client (Citrix Workspace app or VMWare Horizon Client), the vendor's software initiates a virtual channel. The Webex App plugin and agent use this virtual channel to communicate.
This diagram shows the expected protocol sessions that are set up during normal Webex App use when deployed with Unified CM calling over Mobile and Remote Access (MRA).
Although the diagram depicts Webex App VDI over MRA, the flow is the same as an on-premises VDI deployment. However, unlike VDI over MRA, on-premises deployments don't route traffic through the DMZ and all the traffic resides on the LAN.
-
To start a session, users first launch their virtual broker-client (Citrix Workspace App or VMware Horizon Client),connect to the connection broker, and then select an HVD or virtual application. Once selected, a virtual channel is set up between the user's thin client (physical machine) and the HVD (virtual machine) hosted on the Hypervisor.
-
After a user launches the Webex App on the HVD, Webex determines if it is in a virtual environment and if Unified CM is used for phone service. If Unified CM is enabled, the Webex App starts the
teamshvdagent.exeprocess and begins internal service discovery. (The internal service discovery includes the UDS DNS SRV lookup, Unified CM authentication, home cluster lookup, and configuration retrieval.) -
The Webex App client and Webex App VDI plugin then go set up all the control streams that are used to exchange data over the virtual channel. After these channels are set up, the Webex App client sends the voice service domain information to the Webex App VDI plugin.
-
Next, the Webex App VDI plugin performs service discovery. The Webex App VDI plugin does this by referencing the voice service domain information that was sent to it from the Webex App client. In this scenario, the Webex App VDI plugin resolves the _collab-edge DNS SRV record because the VDI plugin machine is connecting from an external network, therefore needing to connect over MRA. Once service discovery is complete, Webex App VDI plugin sends the Expressway-E FQDN to the Webex App client.
-
After receiving and caching the Expressway-E FQDN, the Webex App (HVD) then performs a DNS A record lookup for the Expressway-E FQDN. For a single NIC deployment, this step retrieves the Expressway-E's IP address (internal IP with split DNS or external IP without split DNS), which is used for Edge configuration and SSO authentication over port 8443.
If Expressway-E is set up in a dual NIC deployment, both interfaces can have an internal IP address. In this case, the internal interface is the opposite of what's configured for the external interface.
-
After the Edge details are retrieved, the Webex App (HVD) establishes HTTPS connections to the Expressway-E IP for UDS and TFTP requests. Through this process, the Webex App (HVD) authenticates and retrieves configuration details, such as Soft-phone Device Config, Application Dial Rules, and Directory Lookup Dial Rules.
-
The Webex VDI plugin resolves the Expressway-E external IP and then sends to the Webex App (HVD). Through the device information that is retrieved in the previous step, Webex App begins the CSF device (Windows desktop) registration through the Expressway-E external interface.
Hosted virtual desktop and thin client requirements
Make sure your VDI environment meets the requirements for the supported servers (Hosted Virtual Desktop (HVD), where the Webex app is installed) and thin clients (user-side device where the Webex VDI plugins are installed).
For users joining Webex meetings from Webex App, please refer to Hosted virtual desktop and thin client requirements for Webex meetings VDI.
Hosted virtual desktop
|
VDI component |
Supported platforms |
|---|---|
| Single-session operating system—Installed on the HVD |
|
|
Multi-session operating system—Installed on the HVD |
|
|
Multi-session cloud virtualization service |
|
| Connection broker for the hosted virtual desktop |
A connection broker is software that creates connections to hosted virtual desktops. A connection broker performs a number of tasks including the following:
|
Windows thin clients
|
VDI component |
Supported platforms |
|---|---|
| Microsoft Windows-based thin client hardware |
Supported Hardware
If you want users to use virtual backgrounds, you must meet the virtual background requirements. (Webex App for VDI has the same requirements as the Windows standalone app.) Supported Software We support 64-bit architectures for the following Windows versions:
|
| Windows Embedded Standard-based thin client hardware |
Supported Hardware Installed RAM 2 GB Free Physical Memory 128 MB Free Disk Space 256 MB CPU performance affects the maximum video resolution. With Windows Embedded Standard thin clients, the expected resolution depends on the CPU:
These hardware specifications are only guidelines for the expected resolutions. Other factors can affect video resolution. DirectX 11 compatible GPU USB 2.0 for USB camera and audio devices Supported Software
|
|
Citrix Workspace app or VMware Horizon client |
|
Linux thin clients
|
VDI component |
Supported platforms |
|---|---|
| Thin Client OS |
Ubuntu (64-bit)
|
|
Unicon eLux (64-bit)
|
|
|
HP ThinPro 7.1 (End of life) HP ThinPro 8.0, 8.1 (64-bit)
|
|
|
IGEL OS
The Webex VDI plugin is packaged with IGEL OS. Because of this
third-party integration, you must contact IGEL for technical
support. For more information, see the IGEL OS documentation
for your supported release; the |
|
|
Dell Wyse ThinOS
Specific versions of the Webex VDI plugin are supported with Dell Wyse ThinOS. Because of this third-party integration, you must contact Dell for technical support. For more information, see the Dell Wyse ThinOS documentation for your supported release; the |
|
|
10ZiG Zero Client Thin Clients Specific versions of the Webex VDI plugin are supported with 10ZiG zero client thin clients. Because of this third-party integration, you must contact 10ZiG for technical support. For more information, see the 10ZiG page for your specific thin client. |
|
|
Stratodesk NoTouch OS Specific versions of the Webex VDI plugin are supported with Stratodesk NoTouch OS. Because of this third-party integration, you must contact Stratodesk for technical support. For more information, see the Stratodesk NoTouch OS documentation for your supported release. |
|
| Ubuntu/Thinpro Thin Clients Hardware |
The minimum hardware requirements for thin clients are as follows:
If you want users to use virtual backgrounds, you must meet the virtual background requirements. (Webex App for VDI has the same requirements as the Windows standalone app.) |
| eLux RP 6 Thin Clients Hardware |
Minimum hardware requirements The following system properties enable using basic eLux RP 6 features.
If you want users to use virtual backgrounds, you must meet the virtual background requirements. (Webex App for VDI has the same requirements as the Windows standalone app.) |
| Tested and Recommended Devices |
* Based on hardware requirements, these devices are not recommended for use with virtual backgrounds. See virtual background requirements for more information. (Webex App for VDI has the same requirements as the Windows standalone app.) |
|
Citrix Workspace app or VMware Horizon client |
|
macOS thin clients
|
VDI component |
Supported platforms |
|---|---|
| MacOS-based thin client hardware |
Supported hardware
Intel Core 2 Duo or later processors on any of the following Apple hardware:
If you want users to use virtual backgrounds, you must meet the virtual background requirements. (Webex App for VDI has the same requirements as the Windows standalone app.) Supported software The Webex App VDI plugin is supported on the following macOS versions:
|
|
Citrix Workspace app or VMware Horizon client |
|
Webex App and plugin requirements
-
Get the necessary install builds of the Webex App (installed on HVD) and Webex App plugin (installed on a user's thin client machine) from the Downloads tab of the Webex App VDI release notes.
-
While we support backwards compatibility, as outlined in the release notes, we recommend that you use the latest versions of the install builds wherever possible.
-
For users joining Webex meetings from Webex App, please refer to Hosted virtual desktop and thin client requirements for Webex meetings VDI.
-
VDI users typically do not have admin control over their machine and the plugin does not require admin privileges. However, if your users require Outlook integration, you must register the office integration .dll file using the directions in Enable users' status to display in Microsoft Outlook.
Headset Requirements
For Webex App VDI, we support the same headsets as the standalone Webex App unless otherwise noted. See Details about headset support for more information.
Supported realtime media workflows for calling and meetings
Webex App VDI supports the following realtime media workflows:
-
Calls on Webex (built into the app)
-
Unified CM
-
Webex Calling
-
Webex for BroadWorks
-
Webex Meetings
To integrate a supported calling service and Webex Meetings, you must follow configuration steps in the documentation for those solutions. Choose an option and then use the documentation that is linked in that section.
Unified CM requirements
If you want to use Unified CM as your call service for Webex App VDI users, use the Deployment Guide to walk through the required configuration steps. The document contains an overview of the service, prerequisites, and deployment steps.
Move a call to a meeting
To support this feature, make sure you've configured your Unified CM calling deployment correctly.
Additionally, make sure the following VDI configuration is in place so that offloading to meetings is supported: Full-featured meetings requirements.
Mobile and Remote Access (MRA)
Mobile and Remote Access (MRA) is supported. Follow the standard MRA deployment steps in the Expressway MRA documentation and keep the following points in mind for a supported VDI deployment:
-
See Mobile and Remote Access (MRA) requirements for more guidance for VDI support.
-
You must run a minimum of X12.7 and later.
-
Dual NIC deployments are supported. You must ensure there's a connection from the HVD to both the external and internal IP addresses of the Expressway-E. You must add a NAT between the HVD and the external IP of the Expressway-E.
Webex Calling requirements
If your HVD supports IPv4 and IPv6, we recommend that you disable IPV6 in your HVD environment to prevent compatibility issues with Webex Calling.
Configuration in Control Hub (partners and administrators)
Control Hub ( https://admin.webex.com) is a web-based management portal that integrates withWebex Calling to streamline your orders and configuration, and centralize your management of the bundled offer—Webex Calling, Webex App, and Meetings.
As a partner service provider, you can brand, market, and sell Webex Calling to your customers. You can set up and extend trials, deploy services for your customers, and create and provision orders for your customers. For more partner resources, see the Webex Calling Sales Connect resources. (Requires partner credentials).
As a customer administrator on a trial or paid subscription to Webex Calling, you can set up your organization in the Control Hub by adding locations, licenses, phone numbers, calling features, users, and Workspaces (Room Devices that register to the Webex cloud).
Make sure that your environment supports Webex Calling by following the prerequisites and port reference material before you start specific configuration steps in the Control Hub. You can refer to the following configuration work flow diagram and the article links, in the order presented, to get your organization up and running with Webex Calling:
For more information on the Webex Calling offer, see Cisco Webex Calling in the Cisco Collaboration Flex Plan for End Customers Data Sheet.
Webex for BroadWorks requirements
The Webex App in a VDI environment supports Webex for BroadWorks. Webex for BroadWorks is an offer that integrates BroadWorks Calling in Webex. Subscribers use a single application (the Webex App) to take advantage of features provided by both platforms.
For general information about Webex for BroadWorks, see the Webex for BroadWorks Solution Guide.
Full-featured meetings requirements
Keep these points in mind when deploying Webex App VDI for full-featured meetings:
-
Install the Webex App onto the Hosted Virtual Desktop (HVD).
-
You must install Webex App VDI plugin for users joining full-featured Webex meetings.
Refer to Hosted virtual desktop and thin client requirements for Webex meetings VDI.
-
For Linux thin clients, you must also install the Webex Meetings VDI plugin for Linux (see Install Webex Meetings VDI plugin on thin client systems).
Mobile and Remote Access (MRA) requirements
Prerequisites
-
You must run a minimum of Expressway X12.7 for the traversal pair for MRA to work with Webex VDI. Earlier versions must be upgraded to X12.7 or later to avoid routing issues.
-
Ensure connectivity between Webex in the HVD environment, external interface, and internal interface (dual NIC deployment) of Expressway.
MRA with Webex App VDI workflow
For information about the MRA with Webex VDI workflow, see Webex App VDI login flow.
Dual NIC considerations
Keep these design considerations in mind when deployment Webex App VDI over MRA with an Expressway-E dual NIC deployment.
-
Static route—Verify the default gateway on the Expressway-E. Typically, this is the default gateway of the external interface IP subnet. Once you verify the Expressway default gateway configuration, you must add a Static Route to the Expressway-E for the IP subnet that is used for the HVD machines.
The static route sends traffic out of the internal interface of the Expressway-E to the HVD subnet. This configuration is needed, because of the UDS and TFTP config queries sent from the HVD to the Expressway E internal interface. Once Unified CM responds to the request, the Expressway-E sends the response through the default gateway if the static route to the HVD subnet does not exist.
-
NAT transition—The SIP traffic from the HVD to the Expressway-E external interface needs to have the source IP changed before reaching the Expressway to avoid a routing issue. NAT addresses this problem. A NAT translation must be put in place on a network device that is the path between the HVD and Expressway-E.
DNS configuration
Internal DNS
-
For dual NIC deployments, you can specify the Expressway-E address using a FQDN that resolves to the IP address of the internal interface. With split DNS, you can optionally use the same FQDN that is available on the public DNS. If you don't use split DNS, you must use a different FQDN.
To avoid a routing issue, the SIP traffic from the HVD to the Expressway-E external interface needs to have the source IP changed before reaching the Expressway. You must set up a NAT translation on a network device that is between the HVD and Expressway-E.
-
For single NIC with static NAT, you must specify the Expressway-E address using a FQDN that resolves to the public IP address. This setup also means that the external firewall must allow traffic from the Webex app in HVD to the external FQDN of the Expressway-E. This design is known as NAT reflection, and may not be supported by all types of firewalls.
-
The internal DNS must be configured with
_cisco-uds._tcp.<domain>SRV records so that the Webex app can discover Unified CM.
Public DNS
SRV records
The public, external DNS must be configured with _collab-edge._tls.<domain> SRV records so that endpoints can discover the Expressway-Es to use for MRA.
GeoDNS
In versions 43.6 and later, you can configure the Webex App to work with GeoDNS. This option improves network efficiency by enabling the App to connect to the geographically nearest Expressway-E.
If you have configured GeoDNS for your SRV records, we recommend that you edit the registry on your HVD as follows:
-
Open the registry to
HKEY_LOCAL_MACHINE\SOFTWARE\Cisco Spark Native. -
Create a new DWORD key named
VDIGeoDnsEnabled. -
Set
VDIGeoDnsEnabledto1.(Set
VDIGeoDnsEnabledto0(the default) if you want to disable GeoDNS compatibility for the Webex App on this HVD). -
Save the registry.
Firewall configuration
Both the internal and external firewall must allow the following outbound connections from Webex App on the HVD to Expressway-E:
-
SIP—TCP 5061
-
HTTPS—TCP 8443
The external firewall must also allow the following inbound connections from the user thin client to Expressway:
-
Media—UDP 36002–59999
Deploy Webex App VDI
Webex App VDI deployment task flow
These steps walk you through how to deploy the Webex App in your VDI environment. The steps include what you need to do on the hosted virtual desktop (HVD) environment and what users need to do on their thin clients.
Before you begin
Prepare your environment for Webex App for VDI
If you want your Webex App VDI users to have access to calling features in your organization, you must use the directions in the Prepare your environment chapter to deploy a call service (Unified CM, Webex Calling, or BroadWorks) before you deploy VDI.
| 1 |
Configure one of the following types of Hosted Virtual Desktop:
To prepare for your users wanting to access the Webex App remotely from thin client devices, set up the Webex App on the centralized hosted virtual desktop (HVD) environment. |
| 2 |
Install the Webex App VDI plugin on thin client machines for the following platforms:
After Webex App is installed on your central HVD environment, you next get your users to install a Webex App VDI plugin on their thin client devices. Thin clients are typically lightweight or repurposed computers that users use to establish a remote connection with a centralized HVD server where Webex App is hosted. The thin client plugins for supported platforms are available from the Webex App VDI release notes. |
| 3 |
(Optional) On Linux thin clients, you must also Install Webex Meetings VDI plugin on thin client systems. For full-featured meetings in Webex App, you must install two separate VDI plugins on Linux thin clients. |
Configure hosted virtual desktop and install Webex App
To prepare for your users wanting to access the Webex App remotely from thin client devices, set up Webex App on the centralized hosted virtual desktop (HVD) environment.
Before you begin
-
Follow all the prerequisites in Prepare your environment for Webex App for VDI.
If you want your Webex App VDI users to have access to calling features in your organization, you must deploy a call service (Unified CM, Webex Calling, or BroadWorks) before you deploy VDI.
-
This section only covers how to install the Webex App in an existing HVD environment. See the Citrix or Vmware documentation for HVD deployment best practices.
| 1 |
Sign in to Microsoft Windows HVD as a new user with domain administration rights. |
| 2 |
Join the HVD to the corporate domain. |
| 3 |
Set up Citrix or VMware access to the HVDs. |
| 4 |
If your organization has its own download site that includes your site-specific Webex App, go to that site and download your organization-specific version. Otherwise, for the generic version, go to Webex App VDI release notes > Downloads and download the Webex App you need:
|
| 5 |
Using administrative permissions, install the app on the HVD using these
command and arguments (these examples use a download directory of
See the following table for explanations of the arguments that you can use when installing Webex App in a VDI environment. |
| 6 |
Clone the HVD image. For more information about the best practices for cloning Microsoft Windows HVD images, see the documentation for your Citrix or VMware product. |
What to do next
For information about user preferences and how to preserve them, see User preferences.
Installation arguments, explanations, and required privileges
See the following table for explanations of the arguments that you can use when installing Webex App in a VDI environment.
| Argument | Notes | Requires admin install privileges |
|---|---|---|
ALLUSERS=1 |
Installs Webex App in c:\program files. This is useful in a shared environment (typically non-persistent VDI). This is a mandatory argument for installation. VDI must be installed per HVD. Per user installation is not supported yet. | ✓ |
|
|
A value of Use this option if you prefer to manually maintain upgrades. Use the versions that are linked from the Webex App VDI release notes. The argument does not affect a non-VDI environment. A value of This argument must be accompanied by | ✓ |
|
|
Controls the optimized VDI solution. (Officially supported.)
| ✓ |
|
Only for the bundle installer. When installing the bundled components for Webex App, you can use this argument to lock the version of the app that is used to join meetings, if the version is compatible with the site version. | ✓ |
INSTALLWV2=1 |
Install Microsoft's WebView2 embedded browser while installing Webex App using the For more information on the Webex App and WebView2 requirements, see Webex App | WebView2 requirement. | ✓ |
ROAMINGENABLED=1 |
If this argument is specified,
then the roaming database
( This argument must be accompanied by See User preferences for more information. | ✓ |
Installation comparison
Users may be in a Citrix environment and not have the thin client installed or the virtual channel is disconnected. We support this scenario with fallback to a non-virtual Webex App installation. In this mode, the app shows a warning that the quality of video may be affected. Once the virtual channel is connected, the app can change to VDI mode.
Use this table to understand the different installation combinations and how they affect media optimization for Unified CM, Webex Calling, and calls on Webex App.
| HVD VDI argument | Thin client plugin | Call service-enabled User | Calls on Webex App |
|---|---|---|---|
| ENABLEVDI=0 | Not installed | Media is not optimized | Media is not optimized |
| ENABLEVDI=0 | Installed | Media is not optimized | Media is not optimized |
|
ENABLEVDI=1 * ENABLEVDI=2 ** | Installed | Supported deployment; media is optimized | Supported deployment; media is optimized |
|
ENABLEVDI=1 * ENABLEVDI=2 ** | Not installed | Fallback to non-optimized media | Fallback to non-optimized media |
* This argument does not detect the VDI environment automatically.
** This argument detects the VDI environment automatically.
User preferences
All user preferences are in the roaming database (spark_roaming_store.db). This database is much smaller than the main db (spark_persistent_store.db).
If you are a non-persistent VDI customer (a VDI environment that is deleted everytime the user logs out), you can quickly back up and restore the folder Appdata\Roaming\CiscoSpark so that VDI users won't lose preferences between sessions.
The roaming database contains all user credentials and preferences, encrypted using AES256. As a VDI customer, you should always back up the above folder, so that user credentials and preferences are maintained across VDI sessions.
To decrypt the roaming database, you should also synchronize the following folders across VDI sessions:
-
AppData\Roaming\Microsoft\Credentials -
AppData\Roaming\Microsoft\Crypto -
AppData\Roaming\Microsoft\Protect -
AppData\Roaming\Microsoft\SystemCertificates
Configure Azure Virtual Desktop for the Webex App
Use these high-level steps to deploy a new Windows environment on Azure Virtual Desktop (formerly Windows Virtual Desktop). AVD is a cloud-managed VDI solution. Users access the Webex App through a virtualized Windows environment.
We do not support full-featured meetings using the Webex App on Azure Virtual Desktop.
Before you begin
-
This solution requires a Microsoft Azure subscription.
-
You must have a user account with the TenantCreator role.
-
User accounts must be synchronized into Azure Active Directory.
| 1 |
Walk through the deployment steps in the Azure admin portal to create the host pool, virtual machines, and related settings. A host pool is a collection of VMs that offer a similar service. Azure indicates when the virtual environment is ready. |
| 2 |
Use the Windows client to test if a user can access the host pool. For specific deployment steps, see the Microsoft documentation on getting started with AVD. |
Install the Webex App VDI plugin on Windows thin client systems
After you install Webex App on your central HVD environment, you must install a Webex App VDI plugin on the thin client devices.
Download the thin client plugins from the Webex App VDI release notes.
If you're unable to install the VDI plugin for your users, walk them through these steps on their thin client devices.
Before you begin
-
See Windows thin clients for a list of supported platforms for the Webex App VDI Plugin for Windows.
-
Webex App needs to be installed on your central HVD environment.
| 1 |
Go to Webex App VDI release notes > Downloads, and download the Webex App VDI plugin installer for Windows. |
| 2 |
Run the |
| 3 |
To open the executable file, click OK. |
| 4 |
Read the EULA and, if you agree, click Accept and Install. |
| 5 |
To complete the installation, click Finish. |
| 6 |
(Optional) If you or users are manually installing the two plugins for full featured meetings, follow the steps in Install Meetings VDI plugin on thin client systems. |
What to do next
For Webex App to function properly for your users, you must use the official thin client plugin. To confirm, the Health Check shows a connected status for the Virtual Channel.
Install the Webex App VDI plugin on Linux thin client systems
After Webex App is installed on your central HVD environment, you next get your users to install a Webex App VDI plugin on their thin client devices. Thin clients are typically lightweight or repurposed computers that users use to establish a remote connection with a centralized HVD server where Webex App is hosted. The thin client plugins for supported platforms are linked from the Webex App VDI release notes.
Before you begin
See Linux thin clients for a list of supported platforms for the Webex App VDI Plugin for Linux.
For Webex App to function properly for your users and be optimized for VDI, you must use the thin client build. To confirm, the Health Check in Webex App shows a connected status for the Virtual Channel.
Install the Webex App VDI plugin on macOS thin client systems
After Webex App is installed on your central HVD environment, you next get your users to install a Webex App VDI plugin on their thin client devices. Thin clients are typically lightweight or repurposed computers that users use to establish a remote connection with a centralized HVD server where Webex App is hosted. The thin client plugins for supported platforms are linked from the Webex App VDI release notes.
Run the MacOS installer (PKG) to install the Webex VDI plugin.
Before you begin
See macOS thin clients for a list of supported platforms for the Webex App VDI plugin for macOS.
| 1 |
Download the Webex App plugin for your macOS thin client systems from Webex App VDI release notes > Downloads. |
| 2 |
Run the |
| 3 |
Read the EULA and, if you agree, click Continue. |
| 4 |
Click Install, and if a prompt appears that Citrix Workspace client or VMware Horizon client must be closed first, click Close Application and Install. You can also click Install Later if you cannot close Citrix or VMware at the time. |
| 5 |
Click through the remaining screens to complete the installation. |
What to do next
When users launch the Webex App VDI plugin for the first time, accept the following required permissions:
| Permission | Description |
|---|---|
| Access Camera | Uses the camera in a video call, or trying to open the camera in Settings. |
| Access Microphone | Uses the microphone for voice in a call. |
| Record Screen | Uses the camera in a video call, or trying to open the camera in Settings. |
For Webex App to function properly for your users, you must use the official thin client plugin from the download site. To confirm, the Health Check shows a connected status for the Virtual Channel.
Install Webex Meetings VDI plugin on thin client systems
For full featured meetings with Webex App:
-
On Windows or MacOS thin clients, install the bundled (App + Meetings) plugin.
-
On Linux thin clients, install the separate Meetings VDI plugin after installing the separate App VDI plugin.
Before you begin
-
Install only the Webex App in the HVD environment. No other apps are required.
-
Make sure you follow the Full-featured meetings requirements.
Known issues and limitations with Webex App for VDI
Features
For feature limitations for each release, see the Webex App VDI release notes.
Webex App and VDI client
-
For VDI mode, we only support the provided Webex App for Windows (HVD installer) and Webex App thin-client plugin versions that are posted on Webex App VDI release notes.
-
We only support IPv4 for the HVD and thin client environments.
-
When users either don't use the VDI optimized solution or are in fall back mode, HD video is disabled and Webex App shows a notification that you may see a media quality issue.
We do not recommend that users use VDI in unoptimized or fallback mode. Their camera or headset may not work and they may experience poor media quality.
-
On the MacOS VDI client, a video feed spills into the MacOS system bar or Application menu when the HVD connection is full screen.
-
On Linux VDI clients, an incoming call does not ring all devices (including speakers on the thin client) even if that option is selected in Webex App on the HVD host. Only the audio device selected on the HVD plays the ringtone.
Unified CM calling
-
For on-premises calling only with Expressways: if there is is no NAT between the HVD and Expressway-E in a traversal pair used for MRA, Expressway treats the SIP and media signaling as internal and does not transmit the media to the thin client. To fix this, deploy a NAT between the HVD and the Expressways. That way, when HVD sends a SIP INVITE to the Expressway-E, it goes to the NAT first. Then, Expressway-E can transmit to the thin client.
-
For fallback mode, the Mode Selection registry key cannot control the media for an auto-answered Unified CM call.
Citrix
-
The multitasking feature does not work with the Webex App on VDI.
-
In non-optimization mode or fall back mode, Citrix device mapping supports a maximum of 4 devices.
-
On Citrix for Linux, we only support voicemail playback by using the default device on the thin client. So when you want to play back voicemail using your preferred audio device, you need to open the sound settings on the thin client to set the device that you want to use by default.
-
You must install Citrix Receiver/Workspace before you install the Webex App VDI client, including when you update the Receiver/Workspace environment. If either a Citrix or VMWare client are not installed, the Webex App VDI client shows an error and the installation ends.
-
For Windows, if you're running a version of Citrix Workspace that is earlier than 2002, you must reinstall (uninstall and then install again or repair) the Webex App VDI client after you uninstall and reinstall the Citrix Receiver/Workspace. If you run version 2002 or later, you don't have to uninstall and reinstall.
For all supported versions of Citrix Workspace for Linux, you must reinstall (uninstall and then install again or repair) the Webex App VDI client after you uninstall and reinstall the Citrix Receiver/Workspace.
-
Citrix Receiver/Workspace uses 32-bit architecture. Webex App VDI works with this environment.
Azure Virtual Desktop (Formerly Windows Virtual Desktop)
-
On Azure Virtual Desktop (AVD) for on-premises Unified CM calling, we currently only support the thin client working under MRA. Webex App in a WVD desktop (a cloud based remote desktop) works on MRA. If the thin client is on-premises, Unified CM calling may be blocked by some firewall settings. Webex Calling and Webex App built-in calling are not affected.
-
AVD doesn't support "Fit session to Window" in the AVD client setup.
-
For AVD deployments, you must enable the UDP connections between the internal network and the Expressway-E—port ranges from 16384–32767.
VMware
-
You must install VMware Horizon client before you install the Webex App VDI client. If either a Citrix or VMware client are not installed, the Webex App VDI client shows an error and the installation ends.
-
VMware Horizon client version 8.x (2103) is supported from the Webex VDI plugin version 41.4 onward.
For compatibility mode: If users have the previous VDI plugin version (including only upgrading the Webex app to 41.4), video in a call may not appear correctly.
-
We do not support VMWare Horizon client on 32-bit architecture, because we discontinued the 32-bit plugin for Windows.
The Webex App VDI client must have the same architecture as VMware Horizon client: the 64-bit VMware Horizon client works with the (64-bit) Webex App VDI client. The VMware Horizon client only has one installer and the default installation is 64-bit.
If
vdpService.dllexists inC:\Program Files (x86)\VMware\VMware Horizon View Client\x64, you have the 64-bit VMware Horizon client.If
vdpService.dllis underC:\Program Files (x86)\VMware\VMware Horizon View Client\, you have the 32-bit VMware Horizon client. -
On VMware for Linux and Windows, we only support voicemail playback by using the default device on the thin client. So when you want to play back voicemail using your preferred audio device, you need to open the sound settings on the thin client to set the device that you want to use by default.
-
On VMware Cloud desktop for on-premises Unified CM calling, we currently only support the thin client working under MRA. Webex App in a VMware Cloud desktop (a cloud based remote desktop) works on MRA. If the thin client is on-premises, Unified CM calling may be blocked by some firewall settings. Webex Calling and Webex App built-in calling are not affected.
-
For VMware Cloud desktop deployments, you must enable the UDP connections between the internal network and the Expressway-E—port ranges from 16384–32767.
-
After you check check the camera or audio device in Connect USB Device on the VMware Horizon Client, Webex in HVD cannot detect or show those devices.
Amazon WorkSpaces
- On the hosted virtual desktop, please follow instructions here to enable extensions for WSP by GPO.
- In case "No VDI environment is detected" was reported in Health Checker of Webex App after new installing manually by command line, please try to sign out/sign in hosted Windows desktop first.
Miscellaneous
-
In Citrix and Windows Virtual Desktop vGPU environments, Webex App is not detected as working in a VDI environment.
We recommend you install the Webex App with the
ENABLEVDI=1argument, to enforce VDI optimization. -
We support one Webex App VDI client working together with one instance of Webex App. Users can start multiple Citrix or VMware sessions, but only one connection instance works and the other instances fall back to non-VDI mode.
-
Webex App VDI detects Citrix at first and then VMware in the HVD environment. If you want to use VMware, make sure no Citrix Agent is installed.
Manage Webex App for VDI
Upgrade management
Webex App upgrades on the virtual desktop
For VDI environments, a new release of the Webex App comes out every two months. You can get the latest and supported versions from Webex App VDI release notes > Downloads.
We recommend that you enable automatic upgrades for the Webex App on the virtual desktop. This option ensures that users automatically get the latest features. Another option is to manually upgrade when the new release is available.
You have two options to enable automatic upgrade of the Webex App on the virtual desktop:
-
Enable it during initial installation from the command line (see Configure hosted virtual desktop for Webex App in the deployment chapter of this book).
-
Edit a Windows registry key on the virtual desktop:
In the registry entry for
HKEY_LOCAL_MACHINE\SOFTWARE\Cisco Spark Native, setAutoUpgradeEnabled=1.If you want to manually upgrade the Webex App, set
AutoUpgradeEnabled=0.
-
VDI users of Webex App do not receive monthly updates, because monthly thick client releases are not pushed to hosted virtual desktops.
VDI users are prompted to upgrade when the virtual desktop version of Webex App becomes available (released once every two months).
-
The upgrade package is stored in
%appdata%\Local\CiscoSparkLauncher. If this folder is non-persistent in user's environment, Webex App rolls back to the previous version after rebooting the virtual desktop. -
The Webex App on your HVD is backwards compatible with the Webex App VDI plugins (N-4) on your users' thin clients. Keep in mind that the latest features and functionality may not work if you or your users are not using the latest HVD version and VDI plugin. See Version Support in the Release Notes for more information.
-
Automatic upgrade of Webex App is not applied for Slow Channel.
Thin client upgrades
The Webex App VDI plugin is released once every two months.
We recommend that you enable automatic upgrades for the plugins. To enable automatic upgrades for the VDI plugin, you must edit a Windows registry key on the virtual desktop:
-
In the registry entry for
HKEY_LOCAL_MACHINE\SOFTWARE\Cisco Spark Native, setAutoUpgradeVDIPluginEnabled=1. -
In the same path, check that
AutoUpgradeEnabled=1.
If you want to prevent automatic upgrade of the plugin, set AutoUpgradeVDIPluginEnabled=0 on the virtual desktop. If you choose this option, you must manually upgrade the plugins to maintain version compatibility with the app.
-
Automatic upgrade of the plugins is only available with Webex App 42.2 and later.
-
Automatic upgrade of the plugin is supported on Windows and MacOS thin clients. The plugin does not automatically upgrade on Linux thin clients.
-
Users are prompted to upgrade the plugin after the Webex App has upgraded on the virtual desktop.
-
We recommend that you keep the plugin and the virtual desktop Webex App on the latest version. There is some backwards compatibility if you can't upgrade them together. See
Version support
in the Release notes for more information. -
Automatic upgrade of the plugins is also applied for Slow Channel.
Citrix or VMware upgrades
Keep this information in mind as you manage upgrades or changes to your Citrix or VMware connection brokers. Be sure to use the supported versions that are listed in the Prepare Your Environment chapter.
Citrix
|
Install or upgrade |
Windows and Mac thin clients |
Linux thin clients |
|---|---|---|
|
New install |
Install Citrix Receiver or Workspace before you install the Webex App VDI plugin on a Windows or Mac thin client. You and your users see a warning in the VDI plugin installation steps that reminds you to install the connection broker first. |
Install Citrix Receiver or Workspace before you install the Webex App VDI plugin on a Linux thin client. You and your users see a warning in the VDI plugin installation steps that reminds you to install the connection broker first. |
|
Upgrade |
If you see an upgrade notice in the Citrix environment, performing this upgrade does not affect the Webex App VDI plugin on a Windows or Mac thin client. |
If you see an upgrade notice in the Citrix environment, you must reinstall the Webex App VDI plugin on a Linux thin client after upgrading your Citrix environment. |
|
Reinstall |
|
For reinstallation of any supported Citrix Workspace version, you must reinstall the Webex App VDI plugin on a Linux thin client. |
VMware
|
Install or upgrade |
Windows thin client |
Linux and Mac thin clients |
|---|---|---|
|
New install |
Install the VMware Horizon client before you install the Webex App VDI plugin on a Windows thin client. You and your users see a warning in the VDI plugin installation steps that reminds you to install the connector broker first. |
Install the VMware Horizon client before you install the Webex App VDI plugin on a Linux or Mac thin client. You and your users see a warning in the VDI plugin installation steps that reminds you to install the connector broker first. |
|
Upgrade | If you see an upgrade notice in the VMware environment, performing this upgrade does not affect the Webex App VDI plugin on a Windows thin client. |
If you see an upgrade notice in the VMware environment, you must reinstall the Webex App VDI plugin on a Linux or Mac thin client after upgrading your Citrix environment. |
|
Reinstall |
For a VMware reinstallation, the Windows VDI plugin works and is not affected. |
For a VMware reinstallation, you must reinstall the Webex App plugin on a Linux or Mac thin client. |
Disable VDI detection after installation
If you have users that don't want to use the VDI client and Webex App is already deployed, you can disable VDI detection after installation. After this configuration, Webex App runs on the non-optimized solution.
| 1 |
Open one of the following installation paths, depending on how you deployed Webex App in your HVD:
|
| 2 |
Rename |
What to do next
If you uninstall Webex App later, the TSDetectionLib_b.dll remains in the folder. You must either rename the file back to TSDetectionLib.dll before you uninstall Webex App or delete the TSDetectionLib_b.dll manually after you uninstall Webex App.
Enable or disable advanced video features in Webex App VDI fallback mode
By modifying the registry, you can enable or disable specific Webex App features such as high definition (HD) and screen sharing. Doing so can save resources on the server in the data center. You can also decide whether users can do full or HVD window only screen share. If your users are on systems that are capable of more advanced video features, you can enable the features as needed.
Before you begin
-
You can modify the registry keys before or after the VDI plugin is installed.
Changes to the Windows registry should be done with extreme caution. We recommend that you make a backup of your registry before using these steps.
-
Virtual backgrounds are disabled by default.
-
To enable them, follow the steps in Configure Virtual Backgrounds for Webex Users.
-
Make sure your users' thin client devices meet the system requirements for virtual backgrounds.
-
| 1 |
In Windows search or the Run window, type regedit and then press Enter |
| 2 |
Go to HKEY_LOCAL_MACHINE\Software\Cisco Spark Native\. |
| 3 |
Change values for the following registry keys as needed: |
| 4 |
Choose a DWORD value for VDIFallBackConf:
This registry key only works when |
| 5 |
Choose a DWORD value for VDIBackgroundEnabled:
|
| 6 |
Choose a DWORD value for VDIScreenShareEnabled:
|
Configure VDI plugin notification
By default, users are notified if their Citrix or VMware client is connecting to an HVD without the VDI plugin. A notice appears to let them know to install the VDI plugin so that optimized VDI mode is enabled. Users can dismiss the reminder if they want.
Also, if the version of Webex App VDI plugin is not compatible with Webex App on HVD, a popup notifies users to upgrade the Webex App VDI plugin. The reminder appears weekly until users take action. Users can also dismiss this notification.
As an administrator, you can enable or disable these notifications at the organization-wide level.
Before you begin
You can modify the registry keys before or after the VDI plugin is installed.
Changes to the Windows registry should be done with extreme caution. We recommend that you make a backup of your registry before using these steps.
| 1 |
In Windows search or the Run window, type regedit and then press Enter |
| 2 |
Go to HKEY_LOCAL_MACHINE\Software\Cisco Spark Native\. |
| 3 |
Choose a DWORD (32-bit) reg key value for VDIPluginNotificationEnabled:
|
Disable VDI version compatibility check
By default, Webex App on the HVD checks for version compatibility with the Webex VDI plugin on the thin client. The plugin version should not be more than 4 bi-monthly releases behind the Webex App. For example, if Webex App on the HVD is version 43.8 (August 2023), then the following plugin versions are compatible:
-
43.8 (N) August 2023
-
43.6 (N-1) June 2023
-
43.4 (N-2) April 2023
-
43.2 (N-3) February 2023
-
42.12 (N-4) December 2022
This compatibility gives you up to 6 months to upgrade your thin client plugins, after you upgrade your hosted virtual desktops.
If the Webex VDI plugin is not compatible with Webex App on the HVD, then the Webex App goes into fall-back mode. Users see a popup notification to upgrade the plugin. The reminder appears weekly until users take action.
You can use the registry on the HVD to control the version compatibility check:
We recommend that you back up your registry before using these steps.
-
In the Windows Run window, type
regeditand then press Enter. -
Go to
HKEY_LOCAL_MACHINE\Software\Cisco Spark Native\. -
Create a DWORD (32-bit) registry key named
VDIDisableCompatibilityVersionCheckand give it one of these values:0—Enables the version compatibility check (default).1—Disables the version compatibility check.
Ringers and alerts setting not working for all devices
On Linux VDI clients, the ringtone for an incoming call does not ring all devices (including speakers on the thin client) even if that option is selected in Webex App on the HVD host. Only the audio device selected on the HVD plays the ringtone.
This issue may arise because of the audio device mapping on Citrix or VMware.
Check the registry key
VDIDisablePlaytoneOnLinuxTCEnabled on your HVD environment. If
a Linux thin client user is observing this ringback tone issue, set the value of
this key to 1.
Diagnostics in the Webex App
The diagnostics available in the Webex App (desktop and VDI) help you and your users resolve connection issues, check media quality, and collect important troubleshooting information.
When you set up Calling in Webex App (Unified CM), you may encounter issues related to the connection or required settings (such as voice domain and UC services). Using this tool, you can diagnose what services are configured correctly and what is missing. This feature is useful for troubleshooting scenarios and reducing support cases, whether you're migrating to Calling in Webex App (Unified CM) or setting up new users.
When user experience issues, they can access the diagnostics view and export the data to share with you or support.
-
Unified CM Settings—Critical settings (for Jabber migration as well as new user setup) for phone services to work correctly, such as:
-
Unified CM version
-
UC service domain
-
SSO
-
UC services such as voicemail
-
Expressway for MRA
-
-
Media quality—Quality for video, audio, and sharing in both directions
-
Devices—Device information, when users are connected to devices
For shortcut keys to show the diagnostics window, see Keyboard and navigation shortcuts.
Browser content redirection
Browser content redirection (BCR) is an optimization of the VDI environment that reduces the load on the virtual desktop machine.
When BCR is enabled on the virtual desktop, the Webex App cannot share the browser content by remote screen share, application share, or screen portion share.
Webex users can use local screen sharing to share their browser.
