Vantage/vantage-docs
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: Self review of doc pages

Browse Source
This commit is contained in:
mrhid6
2026-08-10 16:32:23 +01:00
parent bd7b3256fc
commit 83c38db92e
34 changed files with 860 additions and 991 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/vantage/browser-console.md
+36 -47
View File
@@ -4,70 +4,59 @@ title: Browser console
sidebar_label: Browser console
---
An SSH, RDP or VNC session in a browser tab, with no client software and no
inbound port on the target beyond the one the protocol already uses.
An SSH, RDP or VNC session in a browser tab, with no client software to install
and no new port to open on the target machine.
Protocol handling is Apache Guacamole's the control plane proxies a WebSocket
to a **guacd** daemon and manages credentials around it.
:::info Requires the console feature on your licence
The console is a per-instance feature you enable on a paid plan. Without it, the
Console button is unavailable. See
[Licensing and entitlements](../hq/licensing-and-entitlements.md).
:::
## Requirements
## What you need
- `guacd` running and reachable from the server. The bundled Compose stack
includes it; `GUACD_ADDR` defaults to `guacd:4822`.
- `KEY_ENCRYPTION_KEY` set, since every credential involved is stored encrypted.
- The target's **agent must be online**. Console traffic is relayed over the
agent's existing outbound connection, so the control plane never needs a route
to the server's address — but it does need the agent.
- No inbound port on the target, beyond what the protocol already listens on
locally. A service bound only to `127.0.0.1` works, because the agent dials
loopback on the target itself.
- The target server's **agent must be online**. Console traffic travels over the
connection the agent already holds, so an offline agent means no session.
- `KEY_ENCRYPTION_KEY` set on a self-hosted install, since every credential
involved is stored encrypted.
- The service you are connecting to listening on the machine itself. It does not
have to be reachable from anywhere else, because the agent connects to it
locally.
## Opening a session
From a server's page, choose **Console**. Then:
1. The UI calls `POST /api/console/connect`, which mints a **one-time** session
token. If the target's agent is not connected, this fails immediately with
`409 agent_offline` rather than hanging.
2. The browser opens a WebSocket to `GET /api/console/tunnel` with that token.
3. The server marks the token consumed atomically, so a second use cannot
race and proxies the connection to guacd.
From a server's page, choose **Console**, pick the protocol and connect. Vantage
issues a one-time ticket for that session, and the connection is refused rather
than left hanging if the agent is not online.
## Credentials
### SSH
Authenticates with a private key stored in the [key library](./ssh-keys.md). The
key must have its private half uploaded; a public-only key cannot open a
session.
Uses a private key from your [key library](./ssh-keys.md). The key must have had
its private half uploaded; a public key alone cannot open a session.
### RDP and VNC
You supply credentials when connecting. They are encrypted, **single-use**, and
consumed when the tunnel opens. They are not retained for the next session.
You type the credentials when you connect. They are encrypted, used once and
discarded, so the next session asks again.
:::info Why single-use
A stored console credential is a standing grant to that machine for anyone who
can reach the endpoint. Consuming it at tunnel-open means a leaked session token
is worth one connection at most, and only until it is used.
:::
## During and after a session
## Session behaviour
Closing the tab ends the session. There is no reconnect: opening it again starts
a fresh session.
Closing the tab ends the session. There is no reconnect and no session
persistence reopening mints a new token and a new connection.
## Auditing
Opening a console is an audited action, with actor, server and time. What
happens _inside_ the session is not recorded: there is no session capture or
keystroke log. If you need that, it has to come from the target machine.
Opening a console is recorded in the [audit log](./audit-log.md), with who did
it, which server and when. What happens inside the session is not recorded.
There is no session replay or keystroke capture, so if you need that, it has to
come from the target machine itself.
## When it does not work
| Symptom | Cause |
| -------------------------------- | ------------------------------------------------------------------------------- |
| Connects then closes immediately | guacd unreachable check `GUACD_ADDR` and that the container is up |
| SSH refuses the key | The stored key has no private half, or is not in the target's `authorized_keys` |
| RDP fails on a fresh credential | Credentials are consumed on open; a retry needs them entered again |
| Hangs, then disconnects | The agent never claimed the relay, nothing is listening on the protocol port on the target's own loopback address, or guacd never dialled in time. Check the audit log for `console.proxy_failed` — its reason (`agent_timeout`, `dial_refused`, `guacd_timeout`, `rejected`) names which |
| Symptom | What to check |
| -------------------------------- | ------------------------------------------------------------------------------------------ |
| Connects, then closes at once | The console daemon is unreachable. On a self-hosted install, check that `guacd` is running |
| SSH refuses the key | The stored key has no private half, or is not assigned to that server |
| RDP fails when you retry | Credentials are used once. Enter them again |
| Hangs, then disconnects | The agent could not reach the service on the machine, or the session timed out setting up. The audit log records the reason |
| Works locally, fails in production | Your reverse proxy is not forwarding WebSocket connections |