WebSSH – Connect Linux Terminal from Your Web Browser

Brief: This article guide demonstrates the installation and usage of WebSSH (a web-based SSH client) for users to be able to easily authenticate and connect to SSH servers from web browsers.

For most Linux users, the traditional approach of connecting to remote servers via an SSH client has always been through a command-line environment. However, WebSSH simplifies client-to-server SSH connection by providing an easy-to-use web interface, which is written in Python and based on xterm.js, paramiko, and tornado.

WebSSH Features

  • Supports modern browsers like Chrome, Edge, Firefox, Opera, and Safari.
  • Implements a resizable terminal Window.
  • The target SSH server’s default encoding is automatically detected.
  • Supports full-screen terminal.
  • Supports Two-Factor Authentication.
  • Supports encrypted keys.
  • Supports SSH public key authentication with the inclusion of DSA RSA ECDSA Ed25519 keys.
  • Supports SSH password authentication with the inclusion of empty passwords.

Step 1 – Installing WebSSH Dependencies (Python and PIP)

Since Python is a major requirement before installing and using WebSSH, you need to make sure that it is installed on your system.

$ sudo apt install python3         [On Debian, Ubuntu and Mint]
$ sudo yum install python3         [On RHEL/CentOS/Fedora and Rocky Linux/AlmaLinux]
$ sudo emerge -a dev-lang/python   [On Gentoo Linux]
$ sudo apk add python3             [On Alpine Linux]
$ sudo pacman -S python3           [On Arch Linux]
$ sudo zypper install python3      [On OpenSUSE]    

Next, you need to install Python PIP, which is used to install Python modules and libraries on the system.

$ sudo apt install python3         [On Debian, Ubuntu and Mint]
$ sudo yum install python3         [On RHEL/CentOS/Fedora and Rocky Linux/AlmaLinux]
$ sudo emerge -a dev-lang/python   [On Gentoo Linux]
$ sudo apk add python3             [On Alpine Linux]
$ sudo pacman -S python3           [On Arch Linux]
$ sudo zypper install python3      [On OpenSUSE]    

Once installed, you can confirm Python and PIP versions using the following commands.

$ python3 -V
$ pip --version
Check Python and PIP Versions
Check Python and PIP Versions

Step 2 – Installing WebSSH in Linux

With Python and Python PIP installed on your system, we can finally install WebSSH:

$ pip3 install webssh 
Install WebSSH in Linux
Install WebSSH on Linux

Confirm the installed WebSSH version by running:

$ wssh --version

1.6.0

Step 3 – Connecting to Linux Terminal from Web Browser Using WebSSH

If you’ve installed WebSSH on a local system, you can start the WebSSH by running the following command.

$ wssh

If you’ve installed WebSSH on a remote Linux system, you need to add an additional parameter to the following command, which will allow remote connections over HTTP protocol, which is not secure by default, therefore you need to secure it by enabling HTTPS, as discussed later in the article.

$ wssh --fbidhttp=False
Start WebSSH in Linux
Start WebSSH on Linux

As depicted in the screenshot above, we will be using port 8888, which must be allowed on your firewall.

$ sudo ufw allow 8888
OR
$ sudo firewall-cmd --zone=public --add-port=8888/tcp

On your Web Browser, navigate to the following address to connect to WebSSH by providing regular SSH credentials as shown.

http://127.0.0.1:8888
OR
http://your_domain:8888
Connect WebSSH in Linux
Connect WebSSH in Linux

For key-based authentication, upload your SSH key file usually located in the ~/.ssh folder. Use the keyboard shortcut Ctrl+h to show hidden files and directories before uploading the file.

Upon successfully connecting to your remote machine, you will be presented with the following browser interface:

Connect to SSH from Web Browser Using WebSSH
Connect to SSH from a Web Browser Using WebSSH

Step 4 – Securing WebSSH with SSL Certificate

This step assumes you have a registered domain name and an active LetsEncrypt SSL Certificate. The SSL certificates associated with your domain name should be in the directory location:

/etc/letsencrypt/live/your_domain_name

Your certificate files in this directory will have a .pem file extension e.g fullchain.pem and privkey.pem.

For WebSSH to run with HTTPS support, the path to the cert file (fullchain.pem) and key file (privkey.pem) should be provided.

First, make sure your firewall permits port 4433 used by WebSSH for HTTPS access:

$ sudo ufw allow 4433
OR
$ sudo firewall-cmd --zone=public --add-port=4433/tcp

From here, launch the WebSSH server by pointing it to the domain name cert and key files:

$ sudo wssh --certfile='/etc/letsencrypt/live/your_domain_name/fullchain.pem' --keyfile='/etc/letsencrypt/live/your_domain_name/privkey.pem'

To access the WebSSH web browser interface via HTTPS, implement:

https://127.0.0.1:4433
OR
https://your_domain:4433

Step 5 – Running WebSSH Behind Nginx Reverse Proxy

In this step, user requests to WebSSH will be handled by Nginx (Reverse Proxy), for this to work, you need to install and configure Nginx as a reverse proxy.

$ sudo apt install nginx             [On Debian, Ubuntu and Mint]
$ sudo yum install nginx             [On RHEL/CentOS/Fedora and Rocky Linux/AlmaLinux]
$ sudo emerge -a www-servers/nginx   [On Gentoo Linux]
$ sudo apk add nginx                 [On Alpine Linux]
$ sudo pacman -S nginx               [On Arch Linux]
$ sudo zypper install nginx          [On OpenSUSE]    

Next, allow Nginx access to ports 80 and 443 on your firewall.

$ sudo ufw allow “Nginx Full”
Or
$ sudo firewall-cmd --permanent --zone=public --add-port=80/tcp
$ sudo firewall-cmd --permanent --zone=public --add-port=443/tcp

Create Nginx configuration for WebSSH:

$ sudo nano /etc/nginx/sites-available/webssh

Paste the following info and replace your_domain_name with your actual domain name:

server {
    listen 80 default_server;
    listen [::]:80 default_server;
    server_name your_domain_name www.your_domain_name
    root /var/www/html;

    access_log /var/log/nginx/webssh.access.log;
    error_log /var/log/nginx/webssh.error.log;

    location / {
        proxy_pass http://127.0.0.1:8888;
        proxy_http_version 1.1;
        proxy_read_timeout 300;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
        proxy_set_header Host $http_host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Real-PORT $remote_port;
    }

    listen 443 ssl;
    # RSA certificate
    ssl_certificate /etc/letsencrypt/live/your_domain_name/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/your_domain_name/privkey.pem;

    # For Redirecting non-https traffic to https
    if ($scheme != "https") {
        return 301 https://$host$request_uri;
    }
}

Activate the webssh configuration file:

$ sudo ln -s /etc/nginx/sites-available/webssh /etc/nginx/sites-enabled/webssh

Remove the Nginx default configuration file to avoid conflicts with the newly created Nginx WebSSH configuration file:

$ sudo rm /etc/nginx/sites-enabled/default

Verify Nginx configuration:

$ sudo nginx -t 

You can also remove ports 8888 and 4433 from your firewall rules since Nginx will be handling all traffic.

Restart WebSSH without specifying the cert and key files’ paths.

$ wssh 

From here, you can now directly access your domain name from your web browser without specifying a port.

https://your_domain_name 

Step 6 – Creating WebSSH Systemd File

So far, we have automated all steps except for launching the wssh server from the system using a command line environment. To automate this step, we need to set up a background service.

We need to create a unit file and close the wssh server if it is still running with Ctrl+C keyboard keys.

Create a WebSSH service file:

$ sudo nano /etc/systemd/system/webssh.service

Add the following to the file:

[Unit]
Description=WebSSH terminal interface
After=network.target

[Service]
User=www-data
Group=www-data
ExecStart=wssh

[Install]
WantedBy=multi-user.target

The value for ExecStart under [Service] can be found by running:

$ whereis wssh

wssh: /home/linuxbrew/.linuxbrew/bin/wssh

In the above case, the value input will be:

[Service]
User=www-data
Group=www-data
ExecStart=/home/linuxbrew/.linuxbrew/bin/wssh

We can now start and enable WebSSH with the following commands:

$ sudo systemctl start webssh
$ sudo systemctl enable webssh
$ sudo systemctl status webssh
Check WebSSH in Linux
Check WebSSH in Linux

Each time you reload your domain name URL (http://your_domain_name), You will be able to use a fresh WebSSH session with WebSSH and Nginx running in the background.

WebSSH makes it flexibly easy to access and manage your remote machines from the comfort of a modern and secured Web Browser.

Got something to say? Join the discussion.

Have a question or suggestion? Please leave a comment to start the discussion. Please keep in mind that all comments are moderated and your email address will NOT be published.