Sniffer installation

From VoIPmonitor.org
Revision as of 02:23, 6 January 2026 by Admin (talk | contribs) (Add section explaining two-component architecture (Sniffer + Web GUI) to clarify 'static' package)

Category:Installation

This guide provides step-by-step instructions for installing the VoIPmonitor sensor (sniffer). The recommended method for all modern Linux distributions is to use the pre-compiled static binary.

Understanding VoIPmonitor Components

VoIPmonitor consists of two separate components that work together:

  • Sniffer / Sensor (This Guide)
    • A static binary that captures and analyzes VoIP traffic
    • Runs as a background service on Linux servers
    • Complete and self-contained - the "static" binary is the full production package
    • Does NOT require a web server, PHP, or database to operate on the same machine (it connects to an existing database)
  • Web GUI (Separate Installation)
    • A PHP-based web interface for viewing captured data and configuring settings
    • Requires a web server (Apache/nginx), PHP, MySQL/MariaDB, and additional dependencies
    • The GUI package depends on your PHP version - you must download the version matching your server's PHP
    • See GUI Installation Guide for complete setup instructions
Why are these separate?

The sniffer and web GUI are designed to run independently. You can deploy:

  • Multiple sniffers capturing traffic from different locations, all sending data to a single central GUI
  • Or install both components on the same server for small deployments

The term "Static" in the sniffer package name refers to the binary being self-contained (with embedded libraries), not to the feature set. The static sniffer binary is the complete, recommended production package - there is no separate "full" version.

Overview

The VoIPmonitor sensor installation process follows these steps:

Recommended Method: Static Binary Installation

A static binary includes all necessary libraries and is the quickest and most reliable way to get the sensor running on any supported Linux distribution with a kernel version of 2.6.18 or newer.

Step 1: Download the Correct Archive

First, download the latest stable binary for your system's architecture from the official website.

For 64-bit (x86_64) Systems (most common)
wget https://www.voipmonitor.org/current-stable-sniffer-static-64bit.tar.gz -O voipmonitor-sniffer.tar.gz
For 32-bit (i686) Systems
wget https://www.voipmonitor.org/current-stable-sniffer-static-32bit.tar.gz -O voipmonitor-sniffer.tar.gz
For ARMv6/v7 (e.g., Raspberry Pi)
wget https://www.voipmonitor.org/current-stable-sniffer-static-armv6k.tar.gz -O voipmonitor-sniffer.tar.gz

Step 2: Extract and Run the Install Script

The downloaded archive contains an installation script that automates the setup process. 

# Extract the archive
tar xzf voipmonitor-sniffer.tar.gz

# Navigate into the newly created directory
# The 'cd voipmonitor-*' command will work regardless of the exact version number
cd voipmonitor-*-static

# Run the installation script with root privileges
./install-script.sh

The install-script.sh will:

  • Copy the voipmonitor binary to /usr/local/sbin/
  • Copy the default configuration file to /etc/voipmonitor.conf
  • Copy the service startup script to /etc/init.d/voipmonitor
  • Attempt to enable the service to start on boot
Which user account should the service run as?

If the installation script asks which system user should run the VoIPmonitor sniffer service, you can select any option. The VoIPmonitor capture/sniffer service is always configured to run under the root account, regardless of the choice made during installation. This is necessary for packet capture privileges on the network interface. The systemd service file sets User=root explicitly (see systemd guide for details).

Step 3: Initial Configuration

After the installation, you must edit the main configuration file to connect the sensor to your database and set basic parameters. 

nano /etc/voipmonitor.conf

At a minimum, configure your database connection settings and the network interface to monitor.

Sensor ID Configuration (for Multi-Sensor Deployments)

If you are deploying multiple sniffer instances (either on the same server with multiple network interfaces, or on different servers), you must assign a unique sensor ID to each instance. 

# Set a unique numeric identifier (1-65535) for this sensor
id_sensor = 1
  • The sensor ID is stored in the cdr.id_sensor database column and allows you to distinguish which sensor captured each call.
  • This is essential in multi-sensor deployments, distributed architectures, or when using the Client/Server mode.
  • Leave this parameter unset (default) if you only have a single sensor deployment.

For detailed information, see id_sensor configuration.

System Resource Considerations

Before deploying a sniffer on a new server, ensure the server has adequate CPU, RAM, and disk I/O resources for your expected traffic load.

Resource Recommendation
CPU The main packet capture thread (t0) runs on a single CPU core. A modern Xeon with 2+ cores is recommended for production. Monitor t0CPU usage in logs – if consistently above 90-95%, you may need a faster CPU or additional sensors.
RAM Minimum 2-4 GB for small deployments (<500 concurrent calls). For high traffic (2000+ calls), consider 8-16 GB. If MySQL runs on the same server, carefully allocate RAM to avoid OOM killer events.
Disk I/O If recording audio, ensure adequate disk performance. A standard 7200 RPM SATA drive can handle ~2000 concurrent calls. For higher throughput, use SSD or RAID with WriteBack cache policy.
Storage Plan capacity based on your retention policy. Estimate space for PCAP files and CDR data based on average call duration and daily call volume.

For detailed performance tuning, refer to the Scaling and Performance Tuning guide.

Step 4: Service Management (systemd)

Modern Linux distributions use systemd to manage services. Use the following commands to control the sniffer:

Start the service
systemctl start voipmonitor
Stop the service
systemctl stop voipmonitor
Check the service status
systemctl status voipmonitor
Enable the service to start automatically on boot
systemctl enable voipmonitor

For a more detailed systemd service file template and advanced options, please see the systemd guide.

Step 5: Verification

After starting the service, verify that it is running correctly and capturing traffic:

1. Check service status
systemctl status voipmonitor

You should see Active: active (running).

2. Monitor live logs for traffic capture statistics
journalctl -u voipmonitor -f

Look for periodic output like calls[X][Y] PS[...] SQLq[0] to confirm the sensor is detecting traffic on the configured network interface.

For additional troubleshooting if the sensor is not capturing calls, see Sniffer Troubleshooting.

Troubleshooting Download Issues

If the primary download URL hangs or fails (especially on Debian 11/12), this is often caused by issues with the chain of redirects to SourceForge mirrors. In such cases, use the alternative direct download link that bypasses the redirects:

Alternative direct download for 64-bit systems
wget https://download.voipmonitor.org/current-stable-sniffer-static-64bit.tar.gz
Alternative direct download for 32-bit systems
wget https://download.voipmonitor.org/current-stable-sniffer-static-32bit.tar.gz
Alternative direct download for ARMv6/v7
wget https://download.voipmonitor.org/current-stable-sniffer-static-armv6k.tar.gz

= Downloading Specific Versions

If you need a specific version of the sniffer (e.g., `2025.07.1`), you can download it directly using the version number:

For 64-bit AMD64
wget https://download.voipmonitor.org/sniffer-develop/voipmonitor-amd64-VERSION-static.tar.gz
# Example:
wget https://download.voipmonitor.org/sniffer-develop/voipmonitor-amd64-2025.07.1-static.tar.gz
For 32-bit i686
wget https://download.voipmonitor.org/sniffer-develop/voipmonitor-i686-VERSION-static.tar.gz
For ARMv6/v7
wget https://download.voipmonitor.org/sniffer-develop/voipmonitor-armv6k-VERSION-static.tar.gz

Replace VERSION with the desired version number (e.g., `2025.07.1`, `2025.06.1`, etc.).

This alternative URL provides a direct download from voipmonitor.org, avoiding the redirect chain and potential SourceForge-related issues.

Advanced & Special Installation Cases

Installing on Legacy OS Versions (CentOS 6, Older Distributions)

For legacy operating systems like CentOS 6.9 or distributions with older glibc versions, newer static binaries may have compatibility issues. If you encounter problems with the latest binary, follow these steps:

Step 1: Determine your system's architecture
uname -a

Look for x86_64 (64-bit) or i686 (32-bit) in the output.

Step 2: Download the oldest available sniffer binary for your architecture from the VoIPmonitor download page rather than the latest version. Older binaries are more likely to be compatible with older glibc libraries.
# Example: Find the oldest stable version in the 64-bit category
# Download from the official download page and extract as normal
Step 3: Proceed with extraction and installation as described in Step 2 above.
Step 4: If you are also installing the GUI on the same legacy system and encounter Error: The ionCube Loader is not installed correctly or ioncube-related PHP errors
  • Download the "Linux glibc2.4 (64 bits)" legacy ionCube loader from the official ionCube website
  • Extract and install it according to the ionCube installation instructions for your PHP version
  • Verify the loader is correctly installed by running:
php --version

You should see the ionCube PHP Loader line listed without any error messages.

Installing a Specific or Older Version

If you need a specific version (e.g., one that includes the Wireshark SS7 module), you can find historical releases on the VoIPmonitor SourceForge page.

Copy the download link for the desired file and use it with the wget command from Step 1.

Example for version 20.4.4 with the SS7 module
wget https://sourceforge.net/projects/voipmonitor/files/20.4/voipmonitor-wireshark-amd64-20.4.4-static.tar.gz/download -O voipmonitor-sniffer.tar.gz

Then proceed with the extraction and installation as described above.

Installing a Development Build (Manual Upgrade)

If instructed by the support team, you can manually upgrade to a new development build. 

# Create a temporary directory and download the new build
mkdir /tmp/new-sniffer && cd /tmp/new-sniffer
wget https://download.voipmonitor.org/some-development-build.tar.gz -O sniffer.tar.gz
tar xzf sniffer.tar.gz

# Stop the current service and back up the old binary
systemctl stop voipmonitor
mv /usr/local/sbin/voipmonitor /usr/local/sbin/voipmonitor.backup

# Copy the new binary into place and start the service
cp voipmonitor-*-static/voipmonitor /usr/local/sbin/voipmonitor
systemctl start voipmonitor

Compiling from Source

For developers or special use cases, you can compile the sniffer from its source code. This is not the recommended method for most users.

Clone the master branch (stable)
git clone https://github.com/voipmonitor/sniffer.git
Or clone the develop branch (latest features)
git clone -b develop https://github.com/voipmonitor/sniffer.git

Then follow the instructions in the README file within the repository.

Example: Compiling from Source on Debian 12 (e.g., for ARM64)

1. Install required dependencies
apt install git make g++ unixodbc-dev libvorbis-dev libmp3lame-dev libmpg123-dev \
    libpcap-dev libssl-dev libsnappy-dev libcurl4-openssl-dev libicu-dev libpng-dev \
    libjpeg-dev libfftw3-dev libjson-c-dev librrd-dev libglib2.0-dev libxml2-dev \
    libmariadb-dev-compat libmariadb-dev libzstd-dev liblz4-dev liblzma-dev \
    liblzo2-dev gnutls-dev libgcrypt-dev libgoogle-perftools-dev
2. Clone and compile
cd /usr/src
git clone https://github.com/voipmonitor/sniffer.git
cd sniffer
./configure
make
3. Install the compiled binary
# Back up the existing static binary if present
mv /usr/local/sbin/voipmonitor /usr/local/sbin/voipmonitor.static

# Install the newly compiled binary
mv /usr/src/sniffer/voipmonitor /usr/local/sbin/voipmonitor
4. (Optional) Enable automatic upgrades via git

Add the following to /etc/voipmonitor.conf: 

upgrade_by_git = yes
git_folder = /usr/src/sniffer
5. Restart the service
systemctl restart voipmonitor

Uninstallation

To completely remove the VoIPmonitor sensor from a system, follow these steps.

For systemd-based Systems (Recommended)

# 1. Stop and disable the service
systemctl stop voipmonitor
systemctl disable voipmonitor

# 2. Remove the service files and binary
rm -f /etc/systemd/system/voipmonitor.service
rm -f /etc/init.d/voipmonitor
rm -f /usr/local/sbin/voipmonitor

# 3. Reload systemd to apply changes
systemctl daemon-reload

# 4. (Optional) Back up and remove the configuration file
mv /etc/voipmonitor.conf /etc/voipmonitor.conf.backup

# 5. (Optional) Delete the spool directory (contains all captured data)
# WARNING: This is irreversible!
# rm -rf /var/spool/voipmonitor

For Older SysV-based Systems

Run the following commands to stop the service and remove its files: 

/etc/init.d/voipmonitor stop
update-rc.d voipmonitor remove
rm -f /etc/init.d/voipmonitor
rm -f /usr/local/sbin/voipmonitor
mv /etc/voipmonitor.conf /etc/voipmonitor.conf.backup

See Also

AI Summary for RAG

Summary: Step-by-step guide for installing the VoIPmonitor sensor (sniffer) using pre-compiled static binaries. The process involves: downloading the correct archive for your architecture (64-bit, 32-bit, ARM), extracting and running install-script.sh, configuring /etc/voipmonitor.conf (database, network interface, id_sensor for multi-sensor deployments), and managing the service with systemctl. For legacy systems (CentOS 6, older glibc): check architecture with uname -a, download the oldest available binary for better compatibility, and use the "Linux glibc2.4" ionCube loader if installing GUI on legacy systems. Includes system resource requirements, verification steps, alternative download URLs for when primary links fail, compiling from source for ARM64/Debian 12, and complete uninstallation procedures. Keywords: install, installation, setup, sniffer, sensor, static binary, install-script.sh, download, wget, tar.gz, systemd, systemctl, id_sensor, multi-sensor, compile from source, git, ARM64, Debian 12, uninstall, remove, CentOS 6, legacy, older systems, glibc, old binary, oldest available, ionCube loader, glibc2.4, php --version, x86_64, i686, uname -a Key Questions:

  • How do I install the VoIPmonitor sniffer on a legacy CentOS 6 system?
  • Which sniffer binary should I use for older operating systems?
  • How do I check if my system is 32-bit or 64-bit?
  • What do I do if the ionCube Loader is not installed correctly on a legacy system?
  • How do I install the VoIPmonitor sniffer?
  • Where can I download the sensor static binary?
  • How do I configure id_sensor for multi-sensor deployments?
  • What are the CPU and RAM requirements?
  • How do I start and enable the voipmonitor service?
  • What if the download URL hangs or fails?
  • How do I compile from source on Debian 12 or ARM64?
  • How do I uninstall VoIPmonitor completely?
Retrieved from "https://www.voipmonitor.org/doc/index.php?title=Sniffer_installation&oldid=7504"