Monitoring Outline VPN Server with Vigilmon

Outline VPN (developed by Jigsaw/Google) is an open-source Shadowsocks-based VPN designed for journalists, human rights workers, and individuals in censorship-heavy regions. The Outline Manager desktop app deploys an Outline Server on any VPS and generates shareable access keys — the server runs in Docker and blends VPN traffic with regular HTTPS traffic to evade detection and blocking.

Outline's biggest operational challenge is that its failures are silent. If the Shadowsocks server stops routing connections, access key holders don't receive an error message — they simply can't reach the internet. The management API may still respond while the data plane has quietly stopped working. Vigilmon lets you monitor all layers of the Outline stack and catch silent failures before they strand users who depend on the service.

What You'll Set Up

• HTTP monitor for the Outline management API confirming server health
• TCP port monitor for the Shadowsocks proxy port
• TLS certificate monitoring for the management API's self-signed certificate
• Heartbeat monitor verifying access keys are processing traffic

Prerequisites

• Outline Server running in Docker on a VPS
• Management API accessible (typically on a dynamically assigned HTTPS port, e.g. 22012)
• Management API certificate fingerprint and API key from user-data/outline-ss-server/access.txt
• Shadowsocks proxy port number (shown in the Outline Manager app)
• A free Vigilmon account

Step 1: Monitor the Outline Management API

The Outline management REST API confirms the server name, version, and access key count. It runs on a randomly assigned HTTPS port (e.g. 22012) that is set during installation and stored in user-data/outline-ss-server/access.txt. A healthy API response confirms the Outline Server container is running and the management layer is functional.

To find your management port and API key:

cat /opt/outline/access.txt
# apiUrl:https://YOUR_VPS_IP:22012/YOUR_SECRET_PATH
# certSha256:YOUR_CERT_FINGERPRINT

In Vigilmon:

1. Log in to vigilmon.online and click Add Monitor.
2. Set Type to HTTP / HTTPS.
3. Enter the URL: https://YOUR_VPS_IP:22012/YOUR_SECRET_PATH/server
4. Under Advanced, check Allow self-signed certificates (Outline uses a self-signed cert with certificate pinning).
5. Set Expected HTTP status to 200.
6. Under Advanced, add an Expected body contains check: "version" (the /server endpoint returns a JSON object including the server version).
7. Set Check interval to 2 minutes.
8. Click Save.

The /server endpoint is the canonical health check for Outline Server — it returns {"name":"...", "serverId":"...", "metricsEnabled":..., "createdTimestampMs":..., "version":"..."} when the server is healthy.

Step 2: Monitor the Shadowsocks Proxy Port

The Outline Server's data plane — the Shadowsocks proxy that routes actual VPN traffic — listens on a separate TCP/UDP port assigned when you create access keys. This is the port that access key holders connect to. If this port is unreachable while the management API is fine, users are blocked even though the server appears healthy.

Find your Shadowsocks port in the Outline Manager app or via the management API:

# List access keys and their ports
curl -sk "https://YOUR_VPS_IP:22012/YOUR_SECRET_PATH/access-keys" | python3 -m json.tool

In Vigilmon:

1. Add Monitor → TCP Port.
2. Host: YOUR_VPS_IP.
3. Port: YOUR_SHADOWSOCKS_PORT (e.g. 44444).
4. Set Check interval to 2 minutes.
5. Click Save.

A TCP failure on the Shadowsocks port typically indicates the outline-ss-server process has crashed inside the Docker container, or a firewall rule was changed that blocks the port. This is separate from the management API failure mode and must be monitored independently.

Step 3: Monitor the Management API TLS Certificate

Outline Server uses a self-signed TLS certificate for its management API, with certificate pinning enforced by the Outline Manager. If this certificate expires, the management API becomes inaccessible to the Outline Manager desktop app — you won't be able to add access keys, check server status, or perform any management operations.

The certificate is generated during installation and does not auto-renew. Track its expiry:

1. Open the HTTP monitor created in Step 1.
2. Enable Monitor SSL certificate under the SSL section.
3. Set Alert when certificate expires in less than 30 days (use a longer window than normal because self-signed cert renewal requires reinstallation steps).
4. Click Save.

A 30-day warning gives you enough time to plan a managed Outline Server reinstallation or certificate rotation before the management layer becomes inaccessible.

Step 4: Heartbeat Monitor for Access Key Traffic Throughput

The Outline management API exposes a /metrics/transfer endpoint that reports per-access-key traffic statistics. A scheduled heartbeat check against this endpoint confirms two things: the metrics API is functional, and access keys are actually being used to route traffic. If the Shadowsocks server silently stops routing connections, traffic metrics will show zero bytes for all keys — a signal that can be detected automatically.

Create a script on your Outline VPS:

#!/bin/bash
# outline-traffic-check.sh
# Monitors Outline Server for API health and traffic activity

OUTLINE_API="https://localhost:22012/YOUR_SECRET_PATH"
HEARTBEAT_URL="https://vigilmon.online/api/heartbeat/YOUR_HEARTBEAT_ID"

# Check server endpoint
server_code=$(curl -sk -o /dev/null -w "%{http_code}" \
  "$OUTLINE_API/server" --max-time 10)

if [ "$server_code" != "200" ]; then
  echo "$(date): Outline management API returned HTTP $server_code"
  exit 1
fi

# Fetch transfer metrics
transfer_response=$(curl -sk -w "\n%{http_code}" \
  "$OUTLINE_API/metrics/transfer" --max-time 10)

http_code=$(echo "$transfer_response" | tail -1)
body=$(echo "$transfer_response" | head -n -1)

if [ "$http_code" != "200" ]; then
  echo "$(date): Outline metrics API returned HTTP $http_code"
  exit 1
fi

# Log total bytes transferred (optional: alert if all keys show 0 for extended period)
total_bytes=$(echo "$body" | python3 -c "
import json, sys
data = json.load(sys.stdin)
total = sum(data.get('bytesTransferredByUserId', {}).values())
print(total)
" 2>/dev/null)

echo "$(date): Outline metrics OK — total bytes transferred: $total_bytes"

# Ping heartbeat — confirms the Outline API is healthy and reachable
curl -s "$HEARTBEAT_URL" --max-time 10 --retry 2
echo "$(date): Outline health heartbeat sent"

Make executable and schedule:

chmod +x /opt/scripts/outline-traffic-check.sh
crontab -e

*/10 * * * * /opt/scripts/outline-traffic-check.sh >> /var/log/outline-monitor.log 2>&1

Set up the heartbeat in Vigilmon:

1. Monitors → New Monitor → Heartbeat
2. Name: Outline Server API and Traffic
3. Interval: 15 minutes
4. Grace period: 5 minutes
5. Click Save and copy the heartbeat URL into the script.

If the management API becomes unreachable — due to a Docker container crash, OOM kill, or certificate issue — the heartbeat will stop pinging and Vigilmon fires an alert, even though access key users won't receive any error notification themselves.

Step 5: Alert Channels

Outline is often deployed in contexts where availability is critical and users may be in sensitive situations:

1. Alert Channels → Add Channel → add your preferred channel (email or a private Slack/webhook).
2. For the Shadowsocks port monitor and API monitor, set Consecutive failures before alert to 1 — silent failures are the primary risk, so alert immediately.
3. For the traffic heartbeat, allow a 10-minute grace period before alerting — brief API restarts during Docker updates are normal.

Summary

| Monitor | Target | What It Catches | |---|---|---| | Management API | :22012/…/server | Container crash, API unresponsive | | Shadowsocks TCP port | Shadowsocks port | Data plane down, firewall change | | Management TLS cert | Management HTTPS | Self-signed cert expiry | | Traffic heartbeat | /metrics/transfer | Silent proxy failure, zero traffic |

Outline's silence-by-design — traffic that blends in and doesn't announce failures — means standard monitoring approaches miss the most common failure modes. With Vigilmon watching the management API, the Shadowsocks port, the TLS certificate, and the traffic metrics, you get the observability that Outline deliberately omits.

Start monitoring your Outline VPN server today at vigilmon.online — free, no credit card required.