Monitoring OpenZiti with Vigilmon

OpenZiti's promise is that your applications expose zero open ports to the internet — network connectivity is embedded into the application layer itself, and the fabric routes traffic through enrolled Edge Routers without any firewall hole-punching. But that zero-trust overlay still runs on infrastructure: the OpenZiti Controller must be reachable to manage identities and router enrollment, and Edge Routers must maintain their connection to the fabric. Vigilmon monitors the Controller REST API, router management endpoints, SSL certificates, and router health heartbeats so you know the zero-trust fabric is operating before your applications go dark.

What You'll Set Up

• HTTP uptime monitor for the OpenZiti Controller version endpoint
• Router management API availability check
• TCP port monitor for the Controller management API (port 8441)
• SSL certificate alerts for HTTPS Controller deployments (PKI-critical)
• Cron heartbeat for Edge Router enrollment and health monitoring

Prerequisites

• OpenZiti Controller running (typically deployed via the ziti binary or Docker/Kubernetes)
• Controller REST API accessible at https://your-controller:8080 or your configured port
• A free Vigilmon account

Step 1: Monitor the OpenZiti Controller REST API

The Controller is the central authority in an OpenZiti network — it manages identities, policies, Edge Routers, and the certificate chain for the entire overlay. If the Controller REST API goes down, new connections can't be established and router enrollment fails.

1. Log in to vigilmon.online and click Add Monitor.
2. Set Type to HTTP / HTTPS.
3. Enter the URL: https://your-controller:8080/edge/v1/version
4. Set Check interval to 1 minute.
5. Set Expected HTTP status to 200.
6. Optionally set Response body contains to "version" to validate the JSON response structure.
7. Click Save.

The /edge/v1/version endpoint returns the Controller version, API version, and build metadata without requiring authentication. A 200 response confirms the Edge API is up and the Controller process is running:

{
  "data": {
    "apiVersions": { "edge": { "v1": { "path": "/edge/v1" } } },
    "version": "v1.2.3"
  }
}

Step 2: Monitor the Router Management API

The router management endpoint is used by the Controller to manage Edge Router lifecycle — enrollment, configuration updates, and termination. Monitoring it separately from the version endpoint confirms the management plane is available, not just the client-facing API.

1. Click Add Monitor → HTTP / HTTPS.
2. Enter the URL: https://your-controller:8080/edge/management/v1/routers
3. Set Expected HTTP status to 401 (unauthenticated access returns 401 Unauthorized, which still confirms the endpoint is live and the management API is running).
4. Set Check interval to 1 minute.
5. Click Save.

Using 401 as the expected status is a deliberate choice: this endpoint requires authentication with a management API token. A 401 response means the endpoint is reachable and the authentication middleware is working. A 502 or timeout means the management API itself is down.

Step 3: Monitor TCP Port 8441 (Controller Management API)

Port 8441 is the default TCP port for the OpenZiti Controller management API — the port that the ziti CLI, Admin Console, and automation tooling use to interact with the Controller. TCP-level monitoring catches connection failures that happen below the HTTP layer (firewall changes, process crashes, socket exhaustion).

1. Click Add Monitor → TCP Port.
2. Enter the host: your-controller
3. Enter the port: 8441
4. Set Check interval to 1 minute.
5. Click Save.

If you've configured the management API on a non-standard port, check your Controller config file:

# ziti-controller.yaml
web:
  - name: all-apis-localhost
    bindPoints:
      - interface: 0.0.0.0:8441
        address: 0.0.0.0:8441

Use whatever port is configured under bindPoints for the management listener.

Step 4: SSL Certificate Alerts for the OpenZiti Controller

PKI management is at the heart of OpenZiti — the Controller acts as the root CA for the entire zero-trust fabric, issuing certificates for Edge Routers and client identities. The Controller itself uses a certificate for its HTTPS endpoints, and that certificate must stay valid. An expired Controller certificate breaks the management API and prevents new router enrollments.

Add a certificate expiry monitor for the Controller HTTPS endpoint:

1. Open the HTTP monitor created in Step 1.
2. Enable Monitor SSL certificate in the SSL section.
3. Set Alert when certificate expires in less than 30 days.
4. Click Save.

A 30-day alert window is recommended for OpenZiti (longer than typical) because certificate rotation requires re-enrolling routers and identities — it's not a quick certbot renew operation. Give yourself time.

To inspect the current certificate chain:

# Check the Controller's TLS certificate expiry
echo | openssl s_client -connect your-controller:8441 2>/dev/null \
  | openssl x509 -noout -subject -dates
# subject=CN=openziti-controller
# notAfter=Jan 15 00:00:00 2026 GMT

Also add a separate SSL monitor for port 8080 (Edge API) if it uses a different certificate than the management port:

https://your-controller:8080/edge/v1/version

Step 5: Heartbeat Monitoring for Edge Router Enrollment Health

Edge Routers must maintain valid enrollment certificates — issued by the Controller's CA chain — to participate in the fabric. Router enrollment certificates have a finite lifetime and must be refreshed before expiry. There's no built-in alert when a router's enrollment is nearing expiry or when a router goes offline.

Use Vigilmon's cron heartbeat to monitor router health via a scheduled check script.

In Vigilmon:

1. Click Add Monitor → Cron Heartbeat.
2. Set the expected ping interval to 60 minutes (for an hourly router health check).
3. Copy the heartbeat URL (e.g. https://vigilmon.online/heartbeat/abc123).

Router health check script:

#!/bin/bash
# Check Edge Router status via the management API
CONTROLLER="https://your-controller:8080"
API_TOKEN="your-management-api-token"

# Get all routers and check their isOnline status
OFFLINE_ROUTERS=$(curl -s \
  -H "Authorization: Bearer $API_TOKEN" \
  "$CONTROLLER/edge/management/v1/edge-routers" \
  | jq '[.data[] | select(.isOnline == false)] | length')

if [ "$OFFLINE_ROUTERS" -eq 0 ]; then
  # All routers online — ping the heartbeat
  curl -s https://vigilmon.online/heartbeat/abc123
else
  echo "WARNING: $OFFLINE_ROUTERS router(s) offline — skipping heartbeat ping"
  exit 1
fi

Schedule this script with cron:

0 * * * * /usr/local/bin/check-openziti-routers.sh >> /var/log/ziti-health.log 2>&1

If any router goes offline, the script exits without pinging Vigilmon — and after one hour without a heartbeat, Vigilmon alerts.

Step 6: Configure Alert Channels

1. Go to Alert Channels in Vigilmon and add Slack, email, or a PagerDuty webhook for zero-trust infrastructure alerts.
2. Set Consecutive failures before alert to 1 for the Controller version endpoint — the Controller is the single point of authority for the entire overlay, so a single failure warrants immediate attention.
3. Keep the TCP port monitor at 2 consecutive failures to handle brief Controller restarts during version upgrades.

Summary

| Monitor | Target | What It Catches | |---|---|---| | Controller version API | /edge/v1/version | Controller process down, Edge API failure | | Router management API | /edge/management/v1/routers | Management plane unavailable | | TCP port 8441 | Controller management port | Firewall block, socket failure, process crash | | SSL certificate | Controller HTTPS | PKI certificate expiry, TLS failure | | Cron heartbeat | Heartbeat URL | Edge Router offline, enrollment check missed |

OpenZiti's zero-trust model eliminates open ports for application traffic — but the Controller and management APIs are the control plane that makes the entire fabric work. With Vigilmon monitoring those endpoints, your SSL certificate, and your router health, you get early warning of control-plane failures before they cascade into application-level outages across your zero-trust overlay.