How to Monitor Coturn (TURN/STUN Server) with Vigilmon

Coturn is the most widely deployed open-source TURN/STUN server for WebRTC applications. It relays audio, video, and data streams for users behind NAT or firewalls — the peers that would otherwise never successfully establish a peer-to-peer connection. When Coturn goes down, those users get dropped calls, failed video conferences, and broken screen shares, with no clear error message explaining why.

This tutorial shows you how to monitor Coturn with Vigilmon so you detect relay failures before they impact your users.

Why monitoring a TURN server is harder than monitoring a web service

Coturn operates at layers 4 and 7, handles UDP and TCP simultaneously, and its primary protocol (STUN/TURN) is not HTTP. This creates monitoring blind spots that traditional uptime tools miss:

UDP port failures — Coturn's primary TURN port (3478 UDP) can go unreachable due to firewall changes or kernel buffer exhaustion, while the admin interface on TCP 5766 still responds fine
TLS relay failures — TURNS (TURN over TLS) on port 5349 can fail independently of plain TURN; if your clients use TLS relay by default, plain TURN failures won't surface in your monitoring
Authentication failures — the TURN credential mechanism can break (wrong shared secret, expired credentials, database outage if using an auth backend) while the port remains reachable
Relay bandwidth saturation — the server is up and accepting connections, but relay performance degrades because the network interface is saturated; UDP checks still succeed while user experience degrades
Admin interface crashes — the Coturn admin HTTP API becomes unresponsive while relay service continues; you lose visibility into active allocations and statistics

External monitoring across multiple protocols gives you defense in depth.

What you'll need

A running Coturn server (systemd service or Docker)
A free Vigilmon account — no credit card required
Coturn's admin REST API enabled (optional but recommended)

Step 1: Understand Coturn's ports and interfaces

Coturn listens on several ports by default:

| Port | Protocol | Purpose | |------|----------|---------| | 3478 | UDP + TCP | STUN and TURN (plain) | | 5349 | UDP + TCP | TURNS (STUN/TURN over TLS) | | 5766 | TCP | Admin REST API (--rest-api-port) | | 49152-65535 | UDP | Relay port range (media traffic) |

For monitoring purposes, you want to verify:

The TCP component of port 3478 is reachable (TCP check)
The TCP component of port 5349 is reachable (TCP check)
The admin REST API is responding (HTTP check)

UDP-level verification requires a STUN/TURN client — we'll cover a lightweight approach using a shell script and a Vigilmon heartbeat monitor.

Step 2: Enable the Coturn admin REST API

Add these lines to your turnserver.conf to enable the admin interface:

# Enable admin REST API
rest-api-separator=:
cli-password=your_secure_admin_password

# Admin web interface (optional, for browser access)
admin-web-interface=http://localhost:8080/admin

After restarting Coturn, the admin interface will be available at:

http://your-coturn-server:5766/web/

The REST API provides endpoints like:

GET /web/status — server status JSON
GET /web/info — session and allocation counts

Step 3: Set up HTTP monitoring in Vigilmon

Monitor 1: Admin REST API health

Log in to vigilmon.online and go to Monitors → New Monitor
Choose HTTP / HTTPS
Set the URL to:
```
http://your-coturn-server:5766/web/
```
Check interval: 2 minutes
Expected status code: 200
Save the monitor

If you expose the admin interface only on localhost and use a reverse proxy or SSH tunnel for access, set up the proxy first before configuring Vigilmon. Alternatively, set up a lightweight health-check endpoint on your server using nginx to proxy the admin interface externally.

Monitor 2: Admin server status

Create a second HTTP / HTTPS monitor

URL:

http://your-coturn-server:5766/web/status

Expected status code: 200
(Optional) Response body contains: "status":"ok" or "running"
Check interval: 2 minutes

Step 4: Set up TCP port monitoring

TCP checks verify that Coturn's relay ports are reachable at the network level — essential for catching firewall changes or service binding failures.

TCP Monitor 1: TURN port (plain)

Go to Monitors → New Monitor → TCP Port
Enter:
- Host: your-coturn-server.com
- Port: 3478
Check interval: 1 minute
Save the monitor

TCP Monitor 2: TURNS port (TLS)

Create a second TCP monitor
Enter:
- Host: your-coturn-server.com
- Port: 5349
Check interval: 1 minute

TCP Monitor 3: Admin interface

Create a third TCP monitor
Enter:
- Host: your-coturn-server.com
- Port: 5766
Check interval: 2 minutes

Step 5: Set up a STUN/UDP heartbeat monitor

TCP checks can't verify UDP relay functionality. For full UDP coverage, use a heartbeat monitor: a cron job on your server that runs a STUN probe and pings Vigilmon if it succeeds.

First, set up a heartbeat monitor in Vigilmon:

Go to Monitors → New Monitor → Heartbeat
Name it "Coturn STUN UDP probe"
Set the expected interval to 5 minutes (with a grace period of 2 minutes)

Copy the heartbeat ping URL — it will look like:

https://vigilmon.online/heartbeat/your-monitor-id

Then, on your Coturn server, install stun client and set up the cron probe:

# Install stun client
apt-get install -y stun

# Create the probe script
cat > /usr/local/bin/coturn-probe.sh << 'EOF'
#!/bin/bash
# STUN UDP probe for Coturn
COTURN_HOST="localhost"
COTURN_PORT="3478"
HEARTBEAT_URL="https://vigilmon.online/heartbeat/your-monitor-id"

# Run STUN probe (maps-address tells us if UDP relay works)
if stun -v "${COTURN_HOST}:${COTURN_PORT}" 2>&1 | grep -q "MappedAddress"; then
    curl -sf "${HEARTBEAT_URL}" > /dev/null
fi
EOF

chmod +x /usr/local/bin/coturn-probe.sh

Add to crontab:

*/5 * * * * /usr/local/bin/coturn-probe.sh

If the STUN probe fails (Coturn UDP is down), the heartbeat ping is never sent, and Vigilmon fires an alert after the grace period expires.

Step 6: Configure Coturn with a system health check

If you run Coturn as a systemd service, add a ExecStartPost health check to verify it starts correctly:

# /etc/systemd/system/coturn.service.d/health.conf
[Service]
# Wait for the TURN port to be available after start
ExecStartPost=/bin/bash -c 'for i in $(seq 1 10); do nc -zv 127.0.0.1 3478 && break || sleep 2; done'
Restart=on-failure
RestartSec=5

For a Docker deployment:

services:
  coturn:
    image: coturn/coturn:latest
    network_mode: host
    volumes:
      - ./turnserver.conf:/etc/coturn/turnserver.conf:ro
    healthcheck:
      test: ["CMD", "nc", "-zv", "127.0.0.1", "3478"]
      interval: 30s
      timeout: 5s
      retries: 3
      start_period: 5s
    restart: unless-stopped

The nc -zv 127.0.0.1 3478 check verifies that the TCP component of the TURN port is bound and listening. Combine with the STUN UDP probe for full coverage.

Step 7: Configure Coturn for reliable operation

While you're setting up monitoring, review these Coturn configuration options that reduce the chance of silent failures:

# /etc/coturn/turnserver.conf

# Basic identity
realm=your-domain.com
server-name=coturn.your-domain.com

# Network
listening-port=3478
tls-listening-port=5349
listening-ip=0.0.0.0

# TLS (required for TURNS)
cert=/etc/letsencrypt/live/coturn.your-domain.com/fullchain.pem
pkey=/etc/letsencrypt/live/coturn.your-domain.com/privkey.pem

# Authentication (use time-limited credentials)
use-auth-secret
static-auth-secret=your_long_random_secret_here

# Relay port range (make sure firewall allows this range)
min-port=49152
max-port=65535

# Logging — essential for correlating with downtime alerts
log-file=/var/log/coturn/turnserver.log
verbose

# Admin interface
rest-api-separator=:

Key monitoring-relevant settings:

verbose logging lets you correlate Vigilmon alerts with Coturn log entries
use-auth-secret with a static secret avoids database failures breaking authentication
min-port/max-port should match your firewall rules exactly — a mismatch causes relay allocation failures without crashing the server

Step 8: Configure alert channels

In Vigilmon, go to Alert Channels → Add Channel
Add your notification channels:
- Slack — #infrastructure or #ops channel for your engineering team
- PagerDuty / Opsgenie — for production WebRTC services where relay downtime is customer-impacting
- Email — for escalation if the outage lasts more than 5 minutes

For Coturn, we recommend:

TCP port 3478 failure → immediate pager (users can't connect at all)
TCP port 5349 failure → immediate pager (TLS relay broken)
UDP heartbeat failure → high-priority Slack alert (relay is degraded)
Admin API failure → Slack notification (observability lost, not user-impacting)

Complete monitor setup summary

| Monitor | Type | Target | Interval | Catches | |---------|------|--------|----------|---------| | TURN TCP port | TCP | :3478 | 1 min | TURN service binding failure | | TURNS TLS port | TCP | :5349 | 1 min | TLS relay binding failure | | Admin API | HTTP | :5766/web/ | 2 min | Admin interface crash | | Admin status | HTTP | :5766/web/status | 2 min | Coturn process health | | Admin port | TCP | :5766 | 2 min | Admin service availability | | STUN UDP probe | Heartbeat | cron → heartbeat URL | 5 min | UDP relay functionality |

Conclusion

Coturn is invisible infrastructure — users never know it's there until it fails. A WebRTC app that drops calls or shows blank video feeds when Coturn is down is indistinguishable from one with a broken video codec. Your users just see failures.

With Vigilmon's TCP port checks, HTTP admin monitoring, and heartbeat-based UDP validation, you have comprehensive coverage of every failure mode that matters. Set it up once, and you'll know about Coturn outages in under 60 seconds — long before your users start filing bug reports.

Get started free at vigilmon.online — no credit card required.