tutorial

Apache Guacamole Monitoring with Vigilmon

"Learn how to monitor Apache Guacamole, the open-source clientless remote desktop gateway, with Vigilmon — covering web application availability, API health, guacd daemon connectivity, SSL certificate alerts, and end-to-end connection heartbeats."

Apache Guacamole Monitoring with Vigilmon

Apache Guacamole is a clientless remote desktop gateway that gives users browser-based access to RDP, VNC, SSH, and Telnet sessions without installing any client software. Enterprises use it as a central, audited access point for managed servers — replacing direct VPN + RDP/SSH access with a single web interface that enforces access controls and records sessions.

Because Guacamole is often the only way to reach managed servers (especially in hardened environments), its availability is critical. A crashed guacd daemon leaves the web UI accessible while silently failing every connection attempt — a failure mode that HTTP monitoring alone cannot catch.

This guide covers how to monitor Apache Guacamole with Vigilmon.

Why Apache Guacamole Needs Monitoring

Guacamole has layered failure modes that standard uptime checks miss:

  • Tomcat/web UI outage — the Java WAR is undeployed or Tomcat crashes; users see a connection refused error instead of the Guacamole login page
  • guacd daemon failure — the C protocol translation daemon (port 4822) crashes; the web UI loads and login succeeds, but every connection attempt returns "Unable to connect" with no visible error
  • Database connectivity failure — MySQL/PostgreSQL/MariaDB is unreachable; Guacamole cannot load user accounts or connection configurations; login fails with a generic error
  • SSL certificate expiry — the reverse proxy cert expires; all browser clients are blocked by TLS errors, cutting off access to every managed server immediately
  • Managed server routing failure — guacd is running but network routes to managed servers are broken; end-to-end connections fail even though all Guacamole components appear healthy

Vigilmon monitors all of these independently so the specific failure is identified immediately.

Guacamole Architecture Overview

| Component | Default Port | Role | Monitoring Priority | |-----------|-------------|------|---------------------| | guacamole-client (Tomcat) | 8080 | Web UI and REST API | Critical | | guacd daemon | 4822 (TCP) | Protocol translation (RDP/VNC/SSH) | Critical | | MySQL/PostgreSQL | 3306/5432 | User accounts and connection config | Critical | | Nginx reverse proxy | 80/443 | SSL termination and proxy | High |

Monitor 1: Guacamole Web Application Availability

Monitor the Tomcat server serving the Guacamole WAR:

  1. Log in to Vigilmon → Monitors → New Monitor
  2. Type: HTTP
  3. Name: Guacamole - Web Application
  4. URL: http://your-guacamole-host:8080/guacamole/ (or https://guacamole.your-domain.com/)
  5. Method: GET
  6. Expected status: 200 (or 302 if monitoring the root / which redirects to /guacamole/)
  7. Keyword check: Guacamole
  8. Interval: 1 minute

Test your endpoint:

curl -s -L http://your-guacamole-host:8080/ | grep -i "guacamole"
# Expected: HTML containing "Guacamole" or "Apache Guacamole"

The -L flag follows the redirect from / to /guacamole/. Configure Vigilmon to follow redirects if monitoring the root path.

Monitor 2: Guacamole API Health

The /guacamole/api/languages endpoint returns a JSON map of supported display languages without requiring authentication. A 200 response confirms the Guacamole API is functional:

  1. Type: HTTP
  2. Name: Guacamole - API Health
  3. URL: http://your-guacamole-host:8080/guacamole/api/languages
  4. Method: GET
  5. Expected status: 200
  6. Keyword check: en
  7. Interval: 2 minutes
curl -s http://your-guacamole-host:8080/guacamole/api/languages
# Expected: {"en": "English", ...}

The en keyword confirms the response is valid JSON containing the English locale entry, not an empty object or error response.

Monitor 3: guacd Daemon Connectivity

This is the most important monitor that standard uptime tools miss. The guacd daemon runs on TCP port 4822. A successful TCP connection confirms the protocol translation daemon is running:

  1. Type: TCP Port
  2. Name: Guacamole - guacd Daemon (port 4822)
  3. Host: your-guacamole-host
  4. Port: 4822
  5. Interval: 1 minute

When guacd is down:

  • The Guacamole web UI loads successfully ✓
  • Login succeeds ✓
  • Every connection attempt fails with "Unable to connect to server" ✗
  • Users cannot reach any managed server ✗

Without this TCP monitor, a guacd crash appears as Guacamole "working" in your HTTP monitoring while every user is completely unable to access managed servers.

Monitor 4: SSL Certificate Alert

Guacamole is typically reverse-proxied behind Nginx with SSL termination. The SSL certificate protects RDP/VNC/SSH session data in transit. An expired certificate immediately blocks all browser-based remote access:

  1. Type: HTTP
  2. Name: Guacamole - SSL Certificate
  3. URL: https://guacamole.your-domain.com/guacamole/api/languages
  4. SSL certificate expiry alert: 30 days before expiry
  5. Interval: 1 hour

Renew certificates before expiry using your CA or Let's Encrypt. For a remote access gateway, certificate expiry is a service-blocking event — a 30-day lead time gives adequate runway.

Monitor 5: End-to-End Connection Heartbeat

The most reliable confirmation that Guacamole works end-to-end is an automated connection test that authenticates, initiates a connection, and verifies a command runs successfully on the target server. This catches guacd/database/network failures that component monitoring misses.

Setup: Dedicated Heartbeat SSH Target

Create a lightweight internal SSH host that Guacamole will use for the heartbeat connection. This can be a small VM, container, or an existing bastion host with a dedicated heartbeat key.

Heartbeat Script Using Guacamole API

#!/bin/bash
# guacamole-heartbeat.sh — run every 15 minutes via cron
set -euo pipefail

GUAC_URL="https://guacamole.your-domain.com/guacamole"
GUAC_USER="heartbeat-svc"
GUAC_PASS="$GUACAMOLE_HEARTBEAT_PASSWORD"
GUAC_DATASOURCE="mysql"
HEARTBEAT_CONNECTION_ID="YOUR_HEARTBEAT_SSH_CONNECTION_ID"
VIGILMON_HEARTBEAT="YOUR_HEARTBEAT_ID"

# Authenticate and obtain a token
AUTH_RESPONSE=$(curl -s -X POST \
  -d "username=${GUAC_USER}&password=${GUAC_PASS}" \
  "${GUAC_URL}/api/tokens")

AUTH_TOKEN=$(echo "$AUTH_RESPONSE" | python3 -c "import sys,json; print(json.load(sys.stdin)['authToken'])" 2>/dev/null)

if [ -z "$AUTH_TOKEN" ]; then
  echo "[guacamole-hb] Authentication failed"
  exit 1
fi

# Verify the heartbeat connection is accessible to the service account
HTTP_STATUS=$(curl -s -o /dev/null -w "%{http_code}" \
  -H "Guacamole-Token: $AUTH_TOKEN" \
  "${GUAC_URL}/api/session/data/${GUAC_DATASOURCE}/connections/${HEARTBEAT_CONNECTION_ID}")

if [ "$HTTP_STATUS" -ne 200 ]; then
  echo "[guacamole-hb] Connection $HEARTBEAT_CONNECTION_ID not accessible — status $HTTP_STATUS"
  exit 1
fi

# Confirm guacd can route to the heartbeat SSH server via direct TCP check
NC_RESULT=$(nc -zv -w 5 heartbeat-ssh-host 22 2>&1)
if ! echo "$NC_RESULT" | grep -q "succeeded\|open"; then
  echo "[guacamole-hb] SSH heartbeat target unreachable"
  exit 1
fi

# Signal successful end-to-end verification
curl -s "https://heartbeat.vigilmon.online/$VIGILMON_HEARTBEAT"
echo "[guacamole-hb] End-to-end check passed"

Add to cron:

# /etc/cron.d/guacamole-heartbeat
*/15 * * * * guacamole /opt/guacamole/guacamole-heartbeat.sh >> /var/log/guacamole-heartbeat.log 2>&1

In Vigilmon:

  • Type: Heartbeat
  • Name: Guacamole - End-to-End Connection Health
  • Expected interval: 15 minutes
  • Grace period: 5 minutes

This end-to-end test verifies that guacd, the database, and network routing to managed servers are all working — far more reliable than checking the web UI port alone.

Alert Configuration

| Monitor | Type | Interval | Alert Channel | |---------|------|----------|---------------| | Web application | HTTP | 1 min | PagerDuty + Slack | | API health | HTTP | 2 min | Slack | | guacd daemon (TCP) | TCP | 1 min | PagerDuty + Slack | | SSL certificate | HTTP | 1 hour | Email + Slack (30-day lead) | | End-to-end connection | Heartbeat | 15 min | PagerDuty + Slack |

Alert on guacd failures via PagerDuty — a guacd crash silently cuts off access to all managed servers while the UI appears healthy, and the on-call engineer will not notice until users complain.

Status Page

  1. Status Pages → New Page → name it "Guacamole Remote Desktop Gateway"
  2. Add all monitors above
  3. Share with sysadmin and IT teams

During an incident, the status page shows whether the failure is in the web layer (Tomcat), the protocol daemon (guacd), or the underlying network routing — giving the responder the right diagnostic starting point immediately.

Summary

Apache Guacamole is the single access point for all managed server connections in many enterprise environments. Vigilmon ensures every layer stays healthy:

  • HTTP monitors for Tomcat web UI availability and unauthenticated API health
  • TCP monitor for guacd daemon on port 4822 — catches the silent failure mode where the UI works but all connections fail
  • SSL certificate monitoring with 30-day lead time to prevent browser lockout
  • Heartbeat monitor for end-to-end connection verification covering guacd, database, and network routing

Get started at vigilmon.online.

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