NetStacksNetStacks
Contact SalesGet Started

Connection Issues

Diagnose and resolve SSH and Telnet connection problems including timeouts, refused connections, key exchange failures, protocol mismatches, and firewall issues.

Overview

Connection issues are the most common category of problems encountered when working with network devices through NetStacks. These issues fall into several distinct categories, each with different root causes and resolution paths.

Connection Issue Categories

  • Timeout -- The connection attempt hangs and eventually fails after the configured timeout period. Usually indicates network reachability problems or firewall filtering.
  • Connection Refused -- The target device actively rejects the connection. 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 cryptographic algorithms.
  • Protocol Mismatch -- The device speaks an incompatible SSH protocol version or expects Telnet when SSH is attempted (or vice versa).
  • Firewall / ACL Blocking -- Network-level access control lists or firewalls silently drop or reject connection attempts.
Note

NetStacks supports both SSH (v2) and Telnet protocols. SSH is the default and recommended protocol. Telnet should only be used for legacy devices that do not support SSH.

How It Works

Understanding how NetStacks establishes connections helps you diagnose where failures occur in the process.

SSH Connection Flow

  1. DNS Resolution -- NetStacks resolves the hostname to an IP address (skipped if an IP is provided directly).
  2. TCP Connection -- A TCP socket is opened to the target host on the configured port (default 22 for SSH, 23 for Telnet).
  3. Protocol Version Exchange -- Client and server exchange SSH version strings (e.g., SSH-2.0-OpenSSH_9.6).
  4. Key Exchange (KEX) -- Both sides negotiate encryption algorithms: key exchange method, cipher, MAC, and compression.
  5. Authentication -- The client authenticates using the configured credential (password, SSH key, or certificate).
  6. Channel Setup -- An interactive shell channel is opened and the terminal session begins.

Jump Host Chaining

When a jump host (bastion) is configured, NetStacks first establishes an SSH connection to the jump host, then opens a forwarded TCP channel through it to reach the final target device. Multiple jump hosts can be chained for multi-hop access.

Tip

Connection failures at each stage produce different error messages. Timeouts typically occur at stages 1-2, key exchange errors at stage 4, and authentication errors at stage 5.

Step-by-Step Guide

Follow this systematic diagnostic flow to identify and resolve connection issues. Start from step 1 and work through each step until you find the problem.

Step 1: Verify Network Reachability

Confirm the device is reachable at the network level before troubleshooting SSH.

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

# If ping fails, check routing
traceroute 192.168.1.1

Step 2: Check Port Accessibility

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

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

# Test custom SSH port
nc -zv 192.168.1.1 2222

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

Step 3: SSH Debug Connection

Use verbose SSH output to see exactly where the connection fails.

SSH Debugbash
# Maximum verbosity SSH connection
ssh -vvv admin@192.168.1.1

# Look for these key lines in the output:
# "Connection established" -- TCP connected
# "SSH2_MSG_KEXINIT sent" -- Key exchange started
# "Authentications that can continue" -- Auth stage reached

Step 4: Check NetStacks Logs

Review the NetStacks application logs for detailed connection error information. Logs are found in the application data directory.

Step 5: Enable Legacy Mode

If the device uses outdated SSH algorithms, enable Legacy Mode in the session settings to allow older key exchange methods and ciphers.

Warning

Legacy Mode enables weaker cryptographic algorithms (diffie-hellman-group1-sha1, 3des-cbc, aes128-cbc). Only enable it for devices that do not support modern algorithms.

Code Examples

SSH Debug Output Analysis

Successful SSH Connection (verbose)text
$ ssh -vvv admin@10.0.1.1
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: aes256-gcm@openssh.com
debug1: kex: client->server cipher: aes256-gcm@openssh.com
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 if SSH port is allowed
sudo iptables -L INPUT -n --line-numbers | grep 22

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

# Juniper Junos -- check firewall filter
show configuration firewall filter PROTECT-RE
show configuration system services ssh

Enable SSH on Network Devices

Enable SSH on Devicestext
! 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

# Juniper Junos -- Enable SSH
set system services ssh protocol-version v2
set system services ssh root-login deny
commit

Connection Timeout Configuration

Timeout Settingstext
# NetStacks session settings support these timeout values:
# Connection Timeout: 10s (default), 30s, 60s, 120s
# Keep-Alive Interval: 15s (default)
# Keep-Alive Count Max: 3 (default)
#
# For high-latency links (satellite, VPN tunnels):
#   Increase Connection Timeout to 60s or 120s
#   Increase Keep-Alive Interval to 30s

Q&A

Q: Why does my connection time out?
A: Connection timeouts occur when the target device is unreachable at the network level. Common causes include: the device is powered off or unreachable, a firewall is silently dropping packets on port 22, the IP address or hostname is incorrect, or there is a routing issue between NetStacks and the device. Start by pinging the device, then check port accessibility with nc -zv host 22. If the device is behind a NAT, verify port forwarding is configured.
Q: What does "no matching key exchange method found" mean?
A: This error means the SSH client and server cannot agree on a cryptographic algorithm for the key exchange. It typically occurs with older network devices running outdated SSH implementations (e.g., Cisco IOS 12.x, older Junos versions). The device may only support diffie-hellman-group1-sha1 or diffie-hellman-group14-sha1, which modern clients disable by default. In NetStacks, enable Legacy Mode in the session settings to allow these older algorithms.
Q: How do I connect to a device with outdated SSH?
A: Enable Legacy Mode in the NetStacks session configuration. This enables support for older key exchange algorithms (diffie-hellman-group1-sha1), older ciphers (3des-cbc, aes128-cbc), and older host key types (ssh-rsa with SHA-1). You can enable Legacy Mode per-session so it only applies to the specific device that needs it, keeping your other connections secure.
Q: Why do I get "connection refused" immediately?
A: An immediate "connection refused" (TCP RST) means the target host is reachable but nothing is listening on the specified port. Verify that SSH is enabled on the device (show ip ssh on Cisco, show system services ssh on Juniper). Also verify you are connecting to the correct port -- some devices use non-standard SSH ports. If using Telnet, confirm the device has Telnet enabled on the VTY lines.
Q: How do I troubleshoot jump host connections?
A: When using a jump host (bastion), connection failures can occur at two points: the connection to the jump host itself, or the forwarded connection from the jump host to the target device. First verify you can connect to the jump host directly. Then verify the jump host can reach the target device on the SSH port. Check that the jump host has the AllowTcpForwarding option enabled in its SSH configuration. NetStacks shows which hop failed in its connection error details.
Q: How do I increase the connection timeout?
A: In the NetStacks session settings, adjust the Connection Timeout value. The default is 10 seconds, which works for most LAN connections. For devices across WAN links, VPN tunnels, or satellite connections, increase this to 30-60 seconds. You can also adjust the Keep-Alive Interval and Keep-Alive Count to prevent established sessions from being dropped due to idle timeouts on intermediate firewalls.
Q: Why does my session disconnect after a few minutes of inactivity?
A: Idle session disconnects are usually caused by a firewall or NAT device between you and the target that drops idle TCP connections. NetStacks sends SSH keep-alive packets to prevent this, but if the interval is too long the firewall may drop the connection before the next keep-alive. Reduce the Keep-Alive Interval to 10-15 seconds. Also check the device's own idle timeout settings (exec-timeout on Cisco IOS).

Troubleshooting

Use this error message lookup table to quickly identify the cause and fix for common connection errors.

Error MessageCauseFix
Connection timed outDevice unreachable or firewall dropping packetsVerify network path, check firewall rules on port 22
Connection refusedSSH/Telnet service not running or wrong portEnable SSH on device, verify port number
No matching key exchange method foundAlgorithm mismatch with legacy deviceEnable Legacy Mode in session settings
Host key verification failedDevice host key changed (or first connection)Accept new host key or remove old entry from known hosts
Permission denied (publickey)SSH key not accepted by deviceVerify key is authorized on device, check key file permissions
Network is unreachableNo route to target networkCheck routing table, verify VPN is connected
Connection reset by peerDevice forcibly closed connection during handshakeCheck device ACLs, verify SSH version compatibility
No route to hostTarget host unreachable at IP levelVerify IP address, check intermediate routing
Unable to negotiate ... no matching cipher foundNo common encryption cipher between client and deviceEnable Legacy Mode for older cipher support
Connection closed by remote hostDevice closed session (max sessions, ACL, or auth failure limit)Check VTY line availability and login attempt limits
Tip

When reporting connection issues, include the exact error message and the output of ssh -vvv to the target device. This helps pinpoint the exact failure stage.