Monitoring ejabberd with Vigilmon

ejabberd is the battle-tested XMPP server behind some of the largest messaging systems ever built — WhatsApp ran on it for years, and it still powers real-time communication for millions of users worldwide. Erlang's fault tolerance makes ejabberd remarkably resilient, but that resilience doesn't include external uptime monitoring, SSL certificate management, or alerting when the server silently fails to accept new connections. Vigilmon provides the external watchdog layer that complements ejabberd's built-in reliability.

What You'll Set Up

• HTTP uptime monitor for the ejabberd admin web console (port 5280)
• TCP port monitor for the XMPP client port (5222)
• REST API health check via /api/status
• SSL/TLS certificate expiry alerts for XMPP TLS
• Heartbeat monitoring for ejabberd service availability

Prerequisites

• ejabberd 23.x or later installed and running
• Admin web console enabled at http://yourhost:5280/admin
• REST API module (mod_http_api) enabled in ejabberd.yml
• A free Vigilmon account

Step 1: Monitor the ejabberd Admin Web Console

The ejabberd admin console at port 5280 provides a web interface for user management, statistics, and configuration. Monitoring it confirms ejabberd's HTTP layer is running.

1. Log in to vigilmon.online and click Add Monitor.
2. Set Type to HTTP / HTTPS.
3. Enter the URL: http://yourhost:5280/admin
4. Set Check interval to 1 minute.
5. Set Expected HTTP status to 200.
6. Click Save.

If you've restricted the admin console to specific IP ranges, use a Vigilmon IP allowlist to whitelist Vigilmon's probe IPs, or configure ejabberd's acl rules to permit the probe:

# ejabberd.yml
acl:
  monitoring_probe:
    ip: "203.0.113.0/24"  # Replace with Vigilmon probe IP ranges

access_rules:
  configure:
    - allow: admin
    - allow: monitoring_probe

Step 2: Monitor the XMPP Client Port (TCP 5222)

The XMPP client port on 5222 is the primary connection point for all XMPP clients. A TCP monitor confirms the port is accepting connections even when HTTP monitoring can't detect a closed socket.

1. Click Add Monitor → TCP Port.
2. Enter your server hostname or IP.
3. Set Port to 5222.
4. Set Check interval to 1 minute.
5. Click Save.

Also add a monitor for port 5223 if you've enabled XMPP over legacy SSL (deprecated but still common in some setups), and port 5269 for server-to-server federation if you're running a federated deployment.

Step 3: Monitor the REST API Health Endpoint

ejabberd's mod_http_api module exposes a REST API for programmatic administration. The /api/status endpoint returns ejabberd's current status and is the most reliable programmatic health check.

First, ensure mod_http_api is enabled in ejabberd.yml:

modules:
  mod_http_api: {}

listen:
  -
    port: 5280
    module: ejabberd_http
    request_handlers:
      /api: mod_http_api

Reload ejabberd:

ejabberdctl reload_config

Now add the Vigilmon monitor:

1. Click Add Monitor → HTTP / HTTPS.
2. Enter the URL: http://yourhost:5280/api/status
3. Set Expected HTTP status to 200.
4. Set Expected response body to contain "status":"success".
5. Set Check interval to 5 minutes.
6. Click Save.

A healthy response looks like:

{"status": "success", "result": "The node ejabberd@localhost is started with status: started\nejabberd 23.10 is running in that node\n"}

Step 4: Monitor Online Users via the API

For production deployments, a drop in online user count to zero can indicate a clustering or listener failure even when the API responds. Add a monitor that checks the connected users endpoint:

1. Click Add Monitor → HTTP / HTTPS.
2. Enter the URL: http://yourhost:5280/api/connected_users_number
3. Add a request header X-Admin: true if your API requires admin authentication.
4. Set Expected HTTP status to 200.
5. Set Check interval to 5 minutes.
6. Click Save.

This complements the basic status check with a functional health indicator for live systems.

Step 5: SSL/TLS Certificate Alerts for XMPP TLS

XMPP clients connect using STARTTLS on port 5222, and ejabberd also supports direct TLS on 5223. Certificate expiry causes immediate client connection failures — XMPP clients are strict about TLS validation.

For HTTPS admin console monitoring:

1. Open the HTTP / HTTPS monitor created in Step 1 (use https://yourhost:5280/admin if TLS is enabled).
2. Enable Monitor SSL certificate under the SSL section.
3. Set Alert when certificate expires in less than 21 days.
4. Click Save.

For XMPP TLS certificates (port 5222/5223), add a dedicated TCP+SSL monitor:

1. Click Add Monitor → TCP Port.
2. Enter your server hostname.
3. Set Port to 5222 (or 5223).
4. Enable Monitor SSL/TLS certificate.
5. Set Alert when certificate expires in less than 21 days.
6. Click Save.

ejabberd reads certificates from the paths defined in certfiles in ejabberd.yml. Use Certbot or ACME.sh for automated renewal, and set a 21-day alert window to give yourself time to investigate renewal failures.

Step 6: Heartbeat Monitoring for ejabberd Service Availability

ejabberd's Erlang supervision tree restarts crashed processes automatically, but it can't restart itself if the VM crashes or the OS service stops. A Vigilmon heartbeat confirms ejabberd is continuously healthy.

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 cron job on your ejabberd server:

# /etc/cron.d/ejabberd-heartbeat
*/5 * * * * root ejabberdctl status > /dev/null 2>&1 && curl -s https://vigilmon.online/heartbeat/abc123

This pings Vigilmon only if ejabberdctl status exits cleanly. If ejabberd is stopped, crashed, or the RPC connection to the Erlang node is broken, the curl never runs and Vigilmon alerts after 5 minutes.

For systemd-managed installs, you can also use a systemd service override with a heartbeat:

# /etc/systemd/system/ejabberd.service.d/heartbeat.conf
[Service]
ExecStartPost=/bin/bash -c 'sleep 30 && curl -s https://vigilmon.online/heartbeat/abc123'

Step 7: Configure Alert Channels

1. Go to Alert Channels in Vigilmon and add email, Slack, or a PagerDuty webhook.
2. Set Consecutive failures before alert to 2 on the TCP monitor — ejabberd may briefly drop connections during hot code reloads.
3. Use Maintenance windows during ejabberd upgrades:

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

Summary

| Monitor | Target | What It Catches | |---|---|---| | Admin console | http://yourhost:5280/admin | HTTP layer down, ejabberd stopped | | TCP port | :5222 | XMPP listener closed, firewall change | | REST API status | /api/status | ejabberd node unhealthy, RPC broken | | SSL certificate | Port 5222/5280 TLS | Certificate expiry, renewal failure | | Cron heartbeat | Heartbeat URL | Erlang VM crash, OS service stop |

ejabberd's Erlang heritage gives it extraordinary fault tolerance within the process, but external monitoring is the only way to detect failures you can't self-report. With Vigilmon watching the admin console, XMPP port, REST API, TLS certificates, and service heartbeat, you have the complete external observability layer your messaging infrastructure needs.