### Start the dev server with yarn run start Source: https://github.com/tsl0922/ttyd/blob/main/html/README.md Launches the development server for the HTML frontend. ```bash yarn run start ``` -------------------------------- ### Install dependencies with yarn install Source: https://github.com/tsl0922/ttyd/blob/main/html/README.md Run this command after installing Yarn v2 to install project dependencies. ```bash yarn install ``` -------------------------------- ### Install ttyd on OpenWrt Source: https://github.com/tsl0922/ttyd/blob/main/README.md Installs ttyd using the opkg package manager on OpenWrt. ```bash opkg install ttyd ``` -------------------------------- ### Start ttyd with bash Source: https://github.com/tsl0922/ttyd/blob/main/html/README.md Starts the ttyd server with a bash shell as the default command. ```bash ttyd bash ``` -------------------------------- ### Install ttyd on Windows with Scoop Source: https://github.com/tsl0922/ttyd/blob/main/README.md Installs ttyd using the Scoop package manager on Windows. ```powershell scoop install ttyd ``` -------------------------------- ### Start and enable ttyd service Source: https://github.com/tsl0922/ttyd/wiki/Systemd-service Starts the ttyd service immediately and enables it to start on boot. Run after creating the service file. ```bash sudo systemctl start ttyd && sudo systemctl enable ttyd ``` -------------------------------- ### Install ttyd snap Source: https://github.com/tsl0922/ttyd/blob/main/README.md Installs ttyd as a snap package. Requires sudo privileges and the --classic flag for confinement. ```bash sudo snap install ttyd --classic ``` -------------------------------- ### Install ttyd on Windows with WinGet Source: https://github.com/tsl0922/ttyd/blob/main/README.md Installs ttyd using the WinGet package manager on Windows. ```powershell winget install tsl0922.ttyd ``` -------------------------------- ### Install ttyd on Debian/Ubuntu Source: https://github.com/tsl0922/ttyd/blob/main/README.md Installs ttyd using the apt package manager on Debian/Ubuntu systems. ```bash sudo apt install ttyd ``` -------------------------------- ### Install ttyd on macOS with Homebrew Source: https://github.com/tsl0922/ttyd/blob/main/README.md Installs ttyd using the Homebrew package manager on macOS. ```bash brew install ttyd ``` -------------------------------- ### URL query parameters example Source: https://github.com/tsl0922/ttyd/wiki/Client-Options Client options can also be set via URL query parameters. Note that URL query parameters have higher priority than server-side command-line arguments. ```text http://localhost:7681/?fontSize=24&disableLeaveAlert=true&theme={%22background%22:%20%22green%22} ``` -------------------------------- ### Install ttyd on macOS with MacPorts Source: https://github.com/tsl0922/ttyd/blob/main/README.md Installs ttyd using MacPorts on macOS. Requires sudo privileges. ```bash sudo port install ttyd ``` -------------------------------- ### Run ttyd with advanced client options Source: https://github.com/tsl0922/ttyd/wiki/Client-Options Run ttyd with multiple client options to change xterm settings. This example sets cursor style to bar, line-height to 1.5, and background color to green. ```bash ttyd -t cursorStyle=bar -t lineHeight=1.5 -t 'theme={"background": "green"}' bash ``` -------------------------------- ### TypeScript declaration for window.term with fit() Source: https://github.com/tsl0922/ttyd/wiki/Programming-interface Declares the global window.term as a TtydTerminal, extending xterm.js Terminal with a fit() method from the fit addon. Use this to get typed access to the terminal instance exposed by ttyd. ```TypeScript interface TtydTerminal extends Terminal { fit(): void; } declare global { interface Window { term: TtydTerminal; } } ``` -------------------------------- ### Paste and execute command inside an iframe Source: https://github.com/tsl0922/ttyd/wiki/Programming-interface Variant of the paste+execute example for use when the terminal is inside an iframe. Must first access the iframe's contentWindow and contentDocument to reach the terminal and textarea. ```JavaScript document.getElementById('youriframeid').contentWindow.term.paste("whoami"); document.getElementById('youriframeid').contentDocument.querySelector("textarea.xterm-helper-textarea").dispatchEvent(new KeyboardEvent('keypress', {charCode: 13})) ``` -------------------------------- ### Build man page with go-md2man Source: https://github.com/tsl0922/ttyd/blob/main/man/README.md Converts the Markdown source ttyd.man.md into the troff man page ttyd.1. Requires the go-md2man tool, which is fetched via go get before running the conversion. ```bash go get github.com/cpuguy83/go-md2man go-md2man < ttyd.man.md > ttyd.1 ``` -------------------------------- ### Install dependencies on CentOS 7.9 Source: https://github.com/tsl0922/ttyd/wiki/build-for-centos7 Install required packages for building ttyd on CentOS 7.9. This includes epel-release, development libraries (zlib, libuv, glibc, json-c, libwebsockets), and gcc with patch. ```bash yum install -y epel-release yum install -y zlib-devel libuv-devel glibc-devel json-c-devel libwebsockets-devel yum install -y gcc patch ``` -------------------------------- ### Start ttyd with SSL and client certificate verification Source: https://github.com/tsl0922/ttyd/wiki/SSL-Usage Starts ttyd with the generated server certificate, key, and CA certificate. The --ssl-ca option enables client certificate verification. Remove --ssl-ca to disable client certificate verification. ```bash ttyd --ssl --ssl-cert server.crt --ssl-key server.key --ssl-ca ca.crt bash ``` -------------------------------- ### Build and compile HTML to src/html.h Source: https://github.com/tsl0922/ttyd/blob/main/html/README.md Compiles the inlined HTML into the C header file ../src/html.h. ```bash yarn run build ``` -------------------------------- ### Request a Let's Encrypt certificate with certbot Source: https://github.com/tsl0922/ttyd/wiki/Let's-Encrypt Install certbot first, then run this command to obtain a free SSL certificate for your domain. Replace with your actual domain name. ```bash certbot certonly -d ``` -------------------------------- ### Send input programmatically using Keysim (issue #620) Source: https://github.com/tsl0922/ttyd/wiki/Programming-interface Loads the Keysim library and dispatches keyboard events to the terminal's textarea to simulate typing 'ls' and pressing Enter. Useful for programmatically sending input from the client. ```JavaScript var script = document.createElement('script'); script.src = 'https://unpkg.com/keysim@latest/dist/keysim.js'; script.onload = function() { var input = document.querySelector('textarea'); var keyboard = Keysim.Keyboard.US_ENGLISH; keyboard.dispatchEventsForInput("ls", input); keyboard.dispatchEventsForAction("enter", input); }; document.body.appendChild(script); ``` -------------------------------- ### Paste and execute command in xterm.js (issue #979) Source: https://github.com/tsl0922/ttyd/wiki/Programming-interface Pastes text into the terminal and simulates pressing Enter by dispatching a keypress event on the xterm helper textarea. Use this to paste and execute a command. ```JavaScript term.paste("whoami"); document.querySelector("textarea.xterm-helper-textarea").dispatchEvent(new KeyboardEvent('keypress', {charCode: 13})) ``` -------------------------------- ### Run ttyd with custom port Source: https://github.com/tsl0922/ttyd/wiki/Example-Usage Starts the ttyd web server on port 8080 and launches a bash shell. Open http://localhost:8080 in a browser to access the terminal with debug mode enabled. ```bash ttyd -p 8080 bash ``` -------------------------------- ### Run ttyd with auth header on Unix socket Source: https://github.com/tsl0922/ttyd/wiki/Auth-Proxy Starts ttyd on a Unix domain socket and trusts the X-WEBAUTH-USER header for authentication. Always use a Unix socket to avoid direct unauthenticated access. ```bash ttyd -i /tmp/ttyd.sock -H X-WEBAUTH-USER bash ``` -------------------------------- ### Share single tmux session with multiple clients Source: https://github.com/tsl0922/ttyd/wiki/Example-Usage Starts a tmux session named 'ttyd' running vim, allowing multiple clients to share the same process. Connect from a terminal with 'tmux new -A -s ttyd'. ```bash ttyd tmux new -A -s ttyd vim ``` ```bash tmux new -A -s ttyd ``` -------------------------------- ### ttyd command-line options Source: https://github.com/tsl0922/ttyd/blob/main/README.md Displays the full usage and options for the ttyd command-line tool. Includes options for port, interface, authentication, SSL, and more. ```text USAGE: ttyd [options] [] OPTIONS: -p, --port Port to listen (default: 7681, use `0` for random port) -i, --interface Network interface to bind (eg: eth0), or UNIX domain socket path (eg: /var/run/ttyd.sock) -U, --socket-owner User owner of the UNIX domain socket file, when enabled (eg: user:group) -c, --credential Credential for basic authentication (format: username:password) -H, --auth-header HTTP Header name for auth proxy, this will configure ttyd to let a HTTP reverse proxy handle authentication -u, --uid User id to run with -g, --gid Group id to run with -s, --signal Signal to send to the command when exit it (default: 1, SIGHUP) -w, --cwd Working directory to be set for the child program -a, --url-arg Allow client to send command line arguments in URL (eg: http://localhost:7681?arg=foo&arg=bar) -W, --writable Allow clients to write to the TTY (readonly by default) -t, --client-option Send option to client (format: key=value), repeat to add more options -T, --terminal-type Terminal type to report, default: xterm-256color -O, --check-origin Do not allow websocket connection from different origin -m, --max-clients Maximum clients to support (default: 0, no limit) -o, --once Accept only one client and exit on disconnection -q, --exit-no-conn Exit on all clients disconnection -B, --browser Open terminal with the default system browser -I, --index Custom index.html path -b, --base-path Expected base path for requests coming from a reverse proxy (eg: /mounted/here, max length: 128) -P, --ping-interval Websocket ping interval(sec) (default: 5) -6, --ipv6 Enable IPv6 support -S, --ssl Enable SSL -C, --ssl-cert SSL certificate file path -K, --ssl-key SSL key file path -A, --ssl-ca SSL CA file path for client certificate verification -d, --debug Set log level (default: 7) -v, --version Print the version and exit -h, --help Print this text and exit ``` -------------------------------- ### Create new Docker container per client Source: https://github.com/tsl0922/ttyd/wiki/Example-Usage Runs ttyd to create a new Docker container for each client, launching an Ubuntu container. ```bash ttyd docker run -it --rm ubuntu ``` -------------------------------- ### Run vim in browser Source: https://github.com/tsl0922/ttyd/wiki/Example-Usage Launches a vim editor in the web browser by running ttyd with vim as the command. ```bash ttyd vim ``` -------------------------------- ### Run ttyd with Let's Encrypt SSL certificates Source: https://github.com/tsl0922/ttyd/wiki/Let's-Encrypt Use the fullchain.pem and privkey.pem files generated by certbot to enable HTTPS on ttyd. Replace and with your actual values. ```bash ttyd --ssl --ssl-cert /etc/letsencrypt/live//fullchain.pem --ssl-key /etc/letsencrypt/live//privkey.pem ``` -------------------------------- ### Create ttyd systemd service file Source: https://github.com/tsl0922/ttyd/wiki/Systemd-service Service unit file to launch ttyd on startup and restart automatically on error. Place this content in /etc/systemd/system/ttyd.service. Assumes the ttyd binary is at /opt/ttyd. Runs the 'login' command as root; do not run any other command as root and ensure the root account has a password. ```ini [Unit] Description=TTYD After=syslog.target After=network.target [Service] ExecStart=/opt/ttyd login Type=simple Restart=always User=root Group=root [Install] WantedBy=multi-user.target ``` -------------------------------- ### Enable Sixel image output Source: https://github.com/tsl0922/ttyd/wiki/Example-Usage Enables Sixel image output support (for img2sixel or lsix) by setting the client option enableSixel to true. ```bash ttyd -t enableSixel=true bash ``` -------------------------------- ### Login with system accounts Source: https://github.com/tsl0922/ttyd/wiki/Example-Usage Runs ttyd with the login command so users can authenticate with their system accounts in the web browser. ```bash ttyd login ``` -------------------------------- ### Generate CA and self-signed server/client certificates with OpenSSL Source: https://github.com/tsl0922/ttyd/wiki/SSL-Usage Creates a CA certificate, a server certificate for localhost, and client certificates in PEM and P12 formats. The CA FQDN must differ from server/client. For multiple domains, change subjectAltName to DNS:example.com,DNS:www.example.com. The p12/pem format may be useful for some clients. ```bash # CA certificate (FQDN must be different from server/client) 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 # server certificate (for multiple domains, change subjectAltName to: DNS:example.com,DNS:www.example.com) 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 # client certificate (the p12/pem format may be useful for some clients) 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 openssl pkcs12 -export -clcerts -in client.crt -inkey client.key -out client.p12 openssl pkcs12 -in client.p12 -out client.pem -clcerts ``` -------------------------------- ### Test client certificate verification with curl Source: https://github.com/tsl0922/ttyd/blob/main/man/ttyd.man.md Tests the SSL client certificate using curl. Replace [password] with the p12 password if set. ```bash curl --insecure --cert client.p12[:password] -v https://localhost:7681 ``` -------------------------------- ### Build ttyd <= 1.6.3 on CentOS 7.9 Source: https://github.com/tsl0922/ttyd/wiki/build-for-centos7 Compile ttyd version 1.6.3 or earlier from source. The commands create a build directory, compile each source file with the required include paths, link the object files into the ttyd binary, and copy it to /bin. ```bash mkdir b cd b cc -std=gnu99 -o pty.c.o -c ../src/pty.c cc -std=gnu99 -o http.c.o -c ../src/http.c cc -std=gnu99 -o utils.c.o -c ../src/utils.c cc -std=gnu99 -o terminal.c.o -c ../src/terminal.c cc -std=gnu99 -o protocol.c.o -c ../src/protocol.c -I/usr/include/json-c cc -std=gnu99 -o server.c.o -c ../src/server.c -I/usr/include/json-c -DTTYD_VERSION=\"1.6.3-j8\" cc utils.c.o terminal.c.o protocol.c.o http.c.o server.c.o -o ttyd -lz -luv -lutil -ljson-c -lwebsockets -lssl -lcrypto \cp ttyd /bin ``` -------------------------------- ### ttyd client option CLI flag Source: https://github.com/tsl0922/ttyd/wiki/Client-Options Use the -t/--client-option flag to pass server-side command-line arguments to the browser page. Repeat the flag to add more options. ```bash -t, --client-option Send option to client (format: key=value), repeat to add more options ``` -------------------------------- ### Enable ZMODEM file transfer Source: https://github.com/tsl0922/ttyd/wiki/Example-Usage Enables ZMODEM/lrzsz file transfer support in the terminal by setting the client option enableZmodem to true. ```bash ttyd -t enableZmodem=true bash ``` -------------------------------- ### Launch Chrome in app mode Source: https://github.com/tsl0922/ttyd/wiki/Example-Usage Launches Chrome in app mode pointing to the ttyd URL, allowing Ctrl+n, Ctrl+w etc. to be passed to the terminal. ```bash chrome --app=https://www.example.com/ttyd ``` -------------------------------- ### Enable trzsz file transfer Source: https://github.com/tsl0922/ttyd/wiki/Example-Usage Enables trzsz file transfer support in the terminal by setting the client option enableTrzsz to true. ```bash ttyd -t enableTrzsz=true bash ``` -------------------------------- ### ttyd CMakeLists.txt build configuration Source: https://github.com/tsl0922/ttyd/blob/main/CMakeLists.txt CMake build script for the ttyd project. Configures the project, detects dependencies (libuv, json-c, zlib, libwebsockets), sets compiler flags, and defines the build target. Requires CMake 3.12.0 or higher and libwebsockets built with libuv support. ```cmake cmake_minimum_required(VERSION 3.12.0) list(APPEND CMAKE_MODULE_PATH "${CMAKE_CURRENT_SOURCE_DIR}/cmake") project(ttyd VERSION 1.7.7 LANGUAGES C) set(TTYD_VERSION "${PROJECT_VERSION}") include(GetGitVersion) get_git_version(GIT_VERSION SEM_VER) get_git_head(GIT_COMMIT) if("${SEM_VER}" VERSION_GREATER "${TTYD_VERSION}") set(TTYD_VERSION "${SEM_VER}") endif() if(NOT "${GIT_COMMIT}" STREQUAL "") set(TTYD_VERSION "${TTYD_VERSION}-${GIT_COMMIT}") endif() if(NOT MSVC) set(CMAKE_C_FLAGS "${CMAKE_C_FLAGS} -D_GNU_SOURCE") if(CMAKE_VERSION VERSION_LESS "3.1") if ("${CMAKE_C_COMPILER_ID}" STREQUAL "GNU") set(CMAKE_C_FLAGS "${CMAKE_C_FLAGS} -std=gnu99") else() set(CMAKE_C_FLAGS "${CMAKE_C_FLAGS} -std=c99") endif() else() set(CMAKE_C_STANDARD 99) endif() else() # MSVC: suppress common warnings for C99 code add_compile_options(/W3 /wd4996 /wd4267 /wd4244) add_compile_definitions(_CRT_SECURE_NO_WARNINGS _GNU_SOURCE) endif() set(SOURCE_FILES src/utils.c src/pty.c src/protocol.c src/http.c src/server.c) include(FindPackageHandleStandardArgs) find_path(LIBUV_INCLUDE_DIR NAMES uv.h) find_library(LIBUV_LIBRARY NAMES uv libuv) find_package_handle_standard_args(LIBUV REQUIRED_VARS LIBUV_LIBRARY LIBUV_INCLUDE_DIR) mark_as_advanced(LIBUV_INCLUDE_DIR LIBUV_LIBRARY) if(LIBUV_FOUND) SET(LIBUV_INCLUDE_DIRS "${LIBUV_INCLUDE_DIR}") SET(LIBUV_LIBRARIES "${LIBUV_LIBRARY}") endif() find_path(JSON-C_INCLUDE_DIR NAMES json.h PATH_SUFFIXES json-c) find_library(JSON-C_LIBRARY NAMES json-c) find_package_handle_standard_args(JSON-C REQUIRED_VARS JSON-C_LIBRARY JSON-C_INCLUDE_DIR) mark_as_advanced(JSON-C_INCLUDE_DIR JSON-C_LIBRARY) if(JSON-C_FOUND) SET(JSON-C_INCLUDE_DIRS "${JSON-C_INCLUDE_DIR}") SET(JSON-C_LIBRARIES "${JSON-C_LIBRARY}") endif() find_package(ZLIB REQUIRED) find_package(Libwebsockets 3.2.0 REQUIRED) set(INCLUDE_DIRS ${ZLIB_INCLUDE_DIR} ${LIBWEBSOCKETS_INCLUDE_DIRS} ${JSON-C_INCLUDE_DIRS} ${LIBUV_INCLUDE_DIRS}) if(MSVC) # vcpkg's LIBWEBSOCKETS_LIBRARIES lists both 'websockets' and 'websockets_shared' # but only one target exists per triplet, so resolve the correct one. if(TARGET websockets_shared) set(LINK_LIBS ${ZLIB_LIBRARIES} websockets_shared ${JSON-C_LIBRARIES} ${LIBUV_LIBRARIES}) elseif(TARGET websockets) set(LINK_LIBS ${ZLIB_LIBRARIES} websockets ${JSON-C_LIBRARIES} ${LIBUV_LIBRARIES}) endif() else() set(LINK_LIBS ${ZLIB_LIBRARIES} ${LIBWEBSOCKETS_LIBRARIES} ${JSON-C_LIBRARIES} ${LIBUV_LIBRARIES}) endif() set (CMAKE_REQUIRED_INCLUDES ${INCLUDE_DIRS}) include(CheckSymbolExists) check_symbol_exists(LWS_WITH_LIBUV "lws_config.h" LWS_WITH_LIBUV) check_symbol_exists(LWS_OPENSSL_SUPPORT "lws_config.h" LWS_OPENSSL_ENABLED) check_symbol_exists(LWS_WITH_MBEDTLS "lws_config.h" LWS_MBEDTLS_ENABLED) if(NOT LWS_WITH_LIBUV) message(FATAL_ERROR "libwebsockets was not build with libuv support (-DLWS_WITH_LIBUV=ON)") endif() if(LWS_OPENSSL_ENABLED AND NOT LWS_MBEDTLS_ENABLED) find_package(OpenSSL REQUIRED) list(APPEND INCLUDE_DIRS ${OPENSSL_INCLUDE_DIR}) list(APPEND LINK_LIBS ${OPENSSL_LIBRARIES}) endif() if(WIN32) # libuv static requires dbghelp for MiniDumpWriteDump/Sym* APIs list(APPEND LINK_LIBS shell32 ws2_32 dbghelp) if(MSVC) find_package(getopt CONFIG) if(getopt_FOUND) if(TARGET getopt::getopt_shared) list(APPEND LINK_LIBS getopt::getopt_shared) elseif(TARGET getopt::getopt_static) list(APPEND LINK_LIBS getopt::getopt_static) endif() endif() endif() configure_file(${CMAKE_CURRENT_SOURCE_DIR}/app.rc.in ${CMAKE_CURRENT_BINARY_DIR}/app.rc @ONLY) list(APPEND SOURCE_FILES ${CMAKE_CURRENT_BINARY_DIR}/app.rc) else() find_library(LIBUTIL NAMES util) if(LIBUTIL) list(APPEND LINK_LIBS util) endif() endif() add_executable(${PROJECT_NAME} ${SOURCE_FILES}) target_include_directories(${PROJECT_NAME} PUBLIC ${INCLUDE_DIRS}) target_link_libraries(${PROJECT_NAME} ${LINK_LIBS}) target_compile_definitions(${PROJECT_NAME} PUBLIC TTYD_VERSION="${TTYD_VERSION}" $<$:_WIN32_WINNT=0xa00 WINVER=0xa00> ) include(GNUInstallDirs) install(TARGETS ${PROJECT_NAME} DESTINATION "${CMAKE_INSTALL_BINDIR}" COMPONENT prog) install(FILES man/ttyd.1 DESTINATION "${CMAKE_INSTALL_MANDIR}/man1" COMPONENT doc) ``` -------------------------------- ### Lossless patch for ttyd with _NEW_LWS support Source: https://github.com/tsl0922/ttyd/wiki/build-for-centos7 Apply a patch that wraps the auth header code in #ifdef _NEW_LWS blocks and adds a conditional setting of max_http_header_data. This allows building with either old or new libwebsockets versions. When using new lws, compile with -D_NEW_LWS. ```bash cat <= 1.7.0 with loss patch Source: https://github.com/tsl0922/ttyd/wiki/build-for-centos7 Compile ttyd version 1.7.0 or later after applying the loss patch. The build process is similar to the 1.6.3 build but includes pty.c.o and uses version string 1.7.4-j8. ```bash mkdir b cd b cc -std=gnu99 -o pty.c.o -c ../src/pty.c cc -std=gnu99 -o http.c.o -c ../src/http.c cc -std=gnu99 -o utils.c.o -c ../src/utils.c cc -std=gnu99 -o protocol.c.o -c ../src/protocol.c -I/usr/include/json-c cc -std=gnu99 -o server.c.o -c ../src/server.c -I/usr/include/json-c -DTTYD_VERSION=\"1.7.4-j8\" cc utils.c.o pty.c.o protocol.c.o http.c.o server.c.o -o ttyd -lz -luv -lutil -ljson-c -lwebsockets -lssl -lcrypto \cp ttyd /bin ``` -------------------------------- ### Apache proxy for multiple ttyd instances Source: https://github.com/tsl0922/ttyd/wiki/Auth-Proxy Apache VirtualHost configuration to host multiple ttyd instances on different Unix sockets and paths. ```apache AuthType Basic AuthName ttyd AuthBasicProvider file AuthUserFile /etc/apache2/ttyd_htpasswd Require valid-user RewriteEngine On RewriteRule .* - [E=PROXY_USER:%{LA-U:REMOTE_USER},NS] RequestHeader set X-WEBAUTH-USER "%{PROXY_USER}e" RequestHeader unset Authorization ProxyRequests Off ProxyPass /ttyd/1/ws unix:/tmp/ttyd1.sock|ws://localhost:8001/ws ProxyPass /ttyd/1/ unix:/tmp/ttyd1.sock|http://localhost8001/ ProxyPassReverse ttyd/1/ unix:/tmp/ttyd1.sock|http://localhost:8001/ ProxyPass /ttyd/2/ws unix:/tmp/ttyd2.sock|ws://localhost:8002/ws ProxyPass /ttyd/2/ unix:/tmp/ttyd2.sock|http://localhost8002/ ProxyPassReverse ttyd/2/ unix:/tmp/ttyd2.sock|http://localhost:8002/ ``` -------------------------------- ### Apache reverse proxy with basic auth Source: https://github.com/tsl0922/ttyd/wiki/Auth-Proxy Apache VirtualHost configuration that proxies to ttyd via Unix socket, sets X-WEBAUTH-USER from basic auth user, and strips the Authorization header. ```apache AuthType Basic AuthName ttyd AuthBasicProvider file AuthUserFile /etc/apache2/ttyd_htpasswd Require valid-user RewriteEngine On RewriteRule .* - [E=PROXY_USER:%{LA-U:REMOTE_USER},NS] RequestHeader set X-WEBAUTH-USER "%{PROXY_USER}e" RequestHeader unset Authorization ProxyRequests Off ProxyPass /ws unix:/tmp/ttyd.sock|ws://localhost/ws ProxyPass / unix:/tmp/ttyd.sock|http://localhost/ ProxyPassReverse / unix:/tmp/ttyd.sock|http://localhost/ ``` -------------------------------- ### Allow web server user to access ttyd socket Source: https://github.com/tsl0922/ttyd/wiki/Auth-Proxy Changes ownership of the ttyd Unix socket to www-data so the web server can access it. ```bash sudo chown www-data:www-data /tmp/ttyd.sock ``` -------------------------------- ### Patch webpack.config.js to inline font assets Source: https://github.com/tsl0922/ttyd/wiki/Serving-web-fonts Apply this diff to html/webpack.config.js to add a rule that inlines font files (ttf, otf, eot, woff, woff2) as asset/inline. Ensure the src in the @font-face rule uses a local path. ```diff --- a/html/webpack.config.js +++ b/html/webpack.config.js @@ -29,6 +29,10 @@ const baseConfig = { test: /\.s?[ac]ss$/, use: [devMode ? 'style-loader' : MiniCssExtractPlugin.loader, 'css-loader', 'sass-loader'], }, + { + test: /\.(ttf|otf|eot|woff|woff2)$/, + type: 'asset/inline', + }, ], }, resolve: { ``` -------------------------------- ### Apache OIDC authenticating proxy for ttyd Source: https://github.com/tsl0922/ttyd/wiki/Auth-Proxy Apache configuration using mod_auth_openidc with Keycloak to protect ttyd, restricting access to a single user via preferred_username claim. ```apache RewriteEngine On LogLevel info auth_openidc:info OIDCProviderMetadataURL https://idp.example.com/realms/EXAMPLE/.well-known/openid-configuration OIDCClientID OIDCClientSecret # OIDCRedirectURI is a vanity URL that must point to a path protected by # but must NOT point to any content OIDCRedirectURI https://example.com/ttyd/callback OIDCCryptoPassphrase OIDCOAuthRemoteUserClaim preferred_username AuthType openid-connect Require claim preferred_username:example_user #ttyd ProxyPass /ttyd/ unix:/tmp/ttyd1.sock|http://localhost:8001/ ProxyPassReverse /ttyd/ unix:/tmp/ttyd1.sock|http://localhost:8001/ RewriteCond %{HTTP:Upgrade} =websocket [NC] RewriteRule /ttyd/(.*) unix:/tmp/ttyd1.sock|ws://localhost:8001/$1 [P,L] RewriteCond %{HTTP:Upgrade} !=websocket [NC] RewriteRule /ttyd/(.*) unix:/tmp/ttyd1.sock|ws://localhost:8001/$1 [P,L] ``` -------------------------------- ### Add @font-face rule to index.scss Source: https://github.com/tsl0922/ttyd/wiki/Serving-web-fonts Add your own @font-face rules to html/src/style/index.scss to define a custom font family for bundling into the ttyd executable. ```css @font-face { font-family: 'My Font'; font-style: normal; font-weight: normal; src: url(...); } ``` -------------------------------- ### Nginx reverse proxy with basic auth Source: https://github.com/tsl0922/ttyd/wiki/Auth-Proxy Nginx location block that proxies to ttyd via Unix socket, sets X-WEBAUTH-USER from basic auth user, and clears the Authorization header. ```nginx location / { auth_basic "ttyd"; auth_basic_user_file "/etc/apache2/ttyd_htpasswd"; proxy_set_header X-WEBAUTH-USER $remote_user; proxy_set_header Authorization ""; 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://unix:/tmp/ttyd.sock; } ``` -------------------------------- ### Loss patch for ttyd >= 1.7.0 Source: https://github.com/tsl0922/ttyd/wiki/build-for-centos7 Apply a patch to remove authentication header checks from src/http.c and src/protocol.c. This is needed for ttyd versions 1.7.0 and later, likely to disable proxy authentication handling. ```bash cat <auth_header != NULL) { - if (lws_hdr_custom_length(wsi, server->auth_header, strlen(server->auth_header)) > 0) return AUTH_OK; - return send_unauthorized(wsi, HTTP_STATUS_PROXY_AUTH_REQUIRED, WSI_TOKEN_HTTP_PROXY_AUTHENTICATE); - } +++ src/protocol.c @@ -184,3 +183,0 @@ - if (server->auth_header != NULL) { - return lws_hdr_custom_copy(wsi, pss->user, sizeof(pss->user), server->auth_header, strlen(server->auth_header)) > 0; - } j8 ``` -------------------------------- ### Nginx reverse proxy configuration for ttyd Source: https://github.com/tsl0922/ttyd/wiki/Let's-Encrypt Paste this into /etc/nginx/sites-available/ttyd to proxy HTTPS requests to the default ttyd port 7681. The first server block handles SSL with Let's Encrypt certificates and WebSocket upgrade headers; the second redirects HTTP to HTTPS. ```nginx server { server_name ; # the following section is relevant if you've generated SSL certificates via Let's Encrypt - which you should have >:( listen 443 ssl; ssl_certificate /etc/letsencrypt/live//fullchain.pem; ssl_certificate_key /etc/letsencrypt/live//privkey.pem; ssl_trusted_certificate /etc/letsencrypt/live//chain.pem; include /etc/letsencrypt/options-ssl-nginx.conf; ssl_dhparam /etc/letsencrypt/ssl-dhparams.pem; location / { proxy_pass https://localhost:7681/; # default ttyd port, notice the https prefix proxy_http_version 1.1; proxy_set_header X-Real-IP $remote_addr; proxy_set_header Host $host; proxy_set_header X-Forwarded-For $remote_addr; # needed for websocket proxy_set_header Upgrade $http_upgrade; proxy_set_header Connection $connection_upgrade; } } # redirect http requests to https server { if ($host = ) { return 301 https://$host$request_uri; } listen 80; server_name ; return 404; } ``` -------------------------------- ### Patch for ttyd >= 1.7.4 to adjust max_http_header_data Source: https://github.com/tsl0922/ttyd/wiki/build-for-centos7 Apply a patch to src/server.c that changes the max_http_header_data value from 65535 to 32767 and adds a printf statement to output the value. This is for ttyd versions 1.7.4 and later. ```bash cat <