TCP BBR
TCP BBR is a network optimization for the Citrix® Virtual Delivery Agent (VDA) on macOS. It enables BBR (Bottleneck Bandwidth and Round-trip propagation time) congestion control for HDX™/ICA® session traffic, replacing the standard congestion control offered by the macOS kernel network stack. Unlike loss-based algorithms (such as CUBIC), which treat every packet loss as a sign of congestion and back off aggressively, BBR continuously models the network path’s actual available bandwidth and round-trip latency. It paces traffic to match what the path can genuinely sustain. The benefits for end users are most noticeable on high-latency, lossy, or long-distance networks (for example, remote branch offices, VPNs, cross-region access, or Wi-Fi/cellular links):
- Higher and more stable throughput when packet loss is present.
- Lower queuing delay (“bufferbloat”), improving interactivity and responsiveness.
- Faster recovery after transient network disruptions.
The feature is fully transparent to end users and requires no client-side changes.
Enabling and Disabling the Feature
The feature is enabled by default and is controlled through the registry. After changing the setting, restart the VDA (HDX service) for it to take effect.
Turn the feature on or off - Set TcpBbrEnabled (DWORD) under:
HKLM\SYSTEM\CurrentControlSet\Control\Terminal Server\Wds\icawd\HdxBbr
1 = enabled
0 = disabled (default).
Enable
sudo /opt/Citrix/VDA/bin/ctxreg create -k "HKLM\System\CurrentControlSet\Control\Terminal Server\Wds\icawd\HdxBbr" -t "REG_DWORD" -v "TcpBbrEnabled" -d "0x00000001" --force
<!--NeedCopy-->
Disable
Revert to the kernel network stack:
sudo /opt/Citrix/VDA/bin/ctxreg create -k "HKLM\System\CurrentControlSet\Control\Terminal Server\Wds\icawd\HdxBbr" -t "REG_DWORD" -v "TcpBbrEnabled" -d "0x00000000" --force
<!--NeedCopy-->
Adjust the internal virtual-interface addresses (optional) - when enabled, the feature provisions a private point-to-point interface. Its default addresses (10.200.0.1 / 10.200.0.2, netmask 255.255.255.0) can be changed under:
HKLM\System\CurrentControlSet\Control\Citrix\WinStations\tcp
Use UtunLocalIP, UtunPeerIP, and UtunNetmask, and the IPv6 equivalents UtunLocalIP6, UtunPeerIP6, and UtunPrefix6.
Note:
Change these only if the defaults conflict with your environment.
Limitations
Address conflicts: The default 10.200.0.0/24 range is used for the private virtual interface. If this range overlaps with an existing network or interface on the host, connectivity issues may occur. Reconfigure the addresses using the registry keys above.
Coexistence with other PF users: The feature installs macOS Packet Filter (PF) rules. Other applications that also manage PF, such as firewalls, VPNs, and network-shaping tools, may interfere with or be affected by these rules. Validate behavior when running alongside such software.
Troubleshooting
If sessions do not behave as expected after enabling the feature:
- Verify the toggle - Ensure
TcpBbrEnabled=1and that the VDA was restarted. - Confirm the virtual interface exists -
ifconfigshould show the configured addresses (for example,10.200.0.1 -> 10.200.0.2) while a session is active. - Confirm the PF rule files were created - Check
/etc/pf.anchors/forcom.citrix.macvda*.rulesfiles. - Confirm the rules are loaded - Inspect the Citrix anchor:
sudo pfctl -a com.citrix.macvda -s rules
sudo pfctl -a com.citrix.macvda -s nat
sudo pfctl -s info
<!--NeedCopy-->
If the virtual interface or PF rules are missing, confirm the registry key is set and restart the VDA.