Connecting to Devices

Overview

The NetStacks Terminal connects to network devices over two protocols — SSH and Telnet — and manages the full connection lifecycle so you can focus on the device. You can connect ad-hoc with Quick Connect, or save a reusable session with its host, port, protocol, credential profile, and terminal preferences.

Ways to Connect

• Quick Connect — Press Cmd+Shift+Q (Mac) or Ctrl+Shift+Q (Windows/Linux). Pick a credential profile, enter a host and port, and connect immediately. Recent connections are remembered in history.
• Saved Sessions — Store the host, port, protocol, folder, credential profile, jump host, auto-commands, and reconnect settings for devices you access frequently.
• Enterprise mode — When the Terminal is connected to a Controller, sessions and credentials are provided centrally and the Controller acts as the egress to your device network.

Protocols

• SSH — The default. Supports modern key exchange, ciphers, and host-key algorithms, with an optional legacy-algorithm mode for older gear.
• Telnet — For legacy devices that only speak Telnet (default port 23). See Telnet for Legacy Devices.

Authentication

Credentials live in credential profiles (Settings → Profiles). A profile uses one of two authentication types:

• Password — A stored or prompted password.
• Key — A private key file (path stored in the profile) with an optional passphrase. The agent loads standard OpenSSH key types including Ed25519, ECDSA, and RSA.

In enterprise mode the Controller can additionally provide short-lived SSH certificate authentication — see SSH Certificates.

How It Works

When you start a connection, the Terminal's Rust agent opens the transport to the target device and bridges it to the XTerm.js frontend over a WebSocket. The flow depends on the protocol.

SSH Connection Flow

1. TCP connection — The agent opens a TCP socket to the host and port (default 22). If a jump host is configured, it first connects to the jump host and tunnels a channel through to the target.
2. Host-key check — The server's host key is verified against the known-hosts store. New keys are handled trust-on-first-use; changed keys prompt for approval. See Terminal Overview for host-key management.
3. Algorithm negotiation — The handshake negotiates key exchange, ciphers, MACs, and host-key algorithms. Modern algorithms are preferred; legacy algorithms are offered too, with the strongest common one chosen. Enabling Legacy SSH on the session relaxes preferences for older devices.
4. Authentication — The agent authenticates using the session's credential profile (password or key). In enterprise mode it can authenticate with a Controller-signed SSH certificate.
5. PTY channel — A pseudo-terminal channel opens and the terminal dimensions are sent. Any configured auto-commands run, then data flows bidirectionally over the WebSocket.

Telnet Connection Flow

Telnet opens a raw TCP socket (default port 23) and negotiates standard Telnet options. There is no key exchange or host-key verification — Telnet is cleartext and intended only for legacy devices.

Step-by-Step Guide

Quick Connect (SSH)

1. Press Cmd+Shift+Q (Mac) or Ctrl+Shift+Q (Windows/Linux) to open the Quick Connect dialog.
2. Select a credential profile (it supplies the username and password or key). Create one first under Settings → Profiles if you have none.
3. Enter the Host: core-sw01.dc1.example.net or an IP.
4. Set the Port (defaults to 22).
5. Click Connect. The Terminal opens a new tab, authenticates, and drops you at the device prompt. The connection is added to your history for one-click reconnects.

Create a Saved Session

1. Open Session Settings to create a new session.
2. Give it a Name and choose a Folder (optional).
3. Set Protocol to ssh (or telnet for legacy devices).
4. Enter the Host and Port.
5. Select a credential profile for authentication.
6. For SSH, optionally attach a jump host, enable Legacy SSH Algorithms, and add auto-commands.
7. Save. Double-click the session to connect.

Auto-Commands on Connect

On the SSH session, the Auto Commands on Connect section runs a list of commands automatically once the connection establishes — handy for enable, terminal length 0, or terminal width 0.

Reconnect Behaviour

Sessions have auto-reconnect enabled by default, with a configurable reconnect delay (seconds) and scrollback buffer (default 10,000 lines). If the transport drops, the Terminal re-establishes the session and preserves your scrollback.

Telnet for Legacy Devices

Some legacy switches, terminal servers, and console servers only offer Telnet. The Terminal speaks Telnet over raw TCP for exactly these cases. Telnet is cleartext — use it only on trusted out-of-band management networks, and prefer SSH wherever the device supports it.

Connect over Telnet

1. Open Session Settings and create a new session.
2. Set Protocol to telnet.
3. Enter the Host and set the Port to 23 (the Telnet default). Console servers often expose per-line ports such as 2001–2048.
4. Select a credential profile if the device prompts for a username/password, then save and connect.

Jump Hosts (Bastions)

A jump host (bastion) is an intermediary SSH server used to reach devices on an internal or out-of-band network. In the Terminal, jump hosts are reusable records you create once and then attach to any SSH session.

1. Create a Jump Host record

1. Go to Settings → Jump Hosts and click to add a new jump host.
2. Enter a Name (e.g. Production Bastion), the Host (e.g. bastion.example.com), and the Port (default 22).
3. Choose a credential profile — the jump host authenticates with that profile's username and password or key. (Create the profile first under Settings → Profiles.)
4. Save.

2. Attach it to a session

1. Open the session in Session Settings and go to the SSH tab.
2. In the Jump (Bastion) section, open the Jump dropdown.
3. Pick a Jump Host record, or pick another Session to use as the jump endpoint, or leave it as direct (no jump).
4. Save. The session now connects through the selected bastion automatically.

SSH Certificates (Enterprise)

In enterprise mode the Controller can issue short-lived SSH certificates so devices never need individual public keys distributed to them — they only need to trust the Controller's CA public key.

How the cert flow works

1. The agent generates an Ed25519 keypair for certificate authentication.
2. At login to the Controller, the Controller signs the agent's public key and returns a short-lived certificate. The agent stores it via POST /api/cert/store, along with the CA public key and expiry.
3. On each SSH connection, the agent presents the stored private key plus certificate. The device validates the certificate against the trusted CA key.
4. When the certificate nears expiry it is renewed (POST /api/cert/renew); the current status is queryable for the UI. Expired certificates leave no standing access to revoke.

For setting up the CA and device trust, see SSH Certificates.

Code Examples

Generate an SSH key for a key profile

# Generate an Ed25519 SSH key (recommended)
ssh-keygen -t ed25519 -C "[email protected]" -f ~/.ssh/netstacks_ed25519

# Or RSA if the device does not support Ed25519
ssh-keygen -t rsa -b 4096 -C "[email protected]" -f ~/.ssh/netstacks_rsa

# Install the public key on the device
ssh-copy-id -i ~/.ssh/netstacks_ed25519.pub [email protected]

Then create a credential profile with auth type key and point its key path at ~/.ssh/netstacks_ed25519.

ProxyJump equivalent of a NetStacks jump host

A NetStacks session with a jump host behaves like OpenSSH's ProxyJump:

# Single bastion
Host oob-sw01
    HostName oob-sw01.mgmt.example.net
    User netadmin
    Port 22
    ProxyJump bastion.example.com

# Multi-hop chain (chain sessions as jump endpoints to mirror this)
Host isolated-fw01
    HostName isolated-fw01.secure.example.net
    User fwadmin
    Port 22
    ProxyJump bastion.example.com,internal-jump.dmz.example.net

Conceptual session shape

Sessions are managed in the app, not edited as files; this illustrates the fields a session carries.

{
  "name": "DC1 Core Router",
  "host": "core-rtr01.dc1.example.net",
  "port": 22,
  "protocol": "ssh",
  "profile_id": "prof_netadmin_key",
  "jump_host_id": "jh_prod_bastion",
  "legacy_ssh": false,
  "auto_commands": [
    "terminal length 0",
    "terminal width 0"
  ],
  "auto_reconnect": true,
  "reconnect_delay": 5,
  "scrollback_lines": 10000
}

Jump host record shape

{
  "name": "Production Bastion",
  "host": "bastion.example.com",
  "port": 22,
  "profile_id": "prof_jumpuser"
}

Authentication for the bastion comes entirely from the referenced credential profile — there is no inline username or password on the jump host record.

Verify a Telnet console server line

# Check that the console-server line is listening before adding a Telnet session
nc -zv termserv01.mgmt.example.net 2001

# Telnet defaults to port 23 for plain devices
nc -zv legacy-sw01.mgmt.example.net 23

Questions & Answers

Q: How do I connect through a jump host?

A: First create a jump host record under Settings → Jump Hosts (name, host, port, credential profile). Then open the session's Session Settings, go to the SSH tab, and select that jump host from the Jump dropdown. You can alternatively pick another session as the jump endpoint. Jump hosts apply in standalone mode; in enterprise mode the Controller is the egress.

Q: What SSH key types are supported?

A: The agent loads standard OpenSSH private keys including Ed25519, ECDSA, and RSA. Ed25519 is recommended for new keys. Set auth type key on a credential profile and point it at your private key file (with a passphrase if it has one).

Q: How does SSH certificate authentication work?

A: In enterprise mode the Controller signs the agent's public key at login, producing a short-lived SSH certificate that the agent stores (POST /api/cert/store) and renews as it nears expiry. Devices only need to trust the Controller's CA public key — no per-user keys are distributed and expired certs leave nothing to revoke. There is no per-connection issue endpoint.

Q: Can I save connections for quick access?

A: Yes. Create a saved session storing host, port, protocol, credential profile, jump host, auto-commands, scrollback, and reconnect behaviour. Organize sessions into folders. Quick Connect also keeps a history of recent connections for fast reconnects.

Q: How do I connect to a device on a non-standard port?

A: Set the Port field in Quick Connect or in Session Settings. SSH defaults to 22 and Telnet to 23; override it for devices on custom ports or for console-server lines (e.g. 2001–2048).

Q: How do I connect to a device that only supports Telnet?

A: Create a session with Protocol set to telnet and port 23 (or the console-server line port). Telnet is cleartext, so restrict it to trusted out-of-band management networks.

Q: What happens when a connection drops?

A: Sessions auto-reconnect by default. The Terminal re-establishes the session after the configured reconnect delay and preserves your scrollback buffer so you do not lose output history. You can disable auto-reconnect or tune the delay per session.

Q: How do I connect to an old device that fails key exchange?

A: Enable Legacy SSH Algorithms on the SSH session. This allows older key exchange, cipher, and host-key algorithms (e.g. diffie-hellman-group14-sha1, ssh-rsa) that some legacy Cisco/HP gear requires. Enable it only for devices that need it.

Q: Can I dial a device through an external SOCKS proxy?

A: No. The Terminal does not connect to devices through an external SOCKS4/SOCKS5 proxy. Use a jump host to reach internal devices. (A SOCKS5 dynamic forward exists separately as an SSH tunnel feature for forwarding your own traffic.)

Troubleshooting

Connection Refused

Symptom: Immediate "connection refused" error.

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

Solution: Verify reachability from a local shell tab: nc -zv core-rtr01.dc1.example.net 22. Confirm the service is enabled and check firewall/ACL rules.

Key Exchange / Cipher Failure

Symptom: "no matching key exchange method" or "no matching cipher."

Cause: The device only supports older algorithms that are deprioritized by default.

Solution: Enable Legacy SSH Algorithms on the SSH session to allow older algorithms such as diffie-hellman-group14-sha1 and ssh-rsa.

Host Key Changed

Symptom: A warning that the server's host key does not match the stored key.

Cause: The device was re-imaged or replaced, or the connection is being intercepted.

Solution: Confirm the change is expected, then approve the new key. See Terminal Overview for host-key handling.

Certificate Expired or Rejected (Enterprise)

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

Cause: The signed certificate has expired/not renewed, or the device does not trust the Controller CA.

Solution: Ensure the agent is logged in to the Controller so the certificate is renewed. If the device does not trust the CA, add the Controller CA public key to the device's TrustedUserCAKeys configuration. See SSH Certificates.

Jump Host Timeout

Symptom: The connection hangs while reaching the target through a bastion.

Cause: The jump host cannot reach the target, or the jump host's credential profile is wrong.

Solution: SSH into the bastion directly and confirm the target is reachable from there. Verify the jump host record points at the correct credential profile and port.

Authentication Failed

Symptom: "authentication failed" or "no supported authentication methods."

Cause: The credential profile uses the wrong method (e.g. password where the device requires a key), or the username/key is wrong.

Solution: Check which methods the device accepts and set the matching auth type (password or key) on the profile. From a local shell, ssh -v netadmin@device shows the methods the server offers.

Related Features

• Terminal Overview — Architecture, operating modes, and host-key handling.
• Keyboard Shortcuts — Quick Connect and navigation bindings.
• Tabs & Splits — Working with multiple device connections at once.
• Session Recording — Recording device sessions for audit and review.
• SSH Passwords & Keys — Managing the credential profiles used to authenticate.
• SSH Certificates — Setting up the Controller CA and device trust.
• Credential Vault — Where credentials are stored and encrypted.