NetStacksNetStacks
Contact SalesDownload

Connection Issues

Diagnose and resolve SSH and Telnet connection problems: timeouts, refused connections, key exchange failures, host key changes, jump hosts, and firewalls.

Overview

Connection issues are the most common category of problems when working with network devices through NetStacks. They fall into several distinct categories, each with a different root cause and resolution path.

Connection Issue Categories

  • Timeout — The connection attempt hangs and eventually fails. Usually indicates a network reachability problem or a firewall silently dropping packets.
  • Connection Refused — The target device actively rejects the connection (TCP RST). Indicates the SSH/Telnet service is not running or the port is wrong.
  • Key Exchange Failure — The SSH handshake fails because the client and server cannot agree on a cryptographic algorithm.
  • Host Key Changed — The device's host key no longer matches the previously trusted key, so NetStacks blocks the session for review.
  • Firewall / ACL Blocking — Network access control lists or firewalls silently drop or reject connection attempts.
Note

NetStacks supports SSH (v2) and Telnet. SSH is the default and recommended protocol. Telnet sends credentials and data in cleartext and should only be used for legacy devices that cannot run SSH.

How It Works

Understanding how NetStacks establishes a connection helps you pinpoint where in the process a failure occurs.

SSH Connection Flow

  1. DNS Resolution — The hostname is resolved to an IP address (skipped if an IP is supplied directly).
  2. TCP Connection — A TCP socket is opened to the host on the configured port (default 22 for SSH, 23 for Telnet). NetStacks applies a built-in connect timeout while the socket is being established.
  3. Protocol Version Exchange — Client and server exchange SSH version strings (for example SSH-2.0-OpenSSH_9.6).
  4. Key Exchange (KEX) — Both sides negotiate the key exchange method, host key type, cipher, and MAC. NetStacks advertises a broad list of modern and legacy algorithms and the strongest common one is selected.
  5. Host Key Verification — The presented host key is checked against the trusted record. A new host is recorded on first use; a changed key blocks the session pending approval.
  6. Authentication — The client authenticates with the stored credential (password or SSH key).
  7. Channel Setup — An interactive shell channel is opened and the terminal session begins.

Jump Host Chaining

When a jump host (bastion) is configured on the profile or session, NetStacks first connects to the jump host, then opens a forwarded TCP channel through it to reach the final target. A profile can reference either a saved jump host (jump_host_id) or another session used as the jump endpoint (jump_session_id) — the two are mutually exclusive.

Tip

Failures at different stages produce different errors. Timeouts occur at stages 1–2, key exchange errors at stage 4, host key warnings at stage 5, and credential errors at stage 6 (see the Authentication Problems guide).

Step-by-Step Guide

Follow this diagnostic flow from the outside in. Work through each step until you find the layer where the connection breaks.

Step 1: Verify Network Reachability

Confirm the device is reachable at the IP layer before troubleshooting SSH.

Network Reachabilitybash
# Ping the device to verify basic connectivity
ping -c 4 192.168.1.1

# If ping fails or is filtered, check the path
traceroute 192.168.1.1

Step 2: Check Port Accessibility

Verify the SSH or Telnet port is open and accepting TCP connections.

Port Checkbash
# Test the default SSH port (22)
nc -zv 192.168.1.1 22

# Test a custom SSH port
nc -zv 192.168.1.1 2222

# Test the Telnet port (23)
nc -zv 192.168.1.1 23

Step 3: SSH Debug From a Shell

Use the OpenSSH client with maximum verbosity to see exactly where the handshake fails. This is the fastest way to distinguish a TCP problem from a KEX or auth problem.

SSH Debugbash
# Maximum verbosity SSH connection
ssh -vvv [email protected]

# Key lines to look for in the output:
#   "Connection established"            -> TCP connected
#   "SSH2_MSG_KEXINIT sent"             -> key exchange started
#   "Authentications that can continue" -> auth stage reached

Step 4: Adjust the Connection Timeout

For devices across WAN links, VPN tunnels, or satellite paths, raise the Connection Timeout on the credential profile so the connect does not abort before the device responds.

Step 5: Tune Keepalive for Idle Drops

If sessions establish but drop after a period of inactivity, lower the Keepalive Interval so NetStacks sends keepalive traffic before an intermediate firewall expires the idle TCP flow.

Warning

Some very old devices only support legacy SSH algorithms (for example diffie-hellman-group1-sha1, ssh-rsa with SHA-1, or CBC ciphers). NetStacks already advertises these legacy algorithms in addition to modern ones, so the strongest common algorithm is selected automatically and most legacy devices connect without any extra toggle.

Code Examples

SSH Debug Output Analysis

Successful SSH Connection (verbose)text
$ ssh -vvv [email protected]
OpenSSH_9.6p1, LibreSSL 3.3.6
debug1: Connecting to 10.0.1.1 [10.0.1.1] port 22.
debug1: Connection established.
debug1: SSH2_MSG_KEXINIT sent
debug1: SSH2_MSG_KEXINIT received
debug1: kex: algorithm: curve25519-sha256
debug1: kex: host key algorithm: ssh-ed25519
debug1: kex: server->client cipher: [email protected]
debug1: kex: client->server cipher: [email protected]
debug1: Host '10.0.1.1' is known and matches the ED25519 host key.
debug1: Authentications that can continue: publickey,password
debug1: Next authentication method: publickey
debug1: Offering public key: /home/user/.ssh/id_ed25519
debug1: Server accepts key: /home/user/.ssh/id_ed25519
Authenticated to 10.0.1.1 ([10.0.1.1]:22) using "publickey".

Firewall Rule Checks

Firewall Verificationbash
# Linux iptables -- check whether the SSH port is allowed
sudo iptables -L INPUT -n --line-numbers | grep 22

# Cisco IOS -- verify SSH access in the VTY ACL
show ip access-lists
show line vty 0 4 | include access-class

# Juniper Junos -- check the routing-engine filter and SSH service
show configuration firewall filter PROTECT-RE
show configuration system services ssh

Enable SSH on Network Devices

Enable SSH (Cisco IOS)text
! Cisco IOS -- enable SSH
conf t
hostname Router1
ip domain-name example.com
crypto key generate rsa modulus 2048
ip ssh version 2
line vty 0 4
  transport input ssh
  login local
end
Enable SSH (Junos)bash
# Juniper Junos -- enable SSH
set system services ssh protocol-version v2
set system services ssh root-login deny
commit

Connection Timeout and Keepalive Settings

These fields live on the credential profile and are edited in the profile editor. Both are free integer values in seconds.

Profile connection fieldsjson
{
  "connection_timeout": 30,   // seconds; default 30. Raise for high-latency links.
  "keepalive_interval": 30,   // seconds between keepalive packets; 0 disables keepalive.
  "auto_reconnect": true,     // attempt to reconnect after an unexpected drop (default on)
  "reconnect_delay": 5        // seconds to wait between reconnect attempts (default 5)
}
Note

Defaults come from the product's profile schema: connection_timeout = 30, keepalive_interval = 30, auto_reconnect = on, reconnect_delay = 5. There is no separate "keepalive count" setting — set keepalive_interval to 0 to disable keepalive entirely.

Q&A

Q: Why does my connection time out?
A: A timeout means the target is unreachable at the network level within the configured Connection Timeout window. Common causes: the device is powered off, a firewall is silently dropping packets on the SSH port, the IP or hostname is wrong, or there is a routing problem between you and the device. Ping the device, then test the port with nc -zv host 22. If the device is behind NAT, verify port forwarding. For slow WAN/VPN/satellite paths, raise the Connection Timeout on the profile.
Q: What does "no matching key exchange method found" mean?
A: The client and server could not agree on a key exchange algorithm. This usually involves very old devices that only offer diffie-hellman-group1-sha1 or diffie-hellman-group14-sha1. NetStacks already advertises those legacy algorithms alongside modern ones, so it negotiates the strongest common method automatically. If you see this error from the OpenSSH command line, it is because OpenSSH disables the legacy methods — add them explicitly with -oKexAlgorithms=+diffie-hellman-group14-sha1.
Q: Do I need to enable a "Legacy Mode" to reach old devices?
A: No. NetStacks advertises a broad set of key exchange methods, host key types, ciphers, and MACs that includes legacy options (group1/group14 SHA-1, ssh-rsa with SHA-1, AES-CBC, 3DES). The strongest algorithm common to both sides is chosen during negotiation, so most legacy devices connect out of the box without any toggle.
Q: Why do I get "connection refused" immediately?
A: An immediate refusal (TCP RST) means the host is reachable but nothing is listening on that port. Verify SSH is enabled on the device (show ip ssh on Cisco, show system services ssh on Juniper) and that you are using the correct port — some devices use a non-standard SSH port. If using Telnet, confirm the VTY lines accept Telnet.
Q: How do I troubleshoot jump host connections?
A: A jump host adds two possible failure points: the connection to the jump host itself, and the forwarded connection from the jump host to the target. First confirm you can connect directly to the jump host. Then confirm the jump host can reach the target on the SSH port. Make sure the bastion permits TCP forwarding (AllowTcpForwarding yes in its sshd config). On the profile, the jump host and a jump session are mutually exclusive — only one may be set.
Q: How do I increase the connection timeout?
A: Edit the credential profile and set the Connection Timeout (seconds) field. It is a free integer in seconds and defaults to 30. Raise it to 60 or more for high-latency links. The field applies to establishing the connection, not to the interactive session itself.
Q: Why does my session disconnect after a period of inactivity?
A: A firewall or NAT device between you and the target is expiring the idle TCP flow. NetStacks sends keepalive packets to prevent this; if the interval is longer than the firewall's idle timeout, the flow is dropped first. Lower the Keepalive Interval (seconds) on the profile (set to 0 to disable keepalive entirely). Also check the device's own idle timeout, such as exec-timeout on Cisco IOS. If a drop does occur and Auto-Reconnect is enabled, NetStacks retries automatically after the configured Reconnect Delay.

Troubleshooting

Use this error lookup table to map a message to its likely cause and fix.

Error MessageCauseFix
Connection timed outDevice unreachable or firewall dropping packetsVerify the path; check firewall rules on the SSH port; raise Connection Timeout
Connection refusedSSH/Telnet service not running or wrong portEnable SSH on the device; verify the port number
No matching key exchange method foundNo common KEX algorithm (typically with the OpenSSH CLI)From NetStacks this is auto-negotiated; from OpenSSH add the legacy KexAlgorithms
Host key verification failedHost key changed, or first connection to an unknown hostReview and approve the new host key, or remove the stale trusted entry
Permission denied (publickey)SSH key not accepted by the deviceVerify the key is authorized; check key file permissions (see Auth Problems)
Network is unreachableNo route to the target networkCheck the routing table; verify the VPN is connected
Connection reset by peerDevice forcibly closed the connection during the handshakeCheck device ACLs and SSH version compatibility
No route to hostTarget host unreachable at the IP layerVerify the IP address; check intermediate routing
Unable to negotiate ... no matching cipher foundNo common cipher (typically with the OpenSSH CLI)From NetStacks this is auto-negotiated; from OpenSSH add a legacy Ciphers option
Connection closed by remote hostDevice closed the session (max sessions, ACL, or auth-failure limit)Check VTY line availability and login-attempt limits
Tip

When reporting a connection issue, include the exact error message and the output of ssh -vvv to the target. That pinpoints the failure stage (TCP, KEX, host key, or auth).