tutorial

Monitoring FreeSWITCH with Vigilmon

FreeSWITCH is a scalable open-source telephony platform for softswitches, PBX deployments, and media gateways. Here's how to monitor FreeSWITCH's ESL port, SIP stack, SIP TLS port, REST health checks, and IVR service availability with Vigilmon.

FreeSWITCH is a scalable open-source telephony platform used for softswitches, PBX systems, media gateways, and IVR deployments. Its architecture — a modular core with loadable codecs, call control modules, and dialplan engines — means failure modes are varied: the core process may run while an ESL socket goes unresponsive, a SIP module crashes silently, or a TLS certificate expires and SIPS registrations stop. Vigilmon gives you external monitoring for FreeSWITCH's network interfaces so you detect these failures as they happen, not when callers start reporting problems.

What You'll Set Up

  • TCP port monitor for the ESL (Event Socket Layer) on port 8021
  • TCP port monitor for SIP on port 5060
  • TCP port monitor for SIP TLS on port 5061
  • HTTP monitor for the mod_http_cache REST health check
  • Heartbeat monitor for FreeSWITCH conference/IVR service availability

Prerequisites

  • FreeSWITCH running on Linux (bare metal, Docker, or VM)
  • ESL enabled in event_socket.conf.xml
  • mod_http_cache loaded (or another HTTP module serving a health endpoint)
  • A free Vigilmon account

Step 1: Monitor the ESL Port (8021)

The Event Socket Layer is FreeSWITCH's primary external control interface. Applications, monitoring scripts, and management tools connect to ESL on TCP port 8021 to send commands and subscribe to events. If ESL becomes unreachable, FreeSWITCH can no longer be remotely controlled.

  1. Log in to vigilmon.online and click Add Monitor.
  2. Set Type to TCP Port.
  3. Host: YOUR_FREESWITCH_HOST, Port: 8021.
  4. Set Check interval to 1 minute.
  5. Click Save.

Verify ESL is bound and listening:

ss -tlnp | grep 8021
# LISTEN  0  128  0.0.0.0:8021  ...  users:(("freeswitch",pid=...,fd=...))

A TCP failure on port 8021 means either FreeSWITCH has crashed or the mod_event_socket module failed to load on startup. Check /var/log/freeswitch/freeswitch.log for module load errors.

Step 2: Monitor the SIP Port (5060)

FreeSWITCH's SIP stack (mod_sofia) listens on TCP and UDP port 5060 for SIP signaling. A TCP check on port 5060 confirms the Sofia SIP module is loaded and accepting connections.

  1. Click Add Monitor → TCP Port.
  2. Host: YOUR_FREESWITCH_HOST, Port: 5060.
  3. Set Check interval to 1 minute.
  4. Click Save.

FreeSWITCH's mod_sofia can crash independently of the core process — the ESL port may be responsive while SIP is down. Monitoring both ports separately catches this split-failure scenario.

Step 3: Monitor the SIP TLS Port (5061)

Encrypted SIP (SIPS) runs on TCP port 5061. If FreeSWITCH is configured for TLS SIP (common for enterprise deployments and WebRTC gateway setups), add a TCP monitor for this port:

  1. Click Add Monitor → TCP Port.
  2. Host: YOUR_FREESWITCH_HOST, Port: 5061.
  3. Set Check interval to 2 minutes.
  4. Click Save.

This catches the mod_sofia TLS profile failing to bind — which happens silently if the certificate file path in sofia.conf.xml is wrong or the certificate has been replaced with an invalid file.

Step 4: Monitor the REST Health Endpoint

If your FreeSWITCH deployment uses mod_http_cache or another HTTP module (such as mod_xml_rpc which exposes an HTTP management interface on port 8080), add an HTTP monitor for the health route.

For mod_xml_rpc (HTTP management API on port 8080):

  1. Click Add Monitor → HTTP / HTTPS.
  2. URL: http://YOUR_FREESWITCH_HOST:8080/
  3. Set Check interval to 1 minute.
  4. Set Expected HTTP status to 200 or 401 (if authentication is required, a 401 still confirms the HTTP server is running).
  5. Click Save.

For a custom HTTP health endpoint exposed via mod_lua or a sidecar process:

-- health.lua — expose via mod_lua HTTP handler
stream:write("HTTP/1.0 200 OK\r\n")
stream:write("Content-Type: application/json\r\n\r\n")
stream:write('{"status":"ok","version":"' .. freeswitch.getGlobalVariable("version") .. '"}')

Point the Vigilmon HTTP monitor at the endpoint served by this script.

Step 5: Heartbeat Monitoring for Conference/IVR Service Availability

FreeSWITCH can be network-reachable while its conference or IVR functionality is broken — a missing sound file, a broken Lua script, or a misconfigured dialplan context can cause IVR sessions to fail silently. Use a heartbeat monitor to verify that FreeSWITCH is successfully processing a test call flow.

In Vigilmon:

  1. Click Add Monitor → Cron Heartbeat.
  2. Set the expected ping interval to 10 minutes.
  3. Copy the heartbeat URL (e.g. https://vigilmon.online/heartbeat/abc123).

Configure an ESL script that exercises a simple dialplan extension and pings Vigilmon on success:

#!/usr/bin/env python3
# heartbeat_check.py — run every 10 minutes via cron
import socket, time

FS_HOST = "127.0.0.1"
FS_ESL_PORT = 8021
FS_PASSWORD = "ClueCon"

def esl_command(s, cmd):
    s.sendall(f"api {cmd}\n\n".encode())
    return s.recv(4096).decode()

try:
    s = socket.create_connection((FS_HOST, FS_ESL_PORT), timeout=5)
    # Authenticate
    s.recv(1024)
    s.sendall(f"auth {FS_PASSWORD}\n\n".encode())
    auth_resp = s.recv(1024).decode()
    if "+OK accepted" in auth_resp:
        # Check that FreeSWITCH core is responding to commands
        resp = esl_command(s, "status")
        if "UP" in resp:
            import urllib.request
            urllib.request.urlopen("https://vigilmon.online/heartbeat/abc123", timeout=5)
    s.close()
except Exception as e:
    print(f"Heartbeat failed: {e}")

Add to cron:

# /etc/cron.d/freeswitch-heartbeat
*/10 * * * * freeswitch python3 /usr/local/bin/heartbeat_check.py > /dev/null 2>&1

If FreeSWITCH's core stops accepting ESL commands — even while ports appear open — the heartbeat stops and Vigilmon alerts after 10 minutes.

Step 6: Configure Alert Channels

  1. Go to Alert Channels in Vigilmon and add Slack, email, or a webhook.
  2. Set Consecutive failures before alert to 2 on the ESL and SIP monitors — FreeSWITCH reloads can cause a brief socket reset that should not trigger a page.
  3. Use Maintenance windows before running fs_cli -x "reload mod_sofia" or other module reloads that temporarily drop connections.

Summary

| Monitor | Target | What It Catches | |---|---|---| | TCP ESL | :8021 | FreeSWITCH crash, mod_event_socket failure | | TCP SIP | :5060 | mod_sofia crash, SIP stack down | | TCP SIPS | :5061 | TLS SIP profile bind failure | | HTTP REST | :8080/ | HTTP management API down | | Cron heartbeat | ESL command check | Core unresponsive, IVR/dialplan broken |

FreeSWITCH's modular architecture means the process can be running while critical subsystems have silently failed. With Vigilmon monitoring the ESL port, SIP stack, TLS profile, REST interface, and a live dialplan heartbeat, you get full external visibility into every layer of your FreeSWITCH deployment.

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