tutorial

Monitoring Apache Guacamole with Vigilmon

Apache Guacamole gives your team browser-based VNC, RDP, and SSH access without a VPN — but a crashed guacd daemon or expired SSL cert silently locks everyone out. Here's how to monitor every layer with Vigilmon.

Apache Guacamole is a clientless remote desktop gateway that lets users connect to VNC, RDP, and SSH sessions through a standard web browser — no client software required. IT teams, MSPs, and cloud providers rely on it for secure, auditable remote access over a simple HTTPS connection. When Guacamole goes down — whether the Tomcat web app is unresponsive, the guacd proxy daemon has crashed, or a reverse-proxy SSL certificate has expired — every remote session is immediately unavailable. Vigilmon monitors every critical component so you know the moment something breaks.

What You'll Set Up

  • HTTP uptime monitor for the Guacamole web UI login page
  • REST API endpoint monitor for the JSON authentication endpoint
  • TCP port monitor for the guacd proxy daemon (port 4822)
  • SSL certificate expiry alerts for HTTPS-proxied deployments
  • Heartbeat monitor for the WebSocket tunnel endpoint

Prerequisites

  • Apache Guacamole deployed and accessible (typically port 8080 or proxied to 443)
  • guacd running and accessible on port 4822
  • A free Vigilmon account

Step 1: Monitor the Guacamole Web UI

The Guacamole web application runs inside Apache Tomcat and serves the login page at /guacamole/. Monitoring this path confirms Tomcat is up and Guacamole's web app is deployed.

  1. Log in to vigilmon.online and click Add Monitor.
  2. Set Type to HTTP / HTTPS.
  3. Enter the login page URL: http://guacamole.yourdomain.com:8080/guacamole/ (or https://guacamole.yourdomain.com/guacamole/ if proxied)
  4. Set Check interval to 1 minute.
  5. Set Expected HTTP status to 200.
  6. Click Save.

If Guacamole is behind a reverse proxy (nginx, Traefik, Apache httpd), use the public HTTPS URL instead of the direct Tomcat port:

https://guacamole.yourdomain.com/guacamole/

Step 2: Monitor the Authentication API Endpoint

Guacamole's REST API exposes an authentication endpoint that the web UI calls during login. Monitoring it confirms the backend authentication service — including database connectivity — is operational.

  1. Click Add Monitor → HTTP / HTTPS.
  2. Enter the auth endpoint URL: https://guacamole.yourdomain.com/guacamole/api/ext/json/login
  3. Set Check interval to 2 minutes.
  4. Set Request method to POST.
  5. Set Expected HTTP status to 403 (unauthenticated probes return 403 — this is the expected response for a healthy server).
  6. Click Save.

A 403 response from /api/ext/json/login is the correct health signal: Guacamole is running and actively rejecting unauthenticated requests. A 502 or connection failure means Tomcat or the reverse proxy is down.

Step 3: Monitor the guacd Proxy Daemon (TCP Port 4822)

guacd is the native protocol proxy daemon that translates RDP, VNC, and SSH connections into the Guacamole protocol. It runs as a separate process from the web app and listens on TCP port 4822. If guacd crashes, all active and new remote desktop sessions fail — even if the Guacamole web UI looks healthy.

  1. Click Add Monitor → TCP Port.
  2. Enter your Guacamole hostname and set Port to 4822.
  3. Set Check interval to 1 minute.
  4. Click Save.

To verify guacd is listening:

# Check guacd status
systemctl status guacd

# Verify port is open
ss -tlnp | grep 4822
# Expected: LISTEN ... *:4822

# Or with netcat from a remote machine
nc -zv guacamole.yourdomain.com 4822

Note: port 4822 is often firewalled to localhost-only. If your Guacamole web app and guacd are on the same host, install Vigilmon's monitoring agent on that host, or configure a firewall rule that allows probes from Vigilmon's IP ranges.

Step 4: SSL Certificate Alerts

Guacamole is almost always deployed behind nginx or Traefik for HTTPS termination. If the certificate on that reverse proxy expires, users receive browser security warnings and cannot connect — even though Guacamole itself is perfectly healthy. Vigilmon detects this before your users do.

  1. Open the HTTP monitor you created in Step 1.
  2. Enable Monitor SSL certificate under the SSL section.
  3. Set Alert when certificate expires in less than 21 days.
  4. Click Save.

For nginx-proxied deployments using Let's Encrypt:

# Verify renewal is configured
certbot certificates

# Test renewal
certbot renew --dry-run

# Check renewal timer
systemctl status certbot.timer

For Traefik with automatic ACME certificates, check the Traefik dashboard or ACME storage file:

# Check stored certificates
cat /etc/traefik/acme.json | python3 -m json.tool | grep -A5 '"main"'

Step 5: Heartbeat Monitoring for WebSocket Tunnel Availability

Guacamole delivers remote desktop sessions over a WebSocket tunnel at /guacamole/websocket-tunnel. If the WebSocket path is broken — by a misconfigured proxy, an upstream upgrade failure, or a Tomcat connector issue — users see blank screens or immediate disconnections even when the login page loads fine.

Use Vigilmon's heartbeat to probe the WebSocket tunnel endpoint on a schedule:

  1. 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. Add a cron job on your Guacamole server to probe the tunnel endpoint and ping Vigilmon:
#!/bin/bash
# /usr/local/bin/guacamole-tunnel-heartbeat.sh
GUAC_HOST="https://guacamole.yourdomain.com"
HEARTBEAT_URL="https://vigilmon.online/heartbeat/abc123"

# WebSocket upgrade requests to /websocket-tunnel return 400 for HTTP probes
# (missing required Guacamole handshake params) — 400 means the endpoint exists
HTTP_CODE=$(curl -sf -o /dev/null -w "%{http_code}" \
  "$GUAC_HOST/guacamole/websocket-tunnel")

if [ "$HTTP_CODE" = "400" ] || [ "$HTTP_CODE" = "200" ]; then
  curl -sf "$HEARTBEAT_URL"
fi
  1. Schedule with cron:
crontab -e
# Add:
*/5 * * * * /usr/local/bin/guacamole-tunnel-heartbeat.sh

Make executable: chmod +x /usr/local/bin/guacamole-tunnel-heartbeat.sh

A 400 response from the WebSocket tunnel endpoint is the healthy signal — it means Guacamole received the request and rejected it because the required WebSocket handshake parameters were absent. A 502, 503, or connection error means the endpoint itself is broken.

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 web UI and API monitors — Tomcat restarts take 30–60 seconds.
  3. Keep Consecutive failures before alert at 1 on the guacd TCP monitor — a crashed guacd daemon breaks all active sessions immediately.

Summary

| Monitor | Target | What It Catches | |---|---|---| | HTTP / HTTPS | /guacamole/ | Tomcat down, web app crash | | HTTP / HTTPS | /api/ext/json/login | Backend auth service failure | | TCP Port | :4822 | guacd daemon crash | | SSL Certificate | Guacamole domain | Reverse proxy certificate expiry | | Cron Heartbeat | /websocket-tunnel probe | WebSocket path broken, proxy misconfiguration |

Guacamole eliminates the need for VPN clients and remote desktop software — but that simplicity creates a single point of failure. With Vigilmon watching the web UI, authentication API, guacd daemon, and WebSocket tunnel, you catch every failure layer before your users do.

Monitor your app with Vigilmon

Free plan — 5 monitors, no credit card required. Up and running in 60 seconds.

Start free →
← Back to all articles