Monitoring WebSSH with Vigilmon

WebSSH is a no-configuration browser SSH client: users open a URL, enter a hostname, username, and password (or paste a private key), and get a terminal — no SSH client needed, no pre-configured targets. That simplicity makes it popular for infrastructure teams and support portals. But the Python Tornado server that powers it has no health endpoint and no watchdog. When the process crashes, every SSH attempt silently fails at the browser. Vigilmon gives you HTTP availability checks on the connection form, keyword verification that the form loaded correctly, TCP probes for the SSH servers WebSSH connects to, SSL certificate alerts, and heartbeat confirmation of end-to-end SSH proxying.

What You'll Set Up

HTTP uptime monitor for the WebSSH connection form (port 8888)
Keyword check verifying the connection form HTML loaded correctly
TCP probe confirming SSH target servers are reachable from the WebSSH host
SSL certificate expiry alert for HTTPS WebSSH deployments
Heartbeat monitor for end-to-end WebSSH SSH proxying

Prerequisites

WebSSH installed and running (wssh on port 8888 by default)
At least one target SSH server that WebSSH connects to
A domain or IP accessible from the internet (or from Vigilmon's probe network)
A free Vigilmon account

Step 1: Monitor the WebSSH Connection Form

WebSSH serves the SSH connection form at / on port 8888. A 200 OK on GET / confirms the Python Tornado server is running and the web client is being served.

Log in to vigilmon.online and click Add Monitor.
Set Type to HTTP / HTTPS.
Enter the URL: http://your-server:8888/ (or https://your-webssh.domain.com/ if behind a reverse proxy).
Set Check interval to 1 minute.
Set Expected HTTP status to 200.
Click Save.

WebSSH listens on port 8888 by default, configurable via --port. If you've bound it to a specific address with --address, update the URL. The HTTP check confirms the Tornado server is up and routing requests — but not that the connection form HTML is intact.

Step 2: Keyword Check on the Connection Form

WebSSH's GET / returns a page with a connection form containing name="hostname", name="port", and name="username" inputs. A keyword check on one of these attributes distinguishes a healthy WebSSH response from an nginx error page, a Python crash traceback, or a misconfigured proxy that returns a 200 with an error body.

Open the HTTP monitor created in Step 1.
Enable Keyword check.
Set the keyword to name="hostname".
Click Save.

This keyword appears in the WebSSH connection form and is absent from error pages, so a 200 with name="hostname" present is a reliable health signal. If Tornado returns a 200 with an error body (which can happen with framework-level exceptions in debug mode), the keyword check will fail and alert you.

Step 3: TCP Probe for SSH Target Servers

WebSSH is an SSH proxy — it connects from the server side to whatever SSH host the user enters. If the SSH servers in your infrastructure are unreachable from the WebSSH host, every connection attempt will fail after the user submits the form, with no feedback other than a timeout.

Add a TCP probe for each SSH server WebSSH is expected to connect to:

Click Add Monitor → TCP Port.
Enter the SSH server hostname or IP address.
Set Port to 22 (or the custom SSH port if different).
Set Check interval to 1 minute.
Click Save.

Repeat for each target SSH server. If WebSSH is used to reach a pool of servers, add a TCP monitor for each critical host. This gives you advance warning of SSH connectivity failures — before users start hitting connection timeouts in their browser sessions.

Step 4: SSL Certificate Alerts for HTTPS Deployments

WebSSH is typically deployed behind nginx or Caddy for SSL termination. A certificate expiry causes browsers to show a TLS error before users even reach the connection form — silently blocking all SSH access through WebSSH.

Enable SSL monitoring on the HTTP monitor created in Step 1:

Open the monitor for your WebSSH URL.
Enable Monitor SSL certificate.
Set Alert when certificate expires in less than 21 days.
Click Save.

For nginx with Let's Encrypt, verify the renewal configuration:

# Check if auto-renewal is working
certbot renew --dry-run

# Check certificate expiry
certbot certificates

A 21-day alert window gives you enough lead time to diagnose renewal failures and renew manually without any service interruption.

Step 5: Heartbeat Monitoring for End-to-End SSH Proxying

WebSSH's HTTP check confirms Tornado is serving pages, but doesn't verify the SSH proxy path is functional. A server-side script that programmatically uses WebSSH to make an SSH connection — checking that the connection succeeds and the session token is issued — and then pings a Vigilmon heartbeat on success gives you full end-to-end coverage.

Create the heartbeat monitor

In Vigilmon, click Add Monitor → Cron Heartbeat.
Set the expected ping interval to 10 minutes.
Copy the heartbeat URL: https://vigilmon.online/heartbeat/YOUR_TOKEN.

Create an end-to-end check script

#!/usr/bin/env python3
# /usr/local/bin/webssh-health-check.py
# Verifies WebSSH is serving the connection form and SSH target is reachable

import subprocess
import sys
import urllib.request
import urllib.error

WEBSSH_URL = "http://localhost:8888/"
SSH_HOST = "localhost"
SSH_PORT = 22
HEARTBEAT_URL = "https://vigilmon.online/heartbeat/YOUR_TOKEN"

def check_webssh_form():
    try:
        with urllib.request.urlopen(WEBSSH_URL, timeout=5) as resp:
            body = resp.read().decode("utf-8")
            return resp.status == 200 and 'name="hostname"' in body
    except Exception as e:
        print(f"WebSSH form check failed: {e}")
        return False

def check_ssh_port():
    result = subprocess.run(
        ["nc", "-z", "-w", "3", SSH_HOST, str(SSH_PORT)],
        capture_output=True
    )
    return result.returncode == 0

def ping_heartbeat():
    try:
        urllib.request.urlopen(HEARTBEAT_URL, timeout=5)
    except Exception as e:
        print(f"Heartbeat ping failed: {e}")

if check_webssh_form() and check_ssh_port():
    ping_heartbeat()
    print("WebSSH health check passed")
else:
    print("WebSSH health check failed")
    sys.exit(1)

Schedule the check

# Make executable
chmod +x /usr/local/bin/webssh-health-check.py

# Add to crontab: crontab -e
*/10 * * * * /usr/local/bin/webssh-health-check.py

If either the connection form or the SSH target check fails, the heartbeat won't be sent and Vigilmon alerts after the expected interval passes.

Step 6: Configure Alert Channels

Go to Alert Channels in Vigilmon and add email, Slack, or a webhook.
On the HTTP and keyword monitors, set Consecutive failures before alert to 2 — Tornado restarts under a process manager may cause a brief unavailability.
On the SSH TCP probes, set Consecutive failures before alert to 1 — an unreachable SSH server needs immediate attention.

For planned WebSSH restarts or updates, pause alerts temporarily:

# Open a maintenance window before restarting WebSSH
curl -X POST https://vigilmon.online/api/maintenance \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{"monitor_id": "YOUR_MONITOR_ID", "duration_minutes": 3}'

systemctl restart webssh
# or: pkill wssh && wssh --port 8888 &

Summary

| Monitor | Target | What It Catches | |---|---|---| | HTTP uptime | http://your-server:8888/ | WebSSH process crash, Tornado server failure | | Keyword check | name="hostname" in page body | Error page served instead of connection form | | SSH TCP probe | SSH target port 22 | SSH servers unreachable from WebSSH host | | SSL certificate | WebSSH HTTPS domain | Certificate expiry blocking browser access | | Cron heartbeat | Heartbeat URL | SSH proxy broken, end-to-end connectivity failed |

WebSSH's zero-configuration design means there's no config file to check, no plugin to query, no built-in health endpoint. Vigilmon fills that observability gap — watching the connection form, verifying the HTML is intact, probing the SSH targets, monitoring the TLS certificate, and heartbeating the full proxy path. When WebSSH silently stops working, you find out from Vigilmon, not from a user.