WebSSH 1.6.3

Search for WebSSH in the Marketplace, select the SecureAnyCloud publisher, and choose Create. Configure the network security group as tightly as you can:

• TCP 22 (SSH) for administration, from your management network only.
• TCP 80 (WebSSH UI, behind Basic Auth) from your trusted client networks only. Never open it to 0.0.0.0/0 on a public instance.
• TCP 443 is optional. Open it if you put your own TLS certificate in front of nginx, which is recommended for production (see Security).

az group create --name webssh-rg --location eastus
# Accept the Marketplace terms once per subscription (required before the first CLI deploy)
az vm image terms accept --urn sac1647283583153:webssh-ubuntu-24-04:default:latest
az vm create \
  --resource-group webssh-rg \
  --name webssh-vm \
  --image sac1647283583153:webssh-ubuntu-24-04:default:latest \
  --size Standard_B2s \
  --admin-username azureuser \
  --generate-ssh-keys \
  --public-ip-sku Standard

Then restrict inbound access to your own management CIDR instead of the whole internet:

az network nsg rule create \
  --resource-group webssh-rg --nsg-name webssh-vmNSG \
  --name allow-webssh-ui --priority 1010 \
  --destination-port-ranges 80 --access Allow --protocol Tcp \
  --source-address-prefixes <your-mgmt-cidr>

On first boot, webssh-firstboot.service generates a unique password for the admin front-door account, writes it to /root/webssh-credentials.txt, starts nginx and proves the gate. SSH in as azureuser and read it:

sudo cat /root/webssh-credentials.txt

You will see the WEBSSH_URL, the admin username and the per-VM WEBSSH_PASSWORD, along with security notes. Confirm that the services are healthy and that WebSSH is bound to loopback only, with nginx as the only public listener:

systemctl is-active webssh.service nginx.service
sudo ss -tlnp | grep -E ':8888|:80 ' curl -s -o /dev/null -w 'unauthenticated /healthz -> HTTP %{http_code}\n' http://127.0.0.1/healthz

The credentials file is mode 0600. The image ships only a fail-closed bcrypt entry in /etc/nginx/.webssh.htpasswd, and no plaintext password is ever stored in the image.

Open WEBSSH_URL (http://<your-vm-public-ip>/) in a browser. Your browser prompts for the front-door credentials. Sign in as admin with the per-VM password from Step 3. The WebSSH connect form then appears.

Enter the target host you want to reach: its hostname or IP, the SSH port (22 by default), the username, and either a password or an uploaded private key. You can also add an optional passphrase and a TOTP code for servers that use 2FA.

Choose Connect. WebSSH opens a real SSH session to that host and drops you into a live xterm.js terminal in the browser. The terminal is a full interactive shell, so you can run commands exactly as you would in any SSH client.

WebSSH attempts to connect to any host and port that a signed-in user types. Treat the instance as what it is, an SSH relay, and control both ends.

The front door only opens with the per-VM password

The whole UI and the terminal WebSocket sit behind per-VM HTTP Basic Auth. Without the password, the front door is closed to everyone. A wrong password is rejected, and only the per-VM password reaches the terminal. You can prove this from the VM:

PW=$(sudo grep '^WEBSSH_PASSWORD=' /root/webssh-credentials.txt | cut -d= -f2-)
curl -s -o /dev/null -w 'no password -> HTTP %{http_code}\n' http://127.0.0.1/
curl -s -o /dev/null -w 'wrong password -> HTTP %{http_code}\n' -u admin:wrong-pw http://127.0.0.1/
curl -s -o /dev/null -w 'per-VM pw -> HTTP %{http_code}\n' -u "admin:$PW" http://127.0.0.1/

Restrict who can reach it (inbound)

• Keep the per-VM password secret, and rotate it if it is ever shared (see below).
• Lock inbound TCP 80/443 to trusted source IPs in the Azure NSG, or keep the instance on a private network reachable only over a VPN or Bastion. Do not expose it wide open to 0.0.0.0/0.

Restrict where it can connect (outbound and egress)

By design, WebSSH lets the browser choose the destination, so an unrestricted instance can reach anything routable from the VM. Constrain egress to only the hosts you administer. An Azure NSG outbound rule is the cleanest control. On the VM itself, you can also use UFW, for example to allow SSH only to a specific management subnet:

sudo ufw default deny outgoing
sudo ufw allow out to <your-mgmt-cidr> port 22 proto tcp
sudo ufw allow out 53
sudo ufw enable

Encrypt the front door for production

The image serves the UI over plain HTTP on port 80 by default. For any production or internet-facing use, put your own TLS certificate in front of nginx (port 443). This encrypts the Basic Auth password and the terminal traffic in transit.

SecureAnyCloud ships nginx-ssl-certbot-ubuntu-24-04 as a one-step option. Alternatively, add a listen 443 ssl server block with your certificate to /etc/nginx/sites-available/sac-webssh.

Option A: AWS Marketplace console

• Open the SecureAnyCloud Hardened WireGuard VPN & VPN, Proxy and Remote Access AMIs listing on AWS Marketplace. Choose View purchase options, then Subscribe. One subscription covers every version in the listing.
• When the subscription is active, choose Launch your software.
• Choose One-click launch from AWS Marketplace, or Launch from EC2 Console for the full launch wizard. In Version, choose WebSSH 1.6.3 on Ubuntu 24.04, then choose your Region.
• Pick an instance type (m5.large is recommended) and your key pair.
• For the security group, note that the listing's default group allows SSH (22), HTTP (80) and HTTPS (443) from anywhere. Restrict SSH and 443 to your own addresses before you launch.
• Choose your VPC and a subnet with a route to the servers you will reach. Add a public IP if you browse to WebSSH over the internet. Leave the metadata defaults, because the image already requires IMDSv2. Then choose Launch.

Option B: AWS CLI

Run this on your own workstation. It creates a security group that allows SSH and HTTPS from your management address, then launches the instance. Replace the AMI ID with the one shown for your Region on the Marketplace launch page. Replace the VPC, subnet, key pair and CIDR range with your own.

SG=$(aws ec2 create-security-group --group-name webssh \
  --description "WebSSH" --vpc-id vpc-0123456789abcdef0 \
  --query GroupId --output text)
aws ec2 authorize-security-group-ingress --group-id "$SG" --protocol tcp --port 22 --cidr <your-mgmt-cidr>
aws ec2 authorize-security-group-ingress --group-id "$SG" --protocol tcp --port 443 --cidr <your-mgmt-cidr>
aws ec2 run-instances \
  --image-id ami-0123456789abcdef0 \
  --instance-type m5.large \
  --key-name my-key-pair \
  --security-group-ids "$SG" \
  --subnet-id subnet-0123456789abcdef0 \
  --associate-public-ip-address \
  --tag-specifications 'ResourceType=instance,Tags=[{Key=Name,Value=webssh}]'

You do not need --metadata-options, because the AMI already makes IMDSv2 required. First boot takes a few seconds after the instance is running.

Connect as ubuntu with the key pair you chose:

ssh -i ~/.ssh/my-key-pair.pem ubuntu@<public-ip>

systemctl is-active webssh nginx
sudo test -f /var/lib/sac/data/webssh-firstboot.done && echo FIRSTBOOT_DONE

active active FIRSTBOOT_DONE

webssh-firstboot ran once on the first boot. webssh is WebSSH, and nginx serves it. Only SSH and nginx listen on network ports. WebSSH listens on the loopback address:

sudo ss -lntp | awk 'NR>1 {print $4}' | grep -v '127.0.0.5' | sort -u

0.0.0.0:22 0.0.0.0:443 0.0.0.0:80 127.0.0.1:8888 [::]:22 [::]:443 [::]:80

The URL and the password are in a file only root can read:

sudo cat /root/webssh-credentials.txt

# WebSSH 1.6.3 - generated on first boot by webssh-firstboot.service.
# Every value below is unique to this instance; nothing was baked into the image. Keep this file private.
# Web terminal (HTTPS, self-signed certificate unique to this instance): sign in as admin with the password below,
# then enter the SSH host, port, user and password or private key of the server you want to reach. WEBSSH_URL=https://203.0.113.10/ WEBSSH_USERNAME=admin WEBSSH_PASSWORD=<your-password> WEBSSH_HOST=203.0.113.10
# The certificate served on 443 (/etc/nginx/sac/tls/webssh.crt), to compare with your browser's warning: TLS_CERT_SHA256=3A:1F:...:9C # Anyone with this password can open SSH connections FROM this instance to any host it can reach: restrict port 443 # in the security group to your own addresses. New password:
sudo webssh-new-password
# Self-test:
sudo webssh-selftest Serve WebSSH under your own DNS name:
sudo webssh-set-host <dns-name>
# Guide: https://secureanycloud.com/stacks/webssh-1-6-3/

The URL uses the instance's public IPv4 address (its private address when it has no public one). WebSSH also answers on the instance's public DNS name.

Open WEBSSH_URL in your browser. The certificate is self-signed, so the browser warns once. Compare the fingerprint it shows with TLS_CERT_SHA256 from the credentials file, then continue.

The browser then asks for a user name and password. Enter admin and WEBSSH_PASSWORD. The browser remembers them until you close it. WebSSH then shows its connection form.

• Hostname and Port: the server you want to reach, as this instance sees it. A private IP inside your VPC works. The port defaults to 22.
• Username: the account on that server.
• Password, or Private Key. For a key, choose the key file and add its Passphrase if it has one. RSA, ECDSA and Ed25519 keys work, and DSA keys are not supported. Totp is for servers that ask for a one-time code.
• Choose Connect. The terminal opens in the page. Closing the tab ends the session.

To try it on the instance itself, connect to Hostname 127.0.0.1, Port 22, Username ubuntu and choose your EC2 key pair's private key file (.pem). The key travels to the instance over HTTPS and is used for that one connection. WebSSH does not store it.

Host keys. The first time you connect to a server, WebSSH records its host key in /var/lib/webssh/known_hosts. If the key later changes, because the server was rebuilt or something is intercepting the connection, WebSSH refuses with Bad host key. After you have confirmed that the change is genuine, remove the old entry and restart WebSSH. Open sessions are closed:

sudo -u webssh ssh-keygen -R '[10.0.1.25]:22' -f /var/lib/webssh/known_hosts
sudo systemctl restart webssh

For port 22, the entry is just the host (10.0.1.25). For other ports, it is [host]:port.

Instance metadata. A session aimed at the metadata service fails before any data is exchanged.

sudo webssh-new-password

This generates a new random password, writes it to WEBSSH_PASSWORD in /root/webssh-credentials.txt and stores its bcrypt hash for nginx. The old password stops working at once, and your browser asks for the new one on the next page load.

To pick your own password instead, write a bcrypt entry for admin to /etc/nginx/sac/webssh.htpasswd (mode 0640, owner root, group www-data).

Security group outbound rules are the simplest control. To restrict WebSSH itself to a list of networks, add a systemd drop-in. This example allows this instance's own SSH server and one VPC range:

sudo tee /etc/systemd/system/webssh.service.d/60-egress-allowlist.conf >/dev/null <<'EOF' [Service] IPAddressAllow=localhost 10.0.0.0/16 IPAddressDeny=any EOF
sudo systemctl daemon-reload && sudo systemctl restart webssh

Never put 169.254.0.0/16, 0.0.0.0/0 or ::/0 in IPAddressAllow, because an allow entry overrides the metadata block. For a strict list of servers instead of networks, run WebSSH with --policy=reject. It then connects only to servers whose host keys you have added to /var/lib/webssh/known_hosts (or /etc/ssh/ssh_known_hosts) and refuses every other target before opening a connection:

ssh-keyscan -p 22 10.0.1.25 | sudo -u webssh tee -a /var/lib/webssh/known_hosts
sudo sed -i 's/--policy=autoadd/--policy=reject/' /etc/systemd/system/webssh.service
sudo systemctl daemon-reload && sudo systemctl restart webssh

Check each host key you add, for example against ssh-keygen -lf /etc/ssh/ssh_host_ed25519_key.pub on that server.

Point a DNS A record at the instance, then run:

sudo webssh-set-host webssh.example.com

This issues a new self-signed certificate for that name, updates nginx and the credentials file, and prints the new fingerprint. Running sudo webssh-set-host with no name returns to the instance's own address.

To use a CA-issued certificate instead, put the certificate chain and key in /etc/nginx/sac/tls/webssh.crt and /etc/nginx/sac/tls/webssh.key (key mode 0600, owned by root), then run sudo nginx -t && sudo systemctl reload nginx. Do not add the self-signed certificate to your computer's trust store. Compare its fingerprint, or replace it.

Run the built-in self-test. It opens a real SSH session through the HTTPS front door to a temporary SSH server on 127.0.0.1:2222 and checks that WebSSH cannot reach the metadata service:

sudo webssh-selftest

WebSSH 203.0.113.10: webssh + nginx up, WebSSH 127.0.0.1:8888 only, HTTPS OK, anonymous requests refused, SSH session through the web front door OK, metadata service unreachable SELFTEST_OK

Without the password, every request is refused, the page may not be framed, and port 8888 is not reachable from the network:

H=$(sudo sed -n 's/^WEBSSH_HOST=//p' /root/webssh-credentials.txt)
sudo curl -s -o /dev/null -D - --cacert /etc/nginx/sac/tls/webssh.crt --resolve "$H:443:127.0.0.1" "https://$H/" | tr -d '\r' | grep -iE '^(HTTP|WWW-Authenticate|X-Frame-Options)'
P=$(hostname -I | awk '{print $1}') timeout 5 bash -c "exec 3<>/dev/tcp/$P/8888" 2>/dev/null && echo "8888 OPEN" || echo "8888 refused"

HTTP/1.1 401 Unauthorized WWW-Authenticate: Basic realm="WebSSH (sac)" X-Frame-Options: DENY 8888 refused

WebSSH and nginx are denied the instance metadata service:

systemctl show -p IPAddressDeny webssh nginx

IPAddressDeny=169.254.169.254/32 168.63.129.16/32 fd00:ec2::254/128 IPAddressDeny=169.254.169.254/32 168.63.129.16/32 fd00:ec2::254/128

The password file holds one bcrypt entry and is readable by root and nginx only:

sudo stat -c '%a %U:%G' /etc/nginx/sac/webssh.htpasswd
sudo grep -cE '^admin:\$2b\$12\$' /etc/nginx/sac/webssh.htpasswd

640 root:www-data 1

head -3 /usr/share/doc/webssh/BUILD-INFO.txt /opt/webssh/venv/bin/wssh --version

The command above prints the build information and the installed WebSSH version. These are the main file locations on the image:

• /opt/webssh/venv: WebSSH 1.6.3 and its Python packages, read-only to the service (no pip in it).
• /var/lib/webssh/known_hosts: the host keys WebSSH has accepted.
• /etc/nginx/conf.d/sac-webssh.conf and /etc/nginx/sac/: the nginx server blocks, the password file and this instance's certificate.
• /etc/systemd/system/webssh.service: the service and WebSSH's options (--policy, --maxconn and others).
• /usr/share/doc/webssh/: the MIT licence, build information and the hashed package lock.
• /root/webssh-credentials.txt: the first-boot URL, password and certificate fingerprint.

WebSSH keeps no data besides known_hosts. Back that file up if you rely on the recorded host keys.

Ubuntu security updates install automatically. To update WebSSH and its Python packages, move to a newer SecureAnyCloud version of this listing. The virtual environment deliberately has no pip.

• Restrict ports 22 and 443 in the security group to your own networks, and limit outbound traffic to the servers you need.
• Rotate the password with sudo webssh-new-password when someone no longer needs access. Do not share it more widely than you would an SSH key.
• Prefer private keys to passwords for the servers you reach, and check a host key before the first connection.
• Replace the self-signed certificate with a CA-issued one for wider use.