Monitoring UnrealIRCd with Vigilmon

UnrealIRCd is the backbone of many self-hosted IRC networks — when it goes down, every user on every channel loses connectivity instantly. Vigilmon lets you monitor the daemon process, client-facing ports, WebSocket endpoint, TLS certificate health, and server-to-server links so you know before your users do.

What You'll Set Up

• TCP port monitor for plain IRC client port (6667)
• TCP port monitor for TLS IRC client port (6697)
• TCP port monitor for WebSocket endpoint (8080)
• TLS certificate expiry alert for the IRC TLS port
• TLS certificate expiry alert for the WebSocket TLS endpoint
• HTTP health check for remote include URL
• Cron heartbeat for the UnrealIRCd daemon process
• Uptime monitor for external DNSBL service latency

Prerequisites

• UnrealIRCd running and accessible (native or Docker)
• A free Vigilmon account

Step 1: Monitor the Plain IRC Client Port

The core IRC client connection port (6667 plain-text) must be reachable for clients that do not use TLS. Vigilmon can probe this with a TCP check:

1. Log in to vigilmon.online and click Add Monitor.
2. Set Type to TCP Port.
3. Enter your server's IP or hostname and set Port to 6667.
4. Set Check interval to 1 minute.
5. Click Save.

If UnrealIRCd's listener on 6667 fails — due to a crash, firewall rule change, or config error — this monitor will alert immediately.

Step 2: Monitor the TLS IRC Client Port

IRC clients using SASL authentication or enforced TLS connect on port 6697. A failed TLS port means these clients cannot connect at all:

1. Click Add Monitor → TCP Port.
2. Enter your server hostname and set Port to 6697.
3. Set Check interval to 1 minute.
4. Enable Check SSL/TLS so Vigilmon validates the TLS handshake, not just TCP connectivity.
5. Click Save.

Step 3: TLS Certificate Expiry for the IRC Port

UnrealIRCd uses its own TLS certificate for the IRC server — separate from any web server certificate. If this certificate expires, TLS IRC clients are immediately rejected:

1. Open the TLS IRC port monitor created in Step 2.
2. Enable Monitor SSL certificate.
3. Set Alert when certificate expires in less than 21 days.
4. Click Save.

Check your certificate renewal automation. If you use Let's Encrypt:

# Verify UnrealIRCd is configured to reload after renewal
cat /etc/letsencrypt/renewal-hooks/deploy/unrealircd.sh

A typical hook:

#!/bin/bash
cp /etc/letsencrypt/live/irc.yourdomain.com/fullchain.pem /etc/unrealircd/tls/server.cert.pem
cp /etc/letsencrypt/live/irc.yourdomain.com/privkey.pem   /etc/unrealircd/tls/server.key.pem
/usr/bin/unrealircd rehash

Step 4: Monitor the WebSocket Port

Web IRC clients like KiwiIRC and The Lounge connect to UnrealIRCd over WebSocket (typically port 8080, or 443 if behind a reverse proxy). If this port is unreachable, all browser-based IRC clients lose connectivity:

1. Click Add Monitor.
2. Set Type to HTTP / HTTPS (WebSocket upgrades start as HTTP).
3. Enter http://irc.yourdomain.com:8080 (or your WebSocket URL).
4. Set Expected HTTP status to 101 if Vigilmon supports it, or 200 to validate the endpoint is serving responses.
5. Set Check interval to 2 minutes.
6. Click Save.

If the WebSocket endpoint uses TLS (wss://), enable Monitor SSL certificate and set expiry alerting the same way as Step 3.

Step 5: Monitor the IRCd Process with a Heartbeat

A heartbeat lets Vigilmon detect silent UnrealIRCd crashes that don't affect port availability (e.g., the daemon forks a child that exits while the port is still briefly open):

1. In Vigilmon, click Add Monitor → Cron Job / Heartbeat.
2. Set Expected interval to 2 minutes.
3. Copy the heartbeat URL (e.g., https://vigilmon.online/ping/your-heartbeat-id).

Add a cron job on the IRC server:

# /etc/cron.d/unrealircd-heartbeat
*/2 * * * * root pgrep -x unrealircd > /dev/null && curl -fsS --retry 3 https://vigilmon.online/ping/your-heartbeat-id

This only pings if UnrealIRCd is running — a missed ping means the daemon is dead.

Alternatively, use a systemd service with OnFailure= to trigger an alert script that POSTs to the heartbeat URL.

Step 6: Monitor Services Uplink Connectivity

If you run IRC services (Anope, Atheme) linked to UnrealIRCd via a server-to-server protocol, the services uplink is critical — without it, NickServ and ChanServ are offline. The services daemon listens on a server port; you can probe it with a TCP check:

1. Click Add Monitor → TCP Port.
2. Enter localhost (or the services server IP) and set the port to the services link port (commonly 7029 for Anope or Atheme's link listener — check your services config).
3. Set Check interval to 2 minutes.
4. Click Save.

This validates that the link listener is accepting connections. For deeper validation, add a custom health script that checks UnrealIRCd's /STATS l output for the services server link:

#!/bin/bash
# services-health.sh — post to Vigilmon heartbeat if services server is linked
SERVICES_NICK="services.yourdomain.com"
LINKED=$(echo "LINKS" | nc -q1 localhost 6667 2>/dev/null | grep -c "$SERVICES_NICK")
[ "$LINKED" -gt 0 ] && curl -fsS https://vigilmon.online/ping/your-services-heartbeat-id

Step 7: Monitor DNSBL / Denylist Latency

UnrealIRCd performs DNSBL lookups on connecting clients to block known bot ranges. Slow DNSBL responses cause connection timeouts for legitimate users. Monitor the DNSBL service availability with an HTTP check:

1. Click Add Monitor → HTTP / HTTPS.
2. Use the DNSBL provider's status page URL (most major lists publish one, e.g., https://www.spamhaus.org/status/).
3. Set Expected HTTP status to 200.
4. Set Check interval to 5 minutes.
5. Click Save.

If you self-host DNSBL resolution (e.g., via a local DNS server), add a TCP check on port 53 of that server.

Step 8: Monitor Remote Include URLs

If UnrealIRCd loads remote configuration files via include "https://...", those URLs must be reachable during a /REHASH. An unreachable include blocks config reloads silently:

1. For each remote include URL in your unrealircd.conf, add a Vigilmon HTTP / HTTPS monitor.
2. Set Expected HTTP status to 200.
3. Set Check interval to 10 minutes.
4. Click Save.

This ensures your remote config host is always reachable before you trigger a rehash.

Step 9: Configure Alerts

1. Go to Settings → Alerts in Vigilmon.
2. Add a Slack webhook, email, or PagerDuty integration.
3. Set the failure threshold — 2 consecutive failures reduces false positives from transient network hiccups.
4. Apply the alert profile to all UnrealIRCd monitors.

Recommended alert priority:

| Monitor | Priority | Threshold | |---|---|---| | Plain IRC port 6667 | Critical | 1 failure | | TLS IRC port 6697 | Critical | 1 failure | | WebSocket port | High | 1 failure | | IRCd process heartbeat | Critical | 2 missed | | Services uplink | High | 2 failures | | TLS certificate expiry | Medium | < 21 days | | DNSBL service | Low | 3 failures | | Remote include URL | Low | 3 failures |

What to Watch

| Monitor | Type | Check | Alert threshold | |---|---|---|---| | Plain IRC port | TCP | Port 6667 open | 1 failure | | TLS IRC port | TCP+TLS | Port 6697 handshake | 1 failure | | WebSocket port | HTTP | Port 8080 responds | 1 failure | | IRCd heartbeat | Cron | Ping every 2 min | 2 missed | | Services uplink | TCP | Services link port | 2 failures | | IRC TLS cert | SSL | Expiry < 21 days | Immediate | | WS TLS cert | SSL | Expiry < 21 days | Immediate | | DNSBL service | HTTP | Status page 200 | 3 failures | | Remote includes | HTTP | Config URL 200 | 3 failures |

Conclusion

UnrealIRCd powers entire IRC networks — a single daemon failure takes all your channels offline simultaneously. With Vigilmon covering the IRC ports, WebSocket endpoint, TLS certificates, services uplink, and heartbeat, you have full-stack visibility without running any extra monitoring infrastructure. The free Vigilmon tier covers everything set up here.

Sign up for Vigilmon free →