tutorial

Monitoring Foreman with Vigilmon

Foreman manages the full lifecycle of physical and virtual servers — but when its web UI or Smart Proxies go dark, your entire infrastructure management plane goes with it. Here's how to monitor Foreman with Vigilmon.

Foreman is the open-source lifecycle management tool that brings together provisioning, configuration management, and patching for physical and virtual servers. It sits at the center of your infrastructure: orchestrating Puppet runs, deploying OS images via PXE, and managing DNS and DHCP through Smart Proxies. When Foreman goes down, you can't provision new servers, view system state, or push configuration changes. Vigilmon monitors Foreman's web interface, API, and Smart Proxy services so you know the moment your infrastructure management plane has a problem.

What You'll Set Up

  • HTTP uptime monitor for the Foreman web UI and API
  • Smart Proxy service monitors
  • Cron heartbeat for Foreman scheduled tasks (fact imports, report cleanup)
  • SSL certificate alerts for Foreman's HTTPS interface
  • Alert channels for on-call notification

Prerequisites

  • Foreman 3.x installed (typically on RHEL/CentOS or Debian/Ubuntu)
  • Foreman web interface accessible over HTTPS (default port 443)
  • One or more Smart Proxies configured
  • A free Vigilmon account

Step 1: Monitor the Foreman Web Interface

Foreman's web interface is served by Puma behind Apache or nginx. Add an HTTP monitor to verify the UI is up:

  1. Log in to vigilmon.online and click Add Monitor.
  2. Set Type to HTTP / HTTPS.
  3. Enter your Foreman URL: 
    https://foreman.yourdomain.com/
  4. Set Check interval to 2 minutes.
  5. Set Expected HTTP status to 200 or 302 (Foreman redirects unauthenticated users to the login page).
  6. Enable Keyword check with keyword Foreman.
  7. Click Save.

The keyword check guards against a proxy returning a generic error page when Puma has crashed.

Step 2: Monitor the Foreman API

Foreman's REST API is used by Ansible, Terraform, and CI/CD pipelines to provision and query hosts. Monitor it directly:

  1. Click Add Monitor → HTTP / HTTPS.
  2. Enter the API status endpoint: 
    https://foreman.yourdomain.com/api/status
  3. Set Check interval to 1 minute.
  4. Set Expected HTTP status to 200.
  5. Enable Keyword check with keyword result.
  6. Click Save.

The /api/status endpoint returns JSON like {"result":"ok","version":"3.x.x","api_version":2}. A 200 with the result keyword confirms the Foreman application is running and the database connection is healthy.

Step 3: Monitor Smart Proxies

Smart Proxies extend Foreman's reach to remote network segments and handle DNS, DHCP, TFTP, and Puppet CA functions. Each Smart Proxy has its own health API. Add a monitor for each proxy:

  1. Click Add Monitor → HTTP / HTTPS.
  2. Enter the Smart Proxy health URL: 
    https://smart-proxy.yourdomain.com:8443/
  3. Set Check interval to 2 minutes.
  4. Set Expected HTTP status to 200 or 404 (the root path may return 404, but the proxy itself is responding).
  5. Click Save.

For a more targeted check, probe the Smart Proxy's version endpoint:

https://smart-proxy.yourdomain.com:8443/version

This returns JSON with the proxy version and enabled features. Add a keyword check for "version" to confirm a real proxy response.

Add one monitor per Smart Proxy. If a proxy goes offline, Foreman loses control of its network segment — hosts in that segment can't receive PXE boot instructions, DHCP leases, or Puppet catalog updates.

Step 4: TCP Monitor for Smart Proxy TFTP

Smart Proxies serving TFTP for PXE boot expose port 69. Add a TCP monitor:

  1. Click Add Monitor → TCP Port.
  2. Set Host to your Smart Proxy's IP or hostname.
  3. Set Port to 69.
  4. Set Check interval to 1 minute.
  5. Click Save.

Add monitors for each Smart Proxy that serves TFTP. A TFTP failure means new server deployments triggered through Foreman will stall at network boot.

Step 5: Heartbeat for Foreman Scheduled Tasks

Foreman runs background tasks via Dynflow (its workflow engine): fact imports, report cleanup, and scheduled remote execution jobs. If Dynflow stalls, your fact data goes stale and scheduled tasks queue up silently. Use a Vigilmon heartbeat to verify background processing is healthy:

  1. In Vigilmon, click Add Monitor → Cron Heartbeat.
  2. Set the expected ping interval to 30 minutes.
  3. Copy your heartbeat URL: 
    https://vigilmon.online/heartbeat/abc123
  4. Create a wrapper script:
#!/bin/bash
# /usr/local/bin/foreman-health-check.sh

FOREMAN_URL="https://foreman.yourdomain.com"
API_USER="admin"
API_PASS="your-api-password"

# Check Foreman API status
API_STATUS=$(curl -s -u "${API_USER}:${API_PASS}" \
  -H "Content-Type: application/json" \
  "${FOREMAN_URL}/api/status" | \
  python3 -c "import sys,json; d=json.load(sys.stdin); print(d.get('result','error'))")

# Check Dynflow execution status
DYNFLOW_STATUS=$(curl -s -u "${API_USER}:${API_PASS}" \
  "${FOREMAN_URL}/foreman_tasks/api/tasks?search=state%3Dpaused&per_page=1" | \
  python3 -c "import sys,json; d=json.load(sys.stdin); print(d.get('total', -1))")

if [ "$API_STATUS" = "ok" ] && [ "$DYNFLOW_STATUS" != "-1" ]; then
    curl -s https://vigilmon.online/heartbeat/abc123
    echo "Foreman health OK: API=$API_STATUS, paused_tasks=$DYNFLOW_STATUS"
else
    echo "Foreman health FAILED: API=$API_STATUS, dynflow=$DYNFLOW_STATUS" >&2
    exit 1
fi
  1. Schedule with cron:
crontab -e
# Run every 15 minutes, heartbeat interval is 30 minutes
*/15 * * * * /usr/local/bin/foreman-health-check.sh >> /var/log/foreman-health.log 2>&1

Step 6: Monitor the Foreman Proxy for Puppet CA

If your Foreman Smart Proxy handles the Puppet certificate authority (CA), its puppetca feature must remain accessible for new agents to get certificates signed. Add a monitor:

  1. Click Add Monitor → TCP Port.
  2. Set Host to the Puppet CA host (often the Foreman host itself).
  3. Set Port to 8140 (Puppet server).
  4. Set Check interval to 1 minute.
  5. Click Save.

Also add an HTTP monitor for the Puppet server API:

  1. Click Add Monitor → HTTP / HTTPS.
  2. Enter: 
    https://foreman.yourdomain.com:8140/puppet/v3/environments
  3. Set Expected HTTP status to 200 or 403 (unauthenticated requests return 403, which still proves Puppet is running).
  4. Click Save.

A 403 is acceptable here — you're confirming Puppet is alive, not that you have access.

Step 7: SSL Certificate Alerts

Foreman and Smart Proxies use TLS certificates extensively. The Foreman server, each Smart Proxy, and the Puppet CA all have their own certificates. Add SSL expiry monitors for each:

  1. Open the HTTP monitor for your Foreman web interface.
  2. Enable Monitor SSL certificate.
  3. Set Alert when certificate expires in less than 28 days.
  4. Click Save.

Repeat for each Smart Proxy URL. Foreman uses Puppet's CA infrastructure to issue Smart Proxy certificates — if the CA cert expires, every component that validates against it will simultaneously fail, which is an outage spanning your entire infrastructure management plane.

For Smart Proxy certificates specifically:

# Check how many days remain on a Smart Proxy cert
openssl s_client -connect smart-proxy.yourdomain.com:8443 </dev/null 2>/dev/null | \
  openssl x509 -noout -enddate

Step 8: Configure Alert Channels

  1. Go to Alert Channels in Vigilmon and add Slack, PagerDuty, email, or a webhook.
  2. For the Foreman API monitor, set Consecutive failures before alert to 2.
  3. For Smart Proxy TCP monitors, set Consecutive failures to 1 — a proxy failure immediately breaks provisioning in its network segment.
  4. Use maintenance windows during Foreman upgrades:
# Open a 2-hour maintenance window for a Foreman upgrade
curl -X POST https://vigilmon.online/api/maintenance \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "monitor_ids": ["foreman-web-id", "foreman-api-id", "smart-proxy-id"],
    "duration_minutes": 120,
    "reason": "Foreman 3.x upgrade"
  }'

Summary

| Monitor | Target | What It Catches | |---|---|---| | HTTP web UI | https://foreman.domain.com/ | Puma crash, UI unavailable | | HTTP API | /api/status | Application error, DB connection failure | | HTTP Smart Proxy | :8443/version | Proxy offline, remote segment unmanageable | | TCP TFTP | :69 per proxy | PXE boot broken in network segment | | TCP Puppet | :8140 | Puppet server down, agent cert signing broken | | Cron heartbeat | Health check script | Dynflow stalled, tasks queuing | | SSL certificates | Foreman + each proxy | Expired cert cascades across management plane |

Foreman is the single pane of glass for your entire server fleet — physical and virtual, provisioning and configuration, current state and historical reports. With Vigilmon watching its web UI, API, Smart Proxies, and scheduled task engine, you catch failures in the management plane before they cascade into stalled deployments, stale facts, and engineers unable to see what their servers are doing.

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