Shadow sessions
The session shadowing feature allows domain administrators to view users’ ICA sessions in an intranet. The feature uses noVNC to connect to the ICA sessions.
Note:
To use the session shadowing feature, use
Citrix Director7.16 or later.
Installation and configuration
Dependencies
Two new dependencies, python-websockify and x11vnc, are required for session shadowing. The python-websockify and x11vnc dependencies are installed automatically when you install the Linux VDA on Ubuntu 16.04. On the other supported distributions, you must install python-websockify and x11vnc manually after you install the Linux VDA.
For RHEL 7.x and Amazon Linux2:
Run the following commands to install python-websockify and x11vnc (x11vnc version 0.9.13 or later):
sudo pip3 install websockify
sudo yum install x11vnc
<!--NeedCopy-->
To resolve python-websockify and x11vnc, enable the Extra Packages for Enterprise Linux (EPEL) and optional RPMs repositories on RHEL 7.x:
-
EPEL
The EPEL repository is required for
x11vnc. Run the following command to enable the EPEL repository:yum install https://dl.fedoraproject.org/pub/epel/epel-release-latest-7.noarch.rpm <!--NeedCopy--> -
Optional RPMs
Run the following command to enable the optional
RPMsrepository for installing some dependency packages ofx11vnc:subscription-manager repos --enable rhel-7-server-optional-rpms --enable rhel-7-server-extras-rpms <!--NeedCopy-->
For RHEL 8.x:
Run the following commands to install python-websockify and x11vnc (x11vnc version 0.9.13 or later).
sudo pip3 install websockify
sudo yum install x11vnc
<!--NeedCopy-->
To resolve x11vnc, enable the EPEL and CodeReady Linux Builder repositories:
dnf install -y --nogpgcheck https://dl.fedoraproject.org/pub/epel/epel-release-latest-8.noarch.rpm
subscription-manager repos --enable "codeready-builder -for-rhel-8-x86_64-rpms"
<!--NeedCopy-->
For Ubuntu:
Run the following commands to install python-websockify and x11vnc (x11vnc version 0.9.13 or later):
sudo pip3 install websockify
sudo apt-get install x11vnc
<!--NeedCopy-->
For SUSE:
Run the following commands to install python-websockify and x11vnc (x11vnc version 0.9.13 or later):
sudo pip3 install websockify
sudo zypper install x11vnc
<!--NeedCopy-->
For Debian:
Run the following commands to install python-websockify and x11vnc (x11vnc version 0.9.13 or later):
sudo pip3 install websockify
sudo apt-get install x11vnc
<!--NeedCopy-->
Port
The session shadowing feature automatically selects available ports from within 6001-6099 to build up connections from the Linux VDA to Citrix Director. Therefore, the number of ICA sessions that you can shadow concurrently is limited to 99. Ensure that enough ports are available to meet your requirements, especially for multi-session shadowing.
Registry
The following table lists related registries:
| 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) |
Run the ctxreg command on the Linux VDA to change the registry values. 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
SSL
The noVNC connection between the Linux VDA and Citrix Director uses the WebSocket protocol. For session shadowing, whether ws:// or wss:// is chosen depends on the previously mentioned “ShadowingUseSSL” registry. By default, ws:// is chosen. However, for security reasons, we recommend that you use wss:// and install certificates on each Citrix Director client and on each Linux VDA server. Citrix disclaims any security responsibility for the Linux VDA session shadowing by using ws://.
Obtain server and root SSL certificates
Certificates 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. You can use a wildcard certificate for the whole domain instead. In this case, you must know at least the domain name.
A root certificate is also required for each Citrix Director client that communicates with the Linux VDA. Root certificates are available from the same CAs that issue the server certificates.
You can install server and client certificates from the following CAs:
- A CA that is bundled with your operating system
- An enterprise CA (a CA that your organization makes accessible to you)
- 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 getting certificates.
Important:
- The Common Name for a server certificate must be the exact FQDN of the Linux VDA 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 client
Session 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 standalone 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 on the Authorities tab of Certificate Manager.
Install a server certificate and its key on each Linux VDA server
Name the server certificates “shadowingcert.*” and the key file “shadowingkey.*” (* indicates the format, for example, shadowingcert.pem 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 therefore causes connection failure with Citrix Director.
Usage
From Citrix Director, find the target session and click Shadow in the Session Details view to send a shadowing request to the Linux VDA.
After the connection initializes, a confirmation appears on the ICA session client (not the Citrix Director client) to ask the user for permission to shadow the session.
If the user clicks Yes, a window appears on the Citrix Director side, indicating that the ICA session is being shadowed.
For more information about the usage, see the Citrix Director Documentation.
Limitations
- Session shadowing is designed for use in an Intranet only. It does not work for external networks even connecting through Citrix Gateway. Citrix disclaims any responsibility for the Linux VDA session shadowing in an external network.
- With session shadowing enabled, a domain administrator can only view the ICA sessions, but has no permission to write or control it.
- After an administrator clicks Shadow from
Citrix Director, a confirmation appears to ask the user for permission to shadow the session. A session can be shadowed only when the session user gives the permission. - The previously mentioned confirmation has a timeout limitation, which is 20s. A shadowing request fails when the time runs out.
- One session can be shadowed by only one administrator. For example, if administrator B sends a shadowing request for a session administrator A is shadowing, the confirmation for getting the user permission reappears on the user device. If the user agrees, the shadowing connection for administrator A stops and a new shadowing connection is built for administrator B. If an administrator sends another shadowing request for the same session, a new shadowing connection can also be built.
- To use session shadowing, install
Citrix Director7.16 or later. - A
Citrix Directorclient uses an FQDN rather than an IP address to connect to the target Linux VDA server. Therefore, theCitrix Directorclient must be able to resolve the FQDN of the Linux VDA server.
Troubleshooting
If session shadowing fails, do debugging on both the Citrix Director client and the Linux VDA.
On the Citrix Director client
Through the developer tools of the browser, check the output logs on the Console tab. Or, check the response of the ShadowLinuxSession API on the Network tab. If the confirmation for getting user permission appears but the connection build-up fails, ping the VDA’s FQDN manually to verify that Citrix Director can resolve the FQDN. If there’s an issue with the wss:// connection, check your certificates.
On the Linux VDA
Verify that the confirmation for getting the user permission appears in response to a shadowing request. If it does not, check the vda.log and hdx.log files for clues. To obtain the vda.log file, do the following:
-
Find the /etc/xdl/ctx-vda.conf file. Uncomment the following line to enable the vda.log configuration:
Log4jConfig="/etc/xdl/log4j.xml" -
Open /etc/xdl/log4j.xml, locate the com.citrix.dmc part, and change “info” to “trace” as follows:
<!-- Broker Agent Plugin - Director VDA plugin Logger --> <logger name="com.citrix.dmc"> <level value="trace"/> </logger> <!--NeedCopy--> -
Run the
service ctxvda restartcommand to restart thectxvdaservice.
If there’s an error during connection build-up:
- Check for any firewall limitation that stops session shadowing from opening the port.
- Verify that you have named certificates and key files properly and put them under the correct path if it’s the SSL scenario.
- Verify that there are enough ports left between 6001-6099 for new shadowing requests.