Monitoring zrok with Vigilmon

zrok is an open-source tunneling and sharing platform built on OpenZiti — a zero-trust networking framework. Unlike cloudflared or frp, zrok is fully self-hostable with its own controller, web console, and programmable share model. It lets users create ephemeral or permanent public shares of local services, files, or HTTP endpoints through the zrok network. But when the zrok controller goes down, all shares stop working — public URLs return errors, backend connectivity drops, and users lose access with no clear indication of what failed. Vigilmon gives you the external monitoring layer to catch controller and share failures before they become support incidents.

What You'll Set Up

• HTTP monitor for the zrok web console
• Controller API health check
• Public share endpoint availability
• Backend connectivity verification
• Alert channels for immediate notification

Prerequisites

• zrok v0.4+ self-hosted with the controller running on a Linux host
• Web console accessible at https://<controller-host> (port 443 or 1280 depending on your config)
• At least one active share (public or private) you want to monitor
• A free Vigilmon account

Step 1: Monitor the zrok Web Console

The zrok web console is the user-facing dashboard where users manage their environments, shares, and access grants. It runs on the zrok controller host and is served directly by the controller process.

1. Log in to vigilmon.online and click Add Monitor.
2. Set Type to HTTP / HTTPS.
3. Enter the URL: https://<your-zrok-controller> (e.g. https://zrok.example.com).
4. Set Expected HTTP status to 200.
5. Set Check interval to 2 minutes.
6. Click Save.

The zrok controller serves the React-based web console from its root path. A 502 or connection refused indicates the controller process has stopped — the most common failure after host reboots or failed zrok upgrades.

If you run zrok's controller on a non-standard port (the default is 1280 in development mode), adjust the URL accordingly: http://<host>:1280.

Step 2: Health-Check the Controller API

zrok's controller exposes a REST API used by the CLI and web console. The /api/v1/health endpoint is the canonical health signal:

GET https://<your-zrok-controller>/api/v1/health

A healthy response:

{
  "status": "ok"
}

Configure Vigilmon to assert on this:

1. Add Monitor → HTTP / HTTPS.
2. URL: https://<your-zrok-controller>/api/v1/health.
3. Set Expected body contains to "status":"ok".
4. Set Check interval to 2 minutes.
5. Click Save.

This check validates more than the web console check: the controller's API layer, its connection to the zrok database, and the OpenZiti fabric underneath. A controller that serves the web console HTML (from a CDN or static cache) might fail this API check if the backend process is degraded.

Step 3: Monitor Public Share Endpoints

Public shares are the core value of zrok — they create publicly accessible URLs that route through the zrok controller to a user's local service. When a share is active and the controller is healthy, the share URL returns your backend's response. When either fails, the URL returns a 404 or controller error.

For a public HTTP share:

1. Add Monitor → HTTP / HTTPS.
2. URL: the public share URL (e.g. https://a3f7b2.share.zrok.example.com).
3. Set Expected HTTP status to 200.
4. Set Check interval to 2 minutes.
5. Click Save.

For a public share with a known response body:

1. Add Expected body contains to a distinctive string from your service's response.
2. This rules out the zrok controller returning a synthetic 200 error page instead of your backend's actual content.

Important: zrok public share hostnames are ephemeral by default and change on each zrok share. For persistent monitoring, use reserved shares (zrok reserve public) which maintain a stable hostname. Only reserved or unique-name shares are suitable for long-term Vigilmon monitors.

Step 4: Verify Backend Connectivity Through zrok

A public share endpoint check validates the full path (DNS → controller → OpenZiti fabric → share agent → local backend). But for debugging failures, you need to know where in the chain the failure occurred.

Add a separate monitor for a backend health endpoint exposed through the share:

1. Add Monitor → HTTP / HTTPS.
2. URL: https://<share-hostname>/health (if your backend exposes a health path).
3. Set Expected body contains to a string that only your backend returns (not a zrok error page).
4. Click Save.

When this check fails while the controller API (Step 2) is still healthy, you know the failure is in the OpenZiti fabric layer or the share agent on the backend host — a different remediation path than a controller failure.

For backends that don't expose a health path, use the root path check with an application-specific body assertion. The key is distinguishing between "zrok returned an error page" and "the backend returned a real response."

Step 5: Monitor the OpenZiti Controller Port

zrok is built on OpenZiti, and the OpenZiti controller manages the underlying network fabric. zrok's controller typically runs OpenZiti on port 6262 (management) and 3022 (edge enrollment). If the OpenZiti layer fails, all shares fail immediately.

Monitor the OpenZiti management port:

1. Add Monitor → TCP Port.
2. Host: <your-zrok-controller>, Port: 6262.
3. Set Check interval to 2 minutes.
4. Click Save.

This check is especially useful in split-deployment setups where the zrok controller and OpenZiti controller run on different hosts — a TCP check on port 6262 to the OpenZiti host catches fabric-layer failures that the zrok API check wouldn't surface.

Step 6: Monitor SSL Certificate Expiry

zrok's public share URLs use wildcard or per-subdomain certificates to serve *.share.zrok.example.com through HTTPS. These certificates need renewal attention:

1. Add Monitor → SSL Certificate.
2. URL: https://zrok.example.com (the controller's primary domain).
3. Set Alert when certificate expires in less than 30 days.
4. Click Save.

Add a second SSL monitor for a specific share hostname if you use reserved shares with stable subdomains:

1. URL: https://<reserved-share-name>.share.zrok.example.com.
2. Set Alert when expires in less than 30 days.
3. Click Save.

If you use Let's Encrypt with wildcard certificates, auto-renewal failures are common when DNS validation is misconfigured. Vigilmon's SSL monitors surface certificate expiry independently of your renewal tooling.

Step 7: Configure Alert Channels

1. Go to Alert Channels in Vigilmon and configure your preferred channel: email, Slack, PagerDuty, or webhook.
2. For public share endpoint monitors, set Consecutive failures before alert to 1 — a share going down is user-facing and warrants immediate notification.
3. For the controller API and web console, use 2 consecutive failures to absorb controller restarts during upgrades (zrok restarts take 10–30 seconds).
4. Add Maintenance windows for scheduled zrok controller upgrades.

Consider creating a Status page in Vigilmon for any services you expose to external users through zrok — your users deserve to know when shares are degraded without having to reach out to you directly.

Step 8: Monitoring User Account and Environment Health

zrok's controller API exposes per-user environment status at /api/v1/environment. If you're running a multi-tenant zrok deployment, you can monitor the health of specific user environments:

GET https://<controller>/api/v1/environment
X-TOKEN: <zrok-user-token>

This returns the user's environments and their shares. A failed or empty environment list can indicate that the OpenZiti edge router the environment is bound to has gone offline — a sign of partial fabric degradation that won't surface in the controller health check.

Going Further

• zrok agent monitoring: The zrok share agent runs on the backend host. Add a TCP port check to confirm the agent's local listener is alive — zrok share public opens a listener on localhost:9191 by default. If this port is closed, the share fails even when the controller is healthy.
• Share count alerts: Poll /api/v1/overview with an admin token to monitor active share counts. A sudden drop to zero indicates all clients have disconnected — useful in environments where shares are expected to be persistent.
• OpenZiti router health: Each OpenZiti edge router registers with the controller. Poll /edge/management/v1/edge-routers with an admin token to verify all routers are isOnline: true. Offline routers reduce the fabric's capacity and can cause share failures for users whose environments are bound to affected routers.
• Latency baseline: Vigilmon's response time tracking on your public share endpoints gives you a baseline for normal tunnel latency. A 3× spike in response time often precedes a full share failure by several minutes.

With Vigilmon watching your zrok controller API, public share endpoints, OpenZiti fabric ports, and SSL certificates, you'll know the moment your tunneling infrastructure degrades — from controller failures to individual share disconnections.