DOCSEARCHbyAlgolia
Submit Docs

WebSSH2 Documentation

repository·main·Indexed 25 days ago

https://github.com/billchurch/webssh2

An HTML5 web-based terminal emulator and SSH client that proxies WebSocket/Socket.io connections to an SSH2 server. Built with SolidJS, xterm.js, and TypeScript, it provides a browser-based interface for SSH and optional Telnet access. Features include configurable keyboard capture for tmux/vim, host key verification via SQLite, and flexible deployment options via Docker, Kubernetes, and Nginx reverse proxies.

Tokens
45.8K
Snippets
123
Records
260
Agent score
82%

What's inside WebSSH2

  1. Understand Keyboard Interactive authentication modes

    main

    WebSSH2 operates in three modes for handling Keyboard Interactive prompts:

    1. Default (Auto-password):
      • If all prompts in a round contain "password" (case-insensitive), WebSSH2 auto-responds with the connection password.
      • If any prompt in a round does not contain "password", all prompts in that round are forwarded to the client.
      • Subsequent rounds (like 2FA) are always forwarded to the client.
    2. Server-wide Always Forward: Enabled via alwaysSendKeyboardInteractivePrompts: true. All prompts in all rounds are sent to the client.
    3. Per-session Always Forward: Enabled by the client via forwardAllKeyboardInteractivePrompts: true in the authentication credentials. Overrides server defaults for that session only.

  2. Understand the WebSSH2 Event Flow

    main

    The WebSSH2 connection lifecycle follows a specific sequence of events between the Client, Socket.IO, the WebSSH2 Server, and the target SSH Server:

    1. Connection & Authentication:
      • The Client connects via Socket.IO.
      • The WebSSH2 Server emits request_auth to the Client.
      • The Client sends authentication data, which must include terminal dimensions (cols and rows).
      • The Server processes authentication via handleAuthenticate, stores terminal state in sessionState, and calls initializeConnection.
    2. SSH Connection:
      • The WebSSH2 Server initiates the connection to the SSH Server (ssh.connect).
      • Once the SSH connection is ready (conn.on ready), the Server emits authentication success and permissions to the Client.
    3. Terminal Initialization:
      • The Server updates the Client's footer element.
      • The Server calls createShell using the stored terminal dimensions.
    4. Data Communication Loop:
      • SSH to Client: Data received from the SSH Server (stream.on('data')) is forwarded to the Client via socket.emit('data').
      • Client to SSH: Data sent from the Client (socket.on('data')) is written to the SSH Server (stream.write('data')).
      • Terminal Resizing: The Server handles terminal data via handleTerminal, which can update term, rows, and cols if dimensions change.

  3. Understand the Host Key Verification Socket Protocol

    main

    WebSSH2 uses a Socket.IO event protocol for SSH host key verification. This protocol allows the server and/or client to verify the identity of an SSH host before completing a connection. It supports three operational modes:

    • Server-only: The server uses its own store to verify keys. The client is not involved in verification decisions.
    • Client-only: The server is bypassed for verification, and the client is responsible for checking its local key store and responding to prompts.
    • Hybrid: The server checks its store first. If the key is unknown, it falls back to prompting the client.

    All events use the hostkey: namespace prefix.

  4. Understand WebSSH2 Client Architecture

    main

    The WebSSH2 client is a browser-side application built using the following technology stack:

    • UI Framework: SolidJS (reactive UI)
    • Terminal Emulator: xterm.js 5.5
    • Communication Protocol: Socket.IO 4.8 (via WebSockets)
    • Build Tool: Vite 5.0
    • Language: TypeScript (strict mode)

    Core Component Structure:

    • app.tsx: Main application entry point.
    • components/: Contains Terminal.tsx, LoginModal.tsx, TerminalSettingsModal.tsx, TerminalSearch.tsx, and Modal.tsx.
    • utils/: Contains keyboard-capture.ts (logic) and settings.ts (LocalStorage persistence).
    • stores/: State management.
    • services/: Business logic.

  5. Run WebSSH2 with an SSH Private Key

    main

    You can provide a private key via the WEBSSH2_USER_PRIVATE_KEY environment variable. The key must be provided in a single-line format (newlines replaced by \n).

    # Prepare private key (single line format)
KEY=$(cat ~/.ssh/id_rsa | tr '\n' '~' | sed 's/~/\\n/g')

# Run with private key
docker run -d \
  --name webssh2-key \
  -p 2222:2222 \
  -e WEBSSH2_USER_NAME=myuser \
  -e WEBSSH2_USER_PRIVATE_KEY="$KEY" \
  ghcr.io/billchurch/webssh2:latest

  6. Configure Browser Copy/Paste Features

    main

    If copy/paste is not working, ensure you are accessing the site via HTTPS or localhost. You can manage clipboard features in Terminal Settings or via localStorage under webssh2.settings.global.

    Available Features

    • Auto-copy on selection: Enables automatic copying when text is selected with the mouse.
    • Middle-click paste: Enables pasting using the middle mouse button.

    Keyboard Shortcuts

    • Copy: Ctrl+Shift+C (Windows/Linux) or ⌘+Shift+C (macOS)
    • Paste: Ctrl+Shift+V (Windows/Linux) or ⌘+Shift+V (macOS)

  7. Configure environment variable forwarding to SSH

    main

    WebSSH2 allows forwarding environment variables to the SSH session via URL parameters.

    1. URL Format: Use the env parameter with key-value pairs separated by commas: env=FOO:bar,BAR:baz.
    2. Server Filtering: The server applies filtering and caps. You can optionally provide an allowlist via ssh.envAllowlist or the WEBSSH2_SSH_ENV_ALLOWLIST environment variable.
    3. SSH Server Requirement: The target SSH server must be configured to accept these names via the AcceptEnv directive.

  8. Migrate WebSSH2 configuration to the new format

    main

    If you are upgrading WebSSH2, you must manually update your config.json because the configuration structure has changed significantly.

    Migration Steps:

    1. Create a new config.json file using the latest schema.
    2. Relocate existing settings to their new parent objects (e.g., move algorithms under ssh).
    3. Remove deprecated sections: socketio, terminal, serverlog, accesslog, verify, and safeShutdownDuration.
    4. Remove the user.overridebasic option.
    5. Update session.name to lowercase webssh2.
    6. Move terminal settings (like fontSize, scrollback, cursorBlink) to the client-side application, as they are no longer supported in the server configuration.
    7. Test the new configuration before deploying.

  9. Configure Terminal Theming

    main

    WebSSH2 features an opt-in terminal theming system.

    Core Theming Variables

    VariableTypeDefaultDescription
    WEBSSH2_THEMING_ENABLEDbooleanfalseMaster switch for terminal theming
    WEBSSH2_THEMING_ALLOW_CUSTOMbooleantrueShow the JSON paste textarea in the settings modal
    WEBSSH2_THEMING_THEMEScsv(all built-ins)Comma-separated allowlist of built-in theme names.
    WEBSSH2_THEMING_ADDITIONAL_THEMESbase64 JSON[]Base64-encoded JSON array of operator-defined themes.
    WEBSSH2_THEMING_DEFAULT_THEMEstringDefaultInitial picker value.
    WEBSSH2_THEMING_HEADER_BACKGROUNDenumindependentOne of independent, followTerminal, locked.

    Built-in Theme Names

    Use these case-sensitive names in WEBSSH2_THEMING_THEMES: Default, Dracula, Nord, Solarized Dark, One Dark, Monokai, Gruvbox Dark, Tokyo Night, Catppuccin Mocha.

    Adding Custom Themes via Base64

    WEBSSH2_THEMING_ADDITIONAL_THEMES expects a base64-encoded JSON array of objects with the shape { name, colors, license?, source? }.

    Example Workflow:

    1. Create your JSON array.
    2. Encode it using base64 (use base64 -w 0 on GNU systems to avoid line wraps).
    3. Set the variable.

  10. Set up the WebSSH2 development environment

    main

    To develop with WebSSH2, you must set up both the client and server repositories.

    Prerequisites

    • Node.js 22 LTS (Jod)
    • npm
    • Git
    • Two terminal windows/sessions

    Installation Steps

    1. Create a directory and clone both repositories:
    mkdir webssh2-dev
cd webssh2-dev

# Clone the client repository
git clone https://github.com/billchurch/webssh2_client.git

# Clone the server repository
git clone https://github.com/billchurch/webssh2.git webssh2_server
    1. Install dependencies for both projects:
    # Install client dependencies
cd webssh2_client
npm install

# Install server dependencies
cd ../webssh2_server
npm install
    mkdir webssh2-dev
cd webssh2-dev

# Clone the client repository
git clone https://github.com/billchurch/webssh2_client.git

# Clone the server repository
git clone https://github.com/billchurch/webssh2.git webssh2_server

# Install client dependencies
cd webssh2_client
npm install

# Install server dependencies
cd ../webssh2_server
npm install

  11. Implement Security Best Practices for WebSSH2

    main

    To ensure a secure deployment of WebSSH2, follow these security guidelines:

    1. Manage Secrets Securely: Never commit secrets to version control. Always explicitly set WEBSSH2_SESSION_SECRET using a secure secret management system. Relying on auto-generated secrets breaks session persistence across restarts and replicas and triggers a session_secret_generated warning.
    2. Restrict Algorithms: Use the strict algorithm preset for high-security environments.
    3. Validate Origins: Avoid using wildcard origins (*:*) in production environments.
    4. Use HTTPS: Always use HTTPS in production.
    5. Rotate Secrets: Regularly rotate your session secrets.

  12. Tear down the WebSSH2 + Nginx stack

    main

    To stop and remove the containers in the WebSSH2 + Nginx example stack, run the following command from the examples/nginx directory. Note that volumes are not persisted, but the fullchain.pem and privkey.pem files will remain in the directory for future use.

    docker compose down