The Manager API is a TCP-based interface exposed by the VoIPmonitor sniffer on port 5029. It allows the GUI, scripts, and external tools to query sensor status, list active calls, and perform administrative tasks.

Overview

Feature	Details
Default Port	5029 (TCP)
Default Bind	`127.0.0.1` (localhost only)
Encryption	Enabled by default since sniffer 2024.02.2 / GUI 26.20
Alternative	Unix socket (`managersocket` option)

ℹ️ Note: The GUI communicates with sensors via Manager API. If the GUI shows a sensor as disconnected, verify port 5029 is accessible.

Configuration

Basic Settings

# /etc/voipmonitor.conf

# Bind address - use 127.0.0.1 for local-only access
# Use 0.0.0.0 to allow remote connections (requires firewall!)
managerip = 127.0.0.1

# TCP port (default: 5029)
managerport = 5029

⚠️ Warning: If you change managerip to allow remote access, ensure proper firewall rules are in place. The Manager API can expose sensitive call data.

Unix Socket (Alternative)

For local scripts that need unencrypted access:

# /etc/voipmonitor.conf
managersocket = /tmp/vm_manager_socket

The socket file is created when the sniffer starts. Use with nc -U:

echo 'listcalls' | nc -U /tmp/vm_manager_socket

💡 Tip: Unix sockets bypass encryption, making them useful for local automation scripts.

Encryption

Since sniffer version 2024.02.2 and GUI 26.20, Manager API communication is encrypted by default using AES.

How It Works

The GUI generates an AES key and stores it in the database
The sniffer reads the key from the database on startup
All communication between GUI and sniffer is encrypted

No manual configuration is required - key exchange is automatic.

Manual Key Configuration

If automatic key exchange fails (e.g., sniffer cannot access GUI database), configure keys manually:

Generate a key using the GUI:

cd /var/www/html
php php/run.php generate_aes_key    # Generate without saving
php php/run.php store_aes_key       # Generate and save to DB
php php/run.php delete_aes_key      # Remove key from DB

Configure in voipmonitor.conf (sniffer):

# Base64-encoded AES key and IV
manager_aes_key = <base64_key>
manager_aes_iv = <base64_iv>

Configure in configuration.php (GUI):

$VPMANAGER_AES_KEY = '<base64_key>';
$VPMANAGER_AES_IV = '<base64_iv>';
$VPMANAGER_AES_CIPHER = 'aes-128-cbc';  // default

Disable Encryption (Debugging Only)

⚠️ Warning: Only disable encryption for testing. Never in production!

# /etc/voipmonitor.conf
manager_enable_unencrypted = yes

With encryption disabled, you can use simple netcat:

echo 'listcalls' | nc 127.0.0.1 5029

HA Configuration (Multiple GUIs)

When using High Availability with multiple GUI servers sharing a database, ensure all use the same encryption key:

# Copy key from HOST1 to HOST2
key=$(echo "SELECT content FROM \`system\` WHERE type = 'manager_key'" | \
  mysql -h HOST1 -u root -pPASS1 -D voipmonitor 2>/dev/null | grep key)

echo "UPDATE \`system\` SET content = '$key' WHERE type = 'manager_key'" | \
  mysql -h HOST2 -u root -pPASS2 -D voipmonitor 2>/dev/null

API Commands

Command Reference

Command	Description	Output Format
`listcalls`	List all active calls	JSON
`listregisters`	List active SIP registrations	JSON
`sniffer_stat`	Sensor status and statistics	JSON
`sniffer_threads`	Thread CPU usage and status	Text
`sniffer_version`	Sniffer version	Text
`reload`	Reload configuration from file	Text
`terminating`	Gracefully stop the sniffer	Text

listcalls

Returns JSON array of active calls with caller, called, codec, duration, and quality metrics.

echo 'listcalls' | nc -U /tmp/vm_manager_socket

With filter (via GUI's run.php):

php php/run.php send_manager_cmd -s 1 -c 'listcalls {"limit":30,"filter":[{"caller":"%123%"}]}'

sniffer_stat

Returns comprehensive sensor status in JSON format, including the pbStatString field which contains the syslog status line.

echo 'sniffer_stat' | nc -U /tmp/vm_manager_socket

Key fields in response:

version - Sniffer version
uptime - Seconds since start
calls - Active call count
pbStatString - Status string (same as syslog output)

 * Contains: SQLq[C:X M:Y] - SQL queue sizes
 * Contains: t0CPU[X%] - Packet capture thread CPU

ℹ️ Note:

sniffer_threads

Shows CPU usage of internal threads. Useful for diagnosing performance issues.

echo 'sniffer_threads' | nc -U /tmp/vm_manager_socket

Options:

sniffer_threads no_sort - Don't sort by CPU load
sniffer_threads only_traffic - Only threads with traffic
sniffer_threads all - Include idle threads
sniffer_threads line - Single-line output format

reload

Reloads configuration from /etc/voipmonitor.conf without restart.

echo 'reload' | nc -U /tmp/vm_manager_socket

⚠️ Warning: Not all parameters can be changed at runtime. Some require a full service restart.

Usage Examples

With Encryption Disabled

# Simple query
echo 'listcalls' | nc 127.0.0.1 5029

# Get version
echo 'sniffer_version' | nc 127.0.0.1 5029

With GUI's run.php (Encrypted)

By sensor ID:

php /var/www/html/php/run.php send_manager_cmd -s 2 -c listcalls
# -s = sensor ID from GUI
# -c = command

By IP address:

php /var/www/html/php/run.php send_manager_cmd -h 10.0.0.50 -p 5029 -a -c listcalls
# -h = host
# -p = port
# -a = enable encryption
# -c = command

Via Unix Socket

# Define socket in config first: managersocket = /tmp/vm_manager_socket
echo 'listcalls' | nc -U /tmp/vm_manager_socket

# Or enable socket at runtime
echo 'manager_file start /tmp/vm_manager_socket' | nc 127.0.0.1 5029

Remote Access via SSH

# Query remote sensor through SSH tunnel
ssh sensor-host 'echo listcalls | nc -U /tmp/vm_manager_socket'

Server API (Port 60024)

ℹ️ Note: Don't confuse Manager API (5029) with Server API (60024). Server API is used for distributed sensor communication in client/server deployments.

In distributed deployments, the central server exposes port 60024 for probe management:

# List connected probes
echo '{"type_connection":"manager_command","command":"active"}' | nc 127.0.0.1 60024

# Send command to specific probe
echo '{"type_connection":"gui_command","sensor_id":1011,"command":"terminating"}' | nc 127.0.0.1 60024

Troubleshooting

GUI Cannot Connect to Sensor

Symptom	Cause	Solution
Sensor shows disconnected	Port 5029 blocked	Check firewall: `telnet sensor-ip 5029`
Sensor shows disconnected	Wrong Manager IP in GUI	Settings → Sensors → verify IP
Encryption error	Key mismatch	Regenerate key: `php run.php store_aes_key`
"nc: invalid option -- U"	Wrong netcat version	Install `netcat-openbsd` package

Testing Connectivity

# Test from GUI server to sensor
telnet sensor-ip 5029

# Test with encryption disabled (temporarily)
echo 'sniffer_version' | nc sensor-ip 5029

Netcat -U Not Working

On Debian/Ubuntu, install the correct netcat package:

apt install netcat-openbsd