How to configure Session Shadowing for Linux VDA sessions

book

Article ID: CTX230072

calendar_today

Updated On:

Description

This article describes the method to configure Session Shadowing for Linux VDA sessions.

Instructions

By default, Session Shadowing is enabled on ws:// mode on RHEL 7.3 and Ubuntu 16.04. While as described in Introduction - Session Shadowing for Linux VDA sessions, we use Websockify as a websocket proxy between X11VNC server and noVNC client, which can support SSL encryption (wss://). In this article, we’ll introduce Session Shadowing registry settings and how to configure it in both default mode (ws://) and SSL encryption mode (wss://).

Registry Keys
Below table lists Session Shadowing related registries in Linux VDA under ConfDB path “HKLM\Software\Citrix\VirtualDesktopAgent”:

Registry	Description	Default Value
EnableSessionShadowing	Enables or disables the Session Shadowing feature	1 (Enabled)
ShadowingUseSSL	Determines whether to encrypt the connection between the Linux VDA and Citrix Director	0 (Disabled)

You can use ctxreg tool on the Linux VDA to change the settings. For example, to disable Session Shadowing, run the following command:
/opt/Citrix/VDA/bin/ctxreg update -k "HKLM\Software\Citrix\VirtualDesktopAgent" -v "EnableSessionShadowing" -d 0x00000000
You can also use this tool to enable SSL encryption for VNC connections:
/opt/Citrix/VDA/bin/ctxreg update -k "HKLM\Software\Citrix\VirtualDesktopAgent" -v " ShadowingUseSSL " -d 0x00000001

Install dependencies on supported Linux VDA
Two new dependencies – python-websockify and x11vnc are introduced into Linux VDA to support Session Shadowing. The two dependencies are automatically installed when you install the Linux VDA package on Ubuntu 16.04. While on RHEL 7.3, you must manually install python-websockify and x11vnc after you install the Linux VDA.

Run the following command on RHEL 7.3 to install python-websockify and x11vnc.

# sudo yum install -y python-websockify, x11vnc

To resolve python-websockify and x11vnc, enable the following repositories on RHEL 7.3:
- EPEL

The Extra Packages for Enterprise Linux (EPEL) repository is required for both python-websockify and x11vnc. Run the following command to enable the EPEL repository:
sudo yum install https://dl.fedoraproject.org/pub/epel/epel-release-latest-$(rpm -E '%{rhel}').noarch.rpm

Optional RPMs

Run either of the following commands to enable the optional RPMs repository for installing some dependency packages of x11vnc:

For workstation: subscription-manager repos --enable=rhel-7-workstation-optional-rpms
For server: subscription-manager repos --enable=rhel-7-server-optional-rpms

How to configure Session Shadowing for ws:// mode
Session Shadowing is enabled by default on ws:// mode , you just need to perform following steps for the feature to work:

Make sure the registry key EnableSessionShadowing is enabled while ShadowingUseSSL is disabled (default setting):

If you’re using RHEL 7.3, install the two dependencies following above instructions
On Citrix Director Client machine, make sure the FQDN of the Linux VDA can be resolved since Director Client uses FQDN to connect to target Linux VDA. You can set DNS server to the Domain DNS server that Linux VDA resides in, or you can edit hosts file on Director Client machine as a workaround. The hosts file typically located at C:\Windows\System32\drivers\etc\hosts. For example, add following entries the hosts file:

10.150.136.186 R7-auto.xd.local

Where

10.150.136.186 is the IP address of the Linux VDA
R7-auto.xd.local is the FQDN of the Linux VDA.

How to configure Session Shadowing to support wss:// mode
If you want to enable SSL encryption for VNC connections, you need to perform following steps:

Enable ShadowingUseSSL form command:

/opt/Citrix/VDA/bin/ctxreg update -k "HKLM\Software\Citrix\VirtualDesktopAgent" -v " ShadowingUseSSL " -d 0x00000001
And make sure the registry key EnableSessionShadowing is also enabled (default setting):

If you’re using RHEL 7.3, install the two dependencies following above instructions
On Citrix Director Client machine, make sure the FQDN of the Linux VDA can be resolved since Director Client uses FQDN to connect to target Linux VDA.

Besides these common settings, you also need to perform below SSL specific operations:

Obtain server and root SSL certificatesCertificates must be signed by a trusted Certificate Authority (CA).
A separate server certificate (including the key) is required for each Linux VDA server on which you want to configure SSL. A server certificate identifies a specific computer, so you must know the Fully Qualified Domain Name (FQDN) of each server. For convenience, you can use a wildcard certificate for the whole domain instead. In this case, you must know at least the domain name.
In addition to installing a server certificate on each server, you must install a root certificate from the same CA on each Citrix Director client that communicates with the Linux VDA server. Root certificates are available from the same CAs that issue the server certificates. You can install server and client certificates from a CA that is bundled with your operating system, from an enterprise CA (a CA that your organization makes accessible to you), or from a CA not bundled with your operating system. Consult the security team of your organization to find out which of the methods they require for obtaining certificates.
Important:

The Common Name for a server certificate must be the exact FQDN of the Linux VDA server or at least the correct wildcard plus domain characters (for example, vda1.basedomain.com or *.basedomain.com).
Hashing algorithms including the SHA1 and MD5 are too weak for signatures in digital certificates for some browsers to support. So SHA-256 is specified as the minimum standard.

Install a root certificate on each Citrix Director clientSession Shadowing uses the same registry-based certificate store as IIS, so you can install root certificates using IIS or the Microsoft Management Console (MMC) Certificates snap-in. When you receive a certificate from a CA, you can restart the Web Server Certificate Wizard in IIS and the wizard installs the certificate. Alternatively, you can view and import certificates on the computer using the MMC and add the certificate as a stand-alone snap-in.

Internet Explorer and Google Chrome import the certificates installed on your operation system by default.
For Mozilla Firefox, you must import your root SSL certificates to Authorities of Certificate Manager. You can refer to Importing a Code Signing Certificate into Firefox for more instructions.

Install a server certificate and its key on each Linux VDA serverName the server certificates “shadowingcert.*”and the key file “shadowingkey.*” (* can indicate the format, for example, shadowingcert.csr and shadowingkey.key). Put server certificates and key files under the path /etc/xdl/shadowingssl and protect them properly with restricted permissions. An incorrect name or path makes the Linux VDA unable to find a specific certificate or key file and consequently causes connection failure with Citrix Director.