Vault: Resolving Jump Server (Connector) Network Issues

Overview

The Jump Server, also referred to as Connector, is a mandatory component of the JumpCloud PAM architecture. It acts as a proxy between users and the privileged resources they access (Servers, Databases, and Websites), and every PAM session passes through it. Without a properly installed and reachable Jump Server, no PAM connection can be established.

This article focuses on diagnosing and resolving network issues that prevent the Jump Server (Connector) from working correctly. It covers two communication paths:

1. User to Jump Server (Connector): the connection a user's device makes to reach the Jump Server, whether through a browser (Web Port) or through an external client such as an SSH terminal (Shell Port).
2. Jump Server (Connector) to target resource: the connection the Jump Server makes to the actual Server, Database, or Website the user is trying to reach.

Understanding the connection topology

Every PAM session starts on the user's device and follows the same path. The user opens a connection by calling the Jump Server's DNS address (connector-subdomain.vault.jumpcloud.com), either in a browser (using the Web Port) or through an external client like an SSH terminal (using the Shell Port). This is the first step of the connection of the connection: user to Jump Server.

Once that connection is established, the Jump Server opens a second connection on its own, this time outbound to the target resource. The protocol used here depends on what the user is accessing: HTTP/S for Websites, RDP, SSH, Telnet, VNC, or Kubernetes for Servers, and SQL-type protocols for Databases. This is the second step of the connection: Jump Server to target resource, and it only happens after the first step of the connection succeeds.

Before You Troubleshoot Network Issues

Many cases reported as "network problems" are actually caused by something that happened earlier, during installation. Before testing connectivity, confirm the following:

Installation completed without errors. The Connector installation script runs a system checklist on the host machine before installing. It validates items such as user privileges to run Docker, server clock drift, available RAM (minimum 8GB), available vCPUs (minimum 2), available disk space on / (minimum 80GB), Docker installation, and the availability of command-line tools like curl, nc, and telnet. The script also tests connectivity to JumpCloud PAM platform endpoints as part of this checklist; this is a separate concern from the network paths covered in this article and is not part of the troubleshooting steps below. If any item in the checklist failed, resolve it and re-run the installation before proceeding.

Docker is running and healthy. The Connector runs as a set of Docker containers. Run docker ps -a on the Connector host and confirm all containers are Up, not Exited or Restarting.

The Connector's configured ports are known. When a Connector is registered, an admin sets a Web Port and a Shell Port. These are not fixed values, they can be customized per Connector. Before testing connectivity, check Administration > Connectors in the PAM Platform and confirm which ports are actually configured for the Connector you're troubleshooting.

If installation looks correct and the Connector's ports are confirmed, continue to the next section.

Diagnosing the User to Jump Server Connection

This is the first step of the connection of the connection: the user's device reaching the Jump Server. Most issues here fall into one of three categories: using the wrong port for the wrong purpose, the Jump Server not being reachable from outside the local network, or the connection being blocked along the way (firewall, NAT, or TLS).

Web Port and Shell Port are two different doors

Every Jump Server (Connector) has two separate ports for incoming connections: the Web Port, used when a user connects through a browser, and the Shell Port, used when connecting through an external client such as an SSH terminal. Think of them as two different doors into the same building. Checking that one door opens doesn't tell you anything about the other.

This matters because it's easy to test the wrong door and think everything is fine. For example, opening https://{connector-ip}:443 in a browser may load successfully. But that only tells you the Web Port is open, it says nothing about the Shell Port, which is the one users actually need for browser-based sessions. Before testing, always confirm which port you're testing and make sure it matches how the user is actually trying to connect.

Using Check Connection to test the DNS address

The PAM Platform includes a built-in test for the Jump Server (Connector)'s DNS address. To use it:

1. Go to Administration > Connectors.
2. Find the Jump Server and open the "..." menu, then select Install.
3. In step 3 of the installation modal, click Check Connection.
4. A new browser tab opens and attempts to reach the Jump Server's DNS address.

Compare the result to these two outcomes:

• Success: the page displays "This server can only be accessed from the application." This confirms the Web Port is reachable through the DNS address. You can close the tab.
• Failure: the page shows a browser-level error, such as "This site can't be reached" or a connection reset. This means something between the user's network and the Jump Server is blocking the connection on the Web Port.

If Check Connection fails

Work through these checks in order:

Step 1: Can the user’s network reach the Jump Server (Connector) at all?

If the Jump Server (Connector) sits on a private network and the user connects from outside it (for example, working remotely), the user's device needs a way to reach it. NAT and VPN are just common examples, not the only valid options, what actually matters is that some method exists to route the user's traffic to the Jump Server. If no such method is in place, the connection will not work, regardless of any other configuration being correct.

This needs to work both ways. Think of it like a locked door: the user needs a path to walk up to the door, and the door itself needs to be unlocked and ready to let them in. The user's network needs a way out to the Jump Server (the path), and the Jump Server needs to be set up to accept that connection when it arrives (the unlocked door). If either one is missing, the user can't get through, even if the other one is perfectly fine.

Step 2: Does the address resolve to an IP?

Before the user's device can connect to anything, it needs to turn the address (like {subdomain}.connect.vault.jumpcloud.com) into an actual IP address it can reach. This is called DNS resolution, and it's a separate step from the connection itself. It's possible for resolution to work while the connection still fails, or for resolution to be the actual problem while everything else is fine, so don't skip this check just because something else looks fine.

To test this, run one of the following commands from the user's own device, not from the Jump Server:

Either command does the same thing, use whichever one is installed. If it returns an IP address, resolution is working and you can move to the next step. If it returns nothing, takes a long time and times out, or shows an error, the problem is in DNS resolution, not in the connection.

Common scenarios at this step:

• The lookup returns an IP, but it doesn't look right. This usually means the user's device is asking a DNS server that has old or incorrect information stored, often a company DNS server that hasn't picked up a recent change. Run the same lookup again, but point it at a public DNS server instead (for example: nslookup {subdomain}.connect.vault.jumpcloud.com 8.8.8.8). If that returns the correct IP, the issue is with the user's company DNS server, not with the Jump Server.
• The lookup never gets an answer (it just times out). This usually means the DNS server the user's device is asking can't be reached, or can't resolve addresses outside the company's own network. Ask the user's IT team which DNS server their device is configured to use, and whether that server is able to resolve public addresses in general, not just this one.
• The lookup fails right away with an error, instead of timing out. This can mean that DNS traffic itself (which normally travels over port 53) is being blocked by a firewall. This is less common, but it does happen on networks with stricter security rules. Ask the network administrator whether DNS requests are restricted to specific internal servers only.

Step 3: Once the address resolves, can the user’s device actually reach the Jump Server (Connector)?

Knowing the IP address isn't the same as being able to reach it, this is the actual connection attempt, separate from DNS. From the user's own device, run:

If the connection succeeds, telnet will say "Connected to..." and nc will say "succeeded", and you can move to the next step. If it hangs without responding, eventually times out, or is refused outright, something between the user's device and the Jump Server (Connector) is blocking that path, like a closed door somewhere along the way.

Common scenarios at this step:

• The connection is refused right away, with an immediate response. This usually means the door itself isn't open, the Web Port isn't actually listening on the Jump Server (Connector), or you're testing the wrong port. Go to Administration > Connectors, check the Web Port configured for this Jump Server (Connector), and make sure it matches the port you used in the test.
• The connection just hangs, with no response at all, until it times out. This is different from being refused, here, nothing is saying no, the request is simply disappearing. This is the typical sign of a firewall quietly dropping the traffic instead of rejecting it. Ask the network administrator to confirm that outbound traffic on the Web Port is explicitly allowed, both on the user's own firewall and on any company firewall or proxy further along the way.
• The test fails using the address, but works when you use the Jump Server (Connector)'s IP directly with the same port. This points to something that treats the named address differently from the raw IP, for example, a company proxy or web filter that inspects traffic by the address itself and blocks or redirects it, even though the same traffic by IP is allowed through. Ask the network or security team whether this address needs to be added to an allow list for proxy or web filtering rules.
• The test fails both ways, by address and by IP. This means the block isn't about how the address is written, it's happening regardless. At this point, the most likely explanation is a firewall rule, a routing issue, or simply no path at all from the user's network to the Jump Server (Connector), which is what Step 1 covers.

Step 4: Is the secure connection (TLS) going through?

Connecting to the Jump Server (Connector) happens over a secure (HTTPS) connection. Before any data is exchanged, the user's device and the Jump Server (Connector) do a quick back-and-forth to agree on how to encrypt the traffic, this is called the TLS handshake. Some firewalls let the connection itself through, but interfere specifically during this handshake, which is a different problem from the connection being blocked outright.

To test this, run:

The -v flag prints out each step of the process. Look through the output for the handshake completing successfully. If it hangs or the connection resets while the handshake is happening, rather than failing to connect in the first place, that's the sign to look for.

Common scenarios at this step:

• The connection works (Step 3 succeeded), but the handshake never completes here. This usually means something between the user's device and the Jump Server (Connector) is inspecting or interfering with secure traffic on that port, commonly a firewall or proxy doing what's called TLS inspection. Ask the network or security team whether this kind of inspection is enabled, and whether this address is excluded from it.
• The handshake fails with a certificate-related error in the output. This points to something on the path presenting its own certificate instead of the Jump Server (Connector)'s, which is also a sign of a proxy or firewall intercepting the secure connection. Check whether a corporate proxy is configured on the user's device and whether it's set up to bypass this address.
• Everything in this step works fine. If the handshake completes successfully here, but the user still can't connect through their browser, the issue is likely outside the network path altogether, for example, in the browser itself or in how the user is accessing the address. At that point, it's worth revisiting the Web Port and Shell Port distinction earlier in this section.

Step 5: Is something inside the Jump Server (Connector) host interfering with its own network?

The Jump Server (Connector) runs as a set of Docker containers, and Docker creates its own internal network on the host machine to manage them. If Steps 1 through 4 didn't explain the issue, especially if the connection works sometimes but not consistently, or behaves strangely, the problem may be happening inside the host itself, rather than anywhere in the path between the user and the Jump Server (Connector).

Two scenarios are worth checking here:

• The Docker network is conflicting with the company's own network. When Docker is installed, it sets up an internal network using its own IP range. If that range happens to overlap with the IP range already used by the company's network, traffic can get misrouted in ways that are hard to diagnose from the outside. This has been seen in practice on hosts where the Docker network and the local network used overlapping addresses. To check this, run the following on the Jump Server (Connector) host:
  • docker network inspect bridge
  • Look for the "Subnet" value in the output (it will look something like 172.17.0.0/16). Compare that range against the IP range used by the company's own network on that host (your network team can confirm this, or you can check it with ip addr on the same machine). If the two ranges overlap, that's the conflict. If this is suspected, reinstalling Docker is the recommended fix, this generates a new internal network for Docker to use, which resolves the overlap.
• Another service on the host is interfering with Docker's network rules. Docker manages its own firewall rules (iptables, or ufw on some systems) to control traffic to and from its containers. If another service running on the same machine also modifies these rules, it can unintentionally block or interfere with the Jump Server (Connector)'s traffic. This is uncommon, and the host running the Jump Server (Connector) should ideally not run other services for this reason, but if it does, check whether any other service has changed iptables or ufw rules and whether those changes conflict with Docker's own rules.
  

Diagnosing the Jump Server (Connector) to Target Resource Connection

This is the second step of the connection of the connection: the Jump Server (Connector) reaching the resource the user is trying to access, a Server, a Database, or a Website. Here, the roles are reversed compared to the first step of the connection, the Jump Server (Connector) is the one starting the connection, and the resource is the one that needs to accept it.

Each resource type uses its own protocol and port

When a resource is added to the PAM Platform, the platform suggests a default port based on the protocol selected, for example, SSH typically uses port 22, and RDP typically uses port 3389. Just like the Web Port and Shell Port on the Jump Server (Connector) itself, these suggested ports can be customized per resource. Before testing connectivity to a resource, check the port configured for that specific resource rather than assuming the default.

Diagnosing the connection

The same logic from the first step of the connection applies here, you're just testing from a different starting point. Instead of testing from the user's device, every command in this section runs from the Jump Server (Connector) host itself, toward the resource.

Step 1: Does the resource’s address resolve to an IP?

If the resource was added to the PAM Platform using a hostname rather than an IP address, the Jump Server (Connector) needs to be able to resolve that hostname on its own. This matters because the Jump Server (Connector) may use a different DNS server than the one users rely on, so resolution working for a user doesn't guarantee it works for the Jump Server (Connector). From the Jump Server (Connector) host, run:

If this doesn't return the expected IP, the Jump Server (Connector)'s own DNS configuration is the place to check first, not the resource itself.

Step 2: Can the Jump Server (Connector) reach the resource on the expected port?

This checks whether the connection actually goes through, separate from resolving the address. From the Jump Server (Connector) host, run:

If this succeeds, the path between the Jump Server (Connector) and the resource is open on that port, and the issue, if there still is one, is likely somewhere else (for example, in the credentials being used, rather than the network). If it hangs, times out, or is refused, something between the Jump Server (Connector) and the resource is blocking that specific port.

Step 3: Is the resource itself set up to accept connections from the Jump Server (Connector)?

This is the most common cause of connection failures on the first step of the connection, especially when the resource lives in the cloud (AWS, Azure, GCP, or similar). Cloud resources are usually protected by their own inbound firewall, commonly called a Security Group. Even if the network path between the Jump Server (Connector) and the resource is otherwise open, the resource will still refuse the connection if its Security Group doesn't explicitly allow traffic from the Jump Server (Connector).

This isn't limited to cloud Security Groups. The same idea applies to any firewall running directly on the resource itself (for example, a Linux server's own ufw rules), or to network-level firewalls sitting between the Jump Server (Connector) and the resource, such as when the resource lives in a separate network segment or DMZ that the Jump Server (Connector) doesn't have a route to by default. In all of these cases, the fix is the same in principle: the resource's network needs to explicitly allow inbound traffic from the Jump Server (Connector).

Step 4: Is the Jump Server (Connector)’s own outbound firewall allowing this specific protocol?

On the first step of the connection, the only outbound traffic to worry about was HTTPS. On this second step, the protocol varies depending on the resource, SSH, RDP, a database protocol, and so on, and it's common for a company's firewall to allow some outbound protocols by default while blocking others. The Jump Server (Connector) host itself can be reachable and otherwise healthy, while still being blocked from sending out one specific kind of traffic.

If Step 2 succeeded for one resource type but a different resource (using a different protocol) fails the same test, this is worth checking. Confirm with the network administrator that outbound traffic is explicitly allowed on the Jump Server (Connector)'s firewall for the specific protocol and port the failing resource uses, not just for the protocols that happen to already be working.