mirror of
https://github.com/Studio-Saelix/sencho.git
synced 2026-07-26 11:49:16 +00:00
Anso
d4fa4a4965
* fix(host-console): audit session lifecycle and harden path, resize, and route gating Record an audit-log entry when a host console session opens and when it closes (capturing user, node, client IP, and timestamp), so interactive host-shell access leaves a durable, accountable trail instead of only an ephemeral log line. Fix a stack-path boundary check that allowed a sibling directory sharing the base path's prefix to pass; directory resolution now uses the canonical within-base check via a small testable helper. Validate terminal resize frames (positive integers within a sane bound) before forwarding them to the PTY, dropping malformed frames instead of passing them through. Mirror the backend admin-only console permission on the frontend route so a non-admin who reaches the view cannot mount a console the server would reject, and log (rather than silently swallow) a working-directory resolution failure. Add unit coverage for the path helper, audit open/close rows, resize validation, and the spawn-error path, plus a WebSocket-upgrade integration test exercising the full gate chain and a live session-open audit row. * fix(host-console): record the node the shell actually runs in When the requested node's directory cannot be resolved, the session falls back to the default node's base directory. Record that fallback node in the session audit row (and log it) so the audit trail names the node the shell actually runs in rather than the originally requested one. Strengthen the upgrade integration test to assert the open row captures the user, node, and client IP.
112 lines
6.3 KiB
Plaintext
112 lines
6.3 KiB
Plaintext
---
|
||
title: Host Console
|
||
description: An interactive terminal on your host OS, directly in the browser - no SSH required.
|
||
---
|
||
|
||
The **Console** tab opens a full interactive terminal session on the machine running Sencho. It behaves exactly like an SSH session, but without needing an SSH server, client, or key management.
|
||
|
||
<Note>
|
||
The Host Console requires a **Sencho Admiral** license and the **admin** role. [Learn more about licensing](/features/licensing).
|
||
</Note>
|
||
|
||
<Frame>
|
||
<img src="/images/host-console/host-console-overview.png" alt="Host Console showing a live bash session listing containers with the floating chip strip in the bottom right" />
|
||
</Frame>
|
||
|
||
## What it is
|
||
|
||
The Host Console gives you a real terminal session on the Sencho host, streamed to your browser over a WebSocket. It supports:
|
||
|
||
- Full color and cursor support
|
||
- Tab completion (provided by the host shell)
|
||
- Automatic terminal resizing when you resize the browser window
|
||
- Copy and paste
|
||
- Cursor blinking
|
||
|
||
## Opening the console
|
||
|
||
Click **Console** in the top navigation bar. The session starts immediately in the `COMPOSE_DIR` root. If a stack is selected in the sidebar, the terminal opens directly inside that stack's directory instead, and a small back button appears in the masthead so you can return to the stack editor.
|
||
|
||
## Cockpit layout
|
||
|
||
The Console page is a vertical stack of two surfaces.
|
||
|
||
<Frame>
|
||
<img src="/images/host-console/host-console-masthead.png" alt="Masthead with brand-cyan accent on the left, Connected state in italic, and shell, viewport, and session uptime metadata on the right" />
|
||
</Frame>
|
||
|
||
The **masthead** holds the live connection state. The state word recolors with the tone of the session:
|
||
|
||
- **Connected** in brand cyan with a pulsing dot whenever output is flowing
|
||
- **Reconnecting** in amber when the WebSocket is being re-established
|
||
- **Disconnected** in red when the session has ended
|
||
|
||
The kicker reads `HOST CONSOLE · {NODE}`, so it always tells you which node the session belongs to. The right side carries three metadata pills:
|
||
|
||
| Pill | Meaning |
|
||
|------|---------|
|
||
| **SHELL** | The pill reads `BASH`. In a Docker deployment, the spawned shell is bash, falling back to `sh` if bash is unavailable inside the image. |
|
||
| **VIEWPORT** | Current terminal size in `{cols}×{rows}`, updated automatically when you resize the browser window. |
|
||
| **SESSION** | Time elapsed since the shell was opened (`M:SS UP` while under an hour, then `1H 05M` once it crosses an hour). |
|
||
|
||
The **terminal well** sits below the masthead and fills the remaining height with an xterm.js session.
|
||
|
||
<Frame>
|
||
<img src="/images/host-console/host-console-chip-strip.png" alt="Floating chip strip with Copy, Clear, Download, and Reconnect buttons" />
|
||
</Frame>
|
||
|
||
The **chip strip** floats over the bottom right of the terminal:
|
||
|
||
- **Copy** copies the current xterm selection to your clipboard
|
||
- **Clear** wipes the visible scrollback without killing the shell
|
||
- **Download** exports the full scrollback as a timestamped `.txt` file
|
||
- **Reconnect** closes and reopens the WebSocket without leaving the page
|
||
|
||
## Sessions and limits
|
||
|
||
Sencho enforces a maximum of **5 concurrent console sessions** per instance. If you hit this limit, close an existing session before opening a new one. Each session runs a heartbeat; if the browser tab is closed or the network drops, the server detects the dead connection and cleans up the orphaned shell within 60 to 90 seconds.
|
||
|
||
## Environment variables
|
||
|
||
Environment variables whose names suggest secrets (passwords, tokens, keys, credentials, auth-related variables, private keys, passphrases, encryption and signing secrets) and certain well-known connection strings (`DATABASE_URL`, `REDIS_URL`, `MONGO_URI`, `AMQP_URL`, `DSN`) are stripped from the console environment before the shell spawns. Running `env` or `printenv` inside the console will not reveal them.
|
||
|
||
## Security considerations
|
||
|
||
The Host Console is one of the most powerful features in Sencho and is treated as such:
|
||
|
||
- **Admin role required.** Only users with the **admin** role can open a console session.
|
||
- **Admiral license required.** The Console tab is not available on the Community or Skipper tiers.
|
||
- **Browser sessions only.** Console sessions are only available from a signed-in browser session, not from API tokens.
|
||
- **Audited.** Every console session is recorded in the audit log. Opening and closing a session each write an entry capturing the user, node, client IP, and timestamp, so shell access is fully accountable.
|
||
|
||
<Warning>
|
||
The Host Console provides unrestricted shell access to the machine running Sencho. Do not expose Sencho on a public network without HTTPS and strong authentication.
|
||
</Warning>
|
||
|
||
## Common uses
|
||
|
||
- Inspecting files in your `COMPOSE_DIR` without leaving the browser
|
||
- Running `docker compose logs --follow` or `docker ps` directly
|
||
- Editing files with `nano` or `vim` for quick fixes
|
||
- Running maintenance scripts or one-off commands on the host
|
||
|
||
## Troubleshooting
|
||
|
||
<AccordionGroup>
|
||
<Accordion title="Maximum console sessions reached">
|
||
Sencho limits concurrent console sessions to 5 per instance. Close one or more existing console sessions (either through the UI or by closing the browser tab) and try again. Stale sessions from disconnected browsers are cleaned up automatically within 60 to 90 seconds.
|
||
</Accordion>
|
||
|
||
<Accordion title="Session ends immediately after connecting">
|
||
This typically means the shell could not be found on the host. In a Docker deployment, ensure `bash` or `sh` is available inside the container. You can check by running `docker exec <container> which bash` from the host. Also verify that your user has the **admin** role and your instance has an active Admiral license.
|
||
</Accordion>
|
||
|
||
<Accordion title="Connection drops after a short time">
|
||
If you are running Sencho behind a reverse proxy (Nginx, Caddy, Traefik), the proxy may be closing WebSocket connections after its default idle timeout. Increase the WebSocket timeout in your proxy configuration. For Nginx, set `proxy_read_timeout` and `proxy_send_timeout` to a higher value (for example `3600s`).
|
||
</Accordion>
|
||
|
||
<Accordion title="Console tab is not visible">
|
||
The Console tab only appears for users with the **admin** role on an Admiral-licensed instance. Verify both conditions are met. If you recently activated an Admiral license, refresh the page.
|
||
</Accordion>
|
||
</AccordionGroup>
|