Product documentation
Linux Virtual Delivery Agent
Current Release 2411 2407 2402 LTSR 2311 2308 2305 2303 2301 2212 2210 2209 2207 2206 2204 2203 LTSR 2201 2112 2110 2109 2107 2106 2104 2103 1912 LTSR 7.15
View PDF

HDX Direct for Linux

March 17, 2025
Contributed by: 
C

When accessing Citrix-delivered resources, HDX Direct allows both internal and external client devices to establish a secure direct connection with the session host if direct communication is possible.

System requirements

The following are the system requirements for using HDX Direct:

  • Control plane

    • Citrix DaaS
    • Citrix Virtual Apps and Desktops 2503 or later

  • Virtual Delivery Agent (VDA)

    • Linux: Version 2503 or later

  • Workspace app

    • Windows: version 2503 or later
    • Linux: version 2411 or later
    • Mac: version 2411 or later

  • Access tier

    • Citrix Workspace
    • Citrix StoreFront 2503 or later
    • Citrix Gateway Service
    • Citrix NetScaler Gateway

Network requirements

The following are the network requirements for using HDX Direct.

Session hosts

If your session hosts have a firewall, you must allow the following inbound traffic for internal connections.

Description Source Protocol Port
Direct internal connection Client TCP 443
Direct internal connection Client UDP 443

Client network

The following table describes the client network for internal and external users.

Internal users

Description Protocol Source Source port Destination Destination port
Direct internal connection TCP Client network 1024–65535 VDA network 443
Direct internal connection UDP Client network 1024–65535 VDA network 443

External users

Description Protocol Source Source port Destination Destination port
STUN (external users only) UDP Client network 1024–65535 Internet (see note below) 3478, 19302
External user connection UDP Client network 1024–65535 Data center’s public IP address 1024–65535

Data center network

The following table describes the data center network for internal and external users.

Internal users

Description Protocol Source Source port Destination Destination port
Direct internal connection TCP Client network 1024–65535 VDA network 443
Direct internal connection UDP Client network 1024–65535 VDA network 443

External users

Description Protocol Source Source port Destination Destination port
STUN (external users only) UDP VDA network 1024–65535 Internet (see note below) 3478, 19302
External user connection UDP DMZ / Internal network 1024–65535 VDA network 55000–55250
External user connection UDP VDA network 55000–55250 Client’s public IP 1024–65535

Note:

Both the VDA and Workspace app attempt to send STUN requests to the following servers in the same order:

  • stun.cloud.com:3478
  • stun.cloudflare.com:3478
  • stun.l.google.com:19302

If you change the default port range for external user connections using the HDX Direct port range policy setting, the corresponding firewall rules must match your custom port range.

Configuration

HDX Direct is disabled by default. You can configure this feature using the HDX Direct setting in the Citrix policy.

  • HDX Direct: To enable or disable a feature.
  • HDX Direct mode: Determines if HDX Direct is available for internal clients only or for both internal and external clients.
  • HDX Direct port range: Defines the port range that the VDA uses for connections from external clients.

Considerations

The following are considerations for using HDX Direct:

  • HDX Direct for external users is only available with EDT (UDP) as the transport protocol. Therefore, Adaptive Transport must be enabled.
  • If you are using HDX Insight, note that using HDX Direct prevents the HDX Insight data collection, as the session would no longer be proxied through NetScaler Gateway.
  • Using your own certificates with HDX Direct is not currently supported.

How it works

HDX Direct allows clients to establish a direct connection to the session host when direct communication is available. When direct connections are made using HDX Direct, self-signed certificates are used to secure the direct connection with network level-encryption (TLS/DTLS).

Internal users

The following diagram depicts the overview of the HDX Direct connection process of internal users.

HDX Direct Overview

  1. The client establishes an HDX session through the Gateway Service.
  2. Upon a successful connection, the VDA sends to the client the VDA machine’s FQDN, a list of its IP addresses, and the VDA machine’s certificate via the HDX connection.
  3. The client probes the IP addresses to see if it can reach the VDA directly.
  4. If the client can reach the VDA directly with any of the IP addresses shared, the client establishes a direct connection with the VDA, secured with (D)TLS using a certificate that matches the one exchanged in step (2).
  5. Once the direct connection is successfully established, the session is transferred to the new connection, and the connection to the Gateway Service is terminated.

Note:

After establishing the connection in step 2 above, the session is active. The subsequent steps do not delay or interfere with the user’s ability to use the virtual application or desktop. If any of the subsequent steps fail, the connection through the Gateway is maintained without interrupting the user’s session.

External users

The following diagram depicts the overview of the HDX Direct connection process for external users:

HDX Direct connection process

  1. The client establishes an HDX session through the Gateway Service.
  2. Upon a successful connection, both the client and the VDA send a STUN request to discover their public IP addresses and ports.
  3. The STUN server responds to the client and VDA with their corresponding public IP addresses and ports.
  4. Through the HDX connection, the client and the VDA exchange their public IP addresses and UDP ports, and the VDA sends its certificate to the client.
  5. The VDA sends UDP packets to the client’s public IP address and UDP port. The client sends UDP packets to the VDA’s public IP address and UDP port.
  6. Upon receipt of a message from the VDA, the client responds with a secure connection request.
  7. During the DTLS handshake, the client verifies that the certificate matches the certificate exchanged in step 4. After validation, the client sends its authorization token. A secure direct connection is now established.
  8. Once the direct connection is successfully established, the session is transferred to the new connection, and the connection to the Gateway Service is terminated.

Note:

After establishing the connection in step 2 above, the session is active. The subsequent steps do not delay or interfere with the user’s ability to use the virtual application or desktop. If any of the subsequent steps fail, the connection through the Gateway is maintained without interrupting the user’s session.

NAT compatibility

To establish a direct connection between an external user device and the session host, HDX Direct leverages hole punching for NAT traversal and STUN to facilitate the exchange of the public IP address and port mappings for the client device and session host. This is similar to how VoIP, unified communications, and P2P solutions work.

As long as firewalls and other network components are configured to allow the UDP traffic for the STUN requests and the HDX sessions, HDX Direct for external users is expected to work. However, there are certain scenarios where the NAT types of the user and session host networks lead to an incompatible combination, thus causing HDX Direct to fail.

Validations

You can validate the NAT type and filtering on the client and the session host by using STUNTMAN’s STUN client utility:

  1. Download the appropriate package for the target platform from stunprotocol.org, and extract the contents.
  2. Open a terminal prompt and navigate to the directory where the contents were extracted.
  3. Run the following command: ./stunclient stunserver2024.stunprotocol.org --mode behavior

  4. Take note of the output.

    If the binding and behavior tests are successful, both binding test and behavior test report the success and a NAT behavior is specified:

    NAT success

    If the tests fail, binding test and/or behavior test report the failure.

    NAT failure

  5. Run the following command: ./stunclient stunserver2024.stunprotocol.org --mode filtering

  6. Take note of the output.

    NAT filtering

See the following table to determine if HDX Direct for external users is expected to work based on the test results of both the client and session host:

Client NAT Behavior Client NAT Filtering Session Host NAT Behavior Session Host NAT Filtering Expected to work?
Endpoint Independent Mapping Any Endpoint Independent Mapping Any Yes
Endpoint Independent Mapping Endpoint Independent Filtering Address Dependent Mapping Any Yes
Endpoint Independent Mapping Address Dependent Filtering Address Dependent Mapping Any No
Endpoint Independent Mapping Address and Port Dependent Filtering Address Dependent Mapping Any No
Endpoint Independent Mapping Endpoint Independent Filtering Address and Port Dependent Mapping Endpoint Independent Filtering Yes
Endpoint Independent Mapping Address Dependent Filtering Address Dependent Mapping Any No
Endpoint Independent Mapping Address and Port Dependent Filtering Address Dependent Mapping Any No
Address Dependent Mapping Any Endpoint Independent Mapping Endpoint Independent Filtering Yes
Address Dependent Mapping Any Endpoint Independent Mapping Address Dependent Filtering No
Address Dependent Mapping Any Endpoint Independent Mapping Address and Port Dependent Filtering No
Address Dependent Mapping Any Address Dependent Mapping Any No
Address Dependent Mapping Any Address and Port Dependent Mapping Any No
Address and Port Dependent Mapping Any Endpoint Independent Mapping Endpoint Independent Filtering Yes
Address and Port Dependent Mapping Any Endpoint Independent Mapping Address Dependent Filtering No
Address and Port Dependent Mapping Any Endpoint Independent Mapping Address and Port Dependent Filtering No
Address and Port Dependent Mapping Any Address Dependent Mapping Any No
Address and Port Dependent Mapping Any Address and Port Dependent Mapping Any No
Fail Any Any Any No
Any Any Fail Any No
Fail Any Fail Any No
HDX Direct for Linux
March 17, 2025
Contributed by: 
C
March 17, 2025
Contributed by: 
C

In this article

Site feedback | Your privacy choices footer linkYour Privacy Choices | Privacy and legal terms | Cookie preferences | Consent settings | docs.cloud.com
© 1999- Cloud Software Group, Inc. All rights reserved.
OSZAR »