Monitoring Haraka SMTP Server with Vigilmon

Haraka is a high-performance, plugin-driven SMTP server written in Node.js. Unlike traditional MTAs like Postfix or Exim, Haraka is built specifically for customization — every stage of email processing (connection, MAIL FROM, RCPT TO, DATA, queue) is handled by plugins that you write and configure. Email service providers, developers building transactional email infrastructure, and organizations with custom routing requirements use Haraka for its speed and flexibility. When Haraka goes down, email stops flowing. Vigilmon gives you real-time visibility into every layer of your Haraka deployment.

What You'll Set Up

• TCP port monitors for Haraka SMTP (25) and submission (587)
• HTTP status API monitor for Haraka process and queue metrics
• SSL certificate expiry alerts for Haraka STARTTLS/TLS
• Heartbeat monitoring for the full Haraka plugin pipeline

Prerequisites

• Haraka installed and running (via npm or from source)
• Haraka configured to listen on ports 25 and/or 587
• Haraka http plugin enabled (for the metrics API — optional but recommended)
• A free Vigilmon account

Step 1: Monitor Haraka SMTP Port 25

Port 25 is Haraka's primary SMTP listener — the port other mail servers use to deliver email to you. A TCP probe on port 25 confirms Haraka's Node.js process is running and accepting connections.

1. Log in to vigilmon.online and click Add Monitor.
2. Set Type to TCP Port.
3. Enter your mail server hostname: mail.yourdomain.com
4. Set Port to 25.
5. Set Check interval to 1 minute.
6. Click Save.

Haraka's connection phase runs your first plugins immediately on TCP accept. If the process has crashed or the Node.js event loop is stuck, this probe fails — giving you the fastest possible signal that inbound email delivery is broken.

Step 2: Monitor Haraka Submission Port 587

Port 587 is the authenticated submission port used by mail clients and applications to send outbound email through Haraka. Submission typically requires SASL authentication (via the auth plugin) and may run different plugin configurations from port 25.

1. Click Add Monitor in Vigilmon.
2. Set Type to TCP Port.
3. Enter mail.yourdomain.com.
4. Set Port to 587.
5. Set Check interval to 1 minute.
6. Click Save.

Port 25 and port 587 run as separate Haraka listeners. A misconfigured plugin can crash one listener without affecting the other — monitor both independently.

Step 3: Monitor the Haraka HTTP Metrics API

Haraka ships an optional http plugin that exposes a status and metrics endpoint over HTTP. When enabled, it provides a JSON response with process health, queue status, and plugin information — far more useful than a raw TCP probe.

Enable the HTTP plugin in your Haraka configuration:

# config/plugins (add this line)
http

// config/http.ini
[server]
listen=0.0.0.0:8025

Restart Haraka, then add the monitor in Vigilmon:

1. Click Add Monitor → set Type to HTTP / HTTPS.
2. Enter: http://mail.yourdomain.com:8025/metrics (or /status depending on your Haraka version and plugin config).
3. Set Expected HTTP status to 200.
4. Under Response body, set Contains to "uptime" or another expected JSON field.
5. Set Check interval to 1 minute.
6. Click Save.

The HTTP metrics endpoint exposes Haraka process uptime, queue depth, connection counts, and plugin errors — invaluable for distinguishing a crashed process from a slow queue from a plugin fault.

Note: Restrict port 8025 to trusted IPs in your firewall. The HTTP metrics endpoint should not be publicly accessible.

Step 4: SSL Certificate Alerts for Haraka STARTTLS

Haraka supports STARTTLS on SMTP connections via its tls plugin. An expired TLS certificate causes other mail servers to reject your connections and prevents mail clients from authenticating on port 587.

SMTP STARTTLS Certificate (Port 25)

1. Open the TCP Port 25 monitor you created in Step 1.
2. Enable Monitor SSL certificate — Vigilmon issues a STARTTLS probe to SMTP ports automatically.
3. Set Alert when certificate expires in less than 21 days.
4. Click Save.

Submission TLS Certificate (Port 587)

1. Open the TCP Port 587 monitor.
2. Enable Monitor SSL certificate.
3. Set Alert when certificate expires in less than 21 days.
4. Click Save.

Haraka's TLS plugin reads certificates from config/tls_cert.pem and config/tls_key.pem. When you renew certificates via certbot or another ACME client, you need to either restart Haraka or send it a SIGHUP to reload the new certificate. Set a 21-day alert window so you have time to catch renewal problems and reload the daemon before expiry.

After renewing, confirm Haraka reloaded the certificate:

# Check the certificate expiry date Haraka is currently serving
echo | openssl s_client -starttls smtp -connect mail.yourdomain.com:25 2>/dev/null | \
  openssl x509 -noout -dates

Step 5: Heartbeat Monitoring for the Haraka Plugin Pipeline

Haraka processes email through a chain of plugins. A plugin that deadlocks, crashes, or begins rejecting connections silently breaks email processing even when the TCP port is still accepting connections. Use an end-to-end SMTP probe that exercises the full plugin chain to verify everything is operational.

1. In Vigilmon, click Add Monitor → Cron Heartbeat.
2. Set Expected ping interval to 5 minutes.
3. Copy the heartbeat ping URL (e.g. https://vigilmon.online/heartbeat/abc123).
4. On your Haraka host (or a monitoring server with network access), add a cron job that sends a full SMTP session through port 587:

# /etc/cron.d/haraka-pipeline-heartbeat
*/5 * * * * root bash -c '
  # End-to-end SMTP probe through submission port
  # Tests: TCP accept, EHLO handler, MAIL FROM plugin, RCPT TO plugin, relay auth
  SMTP_RESPONSE=$(printf "EHLO monitor.local\r\nMAIL FROM:<probe@monitor.local>\r\nRCPT TO:<test@yourdomain.com>\r\nQUIT\r\n" | \
    nc -w 10 mail.yourdomain.com 587 2>/dev/null)
  
  # A 250 response to EHLO confirms the connection and plugin chain responded
  echo "$SMTP_RESPONSE" | grep -q "^250" && curl -s https://vigilmon.online/heartbeat/abc123
'

This probe sends EHLO, MAIL FROM, and RCPT TO commands and checks for a 250 response. A healthy Haraka processes these through its connection plugins, mail-from plugins, and rcpt-to plugins in sequence. If any plugin in the chain crashes or stalls, the 250 response won't come and the heartbeat ping is skipped.

For a minimal check that only verifies the TCP banner is sent (Haraka is alive but not fully validating plugin response):

*/5 * * * * root nc -zw 5 mail.yourdomain.com 587 && \
  echo "EHLO probe" | nc -w 5 mail.yourdomain.com 587 | grep -q "^220" && \
  curl -s https://vigilmon.online/heartbeat/abc123

The 220 banner is Haraka's greeting — sent before any plugin processing. A 220 confirms the Node.js process is alive; a 250 to EHLO confirms the plugin chain is running.

Step 6: Monitor Haraka Queue Health

Haraka uses a queue plugin (typically queue/smtp_forward, queue/discard, or a custom plugin) to deliver or route messages. Queue backup is an early warning sign of delivery problems.

If you have the HTTP metrics plugin enabled, add a check for queue depth:

# /etc/cron.d/haraka-queue-heartbeat
*/5 * * * * root bash -c '
  # Fetch Haraka metrics and check queue depth
  QUEUE_DEPTH=$(curl -sf http://localhost:8025/metrics 2>/dev/null | \
    grep -o '"'"'queue_size":[0-9]*'"'"' | grep -o "[0-9]*")
  
  # Alert via heartbeat only when queue is healthy (under 100 messages)
  [ -n "$QUEUE_DEPTH" ] && [ "$QUEUE_DEPTH" -lt 100 ] && \
    curl -s https://vigilmon.online/heartbeat/YOUR_QUEUE_HEARTBEAT_URL
'

Create a second heartbeat monitor in Vigilmon with an 8-minute interval for this queue check. If the queue grows beyond your threshold, the heartbeat stops and you get alerted.

Step 7: Configure Alert Channels

1. Go to Alert Channels in Vigilmon and add email, Slack, or PagerDuty notifications.
2. For TCP port monitors, set Consecutive failures before alert to 2 — Haraka's Node.js process may briefly restart under a plugin reload (SIGHUP).
3. For the HTTP metrics monitor, set Consecutive failures before alert to 1 — a 500 from the metrics endpoint indicates a real process problem.
4. For heartbeat monitors, choose the interval based on your mail volume tolerance. High-volume email infrastructure should use 2–3 minute heartbeat intervals; personal or low-volume servers can use 10 minutes.
5. Use Maintenance windows before deploying Haraka plugin updates:

# Suppress alerts during plugin reload
curl -X POST https://vigilmon.online/api/maintenance \
  -H "Authorization: Bearer YOUR_VIGILMON_API_KEY" \
  -d '{"monitor_id": "YOUR_HARAKA_MONITOR_ID", "duration_minutes": 5}'

# Reload Haraka config and plugins
kill -HUP $(cat /var/run/haraka.pid)

Summary

| Monitor | Type | Target | What It Catches | |---|---|---|---| | SMTP port 25 | TCP Port | Port 25 | Process crash, inbound mail failure | | Submission port 587 | TCP Port | Port 587 | Client send failure | | HTTP metrics API | HTTP | Port 8025 /metrics | Process fault, queue backup | | SMTP STARTTLS SSL | SSL Certificate | Port 25 STARTTLS | TLS cert expiry | | Submission TLS SSL | SSL Certificate | Port 587 STARTTLS | Submission cert expiry | | Plugin pipeline heartbeat | Cron Heartbeat | SMTP end-to-end probe | Plugin chain failure | | Queue heartbeat | Cron Heartbeat | Queue depth check | Queue backup / delivery stall |

Haraka's plugin architecture makes it uniquely powerful for custom email workflows — and uniquely sensitive to plugin failures that standard SMTP servers never encounter. With Vigilmon watching the TCP ports, HTTP metrics, TLS certificates, and end-to-end plugin pipeline, you have complete visibility into your Haraka deployment and can catch failures before they become email delivery incidents.