NetStacksNetStacks
Contact SalesGet Started

Connecting to Devices

Professional

Learn how to connect to network devices using SSH and Telnet with password, key, and certificate authentication, jump hosts, and saved connection profiles.

Overview

The NetStacks Terminal provides multiple ways to connect to network devices. Whether you are SSHing into a core router, Telnetting to a legacy switch, or chaining through jump hosts to reach an out-of-band management network, the Terminal handles the connection lifecycle so you can focus on the device.

Connection Methods

  • Quick Connect — Enter a hostname or IP address and connect immediately. Accepts shorthand syntax like netadmin@core-rtr01.dc1.example.net.
  • Saved Sessions — Store connection settings, credentials, and terminal preferences for devices you access frequently.
  • Enterprise Device Panel — When connected to a Controller, browse the device inventory and connect with a single click using vault credentials.

Authentication Methods

  • Password authentication (entered or stored)
  • SSH key authentication (RSA, ECDSA, Ed25519)
  • SSH certificate authentication (enterprise, via Controller CA)
  • Keyboard-interactive authentication (multi-factor prompts)

Advanced Features

  • Jump host / bastion server chaining (single or multi-hop)
  • SOCKS proxy support (SOCKS4/SOCKS5)
  • Auto-execute commands after authentication
  • Connection profiles with credential associations
  • Legacy device support (older SSH algorithms)

How It Works

When you initiate a connection, the Terminal's Rust backend establishes a transport-layer connection to the target device. The connection flow depends on the protocol and authentication method selected.

SSH Connection Flow

  1. TCP Connection — The backend opens a TCP socket to the target host and port (default 22). If a jump host is configured, it first connects to the jump host and opens a forwarded channel to the target.
  2. Key Exchange — The SSH handshake negotiates encryption algorithms, key exchange methods, and MAC algorithms. The Terminal supports modern algorithms by default and can enable legacy algorithms for older devices.
  3. Authentication — Credentials are resolved in order: session-specific credentials, then credential profile, then prompt. In enterprise mode, the Controller vault provides credentials or issues a short-lived SSH certificate.
  4. Channel Setup — After authentication, a PTY channel is opened with the terminal type set to xterm-256color. The terminal dimensions are sent to the remote device.
  5. Session Active — Data flows over a WebSocket between the XTerm.js frontend and the Rust SSH proxy. Keep-alive packets maintain the connection.

Credential Resolution

The Terminal resolves credentials from multiple sources, checked in priority order:

  1. Credentials saved directly in the session definition
  2. Credential profile linked to the session
  3. Controller vault credentials (enterprise mode)
  4. Interactive prompt (password or key passphrase)
Note

In standalone mode, credentials are encrypted and stored locally on your machine. In enterprise mode, credentials remain in the Controller vault and are never persisted on the Terminal.

Step-by-Step Guide

Basic SSH Connection

  1. Press Cmd+Shift+Q (Mac) or Ctrl+Shift+Q (Windows/Linux) to open Quick Connect.
  2. Enter the hostname or IP: core-sw01.dc1.example.net
  3. Enter port 22 (default).
  4. Enter username: netadmin
  5. Select Password and enter the device password, or select SSH Key and browse to your private key file.
  6. Click Connect. The Terminal opens a new tab, authenticates, and drops you at the device prompt.
Tip

You can also type shorthand in the Quick Connect field: netadmin@core-sw01.dc1.example.net — the Terminal parses the username and host automatically.

Jump Host Connection

  1. Open a new session or edit an existing saved session's settings.
  2. Navigate to Connection → Proxy.
  3. Select SSH Jump Host.
  4. Enter the jump host details: bastion01.dc1.example.net, port 22, username jumpuser.
  5. Configure authentication for the jump host (password or key).
  6. Enter the final target device: oob-sw01.mgmt.example.net, port 22.
  7. Click Connect. The Terminal connects to the bastion first, then tunnels through to the target device.
Warning

For multi-hop jump hosts, each hop must authenticate independently. Ensure credentials are configured for every hop in the chain.

Certificate Authentication (Enterprise)

  1. Ensure your Terminal is connected to a Controller with an SSH Certificate Authority configured.
  2. Open Quick Connect or create a new session.
  3. Enter the target device hostname.
  4. Select SSH Certificate as the authentication method. The Controller issues a short-lived certificate signed by the CA.
  5. Click Connect. The device validates the certificate against the trusted CA public key and grants access.
Note

SSH certificates expire automatically (typically 8–24 hours), providing zero-standing-privilege access. No public key distribution to devices is required — only the CA public key needs to be trusted.

Code Examples

SSH Connection with Key Authentication

SSH key setupbash
# Generate an Ed25519 SSH key (recommended)
ssh-keygen -t ed25519 -C "netadmin@example.com" -f ~/.ssh/netstacks_ed25519

# Or RSA if the device does not support Ed25519
ssh-keygen -t rsa -b 4096 -C "netadmin@example.com" -f ~/.ssh/netstacks_rsa

# Copy the public key to the device
ssh-copy-id -i ~/.ssh/netstacks_ed25519.pub netadmin@core-rtr01.dc1.example.net

Jump Host SSH Configuration

SSH config referencetext
# ~/.ssh/config equivalent of a NetStacks jump host session
Host oob-sw01
    HostName oob-sw01.mgmt.example.net
    User netadmin
    Port 22
    ProxyJump bastion01.dc1.example.net

# Multi-hop jump host chain
Host isolated-fw01
    HostName isolated-fw01.secure.example.net
    User fwadmin
    Port 22
    ProxyJump bastion01.dc1.example.net,internal-jump.dmz.example.net

Connection Profile Structure

Session profilejson
{
  "name": "DC1 Core Router",
  "host": "core-rtr01.dc1.example.net",
  "port": 22,
  "protocol": "ssh",
  "username": "netadmin",
  "auth_method": "key",
  "key_path": "~/.ssh/netstacks_ed25519",
  "auto_execute": [
    "terminal length 0",
    "terminal width 200"
  ],
  "jump_host": {
    "host": "bastion01.dc1.example.net",
    "port": 22,
    "username": "jumpuser",
    "auth_method": "key"
  }
}

Certificate Authentication Flow

Certificate flowtext
# Enterprise mode — certificate lifecycle:
#
# 1. Terminal requests certificate from Controller
#    POST /api/ssh/certificates/issue
#    { "principal": "netadmin", "ttl": "8h" }
#
# 2. Controller CA signs a short-lived certificate
#    Certificate valid: 2026-03-10T14:00:00 to 2026-03-10T22:00:00
#    Principals: netadmin
#
# 3. Terminal uses certificate to authenticate
#    core-rtr01.dc1.example.net validates against trusted CA key
#
# 4. Certificate expires automatically — no cleanup needed

Questions & Answers

Q: How do I connect through a jump host?
A: Open Session Settings, go to Connection → Proxy, select SSH Jump Host, and enter the bastion server details. The Terminal connects to the jump host first, then tunnels through to the target device. Multi-hop chains are supported by adding additional jump hosts in sequence.
Q: What SSH key types are supported?
A: The Terminal supports RSA (2048 and 4096 bit), ECDSA (256, 384, and 521 bit), and Ed25519 keys. Ed25519 is recommended for new keys due to its performance and security characteristics. Keys can be stored locally or in the Controller credential vault.
Q: How does SSH certificate authentication work?
A: In enterprise mode, the Controller operates an SSH Certificate Authority. When you connect to a device, the Controller issues a short-lived certificate signed by the CA. The device validates the certificate against the CA public key. Certificates expire automatically (typically 8–24 hours), so there are no standing privileges to revoke. The device only needs to trust the CA public key, not individual user keys.
Q: Can I save connection profiles for quick access?
A: Yes. After connecting, right-click the tab and select Save Session. Sessions store the host, port, username, authentication method, auto-execute commands, and terminal preferences. In enterprise mode, saved sessions sync across all your Terminal instances via the Controller.
Q: How do I handle devices with non-standard SSH ports?
A: In Quick Connect, append the port after a colon: netadmin@switch01.example.net:2222. In saved sessions, set the port in Session Settings → Connection. The Terminal defaults to port 22 if no port is specified.
Q: What happens when a connection drops?
A: The Terminal shows a reconnect overlay with the disconnection reason. If auto-reconnect is enabled (Session Settings → Connection), the Terminal attempts to re-establish the session with a configurable delay and retry count. The scrollback buffer is preserved, so you do not lose output history.
Q: How do I enable legacy SSH algorithms for older devices?
A: In Session Settings → Connection, enable Legacy Mode. This allows older key exchange algorithms and ciphers that some legacy devices require. Only enable this for devices that need it, as modern algorithms are more secure.

Troubleshooting

Connection Refused

Symptom: Immediate "Connection refused" error.

Cause: The SSH/Telnet service is not running on the target device, the port is wrong, or a firewall is blocking the connection.

Solution: Open a local shell tab and verify connectivity: nc -zv core-rtr01.dc1.example.net 22. Check that the SSH service is enabled on the device. Verify firewall and ACL rules.

Key Exchange Failure

Symptom: Error message mentioning "no matching key exchange method" or "no matching cipher."

Cause: The device supports only older SSH algorithms that the Terminal does not enable by default.

Solution: Enable Legacy Mode in Session Settings → Connection. This adds support for older algorithms like diffie-hellman-group14-sha1 and aes128-cbc.

Certificate Expired or Rejected

Symptom: Authentication fails with "certificate has expired" or "certificate not trusted."

Cause: The SSH certificate TTL has elapsed, or the device does not trust the Controller CA.

Solution: Reconnect to obtain a fresh certificate (certificates are issued on each connection). If the device does not trust the CA, add the CA public key to the device's TrustedUserCAKeys configuration. See SSH Certificates for setup details.

Jump Host Timeout

Symptom: Connection hangs when trying to reach the target through a jump host.

Cause: The jump host cannot reach the target device, or there is a routing issue between the jump host and the target network.

Solution: SSH into the jump host directly and verify that the target device is reachable from there. Check routing tables and firewall rules on the jump host.

Authentication Method Not Supported

Symptom: Error message "no supported authentication methods remaining."

Cause: The device only accepts an authentication method that is not configured in your session (e.g., the device requires key auth but you only have a password configured).

Solution: Check which authentication methods the device accepts and configure the matching method in Session Settings. Use ssh -v netadmin@device from a local shell to see the auth methods offered by the server.

  • Terminal Overview — General Terminal architecture, capabilities, and operating modes.
  • Keyboard Shortcuts — Shortcut reference including Quick Connect, reconnect, and navigation bindings.
  • Session Recording — Recording terminal sessions during device connections for audit and review.
  • Credential Vault — Centralized credential storage and management in the Controller.
  • SSH Passwords & Keys — Managing SSH keys and passwords for device authentication.
  • SSH Certificates — Setting up and using SSH certificate authentication with the Controller CA.