tutorial

Monitoring VyOS with Vigilmon

VyOS is your open-source routing OS — but a silent HTTP API daemon crash or BGP session drop won't announce itself. Here's how to monitor VyOS REST API availability, SSH reachability, routing health, and SSL certificates with Vigilmon.

VyOS turns commodity hardware into a full-featured routing OS — BGP, OSPF, IPsec, WireGuard, and traffic shaping all in a JunOS-style CLI. But when VyOS itself becomes unreachable, you're managing your network blind: config changes are impossible, VPN tunnels can't be diagnosed, and routing failures become invisible until users complain. Vigilmon keeps watch on the VyOS REST API, SSH management access, routing protocol health, and your HTTPS certificate so you know the moment your network OS needs attention.

What You'll Set Up

  • HTTP uptime monitor for the VyOS REST API (port 443 HTTPS)
  • TCP probe for VyOS SSH availability (port 22)
  • Routing health check via the VyOS API version endpoint
  • SSL certificate expiry alert for the VyOS HTTPS API
  • Heartbeat monitor for BGP/OSPF routing protocol health

Prerequisites

  • VyOS 1.3+ (Equuleus or later) with the HTTP API enabled
  • REST API service configured (set service https api)
  • A free Vigilmon account

Step 1: Enable the VyOS HTTP API

The VyOS REST API must be explicitly enabled before it can be monitored. Connect via SSH and configure:

configure
set service https api keys id monitoring-key key YOUR_SECURE_API_KEY
set service https api
commit
save

This enables the HTTPS API on port 443 and creates an API key. Use a dedicated key with a strong random value for monitoring — never reuse your admin key.

Verify the API is running:

curl -k -X POST \
  'https://localhost/retrieve' \
  -H 'Content-Type: application/json' \
  -d '{"op": "showConfig", "path": [], "key": "YOUR_SECURE_API_KEY"}'

A JSON response containing your running configuration confirms the API daemon is operational.

Step 2: Monitor VyOS REST API Availability

  1. Log in to vigilmon.online and click Add Monitor.
  2. Set Type to HTTP / HTTPS.
  3. Set URL to https://your-vyos-host/retrieve
  4. Set Method to POST.
  5. Set Request body to:
{"op": "showConfig", "path": [], "key": "YOUR_SECURE_API_KEY"}
  1. Set Expected HTTP status to 200.
  2. Set Check interval to 2 minutes.
  3. Click Save.

A 200 response confirms the VyOS HTTPS API daemon (vyos-http-api) is running and the routing OS is fully responsive. If the API daemon crashes or the service is misconfigured after an upgrade, this monitor fires before you notice missing BGP routes.

Step 3: Monitor VyOS SSH Availability via TCP Probe

SSH is the primary management interface for VyOS. Even when the HTTP API is unavailable, SSH access lets you diagnose and recover the system. Monitor SSH independently with a TCP probe:

  1. In Vigilmon, click Add Monitor → TCP Port.
  2. Set Host to your VyOS hostname or IP.
  3. Set Port to 22.
  4. Set Check interval to 1 minute.
  5. Click Save.

A TCP probe to port 22 confirms the OpenSSH daemon is running. SSH failure while routing continues means VyOS is operating but unmanageable — an urgent signal requiring immediate console access or out-of-band management.

Step 4: Monitor VyOS System Health via Version Endpoint

The VyOS API can return version and uptime information to confirm the routing OS is fully operational beyond basic reachability:

  1. In Vigilmon, click Add Monitor → HTTP / HTTPS.
  2. Set URL to https://your-vyos-host/retrieve
  3. Set Method to POST.
  4. Set Request body to:
{"op": "show", "path": ["version"], "key": "YOUR_SECURE_API_KEY"}
  1. Set Expected HTTP status to 200.
  2. Set Expected response body contains to "VyOS" — the version string will include the VyOS build name.
  3. Set Check interval to 5 minutes.
  4. Click Save.

This check confirms the routing subsystem is responsive and returning meaningful data, not just that the HTTP listener is accepting connections.

Step 5: SSL Certificate Alert for the VyOS HTTPS REST API

The VyOS HTTPS API endpoint uses a certificate — either a self-signed cert generated by VyOS or a Let's Encrypt/custom cert you've installed. Monitor the certificate to prevent API authentication failures due to cert expiry:

  1. Open the HTTP / HTTPS monitor from Step 2.
  2. Enable Monitor SSL certificate under the SSL section.
  3. Set Alert when certificate expires in less than 21 days.
  4. Click Save.

To install a custom certificate in VyOS:

configure
set pki certificate my-cert certificate 'BASE64_ENCODED_CERT'
set pki certificate my-cert private key 'BASE64_ENCODED_KEY'
set service https certificates certificate my-cert
commit
save

With a custom cert from a trusted CA, you can also disable the Accept invalid/self-signed certificates option in Vigilmon to enforce certificate chain validation.

Step 6: Heartbeat Monitoring for BGP/OSPF Routing Health

VyOS can be operationally up while BGP or OSPF sessions have dropped — the OS is healthy but traffic is blackholing because routing protocol adjacencies are down. Use a scheduled heartbeat script to probe BGP health via the API:

  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 on a separate host that can reach VyOS:

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

VYOS_HOST="your-vyos-host"
API_KEY="YOUR_SECURE_API_KEY"
HEARTBEAT_URL="https://vigilmon.online/heartbeat/abc123"

# Query BGP neighbor summary
RESPONSE=$(curl -s -k -X POST \
  "https://${VYOS_HOST}/retrieve" \
  -H 'Content-Type: application/json' \
  -d "{\"op\": \"show\", \"path\": [\"bgp\", \"summary\"], \"key\": \"${API_KEY}\"}")

# Check for established BGP sessions
if echo "$RESPONSE" | grep -q "Established"; then
  curl -s "$HEARTBEAT_URL"
fi

Add this to cron on a monitoring host:

*/5 * * * * /usr/local/bin/check-vyos-bgp.sh

For OSPF deployments, replace the BGP path with OSPF neighbor data:

-d "{\"op\": \"show\", \"path\": [\"ospf\", \"neighbor\"], \"key\": \"${API_KEY}\"}"

If the script runs but no BGP sessions are established, the heartbeat ping is not sent and Vigilmon alerts after the expected 5-minute window passes.

Step 7: Configure Alert Channels

  1. Go to Alert Channels in Vigilmon and add Slack, email, or a PagerDuty webhook.
  2. Set Consecutive failures before alert to 1 on the API monitor — VyOS API failures are never benign in production.
  3. Set Consecutive failures before alert to 2 on the SSH monitor — brief SSH daemon restarts happen during updates.
  4. Use Maintenance windows before VyOS upgrades:
curl -X POST https://vigilmon.online/api/maintenance \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{"monitor_id": "MONITOR_ID", "duration_minutes": 30}'

Summary

| Monitor | Target | What It Catches | |---|---|---| | REST API | POST /retrieve showConfig | HTTP API daemon crash, VyOS unresponsive | | SSH TCP probe | host:22 | SSH daemon down, unmanageable OS | | Version check | POST /retrieve show version | Routing OS degraded state | | SSL certificate | VyOS HTTPS endpoint | Certificate expiry, TLS failure | | BGP heartbeat | Cron script → heartbeat URL | BGP session drop, routing failure |

VyOS gives you enterprise routing capabilities without vendor lock-in — but the same self-hosted freedom means you own the uptime monitoring too. With Vigilmon watching the REST API, SSH, routing protocol health, and certificates, you get the observability layer that commercial routing hardware bundles in NMS software, running against your own open-source routing OS.

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