Understand and Troubleshoot Horizon Connections
Understanding Horizon Connections
Before starting to plan or trying to troubleshoot Horizon and Blast connections, it is important to understand how a VMware Horizon Client connects to a resource. This can help determine the best architecture, understand the traffic flow, and network ports, and help in troubleshooting.
Although VMware Horizon is used here, including its Horizon Connection Server, most of what is described here is applicable to VMware Horizon Cloud as well. This guide is focused on Blast Extreme connections but most of the content, especially around understanding connections, also applies to PCoIP connections.
Purpose of This Guide
This guide focuses on the connections between VMware Horizon Client and a resource, and how this understanding can be applied to troubleshooting connection issues in both VMware Horizon and Horizon Cloud Services.
Intended Audience
This guide is intended for IT administrators and product evaluators who are familiar with VMware vSphere and VMware vCenter Server®. Familiarity with networking and storage in a virtual environment, Active Directory, identity management, and directory services is assumed. Knowledge of other technologies, such as Horizon is also helpful.
Components
The core components of Horizon that are used in a Horizon connection are described in the following table.
Table 1: Horizon Components
| Description | |
| Horizon Client | The Horizon Client is installed on a client device to access a Horizon-managed system that has the Horizon Agent installed. You can optionally use a web browser as an HTML client for devices on which installing client software is not possible. |
| Horizon Agent | The Horizon Agent is installed on the guest OS of target VM or system. This agent allows the machine to be managed by Connection Servers and allows a Horizon Client to form a protocol session to the machine. Machines can be virtual desktops, Remote Desktop Session Hosts (RDS Host), physical desktops PCs, or blade PCs. |
| Connection Server | The Horizon Connection Server securely brokers and connects users to the Horizon Agent that has been installed in the desktops and RDS Hosts. The Connection Server authenticates users through Active Directory and directs the request to the appropriate and entitled resource. |
| Unified Access Gateway | VMware Unified Access Gateway is a virtual appliance that enables secure remote access from an external network to a variety of internal resources, including Horizon-managed resources. When providing access to internal resources, Unified Access Gateway can be deployed within the corporate DMZ or internal network, and acts as a proxy host for connections to your company’s resources. Unified Access Gateway directs authenticated requests to the appropriate resource and discards any unauthenticated requests. It also can perform the authentication itself, leveraging an additional layer of authentication when enabled. |
Primary and Secondary Protocols
First, it is important to understand that when a Horizon Client connects to a Horizon environment, several different protocols are used, and a successful connection consists of two phases.
The first phase of a connection is always the primary XML-API protocol over HTTPS, which provides authentication, authorization, and session management. Following successful authentication, a connection using one or more secondary protocols is then made to the resource.
Figure 1: Primary and Secondary Protocols
To explore the components and architecture of Horizon, see the Horizon Architecture section of the VMware Workspace ONE and VMware Horizon Reference Architecture.
Internal Connections
An internal connection is one where the Horizon client connects directly to the Connection Server and then directly to the Horizon agent. Normally, this is for connections that are internal to the corporate network.
In the initial authentication phase, the connection is from the Horizon Client to the Connection Server. The secondary protocol session then normally connects directly from the Horizon Client to the Horizon Agent.
Figure 2: Internal Connection
Secondary protocol connections route through the Connection Server only when a gateway or tunnel—the Blast Secure Gateway, the PCoIP Secure Gateway, or the HTTPS Secure Tunnel—is enabled on the Connection Server. This configuration is less common because the protocol session is then tunneled through the Connection Servers, making it part of the ongoing session.
In most typical deployments, the only gateway service used on a Connection Server is the Blast Secure Gateway, which is only used to handle VMware HTML Access (web-based client) traffic. This is covered as a separate topic later in this guide, in the section HTML Client Access Connections.
Communication Flow
Figure 3: Internal Connection Communication Flow
- Horizon Client logs into a Connection Server
- The Connection Server looks up entitlements for user
- User selects a desktop or app
- Horizon Client connects to the Horizon Agent running in the desktop/ RDSH
Although the above diagram shows three separate network zones, it is also supported to have all internal components on the same network with no firewalls between components.
Load Balancing
When load balancing Connection Servers only the initial XML-API connection (authentication, authorization, and session management) needs to be load balanced. Because the secondary protocol connections go directly from the Horizon Client to the Horizon Agent, they do not need to be load balanced.
Network Ports
To ensure successful connections and correct communication between the components, it is important to understand the network port requirements for connectivity in a Horizon deployment.
The diagrams below show an internal connection using each of the possible display protocols and the destination network ports.
Notes:
- The arrows indicate the direction of traffic initiation (source to destination).
- Horizon UDP protocols are bidirectional, so stateful firewalls should be configured to accept UDP reply datagrams.
The following diagram shows the ports required to allow an internal Blast Extreme connection.
Figure 4: Blast Extreme Network Ports for Internal Connection
The following diagram shows the ports required to allow an internal PCoIP connection.
Figure 5: PCoIP Network Ports for Internal Connection
The following diagram shows the ports required to allow an internal RDP.
Figure 6: RDP Network Ports for Internal Connection
The Network Ports in VMware Horizon guide has more detail, along with diagrams illustrating the traffic. It even has specific sections and diagrams on internal, external, and tunneled connections. To see more detail on the network ports required for an external connection, see Network Ports in VMware Horizon: Internal Connection and the Internal Connection diagram.
External Connections
If the connection is external, communication is typically through a VMware Unified Access Gateway appliance. The initial authentication phase of a connection is from the Horizon Client to a Unified Access Gateway appliance and then to a Connection Server. The protocol session connection goes from the Horizon Client to the Unified Access Gateway and then to the Horizon Agent.
Figure 7: External Connection
The Unified Access Gateway can run the following gateway services: Blast Secure Gateway, PCoIP Secure Gateway, and HTTPS Secure Tunnel. Ensure that the Blast Secure Gateway and PCoIP Secure Gateway are not also enabled on the Connection Server because this would cause a double-hop attempt of the protocol traffic, which is not supported and will result in failed connections.
Communication Flow
Figure 8: External Connection Communication Flow
The figure above demonstrates the connection flow:
- The user uses the Horizon Client to log into a Connection server via a Unified Access Gateway
- The Connection Server looks up entitlements for user.
- The user selects a desktop or application resource to connect to.
- The Horizon Client connects to the Horizon Agent running in the desktop or RDSH.
- This will be via the Blast Secure Gateway on the same Unified Access Gateway appliance as the one where the user authenticated.
Load Balancing
When load balancing Horizon traffic to multiple Unified Access Gateway appliances, the initial XML-API connection (authentication, authorization, and session management) needs to be load balanced. The secondary Horizon protocols must be routed to the same Unified Access Gateway appliance to which the primary Horizon XML-API protocol was routed. This allows the Unified Access Gateway to authorize the secondary protocols based on the authenticated user session.
If the secondary protocol session is misrouted to a different Unified Access Gateway appliance from the primary protocol one, the session will not be authorized. The connection would therefore be dropped in the DMZ, and the protocol connection would fail. Misrouting secondary protocol sessions is a common problem if the load balancer is not configured correctly.
The load balancer affinity must ensure that XML-API connections made for the whole duration of a session (default maximum 10 hours) continue to be routed to the same Unified Access Gateway appliance.
Although the secondary protocol session must be routed to the same Unified Access Gateway appliance as was used for the primary XML-API connection, there is a choice about whether the secondary protocol session is routed through the load balancer or not. This normally depends on the capabilities of the load balancer.
For example, with a VMware NSX Advanced Load Balancer (formerly Avi), primary and secondary protocol traffic goes through the Avi Service Engines, and that ensures the correct routing of secondary protocol sessions by using source IP affinity. This has the advantage of needing only a single public IP address. Where the load balancer does not have this capability, or where source IP affinity cannot be used, another option is to dedicate additional IP addresses for each Unified Access Gateway appliance so that the secondary protocol session can bypass the load balancer. This is often referred to as the N+1 VIP method where a load balanced VIP is used for the primary protocol and the secondary protocol is routed directly to one of the N VIPs dedicated to each Unified Access Gateway appliance. See Load Balancing Unified Access Gateway for Horizon.
Network Ports
To ensure successful external connections, and correct communication between the components, it is important to understand the network port requirements for connectivity in a Horizon deployment. The diagrams below show an external connection using each of the possible display protocols and the destination network ports.
Notes:
- The arrows indicate the direction of traffic initiation (source to destination).
- Horizon UDP protocols are bidirectional, so stateful firewalls should be configured to accept UDP reply datagrams.
The following diagram shows the ports required to allow an external Blast Extreme connection through Unified Access Gateway.
Figure 9: Blast Extreme Network Ports for External Connections
The following diagram shows the ports required to allow an external PCoIP connection through Unified Access Gateway.
Figure 10: PCoIP Network Ports for External Connections
The following diagram shows the ports required to allow an external RDP connection through Unified Access Gateway.
Figure 11: RDP Network Ports for External Connections
The Network Ports in VMware Horizon guide has more detail, along with diagrams illustrating the traffic. It even has specific sections and diagrams on internal, external, and tunneled connections. To see more detail on the network ports required for an external connection, see Network Ports in VMware Horizon: External Connection and the External Connection diagram.
Architecture
When using Unified Access Gateway to provide external access to Horizon, the same Connection Servers can be used for both external and internal connections.
Figure 12: Unified Architecture
With the preferred architecture for traffic flow and load balancing of Unified Access Gateways and Connection Servers, a load balancer is not placed inline between the Unified Access Gateways and the Connection Servers. The architecture simplifies the design and makes it easier to troubleshoot.
Note: It is still a valid architecture and supported to have a load balancer inline between the Unified Access Gateways and the Connection Servers. When a load balancer is placed between the two, the Unified Access Gateway cannot detect if an individual Connection Server is down.
For more information, see External Access Architecture.
Troubleshooting Connections
Now that you have an understanding of how a Horizon connection and session is established, you can start to look when things don’t work. Knowing what is meant to happen during a successful connection helps you understand and troubleshoot when things do not work.
This guide focuses on troubleshooting an external connection, as this shows all possible components and communication flows. The troubleshooting steps can also be applied to internal connections.
The diagram below illustrates an external connection, and the numbers indicate the communication flow.
Figure 13: External Connection Full Communication Flow
- Horizon Client authentication to the load balancer in front of Unified Access Gateways
- Authentication traffic from the load balancer to one of the Unified Access Gateways
- (Optional) Authentication traffic from the Unified Access Gateway to a third-party authentication source (for example RADIUS, RSA SecurID, SAML 2.0 Identity Provider)
- Authentication traffic from the Unified Access Gateway to one of the Connection Servers (as defined in the Unified Access Gateway’s Connection Server URL).
- Protocol session from the Horizon Client to the same Unified Access Gateway that was used for authentication. Depending on the load balancing configuration, this traffic may go via the load balancer.
- Protocol session from the Unified Access Gateway to the Horizon Agent running in the virtual desktop of Windows Server
Note: While not part of the connection communication flow, it is important to note that the Horizon Agent will communicate to the Connection Servers to indicate its state.
To troubleshoot a Horizon connection, first determine which phase is failing (authentication or protocol). Is the user able to authenticate or not? Are they able to log in, select a Horizon resource and launch it? Does the Horizon resource fail to connect for the user? If a user is unable to authenticate, we can limit the initial investigation to the first four steps listed above.
Most problems are not related to the Horizon components themselves. More commonly, they are issues with a misconfigured firewall blocking ports, a misconfigured load balancer misrouting connections, or network routing not allowing traffic to route to the destination (Connection Server, Agent or authentication server).
The initial troubleshooting steps should involve:
- Checking that the required ports are allowed through firewalls. Review the Network Ports information in the Internal Connections and External Connections sections in this guide. For full detail on the ports required see: Network Ports in VMware Horizon.
- Ensuring that network routing is configured to allow traffic to flow between all the components illustrated on the diagram above.
- Checking common issues such as a misconfiguration on the load balancer or an incorrectly defined Blast External URL.
The main areas of the communication flow that should be investigated are:
- Horizon Client to Unified Access Gateway
- (Optional) Unified Access Gateway to third-party authentication source
- Unified Access Gateway to Connection Server
- Unified Access Gateway to Horizon Agent
- Horizon Agent to/from Connection Server
Figure 14: Main Communication Points
Horizon Client to Unified Access Gateway
On the primary authentication phase, the Horizon Client connects to one of the Unified Access Gateways. This requires TCP 443 to be able to be routed from the Horizon Client to the Unified Access Gateway.
For the secondary protocol phase, the ports required depend on the display protocol being used, and with Blast, which specific ports have been configured for use on the Unified Access Gateway. When the Blast connection fails between the Horizon Client and the Unified Access Gateway, this displays a timeout log entry in bsg.log on Unified Access Gateway.
The main areas to investigate in troubleshooting this are as follows.
External Firewall
Ensure that the firewall between the Horizon Client and the Unified Access Gateway is not blocking the ports required by the Blast Extreme protocol port from the Horizon client.
This will be either port TCP 8443 or TCP 443 depending on how the blastExternalUrl setting was configured on the Unified Access Gateway.
Blast can also optionally use UDP 8443 from the Horizon Client to the Unified Access Gateway but should attempt initial connection over TCP first.
Load Balancer Affinity
The secondary Horizon protocol (Blast Extreme, PCoIP) must be routed to the same Unified Access Gateway appliance to which the primary Horizon authentication was routed. This allows the Unified Access Gateway to authorize the secondary protocols based on the authenticated user session.
If the secondary protocol session is misrouted to a different Unified Access Gateway appliance from the primary protocol one, the session will not be authorized. The connection would therefore be dropped in the DMZ, and the Blast connection would fail.
For Blast connections this will show in the bsg.log on the Unified Access Gateway, where the Blast session does not arrive at the same Unified Access Gateway, within the default of 60 seconds.
[absg-master] – Removing idle route 44271692-*** to target 192.168.2.151|22443, idled for 60.00 seconds, registered for 60.01 seconds
Misrouting secondary protocol sessions is a common problem if the load balancer is not configured correctly. The load balancer affinity must ensure that connections made for the whole duration of a session (default maximum 10 hours) continue to be routed to the same Unified Access Gateway appliance that was used for authentication.
Check that the affinity and timeout is configured correctly on the load balancer. See Load Balancing Unified Access Gateway for Horizon.
Load Balancer Websockets
Blast Extreme uses WebSockets. Some load balancers can block WebSockets and some have WebSockets turned off by default. This has been seen with both Citrix NetScaler and Microsoft TMG.
Check the configuration of the load balancer in front of the Unified Access Gateways to ensure that the use of WebSockets is enabled.
Blast External URL
The blastExternalUrl is a configuration on the Unified Access Gateway that specifies the URL and port that should be used by the Horizon Clients to connect with Blast to the Unified Access Gateway.
This should be set to a value usable by the client to connect to the Unified Access Gateway appliances or to the load balancer name if there is one in front of the Unified Access Gateways. When this isn't the case, Unified Access Gateway never receives the Blast connection.
Check the configuration of blastExternalUrl and change the URL and port if required. Valid ports should be either 8443 or 443.
Certificates
Check the TLS/SSL certificates used on the Unified Access Gateway, and on the load balancer if it is handling TLS/SSL offload or re-encryption. The same certificate should be used on the load balancer and the Unified Access Gateway appliances.
If there is a certificate mismatch or a bad SSL certificate on the Unified Access Gateway, connections fail. If the Blast connection is misrouted to the wrong Unified Access Gateway appliance and that appliance has a different certificate to the correct appliance, this also causes connection failures.
You can run the curl command to look at the certificate on the Unified Access Gateway. For example, from the UAG console run this command to see the certificate used with the Horizon edge services:
curl -k -v https://127.0.0.1 >/dev/null
You can also check the certificate used with the admin interface on port 9443:
curl -k -v https://127.0.0.1:9443 >/dev/null
You can also use a web browser to connect to the UAG on port 433 and 9443 to view the user and admin certificates respectively.
Testing Connectivity
From a Windows Client, you can test the connectivity to Unified Access Gateway. Depending on which gateway services and ports are being used, use the appropriate command from below.
Open a PowerShell command shell
Test-NetConnection uag-hostname-or-ip-address -port 443
Test-NetConnection uag-hostname-or-ip-address -port 8443
Test-NetConnection uag-hostname-or-ip-address -port 4172
You can also use curl as a trace equivalent:
curl --trace <outputfile> https://hostname.domain.com
This enables a full trace dump of all incoming and outgoing data, including descriptive information, to the given output file.
Use "-" as the filename to have the output sent to the console, using standard output (stdout), instead of directing it to a file.
curl --trace - https://uag-hostname.domain.com
Alternatively, use curl --trace-ascii. This is very similar to --trace, but leaves out the hex part and only shows the ASCII part of the dump. It makes smaller output making it easier to read by the end user.
curl --trace-ascii <outputfile> https://hostname.domain.com
Install tcpdump on Unified Access Gateway
tcpdump is a useful tool to trace packets in and out of Unified Access Gateway. To install it, run:
/etc/vmware/gss-support/install.sh
You can then run the tcpdump command. Examples are:
tcpdump -i any -n -v port 443
tcpdump -i any -n -v port 8443
tcpdump -i eth0 -n -v udp port 8443
tcpdump -i any -n -v port 4172
Unified Access Gateway to Third-Party Identity Provider
When Unified Access Gateway has been configured to use a third-party identity provider as an authentication source, such as RADIUS or RSA SecurID, ensure that the hostname of the authentication source is resolvable, and that traffic can be properly routed to it.
RADIUS
Run the following command on the Unified Access Gateway to verify name resolution and connectivity. ICMP may be blocked by a firewall so ping will not always work, but name resolution must work.
nslookup radius-server-hostname
tracepath radius-server-hostname
Trace Packets with tcpdump
tcpdump is a useful tool to trace packets in and out of Unified Access Gateway. To install it, run:
/etc/vmware/gss-support/install.sh
You can then run the following tcpdump command.
tcpdump -i any -n -v port 1812
RDS SecurID
Common issues include firewall blocking the ports required, correct network routing not in place, name resolution not working, or the node secret needing to be renegotiated.
Firewall
Unified Access Gateway uses the RSA SecurID client which communicates with the RSA Authentication Manager Server, normally using UDP port 5500 (with UDP replies in the opposite direction). If there is a firewall in between which blocks this UDP and/or reply port the SecurID authentication will fail.
Logs on RSA Authentication Manager server will show that there has been no contact from Unified Access Gateway.
RSA Authentication Manager Hostname Resolution
Inside the sdconf.rec file extracted from RSA Authentication Manager, there is one or more hostname. Those hostnames must be resolvable by Unified Access Gateway.
Run the following command on the Unified Access Gateway using the hostname found in the sdconf.rec file to verify name resolution and connectivity. ICMP may be blocked by a firewall so ping won't always work, but name resolution must work.
nslookup rsa-auth-manager-hostname
tracepath rsa-auth-manager-hostname
This can fail if the DNS, used by Unified Access Gateway, does not have that hostname present.
If the hostname is not resolved, the solution is to either add the hostname to the DNS, used by Unified Access Gateway, or to add a hosts file entry for the host (which can be done automatically during deployment using the PowerShell method).
Logs on RSA Authentication Manager server will show that there has been no contact from Unified Access Gateway.
Clear Node Secret
When first deployed, node secrets are negotiated/exchanged between Unified Access Gateway and RSA Authentication Manager Server. If RSA Authentication Manager Server is redeployed or if Unified Access Gateway and is redeployed, the node secret on the other side needs to be cleared so that the renegotiation happens. There are good logs on RSA Authentication Manager Server which show this problem.
Trace Packets with tcpdump
The tcpdump is a useful tool to trace packets in and out of Unified Access Gateway. To install it, run:
/etc/vmware/gss-support/install.sh
You can then run the tcpdump command.
tcpdump -i any -n -v port 5500
This will show communication attempts with RSA Authentication Manager server using the IP address from the hostname resolution described above. When correctly configured, UDP datagrams will be seen sent on destination port 5500 and reply datagrams from that port will also be seen.
If outbound UDP datagrams are seen but no reply datagrams, then it could be a firewall blocking the port, the datagrams are not reaching RSA Authentication Manager or reply datagrams not being routed back to Unified Access Gateway. Check the RSA Auth Manager logs.
Unified Access Gateway to Connection Server
As part of the primary authentication phase, the Unified Access Gateway will connect to one of the Connection Servers using port TCP 443.
- Networking - Ensure that TCP 443 is open from the Unified Access Gateways to the Connection Servers, allowed through any firewall that may be present, and that network routing is in place between the two components.
- Connection Server URL - Check that the Connection Server URL defined on the Unified Access Gateway is correct and that the Unified Access Gateway can resolve this URL using DNS.
- Certificates – Check that the Connection Server has a TLS/SSL certificate that is trusted by the Unified Access Gateway. Alternatively make sure that the Unified Access Gateway is configured with the Connection Servers URL thumbprints.
Testing Connectivity
Open a remote console or SSH onto the Unified Access Gateway appliance command line. Log on as root and run the following command.
curl -v -k https://hostname-or-ip-address:443/
If the Unified Access Gateway can successfully connect to the Connection Server, you will see similar output to the following screenshot.
Figure 15: Successful curl test of Unified Access Gateway to Connection Server
From the Unified Access Gateway command line, run the following command to check whether the Unified Access Gateway can resolve the name of the Connection Server.
nslookup hostname
Figure 16: nslookup from Unified Access Gateway
On Unified Access Gateway, when there are any issues connecting to the Connection Server, this is logged in esmanager.log on the Unified Access Gateway, similar to the following:
[nioEventLoopGroup-7-1]ERROR view.ViewEdgeService[onFailure: 165][]: Failed to resolve hostname address in proxyDestinationUrl: s1-cs3.eucmobility.com
[nioEventLoopGroup-4-1]WARN client.HttpClient[operationComplete: 359][]: unable to connect to s1-cs3.eucmobility.com:443, reason=io.netty.channel.AbstractChannel$AnnotatedConnectException: Connection timed out: s1-cs3.eucmobility.com/192.168.2.33:443 retryCount:3
nioEventLoopGroup-4-1]ERROR client.HttpClient[lambda$send$1: 246][]: unable to connect to s1-cs3.eucmobility.com:443, reason=io.netty.channel.ConnectTimeoutException: connection timed out: s1-cs3.eucmobility.com/192.168.2.33:443
[Monitoring]ERROR view.ViewEdgeService[healthCheckBroker: 407][]: Exception message: io.netty.channel.ConnectTimeoutException: connection timed out: s1-cs3.eucmobility.com/192.168.2.33:443
[nioEventLoopGroup-4-1]WARN client.HttpClient[operationComplete: 359][]: unable to connect to s1-cs3.eucmobility.com:443, reason=io.netty.channel.AbstractChannel$AnnotatedConnectException: Connection timed out: s1-cs3.eucmobility.com/192.168.2.33:443 retryCount:2
DNS Issues
With Unified Access Gateway 3.7 and newer, which runs on Photon 3, the /etc/resolv.conf file does not contain the DNS server IP addresses. This is by design. Do not manually edit the /etc/resolv.conf file. DNS IP addresses should either be added via the PowerShell .ini setting file at deployment or using the Unified Access Gateway Admin console.
Do not use .local for hostnames, as this is reserved for Multicast DNS (mDNS) and resolve requests for names ending in .local will not be sent to normal (Unicast) DNS. Earlier versions of Unified Access Gateway, based on Photon 2, did allow .local names to be resolved, but this has been rectified in Unified Access Gateway 3.7 and later.
If hosts in the environment have been named with a .local suffix, then there are three workarounds until you can move away from the reserved suffix .local.
- Use an IP address in place of hostname references in settings such as ntpServers, proxydestinationUrl, etc.
- Add the host entry for the .local host in the Unified Access Gateway hosts file (via PowerShell or the Admin UI). Never edit /etc/hosts file directly.
- Add an alias CNAME record in DNS to give an alternative name for any .local host.
- For example, for the myinternalserver.local DNS entry, use myinternalserver.int as a CNAME and then use the .int name for any hostname references on the Unified Access Gateway.
Check which DNS server IP addresses that have been configured on Unified Access Gateway using the following command.
systemd-resolve --status
Make sure that the Unified Access Gateway can ping each DNS server IP address:
ping <DNS Server IP Address>
Attempt to resolve the hostname using DNS.
nslookup <hostname>
You can also look at the DNS protocol activity (requests and responses) by using tcpdump on the Unified Access Gateway.
/etc/vmware/gss-support/install.sh
tcpdump -i any -n -v udp port 53
To run it in the background, just put “&” at the end.
tcpdump -i any -n -v udp port 53&
Note that with tcpdump output with nslookup on Unified Access Gateway 3.7 and newer, it will show DNS queries going to 127.0.0.53 UDP port 53. This is the local DNS listener systemd-resolv which then forwards the DNS query to the configured DNS servers as shown with systemd-resolve --status
Unified Access Gateway to Horizon Agent
As the protocol session connects as part of the secondary session, the Unified Access Gateway connects to the Horizon Agent running in the virtual desktop or the Windows Server (if running RDSH for published applications).
For a Blast connection, this uses TCP 22443 (and optionally UDP 22443). Ensure that any firewall present allows this traffic from the Unified Access Gateway to the Agent and that network routing is in place to allow and direct the traffic.
Connection Server Misconfiguration
If the Connection Server has been configured for Blast Secure Gateway (BSG), this causes Blast connections through Unified Access Gateway to fail.
- Blast Extreme does not support multi-hop Blast Secure Gateway, for example, running the BSG at both the Unified Access Gateway and also on the Connection Server.
- Errors will be visible in the
bsg.logon the Unified Access Gateway.
Figure 17: Ensure Connection Servers have Tunnel and Protocol Gateways Deactivated
Similarly, if PCoIP is used through Unified Access Gateway, the PCoIP Secure Gateway service should not be configured on the Connection Server, as this would also cause a double hop of the protocol and connections to fail.
Testing Connectivity
Testing connections to the Horizon Agent using Blast over 22443 or PCoIP over 4172 is not possible, as the desktops do not listen on these port numbers until a session is ready. You can look at logs to see connection failures on these ports.
Test using the Horizon Framework Channel TCP connection
curl -v telnet://virtualdesktop-ip-address:32111
Test using the Horizon MMR/CDR TCP connection
curl -v telnet://virtualdesktop-ip-address:9427
HTML Client Access Connections
When HTML Access is used, a web browser is used as the client to access a Horizon resource instead of an installed, native Horizon Client. One consideration is that the browser should trust the SSL certificate presented to it.
In an external connection, the Unified Access Gateway runs the Blast Secure Gateway and will present the Unified Access Gateway certificate to the browser to verify identity.
With an internal connection, where the protocol session is normally direct from the client to the Horizon Agent, the agent side must present a trusted certificate to the browser. This presents some challenges.
- By default, Connection Server gives preference to sending the IP addresses, rather than host names, of desktop machines and RDSH servers to clients, which causes the certificate to be mismatched and not trusted. (This behavior can be changed to give preference to DNS names.)
- The desktop machines and RDSH servers must have a certificate installed that will be trusted by the browser on the client device. This behavior has traditionally led to the use of wildcard certificates.
Configuration
A feature on the Horizon Connection Server helps overcome these constraints. In Horizon Administrator, you can configure the use of the Blast Secure Gateway to provide secure access to remote desktops and applications only when HTML Access is used locally.
The Blast Extreme protocol traffic session is routed through the Connection Server and is presented with its SSL certificate. This removes the need to change the default way that the Connection Server sends the machine or RDSH server information to the host. It also means that there is no need to manage certificates on the desktop machines and RDSH servers.
Figure 18: Connection Server Gateway Settings
With only the Enable the Blast Secure Gateway for HTML Access setting configured on the Connection Server, we get the following behavior:
- Internal HTML Access users that connect directly to the Connection Server have the Blast connection go through the Blast Secure Gateway on the Connection Server.
- Internal native Horizon Clients have the Blast connection go directly to the desktop.
- External users (HTML Access or native client) connecting through a Unified Access Gateway have the Blast connection go through the Blast Secure Gateway on the Unified Access Gateway. The connection then goes from the Unified Access Gateway appliance to the Horizon Agent and does not touch the Blast Secure Gateway on the Connection Server, and not incurring a double hop of the protocol.
Figure 19: Internal Connection using HTML Access
It also means a Connection Server can be shared for both internal and external connections, with the gateway services—the Blast Secure Gateway, the PCoIP Secure Gateway, and the HTTPS Secure Tunnel—running on the Unified Access Gateway for most use cases.
Only internal HTML Access connections go through the Blast Secure Gateway on the Connection Server.
HTML Access Failure
In some cases, you may find that the native Horizon Client works with Blast Extreme but using the HTML Access Client fails (with some browsers and not others). With HTML Access and Horizon, if you connect to a Connection Server through a load balancer or a gateway, such as Unified Access Gateway, you must first configure a security setting in Horizon.
A common reason for these failures is an Origin check failure on Connection Server. Look at the debug log file on the Connection Servers and search for "Origin" to look for origin checking failures. For more information, see "Origin Checking" in the Horizon Security document.
To resolve this, see Allow HTML Access Through a Load Balancer.
Summary and Next Steps
This guide described how a VMware Horizon Client connects to a resource to help you plan and troubleshoot Horizon and connections with VMware Horizon. This can be helpful with VMware Horizon Cloud Services as well.
Additional Resources
For more information about VMware Horizon Client connections, you can explore the following resources:
- Horizon Tech Zone activity path
- VMware Workspace ONE and Horizon Reference Architecture
- Allow HTML Access Through a Load Balancer
- Load Balancing Unified Access Gateway for Horizon
- Network Ports in VMware Horizon guide
Changelog
The following updates were made to this guide:
| Date | Change |
| 2022-10-11 | Added info on how to check certificates used by Unified Access Gateway. |
| 2022-10-01 | Updated to reflect the new preferred architecture of not having a load balancer in between the Unified Access Gateways and the Connections Servers. Note that it is still supported to have a load balancer in between them but for new deployments the preference is to have a direct mapping of Unified Access Gateway to Connections Server. |
| 2021-02-01 | Updated for Horizon 8. Changed the heading levels inside the Troubleshooting section to highlight the different areas and the information more clearly for each of them. |
| 2020-04-29 | Initial version. |
Author
Graeme Gordon is a Senior Staff End-User-Computing Architect, End-User-Computing Technical Marketing, VMware.
Reviewers and Contributors
- Mark Benson, VMware Alumni.
- Hilko Lantinga, Staff End-User-Computing Architect, VMware.
To comment on this paper, contact VMware End-User-Computing Technical Marketing at euc_tech_content_feedback@vmware.com