tutorial

Monitoring DefGuard with Vigilmon

DefGuard is enterprise WireGuard VPN management — but tunnel health, PostgreSQL connectivity, LDAP/OIDC auth, and per-site gateway status all need watching. Here's how to monitor every layer with Vigilmon.

DefGuard is an open source enterprise WireGuard VPN and network management platform with multi-site support, user provisioning via LDAP/OIDC, and real-time activity monitoring. It runs a Rust API backend on port 8000 with a React frontend, and coordinates WireGuard kernel modules across multiple network locations. When a tunnel goes down or the enrollment service becomes unreachable, new devices can't connect and existing sessions eventually drop — often without any obvious alert. Vigilmon gives you proactive monitoring across the full DefGuard stack: API health, per-site tunnel status, database connectivity, authentication services, and email delivery.

What You'll Set Up

  • Web server and API availability monitoring
  • WireGuard interface and gateway connectivity per site
  • VPN tunnel establishment health (peer handshake freshness)
  • PostgreSQL database connectivity
  • Authentication service health (LDAP/OIDC)
  • Enrollment service endpoint monitoring
  • Network gateway process health per location
  • Session token service availability
  • SMTP/email notification delivery
  • Admin API endpoint response time tracking

Prerequisites

  • DefGuard running and accessible at https://your-defguard-host:8000 (or behind a reverse proxy on port 443)
  • At least one WireGuard location/site configured
  • PostgreSQL running (local or remote)
  • LDAP/OIDC configured (optional)
  • SMTP configured for email notifications (optional)
  • A free Vigilmon account

Step 1: Monitor Web Server and API Availability

DefGuard serves both its React frontend and REST API from a single process. Add a basic uptime monitor:

  1. Log in to vigilmon.online and click Add Monitor.
  2. Set Type to HTTP / HTTPS.
  3. Enter your DefGuard URL: https://defguard.yourdomain.com (or http://your-host:8000 if not behind a proxy).
  4. Set Check interval to 1 minute.
  5. Set Expected HTTP status to 200.
  6. Enable Monitor SSL certificate if using HTTPS.
  7. Set Alert when certificate expires in less than 21 days.
  8. Click Save.

Add a second monitor targeting the API health endpoint directly:

  1. Click Add Monitor → HTTP / HTTPS.
  2. Enter: https://defguard.yourdomain.com/api/v1/health (or your DefGuard API health endpoint — check the DefGuard API docs for the current path).
  3. Set Expected HTTP status to 200.
  4. Set Keyword must be present to ok or healthy.
  5. Set Check interval to 1 minute.
  6. Click Save.

Step 2: Monitor WireGuard Interface and Gateway Connectivity

DefGuard manages WireGuard interfaces on gateway hosts across multiple locations. A gateway process crash or WireGuard interface failure silently takes down an entire VPN site. Use TCP port monitoring on the WireGuard UDP port for each location's gateway, combined with a heartbeat script on the gateway host itself.

TCP monitor for the WireGuard gateway port:

  1. Click Add Monitor → TCP Port.
  2. Enter the gateway host IP and WireGuard port (default: 51820).
  3. Set Check interval to 2 minutes.
  4. Click Save.

Repeat for each location's gateway. Label monitors by site name (e.g., NYC Gateway — WireGuard).

Gateway process heartbeat:

On each gateway host, create a health check script:

#!/bin/bash
# /opt/scripts/check-defguard-gateway.sh
INTERFACE="wg0"   # Your WireGuard interface name
HEARTBEAT_URL="https://vigilmon.online/heartbeat/your-token"

# Check WireGuard interface is up
if ip link show "$INTERFACE" up > /dev/null 2>&1; then
    # Check DefGuard gateway process is running
    if pgrep -x "defguard-gateway" > /dev/null 2>&1; then
        curl -s "$HEARTBEAT_URL" > /dev/null
    fi
fi

Add to cron every 5 minutes:

*/5 * * * * /bin/bash /opt/scripts/check-defguard-gateway.sh

Create a Cron Heartbeat monitor in Vigilmon with an expected interval of 10 minutes.

Step 3: Monitor VPN Tunnel Health — Peer Handshake Freshness

A WireGuard tunnel is only healthy if peers are actively exchanging handshakes. A stale handshake (no activity for more than 3 minutes) means the tunnel is effectively down even if the interface is up. Monitor handshake freshness on each gateway:

#!/bin/bash
# /opt/scripts/check-wireguard-handshakes.sh
INTERFACE="wg0"
HEARTBEAT_URL="https://vigilmon.online/heartbeat/your-token"
MAX_STALE_SECONDS=300  # 5 minutes — alert if any peer hasn't handshaked

STALE=0
NOW=$(date +%s)

while IFS= read -r line; do
    if [[ "$line" =~ ^[0-9a-f]{64} ]]; then
        # Extract last handshake timestamp from wg show output
        HANDSHAKE=$(wg show "$INTERFACE" latest-handshakes | grep "^${line}" | awk '{print $2}')
        if [ -n "$HANDSHAKE" ] && [ "$HANDSHAKE" != "0" ]; then
            AGE=$((NOW - HANDSHAKE))
            if [ "$AGE" -gt "$MAX_STALE_SECONDS" ]; then
                STALE=$((STALE + 1))
            fi
        fi
    fi
done < <(wg show "$INTERFACE" peers)

if [ "$STALE" -eq 0 ]; then
    curl -s "$HEARTBEAT_URL" > /dev/null
fi

Note: A stale handshake on a mobile peer is normal (phones sleep). Focus this check on always-on site-to-site peers or dedicated gateway-to-gateway tunnels.

Create a Cron Heartbeat monitor with a 10 minute expected interval.

Step 4: Monitor PostgreSQL Database Connectivity

DefGuard stores user accounts, device configurations, WireGuard keys, and activity logs in PostgreSQL. A database failure means users can't log in, new enrollments fail, and the DefGuard API returns errors. Monitor PostgreSQL availability:

  1. Click Add Monitor → TCP Port.
  2. Enter your PostgreSQL host and port: Host: localhost, Port: 5432.
  3. Set Check interval to 1 minute.
  4. Click Save.

For a more thorough database health check, add a heartbeat script that runs a lightweight query:

#!/bin/bash
# /opt/scripts/check-postgres-defguard.sh
DB_HOST="localhost"
DB_PORT="5432"
DB_USER="defguard"
DB_NAME="defguard"
HEARTBEAT_URL="https://vigilmon.online/heartbeat/your-token"

RESULT=$(psql -h "$DB_HOST" -p "$DB_PORT" -U "$DB_USER" -d "$DB_NAME" \
  -c "SELECT 1" -t -A 2>/dev/null)

if [ "$RESULT" = "1" ]; then
    curl -s "$HEARTBEAT_URL" > /dev/null
fi

Run every 3 minutes via cron and set a 6 minute expected interval in Vigilmon.

Step 5: Monitor Authentication Service Health (LDAP/OIDC)

If DefGuard is configured with LDAP or an OIDC identity provider, authentication failures prevent all users from logging in — including admins. Monitor the authentication backend independently:

LDAP:

  1. Click Add Monitor → TCP Port.
  2. Enter your LDAP server host and port: Host: ldap.yourdomain.com, Port: 389 (or 636 for LDAPS).
  3. Set Check interval to 2 minutes.

OIDC provider:

  1. Click Add Monitor → HTTP / HTTPS.
  2. Enter the OIDC discovery endpoint: https://your-oidc-provider.com/.well-known/openid-configuration.
  3. Set Expected HTTP status to 200.
  4. Set Keyword must be present to issuer.
  5. Set Check interval to 2 minutes.

If your OIDC provider is self-hosted (e.g., Keycloak or Authentik), add it to Vigilmon's monitoring list as a separate service.

Step 6: Monitor the Enrollment Service Endpoint

DefGuard's enrollment service allows new users to register their devices and download WireGuard configurations. If the enrollment endpoint is down, users can't onboard. Monitor it directly:

  1. Click Add Monitor → HTTP / HTTPS.
  2. Enter the enrollment endpoint (check your DefGuard config for the enrollment URL — typically the same host with /api/v1/enrollment or a dedicated subdomain).
  3. Set Expected HTTP status to 200 or 404 (an authenticated endpoint may return 404 on unauthenticated GET, which still confirms the service is running).
  4. Set Check interval to 5 minutes.
  5. Click Save.

Step 7: Monitor Admin API Endpoint Response Times

DefGuard's admin API handles all management operations — user creation, policy changes, location management. Slow API responses degrade the admin experience and may indicate database query saturation or lock contention. Add response time monitoring:

  1. Open the API health monitor from Step 1.
  2. Enable Response time alert.
  3. Set Alert if response time exceeds 2000 ms.
  4. Click Save.

For a more representative admin API check, monitor the locations endpoint (returns quickly and requires authentication — test with a service account token):

# Add to your monitoring probe configuration
curl -s -o /dev/null -w "%{http_code} %{time_total}" \
  -H "Authorization: Bearer $DEFGUARD_TOKEN" \
  https://defguard.yourdomain.com/api/v1/location

If this consistently takes more than 1 second, investigate PostgreSQL query performance or connection pool exhaustion.

Step 8: Monitor SMTP/Email Notification Delivery

DefGuard sends email for user enrollment invites, MFA codes, and admin alerts. A broken SMTP configuration means enrollment emails never arrive — users can't complete device setup. Monitor SMTP availability:

  1. Click Add Monitor → TCP Port.
  2. Enter your SMTP server host and port: Host: smtp.yourdomain.com, Port: 587 (STARTTLS) or 465 (SMTPS).
  3. Set Check interval to 5 minutes.
  4. Click Save.

For a deeper test, use a heartbeat script that attempts an SMTP handshake:

#!/bin/bash
# /opt/scripts/check-smtp.sh
SMTP_HOST="smtp.yourdomain.com"
SMTP_PORT="587"
HEARTBEAT_URL="https://vigilmon.online/heartbeat/your-token"

if timeout 10 bash -c "echo QUIT | nc -w 5 $SMTP_HOST $SMTP_PORT" | grep -q "220"; then
    curl -s "$HEARTBEAT_URL" > /dev/null
fi

Step 9: Configure Alert Channels

  1. Go to Alert Channels in Vigilmon and add Slack, email, PagerDuty, or a webhook.
  2. For the core API monitor (Step 1), set Consecutive failures before alert to 2 — the Rust process occasionally restarts briefly.
  3. For WireGuard gateway monitors (Step 2), set Consecutive failures before alert to 1 — a down gateway affects all VPN users at that site immediately.
  4. For PostgreSQL (Step 4), set Consecutive failures before alert to 1 — a database failure cascades to all DefGuard functionality.
  5. For SMTP (Step 8), set Consecutive failures before alert to 3 — brief SMTP connectivity issues are common and self-resolve.
  6. Group per-site WireGuard monitors into alert groups so a datacenter network outage generates one alert, not one per peer.

Conclusion

DefGuard's reliability depends on a chain of dependencies: the API process, WireGuard interfaces, PostgreSQL, authentication backends, and SMTP. Here's the full coverage summary:

| Layer | Monitor | |---|---| | Web server & API | HTTP uptime on DefGuard host + API health endpoint | | TLS certificate | SSL expiry alert (21-day window) | | WireGuard gateway | TCP Port check on WireGuard UDP port + cron heartbeat | | Peer handshake | Cron heartbeat from handshake freshness script | | PostgreSQL | TCP Port check + cron heartbeat from query probe | | LDAP | TCP Port check on port 389/636 | | OIDC provider | HTTP monitor on /.well-known/openid-configuration | | Enrollment service | HTTP monitor on enrollment endpoint | | Admin API latency | Response time alert on API health endpoint | | SMTP | TCP Port check on port 587/465 |

With these monitors in place, you'll know within minutes when a VPN tunnel is down, a gateway has crashed, or the database is unreachable — giving you time to restore service before users lose VPN access.

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