Cloud

VoIPmonitor Cloud Service Architecture

This document details the architecture of the VoIPmonitor Cloud Service. In this service model, the customer is responsible only for running the on-premise sniffer, while the database and web GUI are hosted and managed by VoIPmonitor.

Quick Start: Getting Started with Cloud Service =

Free 30-Day Trial:

If you do not have a VoIPmonitor Cloud Service license, you can try the cloud GUI free for 30 days. To start your trial:

1. Log in to the VoIPmonitor client area at https://www.voipmonitor.org/portal/
2. Navigate to the my services section
3. Order the free 30-day trial for the cloud GUI service
4. The trial gives you full access to all cloud features for 30 days

After ordering the trial, follow the steps below to connect your server.

Quick Start: Connecting Your On-Premise Server to the Cloud

This is the fastest and recommended way to connect your on-premise VoIP server (orPBX) to the hosted VoIPmonitor cloud GUI.

Automated Installation Script Method (Recommended)

This method requires only 3 steps and automatically configures your sniffer to send data to the cloud GUI.

Step 1

Download the Installation Script

• Log in to the VoIPmonitor Portal at https://www.voipmonitor.org/portal/
• Navigate to the my services section
• Find your Cloud service (trial or licensed) and locate the Cloud Service installation script
• Download the script (it will be a small shell script with a .sh extension)

Step 2

Run the Script on Your Sniffer Server

• Upload or copy the script to your sniffer server (the machine that will capture VoIP traffic)
• Make the script executable and run it with root or sudo privileges:

chmod +x voipmonitor-cloud-install.sh
sudo ./voipmonitor-cloud-install.sh

The script will automatically:

• Download and install the latest voipmonitor sniffer binary
• Configure voipmonitor.conf with the correct cloud server settings
• Set up the service to start automatically
• Connect to your cloud account using your license key

Step 3

Verify Connection

• After the script completes, wait a few seconds for the sensor to register
• Log in to your VoIPmonitor Cloud GUI
• Your sensor should automatically appear in the dashboard

This is the recommended method as it eliminates manual configuration errors and ensures all settings are correct.

Manual Configuration Method

If you prefer to configure your sniffer manually (for example, if you already have voipmonitor installed and want to keep your existing setup), you must manually edit voipmonitor.conf to set the cloud server destination and enable packet sender mode.

Required configuration in /etc/voipmonitor.conf:

server_destination = cloud.voipmonitor.org
server_destination_port = 60023
packetbuffer_sender = yes

After making these changes, restart the voipmonitor service:

systemctl restart voipmonitor

Then verify your sensor appears in the VoIPmonitor Cloud GUI dashboard.

Cloud Service on AWS: Resource Configuration

When deploying the VoIPmonitor sniffer on AWS EC2 instances (for example, for a hosted SIP server like Brekeke), it is important to configure resource limits properly to prevent memory exhaustion and ensure stable operation.

AWS environments have finite CPU, RAM, and disk resources. If VoIPmonitor is not properly configured, it can consume all available memory, leading to packet loss, service crashes, or performance degradation on the host system.

Required Configuration Parameters

Add these settings to /etc/voipmonitor.conf on your AWS EC2 instance:

Ringbuffer Configuration

ringbuffer controls the size of the packet capture ring buffer in memory. Larger values help handle traffic bursts but consume more RAM.

ringbuffer = 500

Recommended values based on traffic volume:

• 10-100 Mbit traffic: ringbuffer = 50-100
• 100-500 Mbit traffic: ringbuffer = 500-1000
• 500+ Mbit traffic: ringbuffer = 1000-2000 (maximum allowed)

AWS Note: If you are running VoIPmonitor on the same EC2 instance as your PBX/SIP server, be conservative with ringbuffer to avoid starving the PBX of memory.

Memory Buffer Limit

max_buffer_mem limits the total memory VoIPmonitor can use for packet buffers. This prevents the service from consuming all available system RAM.

max_buffer_mem = 2000

Default value: 2000 (MB)

AWS Considerations:

• On EC2 instances with limited RAM (e.g., t3.small with 2GB), reduce this value (e.g., max_buffer_mem = 500)
• On larger instances (e.g., m5.large with 8GB or more), the default value is typically acceptable
• Monitor memory usage with htop or AWS CloudWatch metrics after deployment

= Spooldir Configuration

spooldir defines the directory where captured packet files (PCAPs) are stored. AWS EC2 instances typically use ephemeral instance store or EBS volumes.

spooldir = /var/spool/voipmonitor

AWS Best Practices:

• Use EBS volumes (gp3 or io2) for durable storage. Instance store is lost if the instance stops.
• Ensure the volume has sufficient IOPS for your workload:
  • For low traffic (under 10 concurrent calls): gp2 or general purpose gp3
  • For high traffic (50+ concurrent calls): gp3 with provisioned IOPS or io2 volume type
• Mount EBS volume to /var/spool/voipmonitor or configure alternative spooldir location

Example: Using EBS volume mounted at /mnt/voipmonitor

spooldir = /mnt/voipmonitor

Storage Pool Size Limit

maxpoolsize sets the maximum disk space (in MB) that VoIPmonitor will use for PCAP files before the auto-cleanup process removes old files.

maxpoolsize = 204800

Default behavior: If unset, VoIPmonitor continues writing until the disk is full, which can cause the system to crash.

AWS Environment Recommendations:**

| EC2 Instance Size | Typical EBS Volume Size | Recommended maxpoolsize | | :--- | :--- | :--- | | t3.small (2GB RAM) | 20-50 GB gp3 | maxpoolsize = 40960 (20 GB) or higher | | m5.large (8GB RAM) | 100-200 GB gp3/io2 | maxpoolsize = 102400 (100 GB) or higher | | m5.xlarge (16GB RAM) | 300-500 GB gp3/io2 | maxpoolsize = 204800 (200 GB) or higher | | Custom/high traffic | 500+ GP3/io2 | maxpoolsize = 307200 (300 GB) or higher |

• Always set maxpoolsize to leave some free space for OS and logs (at least 10-20% of total disk space)
• Monitor disk usage with: df -h /var/spool/voipmonitor
• Consider maxpooldays as an alternative cleanup strategy (based on time vs. size):

maxpooldays = 30

Complete Example Configuration for AWS

Here is a complete AWS-optimized configuration for a medium-workload instance (m5.large, 8GB RAM, 100 GB EBS gp3 volume):

[general]

# Cloud connection settings
server_destination = cloud.voipmonitor.org
server_destination_port = 60023
packetbuffer_sender = yes

# Sensor identification
id_sensor = 1

# Capture interface (typically eth0 or ens5 on AWS)
interface = eth0

# AWS Resource Limits
ringbuffer = 500
max_buffer_mem = 2000

# Storage settings (adjust paths if using EBS mount)
spooldir = /var/spool/voipmonitor
maxpoolsize = 102400

AWS License Configuration

When deploying VoIPmonitor on AWS EC2 instances, you must configure the system to allow license checks to function correctly. AWS instances may have restricted access to certain device files that are used for license validation.

# On AWS EC2 instances, allow license checks by setting correct permissions
chmod 644 /dev/root

⚠️ Warning: The chmod 644 /dev/root command is required for AWS EC2 instances to allow VoIPmonitor license activation and validation. Without this permission, the license check may fail and the GUI will display licensing errors.

Monitoring and Debugging in AWS

Check resource usage

# Check memory usage
free -h

# Check disk usage on spooldir
df -h /var/spool/voipmonitor

# Check VoIPmonitor service status
systemctl status voipmonitor

# View real-time logs for buffer issues
journalctl -u voipmonitor -f | grep -i "buffer\|memory\|full"

Common AWS-Specific Issues

Out of Memory Errors

• Symptoms: VoIPmonitor process killed by OOM (Out of Memory) killer
• Solution: Reduce max_buffer_mem and/or ringbuffer, or upgrade to a larger EC2 instance

Disk Full Errors

• Symptoms: System becomes unresponsive, "No space left on device"
• Solution: Always configure maxpoolsize or maxpooldays to prevent uncontrolled growth

High CPU Usage

• Symptoms: Packet drops in logs, slow UI response
• Solution: Increase EC2 vCPU count or optimize sipport and capture filters

Service Specifications

The VoIPmonitor Cloud Service has the following service limits and specifications:

• Concurrent Channels Maximum: The service supports up to 2000 concurrent channels.
• CDR Retention Period: Call Detail Records (CDRs) are retained for 25 days in the cloud database.
• PCAP Storage Location: SIP+RTP packet storage (PCAP files) is NOT stored in the cloud. If packet capture storage is enabled, all PCAP files are stored on the local sniffer's storage only.

These limits are fixed and apply to all Cloud Service customers. If your requirements exceed these specifications, consider an on-premise VoIPmonitor deployment.

Core Architecture: Client-Server Model

The architecture separates the data capture process (on-premise) from the data storage and analysis interface (in the cloud).

• Sniffer (Client): A VoIPmonitor sniffer runs on the customer's network (either on a dedicated machine or the PBX itself). Its only job is to capture and process VoIP traffic locally. Multiple sniffers can be deployed across various locations.
• Cloud Platform (Server): The central database (storing call metadata) and the web GUI are hosted and managed by VoIPmonitor. All user interaction, analysis, and reporting is done through this central cloud interface.

Data Flow from Sniffer to Cloud

The key aspect of the cloud architecture is how data is transmitted from the customer's sniffer to the hosted server. The system primarily operates in one of two modes.

1. Standard Mode: Local Processing & CDR Upload

This is the default and most efficient mode. The on-premise sniffer captures all VoIP traffic, analyzes it locally, and generates a Call Detail Record (CDR) for each call.

• The sniffer sends only the CDR metadata to the cloud database.
• The actual voice packets (PCAP) are not sent to the cloud; they are discarded after local analysis.

This model ensures minimal bandwidth usage, as only small metadata files are transferred over the internet.

2. Optional Mode: On-Demand Packet Capture Retrieval

For deep diagnostics, users can enable packet capture storage. The process is designed to keep sensitive data on-premise unless explicitly needed.

1. Selective Local Storage: Storing packet captures is not an all-or-nothing feature. The user defines granular Capture Rules to control exactly which calls are saved. These rules can be based on criteria like IP addresses, telephone numbers, or even specific SIP packet headers. Only calls that match a rule will have their PCAP file saved to the sniffer's local disk.
2. On-Demand Request: A user can request to download a PCAP file or listen to a call through the cloud web GUI.
3. Direct Download: The cloud platform instructs the sniffer to serve the requested file. The download then occurs directly from the customer's sniffer to the user's browser, bypassing a permanent upload to the cloud.

This on-demand mechanism ensures that large and sensitive packet capture files remain within the customer's network perimeter, only traversing the internet when requested by an authorized user.

Troubleshooting: Sensor Not Appearing in Cloud

If your on-premise sniffer is running but does not appear in the VoIPmonitor Cloud interface, follow these troubleshooting steps.

Common Issue: ARM64 Cloud Connectivity Bug

On ARM64 architecture systems (aarch64), certain voipmonitor binary builds have a known cloud connectivity issue where the sensor runs locally but fails to properly handshake with the cloud server.

Symptoms

• The voipmonitor process is running and appears active with systemctl status voipmonitor
• The sensor is capturing traffic locally (check via journalctl -u voipmonitor -f)
• No sensor appears in your VoIPmonitor Cloud interface
• Configuration is correct (server_destination, server_destination_port, packetbuffer_sender)
• Firewall rules allow outbound TCP to port 60023

Solution

Update to the Corrected ARM64 Binary

This issue is resolved by downloading and installing a special static binary build that includes the ARM64 cloud connectivity fix.

# 1. Stop the voipmonitor service
systemctl stop voipmonitor

# 2. Request the corrected ARM64 static binary from VoIPmonitor support
# The support team will provide a specific download link for the corrected build
# Example URL format:
# wget https://download.voipmonitor.org/path/to/voipmonitor-arm64-fixed.tar.gz

# 3. Extract the archive
tar xzf voipmonitor-arm64-fixed.tar.gz
cd voipmonitor-*-static

# 4. Backup the existing binary and replace it
mv /usr/local/sbin/voipmonitor /usr/local/sbin/voipmonitor.backup
cp voipmonitor /usr/local/sbin/voipmonitor

# 5. Restart the service
systemctl start voipmonitor

# 6. Verify the sensor appears in Cloud interface
journalctl -u voipmonitor -f

Important Notes

• Do NOT compile from source to fix this issue - use the corrected static binary provided by support
• The fix is specific to ARM64 architecture; x86_64 and 32-bit systems are not affected
• After installing the corrected binary, the sensor should appear in Cloud within a few seconds

General Configuration Verification

If the ARM64 issue is not applicable, verify your cloud connectivity configuration:

1. Check voipmonitor.conf cloud settings

grep -E "server_destination|packetbuffer_sender" /etc/voipmonitor.conf

Required for VoIPmonitor Cloud:

server_destination = cloud.voipmonitor.org
server_destination_port = 60023
packetbuffer_sender = yes

2. Verify network connectivity to cloud

# Test outbound connection to VoIPmonitor Cloud
nc -zv cloud.voipmonitor.org 60023

3. Check for firewall issues

• Ensure outbound TCP traffic to cloud.voipmonitor.org:60023 is allowed
• Check local firewall (ufw, firewalld, iptables)
• Check corporate or cloud provider firewalls

4. First-Time Setup

Initialize Cloud Database

If this is your first time connecting to VoIPmonitor Cloud, you must log in to the Cloud GUI to initialize your cloud database before the service will connect correctly.

Symptoms of uninitialized database

• "failed read rsa key" error in journalctl -u voipmonitor -f
• "loss connection" errors when trying to connect to the cloud service
• The voipmonitor service fails to start or repeatedly tries to reconnect
• Sensor configuration (server_destination, server_destination_port, packetbuffer_sender) is correct

Solution

Initialize Your Cloud Database

1. Log in to the VoIPmonitor Cloud GUI at https://cloud.voipmonitor.org using your voipmonitor.org client area credentials.
2. This action automatically creates the necessary tables and content in your cloud database.
3. Restart the voipmonitor service on your server:

   systemctl restart voipmonitor
   

4. Verify that the sniffer appears as green in the Cloud GUI under Settings -> Sensors.

The RSA key error occurs because the service cannot authenticate with your cloud database until the database structure has been created.

5. Verify sensor IDs match

• If id_sensor is set in voipmonitor.conf, ensure it is unique (no collision with other sensors)
• The sensor ID should match what you expect to see in the Cloud interface

6. Review logs for errors

# Check cloud-specific connection errors
journalctl -u voipmonitor -f | grep -i "cloud\|server\|connection"

AI Summary for RAG

Summary: This document explains the VoIPmonitor Cloud Service, a client-server architecture where the customer runs one or more sniffer clients on-premise, while VoIPmonitor hosts the database and web GUI. The cloud service offers a free 30-day trial for users who want to try the hosted GUI without committing. To start the trial, log in to the VoIPmonitor Portal at https://www.voipmonitor.org/portal/, navigate to the 'my services' section, and order the free 30-day trial for the cloud GUI service. Quick Start section covers the automated installation script method: log in to VoIPmonitor Portal, navigate to 'my services' section, find your Cloud service (trial or licensed) and download the Cloud Service installation script, run it on the sniffer server with sudo. The script automatically downloads/install sniffer binary, configures voipmonitor.conf with cloud settings, sets up the service, and connects to cloud account using license key. Alternative manual configuration method requires setting server_destination=cloud.voipmonitor.org, server_destination_port=60023, packetbuffer_sender=yes. The sniffer's primary mode involves local processing of VoIP traffic, sending only lightweight Call Detail Records (CDRs) to the cloud. Full packet captures (PCAPs) are not automatically uploaded; instead, they are selectively stored on the local sniffer based on user-defined 'capture rules' (e.g., by IP address, phone number, or SIP headers). These stored PCAPs can be downloaded on-demand directly from the sniffer when requested by a user through the cloud GUI. This model is for users who want to avoid managing server infrastructure. Service limits: 2000 concurrent channels maximum, 25 days CDR retention, PCAPs stored locally only. Cloud Service on AWS section provides critical configuration guidance for deploying the sniffer on AWS EC2 instances: configure ringbuffer (50-2000 MB based on traffic, recommended 500+ for AWS), max_buffer_mem (default 2000 MB, reduce on small instances to prevent OOM), spooldir (use EBS volumes gp3/io2 for durability, not instance store), maxpoolsize (ALWAYS set to prevent disk full, recommended values per EC2 instance size: 40960 for t3.small, 102400 for m5.large, 204800 for m5.xlarge, or higher for custom/high traffic). Complete AWS example configuration provided with cloud connection settings and resource limits. AWS-specific troubleshooting: Out of Memory errors (reduce max_buffer_mem/ringbuffer or upgrade instance), Disk Full errors (configure maxpoolsize or maxpooldays), High CPU usage (increase vCPUs or optimize filters). Troubleshooting section covers ARM64 cloud connectivity issue where sensor runs locally but does not appear in cloud - requires corrected static binary from support, not configuration changes. Also includes general troubleshooting steps: verify server_destination=cloud.voipmonitor.org, server_destination_port=60023, packetbuffer_sender=yes, test nc -zv cloud.voipmonitor.org 60023, check firewall rules. First-time setup troubleshooting: if voipmonitor service fails to start with 'failed read rsa key' error or 'loss connection' error, you must log in to https://cloud.voipmonitor.org using voipmonitor.org client area credentials to initialize the cloud database (this creates necessary tables and content), then restart voipmonitor service and verify sensor appears green in Settings -> Sensors. Verify unique id_sensor if configured, review logs with journalctl -u voipmonitor -f | grep -i "cloud|server|connection". Common issue: newly installed sensor agent not sending data to hosted cloud server - usually caused by incorrect id_sensor (must be unique per sensor), firewall blocking TCP port 60023, failed cloud database initialization, wrong server_destination settings, or outdated binary (especially on ARM64 architecture). Keywords: cloud service, cloud architecture, client-server, on-premise sniffer, hosted database, hosted GUI, installation script, automated setup, manual configuration, local processing, CDR, Call Detail Record, local storage, packet capture, PCAP, on-demand download, capture rules, SIP headers, managed service, troubleshooting, ARM64, cloud connectivity bug, sensor not appearing, server_destination, server_destination_port=60023, packetbuffer_sender, firewall, failed read rsa key, loss connection, cloud database initialization, first-time setup, cloud.voipmonitor.org, sensor agent, not sending data, cloud server, 60023, TCP port, free 30-day trial, trial period, my services, AWS, EC2, AWS configuration, ringbuffer, max_buffer_mem, spooldir, maxpoolsize, AWS resource limits, EBS volume, gp3, io2, OOM killer, out of memory, disk full, AWS troubleshooting, Brekeke SIP server AWS Key Questions:

• How do I connect my on-premise server to VoIPmonitor Cloud?
• What is the fastest way to set up cloud connectivity?
• Why is my newly installed VoIPmonitor sensor agent not sending data to the hosted cloud server?
• How do I troubleshoot a sensor that is not appearing in the VoIPmonitor Cloud interface?
• What are the required settings for connecting a sensor to VoIPmonitor Cloud?
• Why is TCP port 60023 important for VoIPmonitor Cloud connectivity?
• How do I use the automated installation script?
• Where do I download the cloud installation script?
• Can I configure the sniffer manually instead of using the script?
• How does the VoIPmonitor Cloud Service architecture work?
• Who is the cloud service intended for?
• Is my call data (PCAP) stored in the cloud?
• How can I control which calls have their packet captures saved?
• How are Call Detail Records (CDRs) and packet captures (PCAPs) handled differently?
• What data does the on-premise sniffer send to the cloud?
• How can I access a full packet capture for a specific call?
• What are the main benefits of this cloud model?
• Why does my ARM64 sensor not appear in the VoIPmonitor Cloud interface?
• How do I fix the ARM64 cloud connectivity issue?
• What are the required voipmonitor.conf settings for VoIPmonitor Cloud?
• How do I test if my firewall is blocking cloud connectivity?
• How do I fix "failed read rsa key" error when connecting to VoIPmonitor Cloud?
• What causes "loss connection" errors when voipmonitor service starts?
• Why does my first cloud connection fail with RSA key errors?
• How do I initialize my VoIPmonitor Cloud database?
• Does VoIPmonitor Cloud offer a free trial?
• How do I get started with the free 30-day trial for VoIPmonitor Cloud?
• Where is the installation script located for Cloud Service?
• How do I deploy VoIPmonitor Cloud on AWS EC2?
• What configuration parameters should I set for VoIPmonitor on AWS?
• What is the ringbuffer setting for AWS deployments?
• How do I prevent memory exhaustion on AWS EC2?
• What is max_buffer_mem and how should I configure it for AWS?
• Which storage type should I use for VoIPmonitor spooldir on AWS?
• What is the recommended maxpoolsize for different EC2 instance sizes?
• How do I fix out of memory errors on AWS when running VoIPmonitor?
• How do I prevent disk full errors with VoIPmonitor on AWS?
• How should I configure VoIPmonitor for a Brekeke SIP server hosted in AWS?