mirror of
https://github.com/tale/headplane.git
synced 2026-07-28 00:28:56 +00:00
Aarnav Tale
74 lines
2.7 KiB
Markdown
74 lines
2.7 KiB
Markdown
---
|
|
title: WebSSH
|
|
description: Open SSH sessions to your Tailnet nodes directly from the browser.
|
|
---
|
|
|
|
# WebSSH
|
|
|
|
<figure>
|
|
<img src="../assets/ssh.png" />
|
|
<figcaption>SSH access via the browser</figcaption>
|
|
</figure>
|
|
|
|
WebSSH lets you open an SSH session to any node directly from the browser. It
|
|
uses a Go-based WASM shim that creates an ephemeral Tailscale node in the
|
|
browser and connects to the target node over the Tailnet.
|
|
|
|
## Prerequisites
|
|
|
|
- **Headscale 0.28 or newer** is required.
|
|
- Target nodes must have **Tailscale SSH** enabled.
|
|
- Users must be authenticated via **OIDC** (API key logins cannot use WebSSH).
|
|
- The **Headplane Agent** must be
|
|
[enabled and configured](/features/agent) so that ephemeral node cleanup
|
|
works correctly.
|
|
- The WASM assets (`hp_ssh.wasm` and `wasm_exec.js`) must be present in the
|
|
build. These are built automatically by `./build.sh --wasm`.
|
|
|
|
## How It Works
|
|
|
|
When a user opens an SSH session from the UI, the browser:
|
|
|
|
1. Loads a Go WASM binary that implements a minimal Tailscale node.
|
|
2. Authenticates to the Tailnet using an ephemeral pre-auth key generated
|
|
server-side.
|
|
3. Connects to the target node over the Tailnet using DERP relay servers.
|
|
4. Opens an SSH session and renders it in an [xterm.js](https://xtermjs.org)
|
|
terminal.
|
|
|
|
The ephemeral node is automatically cleaned up after the session ends.
|
|
|
|
## DERP Servers on Non-Standard Ports
|
|
|
|
In the browser, Tailscale connects to DERP relay servers via WebSockets. If
|
|
your DERP servers run on a non-standard port (e.g. `:8443` instead of `:443`),
|
|
Headplane includes a patch to Tailscale's DERP client that preserves the port
|
|
in WebSocket URLs. This patch is applied automatically during the WASM build.
|
|
|
|
::: warning
|
|
If you are building the WASM module manually (outside of `build.sh`), make sure
|
|
to apply `patches/tailscale-derp-port.patch` to the vendored Tailscale source
|
|
before compiling. See the `build_wasm()` function in `build.sh` for reference.
|
|
:::
|
|
|
|
## Troubleshooting
|
|
|
|
### "WebSSH is not configured in this build"
|
|
|
|
The WASM assets are missing. Rebuild with `./build.sh --wasm` or ensure your
|
|
Docker image was built with the `--wasm` flag.
|
|
|
|
### "Only OAuth users are allowed to use WebSSH"
|
|
|
|
WebSSH requires OIDC authentication to generate pre-auth keys tied to a
|
|
Headscale user. API key logins do not have an associated Headscale user
|
|
identity.
|
|
|
|
### Connection hangs or fails to reach the node
|
|
|
|
- Verify that the target node has Tailscale SSH enabled.
|
|
- If using custom DERP servers on non-standard ports, ensure you are running
|
|
a build that includes the DERP port patch (any build from `build.sh` or
|
|
Docker includes it automatically).
|
|
- Check the browser console for WASM errors or DERP connection failures.
|