Product Documentation

Framehawk virtual channel

Mar 22, 2016


The Framehawk virtual channel optimizes the delivery of virtual desktops and applications to users on broadband wireless and lossy long-haul broadband network connections, when high packet loss or congestion occurs. You can use Citrix policies to implement either Framehawk or Thinwire for a set of users in a way that is appropriate for your network characteristics, and is aligned with overall scalability and performance expectations.

Generally, user experience has focused on frame rate and visual quality as a basis for a positive user experience. Framehawk enhances the definition to account for linearity. Users need to enjoy the experience, not be distracted by it. Under degraded network circumstances, users struggle with the "rubber band" effect that plagues all protocols. This effect includes the tapping-waiting-tapping syndrome where a user isn't sure if the screen will respond, resulting in extra errant clicks by the user, creating more and more undesirable results. Framehawk smooths out those experiences, especially under strenuous network conditions.

High-speed home Internet connections frequently exhibit performance issues, whether due to collisions with neighboring Wi-Fi signals or spectral interference from cordless devices, among others. More and more users are connecting to hosted apps and data via 3G or 4G/LTE cellular networks, or using inflight Internet services. Others like to take advantage of public Wi-Fi hotspots while stopping for a coffee break or at hotels where congestion is a common problem. 

With Framehawk, users notice a more interactive experience (a more linear echoback of characters) at high latencies.

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 it comes to areas of the screen that are changing rapidly, like video or moving graphics, it doesn't matter to the human eye if some pixels are lost along the way because they are quickly overwritten with new data.

But when it comes to static areas of the screen, such as the icons in the systray or a toolbar, or text after scrolling to where the user wants to start reading, the human eye is very fussy; a user expects those areas to be pixel perfect. Unlike protocols that aim 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 QoS 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 distinguishes between scrolling up or down, zooming, moving to the left or right, reading, typing, and other common actions, and 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 needs to be excellent. If the user is scrolling, it should 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 (which we call "gearing", analogous to the tension on a bicycle chain), the Framehawk logic can react 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 well-suited to a broad range of access scenarios and network conditions, it is TCP-based for reliable data communications and therefore must retransmit packets on a lossy or overburdened network, leading to lag in the user experience.

Framehawk is UDP based, taking a best-effort approach at data transmission. UDP is just a small part of how Framehawk overcomes lossiness, as can be seen when comparing the performance of Framehawk with other UDP-based protocols, but it provides an important foundation to the human-centric techniques that sets 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 or 5 Mbps plus about 150 Kbps per concurrent user. 

The Citrix bandwidth recommendation for Thinwire is generally a base of 1.5 Mbps plus 150 Kbps per user (for more detail, refer to XenApp and XenDesktop bandwidth blog), but at 3% packet loss you will find that Thinwire needs much more bandwidth than Framehawk to maintain a positive user experience.

Note: 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.

Framehawk and HDX 3D Pro

Framehawk now supports all the HDX 3D Pro use cases, both for XenApp (server OS) and XenDesktop (desktop OS) apps. In early previews, it has been validated in customer environments with 400-500 ms latency and 1-2% packet loss, 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.

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

localized image

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 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, you need to 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).

Note: 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. 

Consider the following best practices before implementing Framehawk virtual channels:

  • 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.
  • In many cases, NetScaler Gateway might be installed in the DMZ, flanked by firewalls on both the external as well as the internal side. Ensure UDP port 443 is open on the external firewall, and UDP ports 3224-3324 are open on the internal firewall if the environment is using the default port ranges.


Caution: Citrix recommends that you enable Framehawk only for users experiencing high packet loss. It is also recommended that you do not enable Framehawk as a universal policy for all objects in the Site.

The Framehawk virtual channel is disabled by default.  When enabled, the server attempts to use the Framehawk virtual channel for users' 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 port number) that the VDA uses to exchange Framehawk display channel data with the user device. The VDA attempts to use each port, starting with the lowest port number and incrementing for each subsequent attempt. The port handles inbound and outbound traffic.

Opening ports for the Framehawk display channel

In release 7.8, a new option is available to reconfigure the Firewall during the Features step of the VDA installer. This checkbox opens UDP ports 3224-3324 on the Windows Firewall, if selected. Please note that manual Firewall configuration is required in some circumstances:

  • for any network Firewalls, or
  • if the default port range is customized.

To open these UDP ports, select the Framehawk checkbox:

localized image

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

localized image

Verifying Framehawk UDP port assignments

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

localized image

The Summary screen indicates if the Framehawk virtual channel feature is enabled: 

localized image

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 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 will have the public IP and the Gateway VPN vServer will have a dummy IP.

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
  • Multiple Secure Ticket Authority (STA) on NetScaler Gateway
  • NetScaler Gateway with High Availability (HA)
  • NetScaler Gateway with Cluster setup
Scenario Framehawk support
NetScaler Gateway Yes
NetScaler + Global Server Load Balancing  Yes
NetScaler with Unified Gateway


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 (STA) on NetScaler Gateway No
NetScaler Gateway with High Availability (HA) No
NetScaler Gateway with Cluster setup No

Configuring NetScaler for Framehawk support

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. 

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 internal firewalls between NetScaler and XenApp and XenDesktop servers
  • Enable DTLS in the settings for the VPN virtual server
  • Unbind and rebind the SSL cert-key pair; note that this 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 additional 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.

Additional 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 configurd. For additional information, refer to the 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.

Support for other VPN products

NetScaler Gateway is the only SSL VPN product to support the UDP encryption required by Framehawk. The Framehawk policy may fail to apply if another SSL VPN or an incorrect version of NetScaler Gateway is used. Traditional IPSec VPN products will support Framehawk without any modifications.

Configure Citrix Receiver for iOS to support Framehawk

To configure 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 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.

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 the Framehawk virtual channel in any session. To view Framehawk-related metrics, select Graphics-Framehawk.

If the Framehawk connection is established, you will 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.