Monitoring Xpra Remote Applications with Vigilmon

Xpra (X Persistent Remote Applications) is unique in the remote desktop world: it can forward individual graphical applications — not just full desktops — over WebSockets, SSH, or TCP, and when you disconnect, your applications keep running. Scientific computing teams use it to keep long-running analysis GUIs alive on headless servers; sysadmins use it to access graphical admin tools on remote Linux hosts without a VNC session; developers use it to run IDE sessions that persist across network interruptions. Xpra also provides a built-in HTML5 web client on port 14500 for browser-based access. But unlike traditional servers with obvious error responses, a dead Xpra session is silent — the web client loads, but nothing appears. Vigilmon monitors the Xpra web client availability, the multi-protocol WebSocket transport, the /info session health endpoint, and uses a heartbeat to catch silent session death.

What You'll Set Up

• HTTP monitor for the Xpra HTML5 web client (port 14500)
• TCP probe for the Xpra multi-protocol server (port 14500)
• Session health check via the /info endpoint
• SSL certificate alert for SSL Xpra deployments
• Heartbeat monitor for persistent session liveness

Prerequisites

• Xpra 4.0+ running with --html=on and the /info endpoint enabled
• At least one active Xpra session on the server
• A free Vigilmon account

Step 1: Monitor the Xpra HTML5 Web Client

Xpra's built-in HTTP server serves the HTML5 canvas client when started with --html=on. A 200 response confirms the Xpra server process is running and the web client assets are being served:

1. Log in to vigilmon.online and click Add Monitor.
2. Set Type to HTTP / HTTPS.
3. Enter: http://your-server-ip:14500/
4. Set Check interval to 1 minute.
5. Set Expected HTTP status to 200.
6. Under Keyword match, enter xpra to confirm the Xpra web client content is present.
7. Click Save.

Start Xpra with HTML support:

xpra start :10 \
  --bind-tcp=0.0.0.0:14500 \
  --html=on \
  --daemon=yes \
  --start=xterm

Test the web client endpoint:

curl -s http://localhost:14500/ | grep -i "xpra"
# Should return HTML containing "xpra"

A failed HTTP check means the Xpra process has died or the TCP binding failed. No users can reach any forwarded applications.

Step 2: TCP Probe for the Multi-Protocol Transport

Xpra's server is unusual — it listens on a single port and auto-detects the protocol (HTTP, WebSocket, SSL, or raw Xpra protocol) based on the connection handshake. A TCP probe on port 14500 confirms the transport layer is listening, which is a prerequisite for any client connection:

1. Click Add Monitor → TCP Port.
2. Enter your server IP/hostname and port 14500.
3. Set Check interval to 1 minute.
4. Click Save.

This TCP check is faster than the HTTP check and catches cases where the Xpra process has started but is not accepting new connections due to resource exhaustion or binding errors.

For SSL deployments, Xpra can be started with --ssl-cert and --ssl-key:

xpra start :10 \
  --bind-ssl=0.0.0.0:14500 \
  --ssl-cert=/etc/xpra/ssl-cert.pem \
  --ssl-key=/etc/xpra/ssl-key.pem \
  --html=on \
  --daemon=yes \
  --start=xterm

The TCP probe works identically for SSL — it confirms the port is open regardless of the protocol.

Step 3: Monitor the Xpra Session Health Endpoint

Xpra exposes a /info path that returns JSON with active session information — connection count, display name, server version, and session state. This is the most valuable health signal because it confirms an active Xpra display is running, not just that the HTTP server is listening:

1. Click Add Monitor → HTTP / HTTPS.
2. Enter: http://your-server-ip:14500/info
3. Set Check interval to 2 minutes.
4. Set Expected HTTP status to 200.
5. Under Response body contains, enter display (the JSON response includes the Xpra display name like :10).
6. Click Save.

Check it manually:

curl -s http://localhost:14500/info | python3 -m json.tool | head -20
# Returns JSON with version, display, connections, etc.

A 404 or empty response on /info while the HTTP server is still responding means Xpra is running but has no active display session — all forwarded applications have died. A 200 with display in the response confirms the session is alive.

Step 4: SSL Certificate Alert for SSL Xpra Deployments

If Xpra is exposed with SSL (either natively or via an nginx/Caddy reverse proxy), monitor the certificate to catch renewal failures before they lock out users:

Native SSL with Xpra:

xpra start :10 \
  --bind-ssl=0.0.0.0:14500 \
  --ssl-cert=/etc/letsencrypt/live/xpra.yourdomain.com/fullchain.pem \
  --ssl-key=/etc/letsencrypt/live/xpra.yourdomain.com/privkey.pem \
  --html=on

nginx reverse proxy:

server {
    listen 443 ssl;
    server_name xpra.yourdomain.com;

    ssl_certificate /etc/letsencrypt/live/xpra.yourdomain.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/xpra.yourdomain.com/privkey.pem;

    location / {
        proxy_pass http://localhost:14500;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
    }
}

Add an SSL monitor:

1. Open the HTTPS monitor for https://xpra.yourdomain.com/.
2. Enable Monitor SSL certificate.
3. Set Alert when certificate expires in less than 21 days.
4. Click Save.

Step 5: Heartbeat Monitor for Persistent Session Health

Xpra sessions are designed to persist — but the X display or Wayland compositor they depend on can die silently. A systemd unit for Xpra will restart the server process, but it may fail to reattach to the display. The /info endpoint check (Step 3) catches this if checked frequently, but a heartbeat gives you a separate confirmation signal from within the session itself.

Set up a heartbeat that pings Vigilmon only when the Xpra session's display is confirmed alive:

1. In Vigilmon, click Add Monitor → Cron Heartbeat.
2. Set the expected ping interval to 5 minutes.
3. Copy the heartbeat URL (e.g. https://vigilmon.online/heartbeat/abc123).
4. Create a script at /usr/local/bin/xpra-session-check.sh:

#!/bin/bash
HEARTBEAT_URL="https://vigilmon.online/heartbeat/abc123"
XPRA_INFO_URL="http://localhost:14500/info"

# Check /info for a live display session
response=$(curl -s --max-time 5 "$XPRA_INFO_URL")

if echo "$response" | python3 -c "import sys,json; d=json.load(sys.stdin); assert 'display' in d" 2>/dev/null; then
  curl -s "$HEARTBEAT_URL" > /dev/null
fi

5. Make it executable and schedule it:

chmod +x /usr/local/bin/xpra-session-check.sh
echo "*/5 * * * * /usr/local/bin/xpra-session-check.sh" | crontab -

For Xpra sessions managed by systemd, add a watchdog alongside:

[Unit]
Description=Xpra Remote Desktop Session
After=network.target

[Service]
ExecStart=/usr/bin/xpra start :10 --bind-tcp=0.0.0.0:14500 --html=on --start=xterm
Restart=always
RestartSec=10

[Install]
WantedBy=multi-user.target

The heartbeat script checks /info — if the JSON contains a display key, the session is live and Vigilmon gets pinged. If the display dies and Xpra's HTTP server is still running (responding 200 but with an empty session), the heartbeat stops and Vigilmon alerts after 5 minutes of silence.

Step 6: Configure Alert Channels

1. Go to Alert Channels in Vigilmon and add Slack, email, or a webhook.
2. Set Consecutive failures before alert to 2 on the HTTP and TCP monitors — Xpra restarts quickly if systemd is managing it.
3. Set consecutive failures to 1 on the /info session health monitor and the heartbeat — a dead display session means all forwarded applications are gone and the session cannot recover without a restart.

For servers running multiple Xpra sessions on different ports or displays, add a /info monitor for each:

http://server:14500/info   → display :10
http://server:14501/info   → display :11

Summary

| Monitor | Target | What It Catches | |---|---|---| | HTTP check | http://host:14500/ | Xpra process down, web client unavailable | | TCP probe | Port 14500 | Transport layer not listening | | Session health | /info endpoint | Display died, active session lost | | SSL certificate | SSL/proxy domain | Certificate expiry | | Cron heartbeat | /info display check | Silent session death, display crash |

Xpra's persistence promise — that your graphical applications survive disconnects — is only as good as the display session underneath. With Vigilmon watching the web client availability, the TCP transport, and the /info session health endpoint independently, you catch display failures that the Xpra process itself survives, allowing automatic systemd restarts before users notice their persistent sessions have gone dark.