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 and is supported only with RHEL 7.x and Ubuntu 16.04.

Note:

To use the session shadowing feature, the version of Citrix Director must be 7.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 automatically installed when you install the Linux VDA on Ubuntu 16.04. On RHEL 7.x, you must manually install python-websockify and x11vnc after you install the Linux VDA.

Run the following command on RHEL 7.x to install python-websockify and x11vnc (x11vnc version 0.9.13 or later).

sudo yum install -y python-websockify x11vnc
<!--NeedCopy-->

To resolve python-websockify and x11vnc, enable the following repositories on RHEL 7.x:

• Extra Packages for Enterprise Linux (EPEL)

  The 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
   <!--NeedCopy-->
  

• 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
   <!--NeedCopy-->
  

  For server:

   subscription-manager repos --enable=rhel-7-server-optional-rpms
   <!--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:

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 is determined by 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. 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 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.*” (* 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 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 ICA session can be shadowed by only one administrator in one Citrix Director window. If an ICA session has been shadowed by administrator A and meanwhile, administrator B sends a shadowing request, 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. It is the same if another shadowing request for the same ICA session is sent by the same administrator.
• To use session shadowing, install Citrix Director 7.16 or later.
• A Citrix Director client uses an FQDN rather than an IP address to connect to the target Linux VDA server. Therefore, the Citrix Director client must be able to resolve the FQDN of the Linux VDA server.

Troubleshooting

If session shadowing fails, perform 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 the user permission appears but the connection fails to be built, manually ping the FQDN of the Linux VDA to verify that Citrix Director can resolve the FQDN. If there is 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:

1. Find the /etc/xdl/ctx-vda.conf file. Uncomment the following line to enable the vda.log configuration:

   Log4jConfig=”/etc/xdl/log4j.xml”

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

3. Run the service ctxvda restart command to restart the ctxvda service.

If there is an error during connection build-up:

1. Check for any firewall limitation that stops session shadowing from opening the port.
2. Verify that certificates and key files are named properly and put under the correct path if it is the SSL scenario.
3. Verify that there are enough ports left between 6001-6099 for new shadowing requests.