Session shadowing
Shadowing sessions 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 feature, use
Citrix Director7.16 or later.
Installation and configuration
Dependencies
Two new dependencies, python-websockify and x11vnc, are required for session shadowing. Install python-websockify and x11vnc manually after you install the Linux VDA.
For 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-->
For RHEL 9.x/8.x and Rocky Linux 9.x/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-->
Resolve x11vnc by enabling 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:
First, enable the “SUSE Linux Enterprise Workstation Extension 15 SP6” module using either YaST or the following SUSEConnect command:
suseconnect -p sle-we/15.6/x86_64 -r <regcode>
<!--NeedCopy-->
For more information, see the SUSE documentation: https://documentation.suse.com/en-us/sles/15-SP6/html/SLES-all/article-modules.html.
Then, 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 12:
Run the following commands to install python-websockify and x11vnc (x11vnc version 0.9.13 or later):
apt install python3-websockify
sudo apt-get install x11vnc
<!--NeedCopy-->
For Debian 11:
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"
<!--NeedCopy-->
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://.
To enable SSL, run the following command:
/opt/Citrix/VDA/bin/ctxreg update -k "HKLM\Software\Citrix\VirtualDesktopAgent" -v "ShadowingUseSSL" -d "0x00000001"
<!--NeedCopy-->
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. For convenience, consider using a wildcard certificate for the entire domain.
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.
- Chrome has stopped accepting self-signed SSL certificates, considering them insecure. The
NET::ERR_CERT_COMMON_NAME_INVALIDerror occurs because the generated certificate lacks the SAN (subjectAltName) field. To resolve this issue, provide a certificate with extended attributes (X509 v3 extensions) that include the SAN field.
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 CA 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, allowing only ctxsrvr to have read access. 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. Commands are as follows:
cp <vda's-public-key> /etc/xdl/shadowingssl/shadowingcert.pem
cp <vda's-server-private-key> /etc/xdl/shadowingssl/shadowingkey.key
sudo chown ctxsrvr:ctxadm /etc/xdl/shadowingssl/shadowingcert.pem
sudo chown ctxsrvr:ctxadm /etc/xdl/shadowingssl/shadowingkey.key
<!--NeedCopy-->
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
- If your VDAs are joined to a domain and are hosted on Microsoft Azure using Azure Active Directory (AAD) for authentication, the session shadowing feature does not work.
- 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
-
Check the
/var/log/xdl/vda.logfile for clues. -
Edit the
/var/xdl/sessionshadowing.shfile and change the ‘logFile’ variable to specify a log file that can be tailed for clues during session shadowing from the director. -
Also, you can manually verify whether your certificates work correctly with the noVNC connection:
-
Run ps aux | grep xorg to find the current session’s Xorg display number $display-num, for example, :3.
-
Run the following command to start an x11vnc server and wait for an incoming connection.
Note:
Before running the following command, set the $passwd, $port, $display-num variables.
runuser -l "ctxsrvr" -s /bin/bash -c "websockify <port> -v --cert /etc/xdl/shadowingssl/shadowingcert.pem --key /etc/xdl/shadowingssl/shadowingkey.key -- x11vnc -viewonly -shared -passwd $passwd -rfbport $port -display $display-num -many -o /var/log/xdl/x11vnc.log" <!--NeedCopy--> -
Try to connect using noVNC to verify SSL mode as follows. Enter your VDA’s FQDN and the port number. In this example, the port number is 6009.
-
Resolve any errors printed by Websockify on the VDA or reported by the browser on the client.
Key checkpoints during connection establishment:
- 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.
- Run
openssl x509 -in shadowingcert.pem -text -nooutto verify that the certificates are configured correctly, paying particular attention to the CN and SAN fields. -
On RHEL 8, there might be an issue where
rebind.socannot be found. To resolve this issue, run the following command:ln -s /usr/bin/rebind.so /usr/local/bin/rebind.so <!--NeedCopy-->
-