Servers & SSH

The Servers & SSH page gives your team a terminal on your servers without handing out passwords or keys. OpsNexus signs in to the server itself, using a credential kept in the secret store, and streams the terminal to the browser. The browser never receives the password or private key.

The same page also holds Windows servers you open as a desktop. See Remote Desktop for those.

#How it works

Browser (terminal) --WebSocket--> OpsNexus API --SSH--> your server

• The OpsNexus API opens the SSH connection. The server must be reachable from the OpsNexus server, not from your laptop.
• Opening a terminal is two steps. The browser asks for a session with your normal sign-in and permissions, and gets a single-use ticket that is valid for 60 seconds. The WebSocket then presents that ticket. Your access token never appears in a WebSocket URL.
• Host keys are trusted on first use, like known_hosts in OpenSSH. If the key changes later, the connection is blocked until someone with full access resets it.
• Every session is recorded in the session history and the audit log.

Servers belong to the current project. Switching project shows that project's servers.

#Add a server

You need modify access to the Cloud module (see Who can do what).

1. Open Servers & SSH in the sidebar.

2. Click + Add server.

3. Choose SSH terminal. It covers Linux, macOS, network gear, and Windows with OpenSSH Server.

4. Fill in the server details:

   Field	What to enter
   Name	A unique name in this project, for example web-prod-1.
   Tags	Optional, comma-separated, for example prod, web. Up to 20 tags.
   Host name or IP	A host name or IP address only. No ssh://, no user@, no :port.
   SSH port	Defaults to 22.
   Username	The account to sign in as. With a saved credential you can leave it empty to use the credential's username.
   Description	Optional.

5. Under Sign in with, pick one method (see the next section) and fill in its fields.

6. Click Add server.

7. Click Test on the new row. OpsNexus signs in once without opening a shell, shows the user it signed in as and the output of uname -srm, and trusts the server's host key.

#Sign-in methods and where credentials live

The secret store is HashiCorp Vault in production, or encrypted rows in PostgreSQL for local development. API responses only ever say whether a secret exists. They never return the value.

When you edit a server, leave Password or Private key empty to keep the saved one. Switching a server to a saved credential deletes its own stored password or key.

#Open a terminal

1. On Servers & SSH, click Connect on the server's row.
2. The terminal opens in a new browser tab. The header shows the server, the address and the connection state: Connecting, Connected, Disconnected or Failed.

On the first successful connection the terminal prints the host key fingerprint it trusted.

#Terminal controls

• Sizing. The terminal follows the size of the browser window. Each resize tells the server the new number of columns and rows, so full-screen programs like vim and top redraw correctly.
• Scrollback. The terminal keeps the last 5,000 lines.
• Links. URLs printed in the terminal are clickable.
• Copy and paste. Copy and paste go through your browser's clipboard. Pasted text is sent to the server as input and counts towards the session's data in.
• Closing the tab. If a session is open, the browser asks before closing the tab.

#When sessions end

A session ends when:

• you click Disconnect or close the tab,
• the server closes the shell,
• nobody types for TERMINAL_IDLE_MINUTES (default 30),
• the session reaches TERMINAL_MAX_HOURS (default 8),
• someone ends it from the Sessions tab.

Each person can have up to 10 terminals or desktops open at once. Set the timeouts in .env; see Environment variables.

TERMINAL_IDLE_MINUTES=30
TERMINAL_MAX_HOURS=8
TERMINAL_CONNECT_TIMEOUT_SECONDS=15

TERMINAL_CONNECT_TIMEOUT_SECONDS is how long OpsNexus waits for the server to answer before it reports the server as unreachable.

#Host keys

The Host key column shows the SHA-256 fingerprint OpsNexus trusts for each SSH server, or "Trusted on first connection" if it hasn't connected yet.

If a server presents a different key later, the connection fails with a message that shows the trusted and the current fingerprint. This happens when a server is rebuilt, or when something intercepts the connection.

To accept a new key:

1. Confirm that the server really was rebuilt or had its SSH keys changed.
2. On the server's row, click Reset trusted key in the error message. This needs full access.
3. Click Connect or Test. OpsNexus trusts the key it sees on that connection.

Changing a server's host, port or type also forgets its trusted key.

#Session history and audit

The Sessions tab lists terminal and desktop sessions, newest first. Filter it by All, Open now, Closed or Failed.

People see their own sessions. People with full access see everyone's, and can click End on anyone's open session.

OpsNexus records session metadata, not the content of the terminal. There is no keystroke log or screen replay.

The audit log gets these entries, in the Remote access category:

#Who can do what

Servers use the Cloud accounts & resources module in roles (the same module that covers Cloud and Kubernetes). See Access control.

To choose a Saved credential you also need read access to Secrets & variables.

Deleting a server ends its open sessions and removes its stored password or key. Its session history is kept.

#Troubleshooting

For more, see Troubleshooting.