Sniffer upgrade

This guide provides step-by-step instructions for upgrading or downgrading the VoIPmonitor sensor (sniffer). There are two primary methods: using the Web GUI for simplicity, or performing a manual update via the command line for more control.

Method 1: Upgrading via the Web GUI (Recommended)

This is the easiest and safest way to manage your sensor versions. This method only works for sensors that are currently running and connected to the GUI.

1. Navigate to Settings -> Sensors in the VoIPmonitor GUI.
2. Find the sensor you wish to update. If you need to see more details or older versions, click the [+] icon to expand the sensor's information.
3. Click the blue UPGRADE button. A dropdown menu will appear.
4. Select the desired version from the list. The list will contain the latest stable release as well as several previous versions for downgrading.
5. The GUI will automatically handle the download and restart of the remote sensor service.

Method 2: Manual Upgrade/Downgrade (via Command Line)

This method gives you full control and is necessary if the GUI method is not available or if you need to install a specific development build.

Step 1: Stop the Running Sniffer

First, log in to the sensor's server via SSH and stop the service. For modern systems using systemd:

systemctl stop voipmonitor

For older systems using SysV init:

/etc/init.d/voipmonitor stop

Tip: If the service fails to stop, you may need to terminate the process manually as a last resort: `killall -9 voipmonitor`

Step 2: Download the Sniffer Archive

Download the latest stable static binary from the official VoIPmonitor website. This package contains all necessary files.

# This command downloads the latest stable 64-bit static sniffer
wget https://www.voipmonitor.org/current-stable-sniffer-static-64bit.tar.gz -O voipmonitor-sniffer.tar.gz

If you need a specific older version or a special build (like one with SS7 support), you must get the direct download link from the support team or historical archives and use it with the `wget` command.

Step 3: Install the New Binary

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

# Navigate into the new directory. The wildcard (*) handles any version number.
cd voipmonitor-*-static

# (Recommended) Back up your old binary
mv /usr/local/sbin/voipmonitor /usr/local/sbin/voipmonitor.backup

# Copy the new binary into place
cp ./voipmonitor /usr/local/sbin/voipmonitor

# Ensure the new binary is executable
chmod +x /usr/local/sbin/voipmonitor

Step 4: Start the Service

Finally, start the sniffer service again.

systemctl start voipmonitor

Or for older systems:

/etc/init.d/voipmonitor start

Verifying the Version

After an upgrade or downgrade, it's important to verify that the correct version is running.

Local Check

You can check the version directly from the binary on the sensor's server:

/usr/local/sbin/voipmonitor --version

Or, for more detail:

/usr/local/sbin/voipmonitor | head

Remote Check (via Manager API)

If the sniffer is running, you can query its version remotely using its manager API (default port 5029):

echo 'sniffer_version' | nc 127.0.0.1 5029

Reinstalling After Operating System Upgrades

After a major operating system upgrade (for example, upgrading from Debian 10 to Debian 11 or Debian 11 to Debian 12), the VoIPmonitor sniffer service may stop working or report errors such as "sensor is not registered" or fail to start properly. This occurs because system libraries, kernel interfaces, or service management systems (systemd) may have changed incompatibly with the existing installation.

When the sensor fails after an OS upgrade, the recommended solution is to perform a fresh installation using the static binary method rather than attempting to upgrade the existing installation.

Fresh Installation After OS Upgrade

Follow these steps to perform a fresh clean installation:

1. Stop and disable the old service

sudo systemctl stop voipmonitor
sudo systemctl disable voipmonitor

2. Back up your configuration file (important!)

sudo cp /etc/voipmonitor.conf /etc/voipmonitor.conf.backup

This preserves your database connection settings, network interface configuration, and sensor ID.

3. Download the latest stable static binary

wget https://www.voipmonitor.org/current-stable-sniffer-static-64bit.tar.gz -O voipmonitor-sniffer.tar.gz

Use the appropriate URL for your architecture (32-bit or ARM) if needed.

4. Extract and run the installation script

tar xzf voipmonitor-sniffer.tar.gz
cd voipmonitor-*-static
sudo ./install-script.sh

5. Restore your configuration file

sudo cp /etc/voipmonitor.conf.backup /etc/voipmonitor.conf

6. Start and enable the service

sudo systemctl enable voipmonitor
sudo systemctl start voipmonitor

7. Verify the sensor is working

• Check service status: sudo systemctl status voipmonitor
• View logs: sudo journalctl -u voipmonitor -f
• If using client-server mode, verify the sensor appears in the GUI under Settings -> Sensors

For Client-Server deployments, you may need to update firewall rules on the new operating system to allow traffic on the manager port (default 5029) and packet buffer sender port (default 60024).

The fresh installation ensures that all service files, systemd configurations, and dependencies are compatible with the new operating system version, while preserving your original configuration settings.

Troubleshooting

Upgrading One Sensor Upgrades Multiple Sensors

If attempting to upgrade a single sensor causes another sensor (or the entire GUI) to upgrade unexpectedly, the issue is likely due to duplicate sensor configuration.

Symptoms:

• Clicking the UPGRADE button for Sensor A causes Sensor B to update instead
• A sensor configured with 127.0.0.1 (localhost) affects multiple other sensors
• All sensors on the Settings > Sensors page show identical version after upgrade

Root Cause: This occurs when multiple sensor entries in the GUI are configured with the same Manager IP and Manager Port. The GUI sends upgrade commands to a specific endpoint (IP + Port), and any sensor entry pointing to that endpoint will reflect the change.

In particular, if one sensor is configured with 127.0.0.1 (localhost) instead of its actual IP address, it will point to the GUI server itself. This causes unexpected behavior where operations on other sensors may affect the GUI server's local sensor if it exists.

Resolution:

1. Navigate to Settings → Sensors in the GUI 2. Examine the Manager IP and Manager Port columns for each sensor 3. Look for sensors configured with 127.0.0.1 or duplicate IP/Port combinations 4. For any sensor using 127.0.0.1, change it to the actual IP address of that sensor 5. Ensure each sensor has a unique Manager IP (or unique Manager Port if multiple instances run on the same host) 6. Click Save to apply the changes

Verification: After correcting the configuration, attempt the upgrade again on the target sensor. Verify that only that specific sensor updates its version.

For more information on configuring sensors, see GUI Settings.

"New Sensor Version Available" Notification Persists After Upgrade

If the GUI continues to display a "new sensor version available" notification even after all sensors have been updated to the latest version, this is typically caused by the development version upgrade setting.

Symptoms:

• All sensors show the latest version (e.g., 30.4) in Settings > Sensors
• GUI still displays "New sniffer version available" notification
• Clicking the notification shows no newer versions available

root Cause: The GUI may be comparing against development/snapshot versions when the development version option is enabled.

Resolution:

1. Navigate to System Configuration -> Advanced in the GUI 2. Ensure the option "enable upgrade sniffer to development version" is disabled 3. Log out of the GUI and log back in to refresh the session 4. If the notification persists, wait for a period of time as the system may need time to propagate the version information to all components

Prevention: Keep the "enable upgrade sniffer to development version" setting disabled unless you specifically need to test prerelease or snapshot builds. Development versions are not recommended for production use.

Deprecated Configuration Options

When upgrading to sensor version 2025.09.1 or newer, certain configuration options that were supported in older versions have been removed or deprecated. While the sniffer will automatically ignore unknown options, it is recommended to remove these obsolete directives from your `voipmonitor.conf` file for clarity and to avoid confusion.

Options Removed in 2025.09.1

The following configuration options are no longer supported in sensor version 2025.09.1 and should be removed from your configuration file:

• vxlan
• vxlan_port
• vxlan_skipcrc
• packet_buffer_total_size
• udp_reassembly
• udp_reassembly_max_size
• sipdefrag
• sipdefrag_maxpacket
• defragment_max_size
• defragment_timeout
• ignore_sip_parsing_errors
• sip_auto_clean
• max_sip_size
• sip_force_content_length
• sanity_checks
• check_sip_header
• interface_snaplen

Recommended Replacements

If you were previously using any of the removed options, consider the following alternatives:

• VXLAN support: The old `vxlan` family of options has been replaced with `udp_port_vxlan = 4789` (default: 4789) for VXLAN tunnel detection in cloud environments like AWS.

• Packet buffer sizing: The `packet_buffer_total_size` option is no longer needed. Packet buffer memory is now managed automatically via `max_buffer_mem` (default: 2000 MB) and `ringbuffer` (default: 50 MB, increase to 500+ for >100 Mbit traffic).

• UDP reassembly and SIP defragmentation: These features are now handled internally by the sniffer. The `udp_reassembly*` and `sipdefrag*` options are no longer configurable.

• SIP sanitization options: Options like `max_sip_size`, `sip_force_content_length`, `sanity_checks`, and `check_sip_header` have been removed as the sniffer now includes built-in improvements for handling malformed SIP packets.

• Interface snap length: `interface_snaplen` has been removed. Use the `snaplen parameter instead (default: 3200, increase to 65535 or 20000 for large SIP packets with extensive SDP or custom headers).

Remaining Supported Options

The following options mentioned in the upgrade context remain supported and should be kept if needed in your environment:

• udp_port_vxlan = 4789 - VXLAN tunnel detection
• auto_enable_use_blocks = yes - Required for deduplication and correct RTP association
• deduplicate = yes - Packet deduplication
• snaplen = 3200 - Packet capture length

Verification

After removing deprecated options and adding any needed replacements, restart the sensor and verify it starts without warnings about unknown options:

systemctl restart voipmonitor
journalctl -u voipmonitor -n 50 | grep -i "unknown\|option"

If you see warnings about unknown options, identify and remove those directives from your configuration file.

AI Summary for RAG

Summary: This guide details the procedures for upgrading or downgrading the VoIPmonitor sensor. It presents two primary methods. The first and recommended method is using the Web GUI, by navigating to "Settings -> Sensors" and selecting a new version from the upgrade dropdown menu. The second method is a manual update via the command line, which involves four steps: 1) Stopping the voipmonitor service (`systemctl stop voipmonitor`). 2) Downloading the desired static binary `tar.gz` package using `wget`. 3) Backing up the old binary, copying the new one to `/usr/local/sbin/`, and setting execute permissions with `chmod`. 4) Starting the service again. The article also covers version verification methods, includes troubleshooting for sensor upgrade issues (duplicate Manager IP, localhost 127.0.0.1 configuration), troubleshooting for persistent "new sensor version available" notifications (caused by "enable upgrade sniffer to development version" setting), and provides a specific section on reinstalling after operating system upgrades (such as Debian 10 to 11 or 11 to 12). After a major OS upgrade when the sensor stops working or reports "sensor is not registered", the recommended solution is to perform a fresh installation using the static binary method while preserving the configuration file backup. Additionally, the document includes a "Deprecated Configuration Options" section for sensor version 2025.09.1 and newer, which lists 17 options that have been removed (vxlan, vxlan_port, vxlan_skipcrc, packet_buffer_total_size, udp_reassembly, udp_reassembly_max_size, sipdefrag, sipdefrag_maxpacket, defragment_max_size, defragment_timeout, ignore_sip_parsing_errors, sip_auto_clean, max_sip_size, sip_force_content_length, sanity_checks, check_sip_header, interface_snaplen) and provides recommended replacements where applicable (udp_port_vxlan, max_buffer_mem, ringbuffer, snaplen). The section also lists options that remain supported (udp_port_vxlan, auto_enable_use_blocks, deduplicate, snaplen) and provides verification commands to check for unknown options after configuration changes. Keywords: upgrade, downgrade, update, sniffer, sensor, install, new version, old version, GUI upgrade, manual upgrade, command line, CLI, wget, tar.gz, systemctl, service, check version, verify, voipmonitor.org/download, troubleshooting, multiple sensors, duplicate IP, localhost, 127.0.0.1, Manager IP, operating system upgrade, OS upgrade, Debian 10, Debian 11, Debian 12, reinstall, fresh installation, sensor not registered, new sensor version available, notification persists, development version, enable upgrade sniffer to development version, System Configuration Advanced, System Configuration, deprecated options, unsupported options, 2025.09.1, voipmonitor.conf, vxlan, vxlan_port, vxlan_skipcrc, packet_buffer_total_size, udp_reassembly, udp_reassembly_max_size, sipdefrag, sipdefrag_maxpacket, defragment_max_size, defragment_timeout, ignore_sip_parsing_errors, sip_auto_clean, max_sip_size, sip_force_content_length, sanity_checks, check_sip_header, interface_snaplen, udp_port_vxlan, auto_enable_use_blocks, deduplicate, snaplen, max_buffer_mem, ringbuffer, configuration cleanup Key Questions:

• How do I upgrade the VoIPmonitor sniffer?
• How can I downgrade the sensor to a previous version?
• What is the easiest way to update my remote sensors?
• How do I perform a manual upgrade of the sniffer using the command line?
• How can I check which version of the sniffer I am currently running?
• Where can I download the latest stable sniffer binary?
• Why does upgrading one sensor upgrade multiple sensors?
• How do I fix a sensor configured with 127.0.0.1?
• Why are all sensors updating when I upgrade only one?
• What should I do after upgrading the operating system (e.g., Debian 11 to Debian 12)?
• How do I fix a "sensor is not registered" error after an OS upgrade?
• How do I perform a fresh installation of the sniffer after an operating system upgrade?
• Why does the GUI still show "new sensor version available" after all sensors are updated?
• Which configuration options are deprecated in sensor version 2025.09.1?
• What options should I remove from voipmonitor.conf after upgrading to 2025.09.1?
• What are the deprecated options for the latest sniffer version?
• How do I clean up unsupported options from my voipmonitor.conf?
• What is the replacement for the vxlan configuration options?
• What replaced the deprecated interface_snaplen option?
• How do I verify my configuration file has no deprecated options?