XenApp and XenDesktop


Framehawk is a display remoting technology for mobile workers on broadband wireless connections (Wi-Fi and 4G/LTE cellular networks). Framehawk overcomes the challenges of spectral interference and multipath propagation, delivering a fluid and interactive user experience to users of virtual apps and desktops. Framehawk might be a suitable choice for users on long-haul (high latency) broadband network connections where a small amount of packet loss can degrade the user experience. We suggest using adaptive transport for this use case - for more information, see Adaptive transport.

You can use Citrix policy templates to implement Framehawk for a set of users and access scenarios in a way that is appropriate for your organization. Framehawk targets single-screen mobile use cases such as laptops and tablets. Use Framehawk where the business value of real time interactive performance justifies the extra cost in server resources and the requirement for a broadband connection.

How Framehawk maintains a smooth user experience

Think of Framehawk as a software implementation of the human eye, looking at what’s in the frame buffer and discerning the different types of content on the screen. What’s important to the user? When areas of the screen are changing rapidly, like video or moving graphics, it doesn’t matter to the human eye if some pixels are lost because they are quickly overwritten with new data.

But when it comes to static areas of the screen, such as the icons in the notification area or a toolbar, or text after scrolling to where the user wants to start reading, the human eye is fussy. A user expects those areas to be pixel perfect. Unlike protocols aiming to be technically accurate from a ones and zeros perspective, Framehawk aims to be relevant to the human being who is using the technology.

Framehawk includes a next-generation Quality of Service signal amplifier plus a time-based heat map for a finer-grained and more efficient identification of workloads. It uses autonomic, self-healing transforms in addition to data compression, and avoids retransmission of data to maintain click response, linearity, and a consistent cadence. On a lossy network connection, Framehawk can hide loss with interpolation, and the user still perceives good image quality while enjoying a more fluid experience. In addition, Framehawk algorithms intelligently distinguish between different types of packet loss. For example, random loss (send more data to compensate) versus congestion loss (don’t send more data because the channel is already clogged).

The Framehawk Intent Engine in Citrix Receiver distinguishes between scrolling up or down, zooming, moving to the left or right, reading, typing, and other common actions. The engine also manages the communication back to the Virtual Delivery Agent (VDA) using a shared dictionary. If the user is trying to read, the visual quality of the text must be excellent. If the user is scrolling, it must be quick and smooth. And it has to be interruptible, so that the user is always in control of the interaction with the application or desktop.

By measuring cadence on the network connection (gearing, analogous to tension on a bicycle chain), the Framehawk logic reacts more quickly, providing a superior experience over high latency connections. This unique and patented gearing system provides constant up-to-date feedback on network conditions, allowing Framehawk to react immediately to changes in bandwidth, latency, and loss.

Design considerations using Thinwire and Framehawk

While Thinwire has led the industry in bandwidth efficiency and is suited to a broad range of access scenarios and network conditions, it uses TCP for reliable data communications. Therefore, it must retransmit packets on a lossy or overburdened network, leading to lag in the user experience. Thinwire over an enlightened data transport (EDT) layer is available, addressing the limitations of TCP on high latency network connections.

Framehawk uses a data transport layer built on top of (User Datagram Protocol (UDP). UDP is a small part of how Framehawk overcomes lossiness, as you can see when comparing the performance of Framehawk with other UDP-based protocols. UDP provides an important foundation to the human-centric techniques that set Framehawk apart.

How much bandwidth does Framehawk require?

The meaning of broadband wireless depends on several factors, including how many users are sharing the connection, the quality of the connection, and apps being used. For optimal performance, Citrix suggests a base of 4 Mbps or 5 Mbps plus about 150 Kbps per concurrent user.

Our bandwidth recommendation for Thinwire is generally a base of 1.5 Mbps plus 150 Kbps per user. For details, see the XenApp and XenDesktop bandwidth blog). At 3% packet loss, you will find that Thinwire over TCP needs much more bandwidth than Framehawk to maintain a positive user experience.

Thinwire remains the primary display remoting channel in the ICA protocol. Framehawk is disabled by default. Citrix recommends enabling it selectively to address the broadband wireless access scenarios in your organization. Remember that Framehawk requires considerably more server resources (CPU and memory) than Thinwire.

Framehawk and HDX 3D Pro

Framehawk supports all the HDX 3D Pro use cases, both for XenApp (Server OS) and XenDesktop (Desktop OS) apps. It was validated in customer environments with 400-500 ms latency and 1-2% packet loss. Thus, providing good interactivity using typical 3D modeling apps such as AutoCAD, Siemens NX, and others. This support extends the ability to view and manipulate large CAD models while on the move, or working from an offshore location or poor network conditions. (Organizations that have a requirement to deliver 3D applications over long haul network connections are encouraged to use adaptive transport. For more information, see Adaptive transport.)

Enabling this functionality doesn’t require any additional configuration tasks. When installing the VDA, select the 3DPro option at the beginning of the installation:

HDX 3D Pro

By using this selection, HDX uses the GPU vendor video driver rather than the Citrix video driver. It defaults to full-screen H.264 encoding over Thinwire rather than the usual default of Adaptive Display and Selective H.264 encoding.

Requirements and considerations

Framehawk requires minimum VDA 7.6.300 and Group Policy Management 7.6.300.

The endpoint must have a minimum Citrix Receiver for Windows 4.3.100 or Citrix Receiver for iOS 6.0.1.

By default, Framehawk uses a bidirectional User Datagram Protocol (UDP) port range (3224-3324) to exchange Framehawk display channel data with Citrix Receiver. The range can be customized in a policy setting called Framehawk display channel port range. Each concurrent connection between the client and the virtual desktop requires a unique port. For multi-user OS environments, such as XenApp servers, define sufficient ports to support the maximum number of concurrent user sessions. For a single-user OS, such as VDI desktops, it is sufficient to define a single UDP port. Framehawk attempts to use the first defined port, working up to the final port specified in the range. This applies both when passing through NetScaler Gateway, and internal connections directly to the StoreFront server.

For remote access, a NetScaler Gateway must be deployed. By default, NetScaler uses UDP port 443 for encrypted communication between the client Citrix Receivers and the Gateway. This port must be open on any external firewalls to allow secure communication in both directions. The feature is known as Datagram Transport Security (DTLS).


Framehawk/DTLS connections are not supported on FIPS appliances.

Encrypted Framehawk connections are supported, starting with NetScaler Gateway version 11.0.62 and NetScaler Unified Gateway version or later.

NetScaler High Availability (HA) is supported from XenApp and XenDesktop 7.12.

Consider the following best practices before implementing Framehawk:

  • Contact your Security administrator to confirm UDP ports defined for Framehawk are open on the firewall. The installation process does not automatically configure the firewall.
  • Often, NetScaler Gateway might be installed in the DMZ, flanked by firewalls on both the external and the internal side. Ensure UDP port 443 is open on the external firewall. Ensure UDP ports 3224-3324 are open on the internal firewall if the environment is using the default port ranges.



Citrix recommends that you enable Framehawk only for users who are likely to experience high packet loss. We also recommend that you do not enable Framehawk as a universal policy for all objects in the Site.

Framehawk is disabled by default. When enabled, the server attempts to use Framehawk for user graphics and input. If the prerequisites are not met for any reason, the connection is established using the default mode (Thinwire).

The following policy settings affect Framehawk:

  • Framehawk display channel: Enables or disables the feature.
  • Framehawk display channel port range: Specifies the range of UDP port numbers (lowest port number to highest) that the VDA uses to exchange Framehawk display channel data with the user device. The VDA attempts to use each port, starting at the lowest port number and incrementing for each subsequent attempt. The port handles inbound and outbound traffic.

Opening ports for the Framehawk display channel

From XenApp and XenDesktop 7.8, an option is available to reconfigure the Firewall during the Features step of the VDA installer. This check box opens UDP ports 3224-3324 on the Windows Firewall, if selected. Manual Firewall configuration is required in some circumstances:

  • For any network Firewalls.
  • The default port range is customized.

To open these UDP ports, select the Framehawk check box:

open UDP ports

You can also use the command line to open UDP ports for Framehawk using /ENABLE_FRAMEHAWK_PORT:

open FH ports

Verifying Framehawk UDP port assignments

During installation, you can verify the UDP ports assigned to Framehawk in the Firewall screen:

default UDP ports

The Summary screen indicates if the Framehawk feature is enabled:

summary screen FH

NetScaler Gateway support for Framehawk

Encrypted Framehawk traffic is supported on NetScaler Gateway or later, and NetScaler Unified Gateway or later.

  • NetScaler Gateway refers to the deployment architecture where the Gateway VPN vServer is directly accessible from the end user device. That is, the VPN vServer has a public IP address assigned and the user connects to this IP address directly.
  • NetScaler with Unified Gateway refers to the deployment where the Gateway VPN vServer is bound as a target to the Content Switching vServer (CS). In this deployment, CS vServer has the public internet protocol address and the Gateway VPN vServer has a dummy internet protocol address.

To enable Framehawk support on NetScaler Gateway, the DTLS parameter on the Gateway VPN vServer level must be enabled. After the parameter is enabled and the components on XenApp or XenDesktop are updated correctly, Framehawk audio, video, and interactive traffic is encrypted between the Gateway VPN vServer and the user device.

NetScaler Gateway, Unified Gateway, and NetScaler Gateway + global server load balancing are supported with Framehawk.

The following scenarios are not supported with Framehawk:

  • HDX Insight
  • NetScaler Gateway in IPv6 mode
  • NetScaler Gateway Double Hop
  • NetScaler Gateway with Cluster setup
Scenario Framehawk Support
NetScaler Gateway Yes
NetScaler + global server load balancing Yes
NetScaler with Unified Gateway Yes. Note: Unified Gateway version and later is supported.
HDX Insight No
NetScaler Gateway in IPv6 mode No
NetScaler Gateway Double Hop No
Multiple Secure Ticket Authority on NetScaler Gateway Yes
NetScaler Gateway and High Availability Yes
NetScaler Gateway and Cluster setup No

Configuring NetScaler for Framehawk support

To enable Framehawk support on NetScaler Gateway, enable the DTLS parameter on the Gateway VPN *vServer *level. After the parameter is enabled and the components on XenApp or XenDesktop are updated correctly, Framehawk audio, video, and interactive traffic is encrypted between the Gateway VPN vServer and the user device.

This configuration is required if you are enabling UDP encryption on NetScaler Gateway for remote access.

When configuring NetScaler for Framehawk support:

  • Ensure UDP port 443 is open on any external firewalls
  • Ensure CGP port (default 2598) is open on any external firewalls
  • Enable DTLS in the settings for the VPN virtual server
  • Unbind and rebind the SSL cert-key pair. This step is not required if you are using NetScaler version or later.

To configure NetScaler Gateway for Framehawk support:

  1. Deploy and configure NetScaler Gateway to communicate with StoreFront and authenticate users for XenApp and XenDesktop.
  2. In the NetScaler Configuration tab, expand NetScaler Gateway, and select Virtual Servers.
  3. Click Edit to display Basic Settings for the VPN Virtual Server; verify the state of the DTLS setting.
  4. Click More to display more configuration options:
  5. Select DTLS to provide communications security for datagram protocols such as Framehawk. Click OK. The Basic Settings area for the VPN Virtual Server shows that the DTLS flag is set to True.
  6. Reopen the Server Certificate Binding screen, and click + to bind the certificate key pair.
  7. Choose the certificate key pair from earlier, click Select.
  8. Save the changes to the server certificate binding.
  9. After saving, the certificate key pair appears. Click Bind.
  10. Ignore the No usable ciphers configured on the SSL vserver/service warning message, if it appears.

Steps for older NetScaler Gateway versions

If you are using a version of NetScaler Gateway older than

  1. Reopen the Server Certificate Binding screen, and click + to bind the certificate key pair.
  2. Choose the certificate key pair from earlier, click Select.
  3. Save the changes to the server certificate binding.
  4. After saving, the certificate key pair appears. Click Bind.
  5. Ignore the No usable ciphers configured on the SSL vserver/service warning message, if it appears.

To configure Unified Gateway for Framehawk support:

  1. Ensure that Unified Gateway is installed and properly configured. For additional information, see Unified Gateway information on the Citrix Product Documentation site.
  2. Enable the DTLS parameter on the VPN vServer, *which is bound to CS *vServer as Target vServer.


If there are stale DNS entries for the NetScaler Gateway virtual server on the client device, adaptive transport and Framehawk might fall back to TCP transport instead of UDP transport. If fallback to TCP transport occurs, flush the DNS cache on the client and reconnect to establish the session using UDP transport.

Support for other VPN products

NetScaler Gateway is the only SSL VPN product to support the UDP encryption required by Framehawk. If another SSL VPN or an incorrect version of NetScaler Gateway is used, the Framehawk policy might fail to apply. Traditional IPsec VPN products support Framehawk without any modifications.

Configure Citrix Receiver for iOS to support Framehawk

To configure older versions of Citrix Receiver for iOS to support Framehawk, you must manually edit default.ica.

  1. On the StoreFront server, access the App_Data directory of your store in c:\inetpub\wwwroot\.
  2. Open the default.ica file and add the following line in the WFClient section: Framehawk=On
  3. Save the changes.

This procedure allows Framehawk sessions to be established from a compatible Citrix Receiver on iOS devices. This step is not required if you are using Citrix Receiver for Windows.


When using Citrix Receiver for iOS version 7.0 and later, you do not have to add the parameter Framehawk=On explicitly in the default.ica file.

Monitoring Framehawk

You can monitor the use and performance of Framehawk from Citrix Director. The HDX Virtual Channel Details view contains useful information for troubleshooting and monitoring Framehawk in any session. To view Framehawk related metrics, select Graphics-Framehawk.

If the Framehawk connection is established, you see Provider = VD3D and Connected = True in the details page. It is normal for the virtual channel state to be idle, because it monitors the signaling channel, which is used only during the initial handshake. This page also provides other useful statistics about the connection.

If you encounter issues, see the Framehawk troubleshooting blog.