Monitoring GLAuth with Vigilmon

GLAuth solves the "I need LDAP but not a full OpenLDAP installation" problem — a single Go binary, a TOML config file, and you have an LDAP server that Grafana, Nextcloud, GitLab, and Jenkins can authenticate against. But GLAuth's simplicity is also its failure mode: a config file typo after a restart, a port conflict, or a crashed Go process leaves every dependent application locked out with no self-recovery. Vigilmon watches GLAuth's LDAP port, health API, bind health, and LDAPS certificate so you catch GLAuth failures the moment they happen.

What You'll Set Up

• TCP probe for GLAuth LDAP availability (port 389)
• HTTP monitor for the GLAuth health API (port 5555)
• LDAP bind heartbeat confirming end-to-end directory health
• SSL certificate expiry alert for LDAPS (port 636) deployments

Prerequisites

• GLAuth 2.x running as a systemd service or Docker container
• LDAP port 389 (and optionally LDAPS 636) accessible from Vigilmon probes
• GLAuth health API enabled (port 5555 by default)
• A free Vigilmon account

Step 1: Monitor GLAuth LDAP Availability (Port 389)

A TCP probe to port 389 is the primary health check for any LDAP server. Applications that depend on GLAuth for authentication fail immediately the moment port 389 becomes unreachable.

1. Log in to vigilmon.online and click Add Monitor.
2. Set Type to TCP Port.
3. Set Host to your GLAuth server hostname or IP.
4. Set Port to 389.
5. Set Check interval to 1 minute.
6. Click Save.

GLAuth's default port is 389 unless overridden in the config:

# glauth.cfg
[ldap]
  enabled = true
  listen = "0.0.0.0:389"

If you've changed the port, use the configured port in Vigilmon. Alert on the first TCP failure — applications using GLAuth have zero tolerance for LDAP port unavailability.

Step 2: Monitor the GLAuth Health API (Port 5555)

GLAuth ships with a built-in HTTP health endpoint on port 5555. This endpoint returns JSON confirming the Go process is running and operational — a richer check than the bare TCP probe.

1. In Vigilmon, click Add Monitor → HTTP / HTTPS.
2. Set URL to http://your-glauth-host:5555/debug/health
3. Set Method to GET.
4. Set Expected HTTP status to 200.
5. Set Expected response body contains to "healthy":true.
6. Set Check interval to 1 minute.
7. Click Save.

Enable the health API in your GLAuth config:

# glauth.cfg
[api]
  enabled = true
  internals = true
  tls = false
  listen = "0.0.0.0:5555"

The health API response looks like:

{"healthy": true}

A 200 response with "healthy":true confirms the Go HTTP server is running and GLAuth considers itself operational. This catches cases where the LDAP port is bound but the internal state machine has failed.

Step 3: SSL Certificate Alert for LDAPS (Port 636)

If you've configured GLAuth with TLS for LDAPS, monitor the certificate to prevent authentication failures from unexpected expiry.

# glauth.cfg with LDAPS
[ldaps]
  enabled = true
  listen = "0.0.0.0:636"
  cert = "/etc/glauth/server.crt"
  key  = "/etc/glauth/server.key"

Add a certificate monitor in Vigilmon:

1. In Vigilmon, click Add Monitor → TCP Port for basic port 636 connectivity.
2. For certificate monitoring, add an HTTP / HTTPS monitor using any HTTPS URL that serves the same certificate, or use the SSL-specific monitor:
   • Enable Monitor SSL certificate.
   • Set Alert when certificate expires in less than 21 days.
3. Click Save.

Check the current certificate expiry directly:

openssl s_client -connect your-glauth-host:636 -showcerts < /dev/null 2>/dev/null \
  | openssl x509 -noout -enddate

Self-signed certificates for LDAPS don't auto-renew. A 21-day alert window is essential when certificates are manually provisioned.

Step 4: Heartbeat Monitoring for GLAuth LDAP Bind Health

The most important GLAuth health signal is whether authenticated LDAP binds succeed. A TCP port can be open while GLAuth has failed to parse its config file after a restart — binds will time out or return errors even though port 389 shows as open.

Set up a scheduled script that performs an authenticated LDAP search and fires a Vigilmon heartbeat on success:

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).

Create a monitoring script:

#!/bin/bash
# check-glauth-health.sh — run every 5 minutes via cron

GLAUTH_HOST="your-glauth-host"
BIND_DN="cn=monitoring,dc=example,dc=com"
BIND_PW="monitoring_password"
BASE_DN="dc=example,dc=com"
HEARTBEAT_URL="https://vigilmon.online/heartbeat/abc123"

# Authenticated LDAP search — confirms config is loaded and user DB is working
RESULT=$(ldapsearch -x \
  -H "ldap://${GLAUTH_HOST}:389" \
  -D "$BIND_DN" \
  -w "$BIND_PW" \
  -b "$BASE_DN" \
  "(cn=*)" cn 2>&1)

if echo "$RESULT" | grep -q "result: 0 Success"; then
  curl -s "$HEARTBEAT_URL"
  exit 0
fi

echo "GLAuth LDAP health check failed: $RESULT" >&2
exit 1

Define the monitoring account in your GLAuth config:

# glauth.cfg — add a monitoring user
[[users]]
  name = "monitoring"
  uidnumber = 9999
  primarygroup = 9999
  passsha256 = "HASHED_PASSWORD_HERE"

  [[users.capabilities]]
    action = "search"
    object = "*"

[[groups]]
  name = "monitoring-group"
  gidnumber = 9999

Generate the SHA-256 password hash:

echo -n "monitoring_password" | sha256sum | awk '{print $1}'

Add to cron:

*/5 * * * * /usr/local/bin/check-glauth-health.sh

The script performs a bind with the monitoring credentials and searches for any user ((cn=*)). A successful authenticated search returning result: 0 Success confirms:

• GLAuth process is running
• Config file parsed successfully
• User database is loaded and accessible
• LDAP bind credentials are working

If GLAuth is restarted with a config syntax error, the LDAP port may still be open briefly while GLAuth fails to initialize — this bind test catches that scenario where the port probe alone would not.

Step 5: Configure Alert Channels

1. Go to Alert Channels in Vigilmon and add Slack, email, or a webhook.
2. Set Consecutive failures before alert to 1 on the LDAP TCP monitor — any application LDAP outage needs immediate attention.
3. Set Consecutive failures before alert to 1 on the health API monitor — a {"healthy":false} response needs immediate investigation.
4. For the heartbeat monitor, missing a single 5-minute window is sufficient to alert.
5. Use Maintenance windows when updating the GLAuth config or binary:

curl -X POST https://vigilmon.online/api/maintenance \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{"monitor_id": "MONITOR_ID", "duration_minutes": 5}'

# Restart GLAuth after config change
sudo systemctl restart glauth

# Verify it came back up before maintenance window expires
ldapsearch -x -H ldap://localhost:389 -b "dc=example,dc=com" "(cn=*)"

Summary

| Monitor | Target | What It Catches | |---|---|---| | LDAP TCP | host:389 | GLAuth process down, port unreachable | | Health API | GET host:5555/debug/health | Go process failure, internal health state | | LDAPS TCP | host:636 | LDAPS port down | | SSL certificate | LDAPS cert | Certificate expiry, TLS failures | | LDAP bind heartbeat | Cron script → heartbeat URL | Config load failure, bind auth broken |

GLAuth's zero-dependency simplicity is exactly why it needs monitoring: there's no supervisor daemon, no automatic config reload validation, and no built-in alerting when the user database fails to load. With Vigilmon watching the LDAP port, health API, LDAPS certificate, and performing regular authenticated bind checks, you get defense-in-depth monitoring for every failure mode that GLAuth's lightweight design leaves unguarded.