ttyd is a simple command line tool for sharing terminals on the web. In simple terms, it allows you to use SSH terminal services on a web page, and the software is free and open source.

Installing ttyd

The ttyd author has provided pre-compiled binary files, which can be downloaded and used directly. The latest version download address is: https://github.com/tsl0922/ttyd/releases. Here is an example for CentOS 7:

# Download ttyd
wget -O ttyd https://github.com/tsl0922/ttyd/releases/download/1.6.0/ttyd_linux.x86_64
# Add executable permission
chmod +x ttyd
# Move to directory
mv ttyd /usr/sbin

After these steps, we have completed the installation of ttyd. You can check the current version by entering the command ttyd -v:

[root@hosta29d0ffef5 ~]# ttyd -v
ttyd version 1.6.0-c15cfb7

Running ttyd

Enter the command ttyd bash to run ttyd. Note that the firewall needs to allow port 7681, and then open a web browser and access http://IP:7681 to open the web terminal, as shown in the figure below.

However, ttyd does not run in the background and accessing 7681 does not require any password verification, which is very insecure. Next, we will create a systemd service for ttyd and set up username and password authentication.

Creating a service

Create a ttyd.service file: vi /etc/systemd/system/ttyd.service with the following content:

[Unit]
Description=ttyd
After=network.target

[Service]
ExecStart=/usr/sbin/ttyd -c xiaoz:xiaoz.me bash

[Install]
WantedBy=multi-user.target

After creating the file, enter the command: systemctl daemon-reload to make the daemon effective.

The -c parameter is used above, which means setting username and password authentication. The format is -c username:password. The username set above is xiaoz and the password is xiaoz.me. Please modify them to your own username and password.

After the service is created, we can use the systemd command to manage it. The commands are as follows:

# Start ttyd
systemctl start ttyd
# Stop ttyd
systemctl stop ttyd
# Restart ttyd
systemctl restart ttyd
# Enable auto start
systemctl enable ttyd

Nginx reverse proxy

If you don't like the IP + port access method, you can also set up Nginx reverse proxy to access through a domain name. The configuration is as follows:

If it is the root directory of the website

location / {
    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;
}

If it is a subdirectory of the website

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;
}

Note that the ttyd above can be modified to the desired path.

ttyd parameter explanation

Enter ttyd -h to view the ttyd help, the explanations are as follows:

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

VERSION:
    1.6.0

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)
    -c, --credential        Credential for Basic Authentication (format: username:password)
    -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)
    -a, --url-arg           Allow client to send command line arguments in URL (eg: http://localhost:7681?arg=foo&arg=bar)
    -R, --readonly          Do not allow clients to write to the TTY
    -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
    -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)
    -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

Visit https://github.com/tsl0922/ttyd to get more information and report bugs.

Summary

Using ttyd, you can easily and quickly set up a WebSSH service. However, convenience also means taking on more security risks. Although ttyd provides basic password authentication, this authentication method is still not secure. Using ttyd means that your server has an additional entry point, so it is not recommended for production environments, but it doesn't matter if you want to tinker with it.

• ttyd project address: https://github.com/tsl0922/ttyd
• ttyd official homepage: https://tsl0922.github.io/ttyd/