DOCSEARCHbyAlgolia
Submit Docs

ttyd

repository·main·Indexed 11 days ago

https://github.com/tsl0922/ttyd

A command-line tool to share a terminal session over the web via a browser. Built on libuv and WebGL2, ttyd version 1.0.0 supports advanced terminal features including CJK, IME, Sixel images, and ZMODEM file transfers.

Tokens
9.8K
Snippets
31
Records
40
Agent score
90%

What's inside ttyd

  1. Configure ttyd security and authentication

    main

    To secure your terminal session, you can use several methods:

    • Basic Authentication: Use -c, --credential with the format username:password.
    • Reverse Proxy Authentication: Use -H, --auth-header to specify an HTTP header name, allowing an upstream proxy to handle authentication.
    • SSL/TLS: Enable SSL with -S, --ssl and provide certificate paths using -C, --ssl-cert and -K, --ssl-key.
    • Origin Check: Use -O, --check-origin to prevent websocket connections from different origins.

  2. Use ttyd to share a terminal

    main

    The basic usage of ttyd follows this pattern:

    ttyd [options] <command> [<arguments...]]

    ttyd starts a web server that hosts a terminal session running the specified <command>. By default, it listens on port 7681 and provides a read-only terminal unless the --writable flag is used.

    ttyd bash

  3. Enable SSL/TLS in ttyd

    main

    To enable SSL, use the --ssl flag along with paths to your certificate and key. You can also provide a CA file for client certificate verification.

    SSL Command Example

    ttyd --ssl --ssl-cert server.crt --ssl-key server.key --ssl-ca ca.crt bash

    Generating Self-Signed Certificates

    To generate a CA and self-signed certificates for testing:

    1. Generate CA certificate:

      openssl genrsa -out ca.key 2048
openssl req -new -x509 -days 365 -key ca.key -subj "/C=CN/ST=GD/L=SZ/O=Acme, Inc./CN=Acme Root CA" -out ca.crt

    2. Generate server certificate:

      openssl req -newkey rsa:2048 -nodes -keyout server.key -subj "/C=CN/ST=GD/L=SZ/O=Acme, Inc./CN=localhost" -out server.csr
openssl x509 -sha256 -req -extfile <(printf "subjectAltName=DNS:localhost") -days 365 -in server.csr -CA ca.crt -CAkey ca.key -CAcreateserial -out server.crt

    3. Generate client certificate (for client verification):

      openssl req -newkey rsa:2048 -nodes -keyout client.key -subj "/C=CN/ST=GD/L=SZ/O=Acme, Inc./CN=client" -out client.csr
openssl x509 -req -days 365 -in client.csr -CA ca.crt -CAkey ca.key -CAcreateserial -out client.crt
# Convert to p12/pem for easier client use
openssl pkcs12 -export -clcerts -in client.crt -inkey client.key -out client.p12
openssl pkcs12 -in client.p12 -out client.pem -clcerts
    ttyd --ssl --ssl-cert server.crt --ssl-key server.key --ssl-ca ca.crt bash

  4. Build the man page from Markdown

    main

    To generate the ttyd.1 man page from the source Markdown file ttyd.man.md, use the go-md2man tool. This requires having Go installed on your system.

    go get github.com/cpuguy83/go-md2man
go-md2man < ttyd.man.md  > ttyd.1

  5. Install ttyd

    main

    You can install ttyd across various platforms using package managers or by downloading precompiled binaries.

    macOS

    • Homebrew: brew install ttyd
    • MacPorts: sudo port install ttyd

    Linux

    • Debian/Ubuntu: sudo apt install ttyd
    • Snap: sudo snap install ttyd --classic
    • OpenWrt: opkg install ttyd
    • Gentoo: Clone the repository and follow Gentoo wiki instructions.
    • Homebrew (Linux): brew install ttyd
    • Precompiled Binaries: Download from the GitHub releases page.

    Windows

    • WinGet: winget install tsl0922.ttyd
    • Scoop: scoop install ttyd
    • Binary version (recommended): Download from the GitHub releases page.

  8. Run ttyd in development mode

    main

    To run the development environment, you need to start both the ttyd binary and the web development server in separate processes.

    1. Start the ttyd instance (e.g., running bash): ttyd bash
    2. Start the dev server: yarn run start
    ttyd bash
yarn run start

  9. Manage terminal rendering types

    main

    The Xterm class supports three rendering modes via the rendererType option:

    • dom: The default standard DOM-based rendering.
    • canvas: Uses the @xterm/addon-canvas for improved performance.
    • webgl: Uses the @xterm/addon-webgl for high-performance GPU-accelerated rendering.

    If a high-performance renderer (like WebGL) fails to load, the system automatically attempts to fall back to the canvas renderer, and then to the dom renderer.

  10. How Xterm handles flow control

    main

    To prevent overwhelming the client or server with data, ttyd implements a flow control mechanism using limit, highWater, and lowWater values.

    When the amount of written data exceeds the limit, the terminal starts tracking pending writes. If pending exceeds highWater, a PAUSE command is sent to the server. Once the pending count drops below lowWater, a RESUME command is sent to the server to continue data transmission.

  11. Protocol message types for ttyd

    main

    The ttyd protocol uses specific single-character identifiers to communicate between the client (browser) and the server.

    Client to Server messages:

    • INPUT ('0'): Terminal input data.
    • RESIZE_TERMINAL ('1'): Request to resize the terminal dimensions.
    • PAUSE ('2'): Pause the terminal process.
    • RESUME ('3'): Resume the terminal process.
    • JSON_DATA ('{'): Structured JSON data.

    Server to Client messages:

    • OUTPUT ('0'): Terminal output data.
    • SET_WINDOW_TITLE ('1'): Update the browser window title.
    • SET_PREFERENCES ('2'): Send client-side preferences (e.g., theme, settings).

  12. Configure Nginx as a reverse proxy for ttyd

    main

    If you are running ttyd behind an Nginx reverse proxy, use the following configuration to proxy requests under the /ttyd path. This ensures WebSocket upgrades are handled correctly.

    location ~ ^/ttyd(.*)$ {
    proxy_http_version 1.1;
    proxy_set_header Host $host;
    proxy_set_header X-Forwarded-Proto $scheme;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection "upgrade";
    proxy_pass http://127.0.0.1:7681/$1;
}
    location ~ ^/ttyd(.*)$ {
    proxy_http_version 1.1;
    proxy_set_header Host $host;
    proxy_set_header X-Forwarded-Proto $scheme;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection "upgrade";
    proxy_pass http://127.0.0.1:7681/$1;
}