Sniffer upgrade: Difference between revisions

From VoIPmonitor.org
(Add AI Summary Key Question and Keywords for persistent upgrade notification issue)
(Rewrite: konsolidace a vylepšení struktury - kompaktnější formát, tabulky, lepší organizace troubleshootingu)
 
Line 1: Line 1:
{{DISPLAYTITLE:Upgrading and Downgrading the Sniffer}}
{{DISPLAYTITLE:Upgrading and Downgrading the Sniffer}}


'''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.'''
'''This guide covers VoIPmonitor sensor (sniffer) upgrades and downgrades. Two methods are available: Web GUI (recommended) or manual CLI.'''


<kroki lang="mermaid">
<kroki lang="mermaid">
%%{init: {'flowchart': {'nodeSpacing': 15, 'rankSpacing': 30}}}%%
%%{init: {'flowchart': {'nodeSpacing': 15, 'rankSpacing': 30}}}%%
flowchart TB
flowchart LR
     START[Need to Upgrade?] --> Q1{GUI Available?}
     START[Need Upgrade?] --> Q1{GUI Available?}
     Q1 -->|Yes| GUI[Method 1: GUI Upgrade]
     Q1 -->|Yes| GUI[GUI Upgrade]
     Q1 -->|No| CLI[Method 2: Manual CLI]
     Q1 -->|No| CLI[Manual CLI]
 
     GUI --> DONE[Verify Version]
     GUI --> G1[Settings → Sensors]
     CLI --> DONE
    G1 --> G2[Click UPGRADE]
    G2 --> G3[Select Version]
    G3 --> DONE[Verify Version]
 
     CLI --> C1[Stop Service]
    C1 --> C2[Download Binary]
    C2 --> C3[Backup Old Binary]
    C3 --> C4[Install New Binary]
    C4 --> C5[chmod +x]
    C5 --> C6[Start Service]
    C6 --> DONE
</kroki>
</kroki>


== Method 1: Upgrading via the Web GUI (Recommended) ==
== Quick Reference ==
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.


# Navigate to '''Settings -> Sensors''' in the VoIPmonitor GUI.
{| class="wikitable"
# 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.
|-
# Click the blue '''UPGRADE''' button. A dropdown menu will appear.
! Task !! Command
# Select the desired version from the list. The list will contain the latest stable release as well as several previous versions for downgrading.
|-
# The GUI will automatically handle the download and restart of the remote sensor service.
| Stop service || <code>systemctl stop voipmonitor</code>
|-
| Start service || <code>systemctl start voipmonitor</code>
|-
| Check version (local) || <code>/usr/local/sbin/voipmonitor --version</code>
|-
| Check version (remote) || <code>echo 'sniffer_version' <nowiki>|</nowiki> nc 127.0.0.1 5029</code>
|-
| Download latest stable || <code>wget https://www.voipmonitor.org/current-stable-sniffer-static-64bit.tar.gz</code>
|}


=== Scheduling Sensor Upgrades to Avoid Rate-Limiting Errors ===
== Method 1: GUI Upgrade (Recommended) ==


When upgrading a large number of sensors simultaneously via the GUI, all sensors trigger concurrent HTTP requests to <code>download.voipmonitor.org</code>. This can cause '''"429 Too Many Requests"''' errors from the download server due to rate limiting.
# Navigate to '''Settings → Sensors'''
# Click the blue '''UPGRADE''' button next to the sensor
# Select the desired version from the dropdown
# The GUI handles download and restart automatically


To avoid rate-limiting errors, stagger the upgrade times for sensors by configuring specific auto-upgrade datetime settings:
{{Note|This method requires the sensor to be running and connected to the GUI.}}


# Navigate to '''Settings -> Sensors''' in the VoIPmonitor GUI
=== Scheduling Upgrades to Avoid Rate-Limiting ===
# Click the '''wrench icon''' (Edit) next to each sensor you want to upgrade
# Click the '''UPGRADE''' subtab in the sensor settings dialog
# Set a specific '''auto-upgrade datetime''' for different groups of sensors


{{Tip|For example: upgrade 10 sensors at 06:30, the next 10 at 06:40, and so on. This staggers the download requests and prevents hitting the rate limit.}}
When upgrading many sensors simultaneously, you may encounter '''429 Too Many Requests''' errors from <code>download.voipmonitor.org</code>.


The sensors will automatically download and install the upgrade at their scheduled time. The system will attempt retries if the initial download fails due to temporary network issues or rate-limiting.
'''Solution:''' Stagger upgrade times:
# Click the '''wrench icon''' next to each sensor
# Go to the '''UPGRADE''' subtab
# Set different '''auto-upgrade datetime''' values for sensor groups


If the GUI upgrade process is too slow for your environment even with scheduled times, consider using the manual centralized upgrade method described under [[#Offline Upgrade (Servers Without Internet Access)|Offline Upgrade]] to download the binary once and distribute it to sensors via SSH/SCP.
{{Tip|Example: Upgrade 10 sensors at 06:30, next 10 at 06:40, etc.}}


== Method 2: Manual Upgrade/Downgrade (via Command Line) ==
== Method 2: Manual CLI Upgrade ==
This method gives you full control and is necessary if the GUI method is not available or unresponsive. '''Use this method if the "upgrade sensor" button in the GUI is unresponsive or does not work properly.''' It is also useful when you need to install a specific development build.


=== Step 1: Stop the Running Sniffer ===
=== Step 1: Stop Service ===
First, log in to the sensor's server via SSH and stop the service. For modern systems using systemd:
<syntaxhighlight lang="bash">
<syntaxhighlight lang="bash">
systemctl stop voipmonitor
systemctl stop voipmonitor
</syntaxhighlight>
</syntaxhighlight>
For older systems using SysV init:
<syntaxhighlight lang="bash">
/etc/init.d/voipmonitor stop
</syntaxhighlight>
{{Tip|If the service fails to stop, you may need to terminate the process manually as a last resort: <code>killall -9 voipmonitor</code>}}
=== Step 2: Download the Sniffer Archive ===
Download the latest stable static binary from the official VoIPmonitor website. This package contains all necessary files.


=== Step 2: Download Binary ===
<syntaxhighlight lang="bash">
<syntaxhighlight lang="bash">
# 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
wget https://www.voipmonitor.org/current-stable-sniffer-static-64bit.tar.gz -O voipmonitor-sniffer.tar.gz
</syntaxhighlight>
</syntaxhighlight>


'''Alternative: Direct Gzipped Binary Download'''
'''Alternative - Direct binary download:'''
 
You can also download the raw gzipped binary directly from the download server. This method downloads a smaller file and does not require extracting from an archive:
 
<syntaxhighlight lang="bash">
<syntaxhighlight lang="bash">
# For a specific version (replace with desired version)
# For specific version (replace version number)
wget https://download.voipmonitor.org/senzor/download/2025.04.4/voipmonitor.gz.64 -O ./voipmonitor.gz
wget https://download.voipmonitor.org/senzor/download/2025.04.4/voipmonitor.gz.64 -O voipmonitor.gz
 
gunzip voipmonitor.gz
# Unzip the file
gunzip ./voipmonitor.gz
 
# Copy to correct location (preserving executable attributes)
cp voipmonitor /usr/local/sbin/voipmonitor
cp voipmonitor /usr/local/sbin/voipmonitor
# Ensure it is executable
chmod +x /usr/local/sbin/voipmonitor
chmod +x /usr/local/sbin/voipmonitor
</syntaxhighlight>
</syntaxhighlight>


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 <code>wget</code> command.
=== Step 3: Install ===
 
=== Step 3: Install the New Binary ===
<syntaxhighlight lang="bash">
<syntaxhighlight lang="bash">
# Extract the downloaded archive
tar xzf voipmonitor-sniffer.tar.gz
tar xzf voipmonitor-sniffer.tar.gz
# Navigate into the new directory. The wildcard (*) handles any version number.
cd voipmonitor-*-static
cd voipmonitor-*-static


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


# Copy the new binary into place
# Install new binary
cp ./voipmonitor /usr/local/sbin/voipmonitor
 
# Ensure the new binary is executable
chmod +x /usr/local/sbin/voipmonitor
</syntaxhighlight>
 
=== Step 4: Start the Service ===
Finally, start the sniffer service again.
<syntaxhighlight lang="bash">
systemctl start voipmonitor
</syntaxhighlight>
Or for older systems:
<syntaxhighlight lang="bash">
/etc/init.d/voipmonitor start
</syntaxhighlight>
 
== 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:
<syntaxhighlight lang="bash">
/usr/local/sbin/voipmonitor --version
</syntaxhighlight>
Or, for more detail:
<syntaxhighlight lang="bash">
/usr/local/sbin/voipmonitor | head
</syntaxhighlight>
 
=== Remote Check (via Manager API) ===
If the sniffer is running, you can query its version remotely using its manager API (default port 5029):
<syntaxhighlight lang="bash">
echo 'sniffer_version' | nc 127.0.0.1 5029
</syntaxhighlight>
 
== Offline Upgrade (Servers Without Internet Access) ==
 
If your sensor server does not have internet access or if standard web GUI upgrades fail with "Unable to connect to upgrade server!" errors, you can perform an offline upgrade by downloading the files on another machine with internet access and transferring them to the target server.
 
Follow these steps for an offline sniffer upgrade:
 
;1. On a machine WITH internet access, download the sniffer binary:
<syntaxhighlight lang="bash">
# Download the latest stable static binary
wget https://www.voipmonitor.org/current-stable-sniffer-static-64bit.tar.gz -O voipmonitor-sniffer.tar.gz
</syntaxhighlight>
 
;2. Transfer the file to your offline sensor server:
Use SCP or a USB flash drive to transfer <code>voipmonitor-sniffer.tar.gz</code> to the offline server's <code>/tmp</code> directory.
<syntaxhighlight lang="bash">
# Example using SCP:
scp voipmonitor-sniffer.tar.gz user@offline-server:/tmp/
</syntaxhighlight>
 
;3. On the offline sensor server, stop the running sniffer:
<syntaxhighlight lang="bash">
systemctl stop voipmonitor
</syntaxhighlight>
 
;4. Back up the existing binary (important!):
<syntaxhighlight lang="bash">
cp /usr/local/sbin/voipmonitor /usr/local/sbin/voipmonitor.backup
</syntaxhighlight>
 
;5. Extract and install the new binary:
<syntaxhighlight lang="bash">
cd /tmp
tar xzf voipmonitor-sniffer.tar.gz
cd voipmonitor-*-static
cp ./voipmonitor /usr/local/sbin/voipmonitor
cp ./voipmonitor /usr/local/sbin/voipmonitor
chmod +x /usr/local/sbin/voipmonitor
chmod +x /usr/local/sbin/voipmonitor
</syntaxhighlight>
</syntaxhighlight>


;6. Start the sniffer service:
=== Step 4: Start Service ===
<syntaxhighlight lang="bash">
<syntaxhighlight lang="bash">
systemctl start voipmonitor
systemctl start voipmonitor
</syntaxhighlight>
</syntaxhighlight>


;7. Verify the new version:
== Offline Upgrade ==
<syntaxhighlight lang="bash">
/usr/local/sbin/voipmonitor --version
</syntaxhighlight>
 
{{Note|If anything goes wrong, you can restore the backup with <code>cp /usr/local/sbin/voipmonitor.backup /usr/local/sbin/voipmonitor</code> and restart the service.}}


== Reinstalling After Operating System Upgrades ==
For servers without internet access:


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.
# '''On a machine WITH internet:'''
#: <code>wget https://www.voipmonitor.org/current-stable-sniffer-static-64bit.tar.gz</code>
# '''Transfer to offline server:'''
#: <code>scp voipmonitor-sniffer.tar.gz user@offline-server:/tmp/</code>
# '''On offline server:''' Follow Steps 1, 3, 4 from Method 2 above


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.
{{Note|1=Restore backup if needed: <code>cp /usr/local/sbin/voipmonitor.backup /usr/local/sbin/voipmonitor</code>}}


=== Fresh Installation After OS Upgrade ===
== Reinstalling After OS Upgrade ==


Follow these steps to perform a fresh clean installation:
After major OS upgrades (e.g., Debian 10→11→12), perform a fresh installation:


;1. Stop and disable the old service:
<syntaxhighlight lang="bash">
<syntaxhighlight lang="bash">
sudo systemctl stop voipmonitor
# 1. Stop and disable old service
sudo systemctl disable voipmonitor
sudo systemctl stop voipmonitor && sudo systemctl disable voipmonitor
</syntaxhighlight>


;2. Back up your configuration file (important!):
# 2. Backup configuration
<syntaxhighlight lang="bash">
sudo cp /etc/voipmonitor.conf /etc/voipmonitor.conf.backup
sudo cp /etc/voipmonitor.conf /etc/voipmonitor.conf.backup
</syntaxhighlight>
This preserves your database connection settings, network interface configuration, and sensor ID.
;3. Download the latest stable static binary:
<syntaxhighlight lang="bash">
wget https://www.voipmonitor.org/current-stable-sniffer-static-64bit.tar.gz -O voipmonitor-sniffer.tar.gz
</syntaxhighlight>
Use the appropriate URL for your architecture (32-bit or ARM) if needed.


;4. Extract and run the installation script:
# 3. Download and install fresh
<syntaxhighlight lang="bash">
wget https://www.voipmonitor.org/current-stable-sniffer-static-64bit.tar.gz
tar xzf voipmonitor-sniffer.tar.gz
tar xzf voipmonitor-sniffer-*.tar.gz
cd voipmonitor-*-static
cd voipmonitor-*-static
sudo ./install-script.sh
sudo ./install-script.sh
</syntaxhighlight>


;5. Restore your configuration file:
# 4. Restore configuration
<syntaxhighlight lang="bash">
sudo cp /etc/voipmonitor.conf.backup /etc/voipmonitor.conf
sudo cp /etc/voipmonitor.conf.backup /etc/voipmonitor.conf
</syntaxhighlight>


;6. Start and enable the service:
# 5. Enable and start
<syntaxhighlight lang="bash">
sudo systemctl enable --now voipmonitor
sudo systemctl enable voipmonitor
sudo systemctl start voipmonitor
</syntaxhighlight>
</syntaxhighlight>


;7. Verify the sensor is working:
{{Tip|For client-server deployments, verify firewall rules for ports 5029 (manager) and 60024 (packet buffer).}}
* Check service status: <code>sudo systemctl status voipmonitor</code>
* View logs: <code>sudo journalctl -u voipmonitor -f</code>
* 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 <code>127.0.0.1</code> (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 <code>127.0.0.1</code> (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 <code>127.0.0.1</code> or duplicate IP/Port combinations
4. For any sensor using <code>127.0.0.1</code>, 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 [[Settings#Sensors|GUI Settings]].
 
=== Unable to Enable Auto-Upgrade for Default Local Sensor ===


If you cannot enable or modify the auto-upgrade settings for a "local sensor" in the GUI, this is because the default local sensor entry does not support the auto-upgrade configuration. The workaround is to manually create a new sensor to replace the default local sensor.
== Deprecated Options (v2025.09.1+) ==


'''Symptoms:'''
Remove these obsolete directives from <code>voipmonitor.conf</code>:
* Auto-upgrade option is grayed out or cannot be enabled for the local sensor
* Upgrade settings cannot be modified for the default local sensor entry
* The sensor shows as "local" but auto-upgrade configuration is unavailable


'''Root Cause:'''
{| class="wikitable"
The automatically created "local sensor" entry that appears when the GUI detects an active capture on the GUI host machine has limited configuration options and does not support the auto-upgrade feature. To enable auto-upgrade, you must create a new manual sensor entry.
|-
! Removed Option !! Replacement
|-
| <code>vxlan</code>, <code>vxlan_port</code>, <code>vxlan_skipcrc</code> || <code>udp_port_vxlan = 4789</code>
|-
| <code>packet_buffer_total_size</code> || <code>max_buffer_mem</code>, <code>ringbuffer</code>
|-
| <code>udp_reassembly*</code>, <code>sipdefrag*</code> || Handled internally
|-
| <code>interface_snaplen</code> || <code>snaplen = 3200</code>
|-
| <code>max_sip_size</code>, <code>sanity_checks</code>, <code>check_sip_header</code> || Built-in improvements
|}


'''Solution: Replace the Default Local Sensor with a Manual Sensor Entry'''
Verify after cleanup:
 
Follow these steps to create a new sensor that supports auto-upgrade:
 
;1. Navigate to '''Settings -> Sensors''' in the VoIPmonitor GUI
 
;2. Click '''Add new sensor''' or '''New sensor'''
 
;3. Configure the new sensor entry:
** '''Sensor ID:''' Assign a unique ID number (e.g., <code>1</code> or a number not used by other sensors). If a sensor ID is already configured in <code>/etc/voipmonitor.conf</code>, use that value.
** '''Name:''' Enter a descriptive name such as "Local Sensor - GUI Server"
** '''Manager IP:''' Set to <code>127.0.0.1</code> (localhost) if the sensor is on the same machine as the GUI
** '''Manager Port:''' Set to the manager API port (default: <code>5029</code>)
 
;4. Check the configuration on the sensor machine:
If you are creating this for the actual localhost sensor running on the GUI server, verify the manager settings in <code>/etc/voipmonitor.conf</code>:
<syntaxhighlight lang="ini">
# If the sensor is running on the GUI host (localhost),
# verify or set the manager listening address:
managerip = 127.0.0.1
managerport = 5029
</syntaxhighlight>
 
;5. Restart the sensor service to apply changes:
<syntaxhighlight lang="bash">
<syntaxhighlight lang="bash">
systemctl restart voipmonitor
systemctl restart voipmonitor
journalctl -u voipmonitor -n 50 | grep -i "unknown\|option"
</syntaxhighlight>
</syntaxhighlight>


;6. Verify the new sensor appears in the GUI:
== Troubleshooting ==
The sensor should appear online in '''Settings -> Sensors''' with a green status indicator.
 
;7. Configure auto-upgrade for the new sensor:
# Click the '''Edit''' icon (pencil or wrench) next to the new sensor
# Find the auto-upgrade options (auto-upgrade, upgrade version selection, etc.)
# Enable the auto-upgrade feature and configure the desired upgrade settings
# Click '''Save'''
 
The auto-upgrade option should now be available and functional for this manually created local sensor.
 
'''Note:''' The original default local sensor entry may remain visible or may be automatically removed by the GUI after the new sensor is created. You can safely ignore or delete the old default entry if it becomes removable.
 
For information on other sensor configuration options, see [[Settings#Sensors|GUI Sensors Configuration]].
 
=== "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:'''
=== Upgrading One Sensor Affects Multiple Sensors ===


1. Navigate to '''System Configuration -> Advanced''' in the GUI
'''Cause:''' Multiple sensors share the same Manager IP + Port combination.
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:'''
'''Fix:'''
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.
# Check '''Settings → Sensors''' for duplicate IP/Port entries
# Ensure each sensor has a unique Manager IP (or unique port if on same host)
# Never use <code>127.0.0.1</code> for remote sensors


=== "sniffer error: need AES!" After Sensor Upgrade ===
=== Cannot Enable Auto-Upgrade for Default Local Sensor ===


If you see the error message "sniffer error: need AES!" when accessing sensor configuration from a local GUI after a sensor upgrade, this indicates that the sensor is now enforcing AES encryption for the manager API communication channel, and the local GUI has outdated encryption keys in its database.
The default "local sensor" entry does not support auto-upgrade.


This commonly occurs when:
'''Solution:''' Create a new sensor entry:
* You are managing a sensor through a dedicated local GUI rather than the main GUI
# '''Settings → Sensors → Add new sensor'''
* After upgrading the sensor, the encryption requirements or keys have changed
# Set: Sensor ID (unique), Manager IP: <code>127.0.0.1</code>, Manager Port: <code>5029</code>
* The local GUI database contains the old encryption key that no longer matches the upgraded sensor
# Restart service: <code>systemctl restart voipmonitor</code>
# Configure auto-upgrade on the new sensor entry


'''Symptoms:'''
=== "New Sensor Version Available" Notification Persists ===
* Local GUI cannot read or write sensor configuration
* Error message: "sniffer error: need AES!" appears in the GUI
* Issue occurs only after a sensor upgrade


'''Solution 1: Remove AES Encryption Key (Recommended for Local GUIs)'''
'''Cause:''' Development version option is enabled.


Remove the AES encryption key from the local GUI database so the GUI can re-establish communication with the sensor:
'''Fix:''' Disable '''System Configuration → Advanced → "enable upgrade sniffer to development version"'''


<syntaxhighlight lang="bash">
=== "sniffer error: need AES!" ===
# Navigate to the GUI directory
cd /var/www/voipmonitor


# Remove the old AES encryption key
After upgrade, the GUI cannot communicate with sensor due to encryption key mismatch.
php php/run.php delete_aes_key
</syntaxhighlight>
 
This clears the encryption key from the local GUI database. The GUI will then attempt to communicate with the sensor using the current authentication settings.
 
'''Solution 2: Disable AES Encryption via GUI'''
 
If you prefer to disable AES encryption entirely for this sensor:
 
# Log in to the local GUI
# Navigate to '''System settings -> System configuration'''
# Disable the AES-related encryption options
# Save the settings
 
Note: Disabling AES encryption reduces security but may simplify local management in certain scenarios.
 
'''Solution 3: Disable AES Encryption in Sensor Configuration'''
 
If you need to allow unencrypted communication at the sensor level (for example, when accessing the manager API via command line tools or scripts), you can disable the encryption requirement directly in the sensor's configuration file:
 
<syntaxhighlight lang="bash">
# Edit the sensor's voipmonitor.conf file
nano /etc/voipmonitor.conf
</syntaxhighlight>
 
Add this line to disable encryption for the manager API:
<syntaxhighlight lang="ini">
manager_enable_unencrypted = yes
</syntaxhighlight>


Then restart the VoIPmonitor sensor service:
'''Solutions:'''
<syntaxhighlight lang="bash">
<syntaxhighlight lang="bash">
systemctl restart voipmonitor
# Option 1: Remove old AES key from GUI database
</syntaxhighlight>
cd /var/www/voipmonitor && php php/run.php delete_aes_key
 
This configuration option disables encryption enforcement for the manager API (port 5029), allowing unencrypted commands such as <code>listcalls</code>, <code>listregisters</code>, and other manager commands to be executed without authentication requirements.
 
'''Warning:''' This option reduces security as it allows unencrypted configuration access to the sensor. Only use this in trusted network environments or for testing/debugging purposes. For production environments, [[Encryption_in_manager_api|use proper encryption]] whenever possible.
 
'''Prevention: Main GUI vs Local GUI'''
 
To avoid this issue in the future, consider managing sensors through the main GUI rather than using dedicated local GUIs:
 
* '''Main GUI approach:''' Manage all sensors centrally from the primary GUI. When upgrading sensors through the main GUI (Settings -> Sensors), the GUI and sensor configurations stay synchronized.
* '''Local GUI approach:''' If you must use a dedicated local GUI for a sensor, be aware that sensor upgrades may require running <code>delete_aes_key</code> to clear stale encryption keys from the local database.
 
'''Technical Background:'''
 
The "need AES!" error means the sensor's manager API is rejecting unencrypted or improperly encrypted commands from the GUI. This security feature protects against unauthorized configuration changes. After an upgrade, if the encryption keys do not match (either due to changed defaults or required password settings), the communication fails until the mismatch is resolved.
 
For more information on sensor communication and security settings, see [[Settings]] and [[Sniffer_configuration]].
 
== 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 <code>voipmonitor.conf</code> 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:
 
* <code>vxlan</code>
* <code>vxlan_port</code>
* <code>vxlan_skipcrc</code>
* <code>packet_buffer_total_size</code>
* <code>udp_reassembly</code>
* <code>udp_reassembly_max_size</code>
* <code>sipdefrag</code>
* <code>sipdefrag_maxpacket</code>
* <code>defragment_max_size</code>
* <code>defragment_timeout</code>
* <code>ignore_sip_parsing_errors</code>
* <code>sip_auto_clean</code>
* <code>max_sip_size</code>
* <code>sip_force_content_length</code>
* <code>sanity_checks</code>
* <code>check_sip_header</code>
* <code>interface_snaplen</code>
 
=== Recommended Replacements ===
 
If you were previously using any of the removed options, consider the following alternatives:
 
* '''VXLAN support''': The old <code>vxlan</code> family of options has been replaced with <code>udp_port_vxlan = 4789</code> (default: 4789) for VXLAN tunnel detection in cloud environments like AWS.
 
* '''Packet buffer sizing''': The <code>packet_buffer_total_size</code> option is no longer needed. Packet buffer memory is now managed automatically via <code>max_buffer_mem</code> (default: 2000 MB) and <code>ringbuffer</code> (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 <code>udp_reassembly*</code> and <code>sipdefrag*</code> options are no longer configurable.
 
* '''SIP sanitization options''': Options like <code>max_sip_size</code>, <code>sip_force_content_length</code>, <code>sanity_checks</code>, and <code>check_sip_header</code> have been removed as the sniffer now includes built-in improvements for handling malformed SIP packets.
 
* '''Interface snap length''': <code>interface_snaplen</code> has been removed. Use the <code>snaplen</code> 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:
 
* <code>udp_port_vxlan = 4789</code> - VXLAN tunnel detection
* <code>auto_enable_use_blocks = yes</code> - Required for deduplication and correct RTP association
* <code>deduplicate = yes</code> - Packet deduplication
* <code>snaplen = 3200</code> - Packet capture length


=== Verification ===
# Option 2: Disable encryption in sensor config
 
echo "manager_enable_unencrypted = yes" >> /etc/voipmonitor.conf
After removing deprecated options and adding any needed replacements, restart the sensor and verify it starts without warnings about unknown options:
 
<syntaxhighlight lang="bash">
systemctl restart voipmonitor
systemctl restart voipmonitor
journalctl -u voipmonitor -n 50 | grep -i "unknown\|option"
</syntaxhighlight>
</syntaxhighlight>


If you see warnings about unknown options, identify and remove those directives from your configuration file.
{{Warning|1=<code>manager_enable_unencrypted = yes</code> reduces security. Use only in trusted networks.}}


=== "Permission denied" During Manual Upgrade ===
=== "Permission denied" During Upgrade ===


If you encounter "Permission denied" errors when trying to execute the upgrade binary or installation scripts from the <code>/tmp</code> directory, this is typically caused by the <code>/tmp</code> partition being mounted with the <code>noexec</code> flag. Many modern Linux distributions (Debian, Ubuntu, RHEL, CentOS 8+) mount <code>/tmp</code> with <code>noexec</code> for security reasons, which prevents the execution of binaries or scripts located in that directory.
'''Cause:''' <code>/tmp</code> mounted with <code>noexec</code> flag.


'''Symptoms:'''
'''Fix:'''
* <code>Permission denied</code> error when running the downloaded binary or install script from <code>/tmp</code>
* Error occurs immediately after downloading and extracting the archive in <code>/tmp</code>
* Service fails to restart after the upgrade attempt
 
'''Resolution:'''
 
The proper fix is to remount the <code>/tmp</code> partition with execute permissions rather than avoiding <code>/tmp</code> entirely:
 
;1. Check the current mount options:
<syntaxhighlight lang="bash">
mount | grep "/tmp"
</syntaxhighlight>
Look for the <code>noexec</code> flag in the output (e.g., <code>/dev/sda1 on /tmp type ext4 (rw,nosuid,nodev,noexec,relatime)</code>).
 
;2. Remount /tmp with execute permissions (temporary fix):
<syntaxhighlight lang="bash">
<syntaxhighlight lang="bash">
# Temporary fix
mount -o remount,exec /tmp
mount -o remount,exec /tmp
</syntaxhighlight>
;3. Re-run the upgrade process from Step 3 above:
<syntaxhighlight lang="bash">
cd /tmp/voipmonitor-*-static
cp ./voipmonitor /usr/local/sbin/voipmonitor
chmod +x /usr/local/sbin/voipmonitor
</syntaxhighlight>
;4. Make the change permanent by editing <code>/etc/fstab</code>:
<syntaxhighlight lang="bash">
sudo nano /etc/fstab
# OR
sudo vi /etc/fstab
</syntaxhighlight>
Find the line corresponding to the <code>/tmp</code> mount point and remove the <code>noexec</code> option. For example, change:
<syntaxhighlight lang="text">
tmpfs    /tmp    tmpfs    defaults,nosuid,nodev,noexec    0    0
</syntaxhighlight>
To:
<syntaxhighlight lang="text">
tmpfs    /tmp    tmpfs    defaults,nosuid,nodev    0    0
</syntaxhighlight>
;5. Apply the permanent fix by remounting all filesystems:
<syntaxhighlight lang="bash">
sudo mount -a
</syntaxhighlight>
;6. Verify the fix:
<syntaxhighlight lang="bash">
mount | grep "/tmp"
# Should no longer show "noexec" in the options
</syntaxhighlight>
;7. Start the service:
<syntaxhighlight lang="bash">
systemctl start voipmonitor
</syntaxhighlight>
'''Important Notes:'''
* The <code>remount,exec</code> command only applies until the next reboot. Editing <code>/etc/fstab</code> is required for a permanent solution.
* Removing <code>noexec</code> from <code>/tmp</code> is a standard practice for VoIPmonitor sensors that need to execute upgrade scripts in the temporary directory.
* If security policies strictly require <code>noexec</code> on <code>/tmp</code>, download and extract the archive to an alternative directory like <code>/usr/src/voipmonitor-upgrade</code> instead.
For more information on system hardening options, consult your operating system's security documentation.
=== Service Fails to Start After Upgrade Due to "Permission denied" ===
If the VoIPmonitor sensor service fails to start with a "Permission denied" error AFTER the upgrade has completed, this typically indicates that the installed binary at <code>/usr/local/sbin/voipmonitor</code> lacks the execute permission bit. This can happen if the <code>chmod +x</code> command was omitted during the upgrade process, or if permissions were not preserved when copying the binary.
'''Symptoms:'''
* Service fails to start after running <code>systemctl start voipmonitor</code>
* System logs show "Permission denied" when attempting to execute <code>/usr/local/sbin/voipmonitor</code>
* The upgrade appears to complete successfully, but the service will not run
* When manually running <code>/usr/local/sbin/voipmonitor --version</code>, you get a "Permission denied" error
'''Diagnosis:'''
Check the file permissions on the binary:


<syntaxhighlight lang="bash">
# Permanent fix: edit /etc/fstab and remove 'noexec' from /tmp line
ls -l /usr/local/sbin/voipmonitor
</syntaxhighlight>
</syntaxhighlight>


Look for the executable flags in the permission string:
=== Binary Lacks Execute Permission After Upgrade ===
* If you see <code>-rw-r--r--</code> (no 'x' flags), the file lacks execute permissions
* If you see <code>-rwxr-xr-x</code> (with 'x' flags), the file is executable


Also verify the user running the service has permission to execute the file:
'''Symptom:''' Service fails to start, "Permission denied" on <code>/usr/local/sbin/voipmonitor</code>.


<syntaxhighlight lang="bash">
'''Fix:'''
# Check which user runs the voipmonitor service
systemctl cat voipmonitor.service | grep "User="
</syntaxhighlight>
 
If no User is specified, it runs as root by default.
 
'''Resolution:'''
 
;1. Ensure you are logged in as root:
If you are not root, switch to the root user:
<syntaxhighlight lang="bash">
sudo -i
# OR
su -
</syntaxhighlight>
 
;2. Add execute permissions to the binary:
<syntaxhighlight lang="bash">
<syntaxhighlight lang="bash">
chmod +x /usr/local/sbin/voipmonitor
chmod +x /usr/local/sbin/voipmonitor
</syntaxhighlight>
;3. Verify the permissions are correct:
<syntaxhighlight lang="bash">
ls -l /usr/local/sbin/voipmonitor
# Should now show: -rwxr-xr-x (with 'x' flags)
</syntaxhighlight>
;4. Start the service:
<syntaxhighlight lang="bash">
systemctl start voipmonitor
systemctl start voipmonitor
systemctl status voipmonitor
</syntaxhighlight>
;5. Verify the service is running:
<syntaxhighlight lang="bash">
ps aux | grep voipmonitor
/usr/local/sbin/voipmonitor --version
</syntaxhighlight>
</syntaxhighlight>


'''Prevention:'''
=== "Could not resolve host: download.voipmonitor.org" ===
 
This issue highlights the importance of including the <code>chmod +x</code> step during manual upgrades. When performing manual command-line upgrades, always follow the complete procedure:


<syntaxhighlight lang="bash">
'''Solutions:'''
# After copying the new binary:
cp ./voipmonitor /usr/local/sbin/voipmonitor
chmod +x /usr/local/sbin/voipmonitor  # CRITICAL STEP
systemctl start voipmonitor
</syntaxhighlight>
 
The upgrade procedure is documented in [[#Method 2: Manual Upgrade/Downgrade (via Command Line)|Method 2: Manual Upgrade/Downgrade]].
 
If using the GUI upgrade method (recommended), the system handles this automatically and this issue should not occur.
 
=== "Could not resolve host: download.voipmonitor.org" During GUI Upgrade ===
 
If the GUI upgrade fails with the error <code>sniffer error: failed download upgrade: Could not resolve host: download.voipmonitor.org</code>, this indicates that the sensor cannot reach the VoIPmonitor download server. This is typically a DNS, network, or proxy configuration issue.
 
'''Workaround 1: Use curlproxy Configuration'''
 
If the sensor requires a proxy server to access the Internet (common in corporate networks), configure the proxy settings in the sensor's <code>voipmonitor.conf</code> file:
 
<syntaxhighlight lang="bash">
# Edit the sensor's voipmonitor.conf file
nano /etc/voipmonitor.conf
</syntaxhighlight>


Add this line to configure the proxy (replace with your proxy address and port):
'''1. Configure proxy (if required):'''
<syntaxhighlight lang="ini">
<syntaxhighlight lang="ini">
# In /etc/voipmonitor.conf
curlproxy = http://proxy.example.com:3128
curlproxy = http://proxy.example.com:3128
# For authenticated proxy, use:
curlproxy = http://username:password@proxy.example.com:3128
</syntaxhighlight>
Then restart the VoIPmonitor service:
<syntaxhighlight lang="bash">
systemctl restart voipmonitor
</syntaxhighlight>
</syntaxhighlight>


After configuring the proxy, retry the GUI upgrade. The <code>curlproxy</code> option tells the sensor to use the specified proxy server for all HTTP/HTTPS download operations, including upgrades.
'''2. Manual binary copy from another sensor:'''
 
'''Workaround 2: Manual Binary Copy from Another Sensor'''
 
If the sensor cannot reach the download server at all (no Internet connectivity or strict firewall rules), you can manually copy the upgraded sniffer binary from another working sensor in your deployment:
 
<syntaxhighlight lang="bash">
<syntaxhighlight lang="bash">
# Step 1: Stop the service on the failing sensor
scp working-sensor:/usr/local/sbin/voipmonitor /tmp/
systemctl stop voipmonitor
 
# Step 2: Copy the new voipmonitor binary from a working sensor to the failing sensor
# Run this command from your management station or from the failing sensor:
scp working-sensor:/usr/local/sbin/voipmonitor /tmp/voipmonitor
 
# Step 3: Overwrite the old binary on the failing sensor
cp /tmp/voipmonitor /usr/local/sbin/voipmonitor
cp /tmp/voipmonitor /usr/local/sbin/voipmonitor
# Step 4: Ensure the new binary has execute permissions
chmod +x /usr/local/sbin/voipmonitor
chmod +x /usr/local/sbin/voipmonitor
# Step 5: Start the service
systemctl start voipmonitor
# Step 6: Verify the version has updated
/usr/local/sbin/voipmonitor --version
</syntaxhighlight>
Replace <code>working-sensor</code> with the hostname or IP address of a sensor that has the desired version installed. You can verify the version on the source sensor before copying.
After the upgrade, verify the new version appears in the GUI under '''Settings -> Sensors'''.
'''Troubleshooting Tips:'''
* '''DNS Resolution:** Check <code>/etc/resolv.conf</code> for valid DNS nameservers (e.g., <code>nameserver 8.8.8.8</code>).
* '''Network Connectivity:** Test if the sensor can reach the download server: <code>ping -c 4 download.voipmonitor.org</code>
* '''Firewall Rules:** Ensure outbound HTTPS (port 443) traffic is allowed to <code>*.voipmonitor.org</code>.
For information on other configuration options, see [[Sniffer_configuration]].
=== SSL/TLS Protocol Version Error During Sensor Upgrade ===
If the sensor upgrade fails with an SSL/TLS protocol error such as:
<syntaxhighlight lang="text">
sniffer error: failed download upgrade: error:1409442E:SSL routines:ssl3_read_bytes:tlsv1 alert protocol version
</syntaxhighlight>
</syntaxhighlight>
This indicates that the sensor binary is attempting to connect to the VoIPmonitor download server using an outdated TLS protocol version (usually TLS 1.0 or 1.1), but the server requires a modern protocol (TLS 1.2 or higher). This typically occurs when the sensor binary is very old and lacks support for modern TLS versions.
'''Solution 1: Enable HTTP Fallback (Recommended for Old Sensors)'''


The simplest solution is to enable HTTP fallback for upgrade downloads. This allows the sensor to automatically fall back to HTTP if the HTTPS connection fails.
=== SSL/TLS Protocol Error During Upgrade ===


'''IMPORTANT:''' This is a TEMPORARY workaround only. You must disable this option after the upgrade completes.
'''Symptom:''' <code>tlsv1 alert protocol version</code> error.


<syntaxhighlight lang="bash">
'''Temporary fix:'''
# Edit the sensor's voipmonitor.conf file
nano /etc/voipmonitor.conf
</syntaxhighlight>
 
Add this line to enable HTTP fallback for upgrades:
<syntaxhighlight lang="ini">
<syntaxhighlight lang="ini">
# In /etc/voipmonitor.conf
upgrade_try_http_if_https_fail = yes
upgrade_try_http_if_https_fail = yes
</syntaxhighlight>
</syntaxhighlight>


Then restart the VoIPmonitor sensor service:
{{Warning|1=Disable this option after upgrade completes. HTTP is less secure than HTTPS.}}
<syntaxhighlight lang="bash">
systemctl restart voipmonitor
</syntaxhighlight>


'''Method 2: Configure via the Web GUI'''
=== Missing Database Table After Upgrade ===


# Navigate to '''Settings -> Sensors''' in the VoIPmonitor GUI
'''Symptom:''' <code>Table 'voipmonitor.cdr_audio_transcribe' doesn't exist</code>
# Click the '''Edit''' icon (pencil) next to the sensor you want to upgrade
# Scroll down or search for the <code>upgrade_try_http_if_https_fail</code> option
# Set it to <code>yes</code>
# Click '''Save'''


After restarting the service (or saving in the GUI), attempt the upgrade again. The system will now try HTTPS first, and if it fails due to TLS version issues, it will automatically fall back to an HTTP connection.
'''Fix:''' Create the missing table manually:
 
<syntaxhighlight lang="sql">
'''After the Upgrade Completes:'''
-- Connect to database
 
Once the upgrade is successful, DISABLE the <code>upgrade_try_http_if_https_fail</code> option to restore secure HTTPS-only downloads:
 
Edit <code>voipmonitor.conf</code> and remove or comment out the HTTP fallback line, or set it explicitly to no:
<syntaxhighlight lang="ini">
# upgrade_try_http_if_https_fail = yes
upgrade_try_http_if_https_fail = no
</syntaxhighlight>
 
Then restart the service:
<syntaxhighlight lang="bash">
systemctl restart voipmonitor
</syntaxhighlight>
 
Or via the GUI:
# Navigate to '''Settings -> Sensors'''
# Edit the sensor
# Set <code>upgrade_try_http_if_https_fail</code> to <code>no</code>
# Click '''Save'''
 
'''Security Note:''' HTTP downloads are less secure than HTTPS because they are unencrypted. Use the HTTP fallback option only as a temporary workaround for legacy sensors that cannot connect via modern TLS protocols. After upgrading to a sensor version 31.8 or newer (which supports TLS 1.3), always disable this option to restore HTTPS-only downloads.
 
'''Solution 2: Manual Binary Transfer (For Sensors Without Internet Access)'''
 
If the HTTP fallback solution does not work or if the sensor does not have direct Internet access, use the manual upgrade procedure described in [[#Method 2: Manual Upgrade/Downgrade (via Command Line)|Method 2]] above. This method involves downloading the binary on another machine and transferring it via SCP, which bypasses the sensor's internal downloader entirely.
 
'''Solution 3: Using curlproxy with Modern Proxy (For Corporate Networks)'''
 
If the sensor is behind a corporate firewall or proxy that enforces TLS versions, the sensor may need to route connections through a proxy server that supports modern TLS protocols:
 
<syntaxhighlight lang="bash">
# Edit the sensor's voipmonitor.conf file
nano /etc/voipmonitor.conf
</syntaxhighlight>
 
Add this line to configure a proxy server:
<syntaxhighlight lang="ini">
curlproxy = http://proxy.example.com:3128
</syntaxhighlight>
 
Then restart the VoIPmonitor sensor service:
<syntaxhighlight lang="bash">
systemctl restart voipmonitor
</syntaxhighlight>
 
Ensure that the proxy server can connect to <code>download.voipmonitor.org</code> using modern TLS protocols. The proxy handles the HTTPS connection on behalf of the legacy sensor.
 
=== Service Fails to Start After Upgrade Due to Missing Database Table ===
 
If the VoIPmonitor sensor service fails to start after an upgrade with an error message like <code>Table 'voipmonitor.cdr_audio_transcribe' doesn't exist</code>, this indicates that new database tables introduced in the upgraded version were not created during the upgrade process.
 
This typically occurs when:
* The sensor binary was manually updated without updating the database schema
* The database schema update step was skipped or failed
* A new feature (such as audio transcription) was added that requires a new table
 
'''Symptoms:'''
* Service fails to start after upgrade
* Error log shows: <code>Table 'voipmonitor.TABLE_NAME' doesn't exist</code> (e.g., <code>cdr_audio_transcribe</code>, <code>cdr_whisper</code>, or other new tables)
* The error message identifies a specific missing table
 
'''Resolution: Create the Missing Table Manually'''
 
To fix this issue, you need to execute the SQL statement to create the missing table in your VoIPmonitor database.
 
;1. Connect to the MySQL server used by the affected sensor host:
<syntaxhighlight lang="bash">
mysql -h your_db_host -u your_db_user -p voipmonitor
mysql -h your_db_host -u your_db_user -p voipmonitor
</syntaxhighlight>
Replace <code>your_db_host</code> and <code>your_db_user</code> with your actual database host and username. You will be prompted for the database password.


;2. Execute the appropriate SQL statement for the missing table:
-- Create the missing table (example for cdr_audio_transcribe)
For example, if the missing table is <code>cdr_audio_transcribe</code> (introduced in version 2024.11.2 for audio transcription features):
<syntaxhighlight lang="sql">
CREATE TABLE `cdr_audio_transcribe` (
CREATE TABLE `cdr_audio_transcribe` (
   `ID` bigint unsigned NOT NULL AUTO_INCREMENT,
   `ID` bigint unsigned NOT NULL AUTO_INCREMENT,
Line 820: Line 264:
   `a_text` mediumtext,
   `a_text` mediumtext,
   `b_text` mediumtext,
   `b_text` mediumtext,
  `a_segments` mediumtext,
  `b_segments` mediumtext,
   PRIMARY KEY (`ID`,`calldate`),
   PRIMARY KEY (`ID`,`calldate`),
   KEY `fbasename` (`fbasename`)
   KEY `fbasename` (`fbasename`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb3 COMPRESSION='lz4'
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb3
/*!50500 PARTITION BY RANGE COLUMNS(calldate)
PARTITION BY RANGE COLUMNS(calldate)
(PARTITION p202411 VALUES LESS THAN ('2024-12-01') ENGINE = InnoDB,
(PARTITION p_future VALUES LESS THAN MAXVALUE ENGINE = InnoDB);
PARTITION p202412 VALUES LESS THAN ('2025-01-01') ENGINE = InnoDB,
PARTITION p_future VALUES LESS THAN MAXVALUE ENGINE = InnoDB) */
</syntaxhighlight>
 
;3. Adjust the partition definitions as needed for your current date:
The example above shows partitions for November and December 2024. When creating the table:
* Create partitions covering historical data periods that exist in your <code>cdr</code> table
* Ensure the last partition uses <code>LESS THAN MAXVALUE</code> to handle future data automatically
* You can add more partitions as your data grows using <code>ALTER TABLE ... ADD PARTITION</code>
 
;4. Restart the VoIPmonitor service:
<syntaxhighlight lang="bash">
systemctl restart voipmonitor
</syntaxhighlight>
Or on older systems:
<syntaxhighlight lang="bash">
service voipmonitor restart
</syntaxhighlight>
 
'''Alternative Solution: Import Complete Schema File'''
 
If you prefer a simpler approach (use with caution on production databases), you can import the complete schema creation file. This is designed to add missing tables without affecting existing data:
 
<syntaxhighlight lang="bash">
# Import the schema, which will add missing tables
mysql -u root -p voipmonitor < /usr/local/share/voipmonitor/sql/create_tables.sql
</syntaxhighlight>
</syntaxhighlight>


However, this method is generally NOT recommended for production databases because:
Then restart: <code>systemctl restart voipmonitor</code>
* It may try to recreate existing tables (though most SQL scripts use <code>IF NOT EXISTS</code>)
* It takes longer than creating just the missing table
* You have less control over partition configuration
 
'''Verification:'''


After creating the missing table and restarting the service, verify that the service starts successfully:
== See Also ==


<syntaxhighlight lang="bash">
* [[Sniffer_installation]] - Initial sensor installation
# Check service status
* [[Sniffer_configuration]] - Configuration parameters
systemctl status voipmonitor
* [[Settings#Sensors]] - GUI sensor management
</syntaxhighlight>
* [[Systemd_for_voipmonitor_service_management]] - Service management
 
You should see output indicating the service is <code>active (running)</code>.
 
Check the service log to confirm no more table-related errors:
<syntaxhighlight lang="bash">
journalctl -u voipmonitor -n 50 | grep -i "table\|error"
</syntaxhighlight>
 
If no errors appear, the issue is resolved.
 
'''Prevention:'''
 
To avoid this issue in future upgrades:
* Always follow the complete upgrade procedure, which includes database schema updates
* For GUI upgrades, ensure the sensor can execute SQL schema updates (check database permissions)
* For manual upgrades, check the release notes for any required database changes
* Test upgrades in a staging environment before applying to production
 
For more information on audio transcription features, see [[Whisper]] or [[Audio_transcription]] documentation.


== AI Summary for RAG ==
== AI Summary for RAG ==


'''Summary:''' Guide for upgrading/downgrading the VoIPmonitor sensor. Two methods: 1) '''GUI upgrade''' (recommended) - Settings -> Sensors -> UPGRADE button. Includes '''scheduling sensor upgrades to avoid rate-limiting''' - for large sensor deployments, use Settings > Sensors > Edit > UPGRADE subtab to set specific auto-upgrade datetime for different sensor groups (e.g., upgrade 10 sensors at 06:30, next 10 at 06:40) to prevent "429 Too Many Requests" errors from download.voipmonitor.org. 2) '''Manual CLI upgrade''' - stop service, download binary with wget, backup old binary, copy new to <code>/usr/local/sbin/</code>, set permissions with <code>chmod +x</code>, start service. Includes version verification (<code>--version</code> or Manager API port 5029). Covers reinstalling after OS upgrades (Debian 10→11→12) using fresh installation with config backup. Troubleshooting sections: duplicate Manager IP causing multiple sensors to upgrade, unable to enable auto-upgrade for default local sensor (solution: create new sensor entry with unique ID, Manager IP 127.0.0.1, restart service, then configure auto-upgrade on new sensor - default local sensor does not support auto-upgrade), "need AES!" error (fix with <code>php php/run.php delete_aes_key</code> or <code>manager_enable_unencrypted = yes</code>), deprecated options in v2025.09.1 (vxlan, sipdefrag, etc. replaced by udp_port_vxlan, snaplen), "Permission denied" during upgrade (<code>noexec</code> on /tmp - remount with exec), "Could not resolve host" (use <code>curlproxy</code> or manual SCP), TLS protocol errors (<code>upgrade_try_http_if_https_fail = yes</code> temporarily), missing database tables after upgrade (manually CREATE TABLE).
'''Summary:''' Guide for upgrading/downgrading VoIPmonitor sensor. Two methods: (1) '''GUI upgrade''' - Settings → Sensors → UPGRADE button, includes scheduling to avoid 429 rate-limiting errors by setting different auto-upgrade datetime per sensor group. (2) '''Manual CLI''' - stop service, wget binary, backup old, copy new to <code>/usr/local/sbin/</code>, chmod +x, start. Covers offline upgrade (SCP transfer), fresh install after OS upgrade (backup config, run install-script.sh, restore config). Deprecated options in v2025.09.1: vxlan→udp_port_vxlan, sipdefrag→internal, interface_snaplen→snaplen. Troubleshooting: duplicate Manager IP causes multi-sensor upgrade, default local sensor needs manual replacement for auto-upgrade, "need AES" fix with delete_aes_key or manager_enable_unencrypted, noexec /tmp fix with remount, missing chmod +x, curlproxy for network issues, upgrade_try_http_if_https_fail for TLS errors, manual CREATE TABLE for missing DB tables.


'''Keywords:''' upgrade, downgrade, sniffer, sensor, GUI upgrade, manual upgrade, wget, tar.gz, systemctl, chmod +x, version check, Manager API, OS upgrade, reinstall, fresh installation, rate limiting, 429 Too Many Requests, stagger upgrades, schedule upgrades, auto-upgrade datetime, UPGRADE subtab, download.voipmonitor.org, need AES, delete_aes_key, manager_enable_unencrypted, deprecated options, 2025.09.1, vxlan, sipdefrag, snaplen, permission denied, noexec, /tmp, fstab, curlproxy, proxy, scp, TLS error, upgrade_try_http_if_https_fail, HTTP fallback, missing table, cdr_audio_transcribe, database schema, new sensor version available, notification persists, enable upgrade sniffer to development version
'''Keywords:''' upgrade, downgrade, sniffer, sensor, GUI upgrade, manual upgrade, wget, systemctl, chmod, version check, Manager API, OS upgrade, reinstall, rate limiting, 429 error, schedule upgrades, auto-upgrade datetime, need AES, delete_aes_key, manager_enable_unencrypted, deprecated options, 2025.09.1, permission denied, noexec, curlproxy, TLS error, upgrade_try_http_if_https_fail, missing table


'''Key Questions:'''
'''Key Questions:'''
* How do I upgrade the VoIPmonitor sniffer?
* How do I upgrade the VoIPmonitor sniffer via GUI or CLI?
* How can I downgrade the sensor to a previous version?
* How can I downgrade the sensor to a previous version?
* How do I perform a manual upgrade via command line?
* How can I check the current sniffer version?
* Why does the GUI show a "new sensor version available" notification after all sensors are updated?
* What should I do after upgrading the operating system?
* Why does upgrading one sensor upgrade multiple sensors?
* How do I avoid "429 Too Many Requests" errors when upgrading many sensors?
* How do I avoid "429 Too Many Requests" errors when upgrading many sensors?
* How do I schedule sensor upgrades to prevent rate limiting?
* How do I schedule sensor upgrades to prevent rate limiting?
* How do I stagger sensor upgrade times?
* Where is the auto-upgrade datetime setting in the GUI?
* Why can I not enable auto-upgrade for the default local sensor?
* Why can I not enable auto-upgrade for the default local sensor?
* How do I fix the auto-upgrade issue for a local sensor?
* What should I do after upgrading the operating system?
* Why does upgrading one sensor upgrade multiple sensors?
* How do I fix "sniffer error: need AES!" after upgrade?
* How do I fix "sniffer error: need AES!" after upgrade?
* Which configuration options are deprecated in version 2025.09.1?
* Which configuration options are deprecated in version 2025.09.1?

Latest revision as of 16:48, 8 January 2026


This guide covers VoIPmonitor sensor (sniffer) upgrades and downgrades. Two methods are available: Web GUI (recommended) or manual CLI.

Quick Reference

Task Command
Stop service systemctl stop voipmonitor
Start service systemctl start voipmonitor
Check version (local) /usr/local/sbin/voipmonitor --version
Check version (remote) echo 'sniffer_version' | nc 127.0.0.1 5029
Download latest stable wget https://www.voipmonitor.org/current-stable-sniffer-static-64bit.tar.gz

Method 1: GUI Upgrade (Recommended)

  1. Navigate to Settings → Sensors
  2. Click the blue UPGRADE button next to the sensor
  3. Select the desired version from the dropdown
  4. The GUI handles download and restart automatically

ℹ️ Note: This method requires the sensor to be running and connected to the GUI.

Scheduling Upgrades to Avoid Rate-Limiting

When upgrading many sensors simultaneously, you may encounter 429 Too Many Requests errors from download.voipmonitor.org.

Solution: Stagger upgrade times:

  1. Click the wrench icon next to each sensor
  2. Go to the UPGRADE subtab
  3. Set different auto-upgrade datetime values for sensor groups

💡 Tip: Example: Upgrade 10 sensors at 06:30, next 10 at 06:40, etc.

Method 2: Manual CLI Upgrade

Step 1: Stop Service

systemctl stop voipmonitor

Step 2: Download Binary

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

Alternative - Direct binary download: 

# For specific version (replace version number)
wget https://download.voipmonitor.org/senzor/download/2025.04.4/voipmonitor.gz.64 -O voipmonitor.gz
gunzip voipmonitor.gz
cp voipmonitor /usr/local/sbin/voipmonitor
chmod +x /usr/local/sbin/voipmonitor

Step 3: Install

tar xzf voipmonitor-sniffer.tar.gz
cd voipmonitor-*-static

# Backup old binary
mv /usr/local/sbin/voipmonitor /usr/local/sbin/voipmonitor.backup

# Install new binary
cp ./voipmonitor /usr/local/sbin/voipmonitor
chmod +x /usr/local/sbin/voipmonitor

Step 4: Start Service

systemctl start voipmonitor

Offline Upgrade

For servers without internet access:

  1. On a machine WITH internet:
    wget https://www.voipmonitor.org/current-stable-sniffer-static-64bit.tar.gz
  2. Transfer to offline server:
    scp voipmonitor-sniffer.tar.gz user@offline-server:/tmp/
  3. On offline server: Follow Steps 1, 3, 4 from Method 2 above

ℹ️ Note: Restore backup if needed: cp /usr/local/sbin/voipmonitor.backup /usr/local/sbin/voipmonitor

Reinstalling After OS Upgrade

After major OS upgrades (e.g., Debian 10→11→12), perform a fresh installation: 

# 1. Stop and disable old service
sudo systemctl stop voipmonitor && sudo systemctl disable voipmonitor

# 2. Backup configuration
sudo cp /etc/voipmonitor.conf /etc/voipmonitor.conf.backup

# 3. Download and install fresh
wget https://www.voipmonitor.org/current-stable-sniffer-static-64bit.tar.gz
tar xzf voipmonitor-sniffer-*.tar.gz
cd voipmonitor-*-static
sudo ./install-script.sh

# 4. Restore configuration
sudo cp /etc/voipmonitor.conf.backup /etc/voipmonitor.conf

# 5. Enable and start
sudo systemctl enable --now voipmonitor

💡 Tip: For client-server deployments, verify firewall rules for ports 5029 (manager) and 60024 (packet buffer).

Deprecated Options (v2025.09.1+)

Remove these obsolete directives from voipmonitor.conf:

Removed Option Replacement
vxlan, vxlan_port, vxlan_skipcrc udp_port_vxlan = 4789
packet_buffer_total_size max_buffer_mem, ringbuffer
udp_reassembly*, sipdefrag* Handled internally
interface_snaplen snaplen = 3200
max_sip_size, sanity_checks, check_sip_header Built-in improvements

Verify after cleanup: 

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

Troubleshooting

Upgrading One Sensor Affects Multiple Sensors

Cause: Multiple sensors share the same Manager IP + Port combination.

Fix:

  1. Check Settings → Sensors for duplicate IP/Port entries
  2. Ensure each sensor has a unique Manager IP (or unique port if on same host)
  3. Never use 127.0.0.1 for remote sensors

Cannot Enable Auto-Upgrade for Default Local Sensor

The default "local sensor" entry does not support auto-upgrade.

Solution: Create a new sensor entry:

  1. Settings → Sensors → Add new sensor
  2. Set: Sensor ID (unique), Manager IP: 127.0.0.1, Manager Port: 5029
  3. Restart service: systemctl restart voipmonitor
  4. Configure auto-upgrade on the new sensor entry

"New Sensor Version Available" Notification Persists

Cause: Development version option is enabled.

Fix: Disable System Configuration → Advanced → "enable upgrade sniffer to development version"

"sniffer error: need AES!"

After upgrade, the GUI cannot communicate with sensor due to encryption key mismatch.

Solutions: 

# Option 1: Remove old AES key from GUI database
cd /var/www/voipmonitor && php php/run.php delete_aes_key

# Option 2: Disable encryption in sensor config
echo "manager_enable_unencrypted = yes" >> /etc/voipmonitor.conf
systemctl restart voipmonitor

⚠️ Warning: manager_enable_unencrypted = yes reduces security. Use only in trusted networks.

"Permission denied" During Upgrade

Cause: /tmp mounted with noexec flag.

Fix: 

# Temporary fix
mount -o remount,exec /tmp

# Permanent fix: edit /etc/fstab and remove 'noexec' from /tmp line

Binary Lacks Execute Permission After Upgrade

Symptom: Service fails to start, "Permission denied" on /usr/local/sbin/voipmonitor.

Fix: 

chmod +x /usr/local/sbin/voipmonitor
systemctl start voipmonitor

"Could not resolve host: download.voipmonitor.org"

Solutions:

1. Configure proxy (if required): 

# In /etc/voipmonitor.conf
curlproxy = http://proxy.example.com:3128

2. Manual binary copy from another sensor: 

scp working-sensor:/usr/local/sbin/voipmonitor /tmp/
cp /tmp/voipmonitor /usr/local/sbin/voipmonitor
chmod +x /usr/local/sbin/voipmonitor

SSL/TLS Protocol Error During Upgrade

Symptom: tlsv1 alert protocol version error.

Temporary fix: 

# In /etc/voipmonitor.conf
upgrade_try_http_if_https_fail = yes

⚠️ Warning: Disable this option after upgrade completes. HTTP is less secure than HTTPS.

Missing Database Table After Upgrade

Symptom: Table 'voipmonitor.cdr_audio_transcribe' doesn't exist

Fix: Create the missing table manually: 

-- Connect to database
mysql -h your_db_host -u your_db_user -p voipmonitor

-- Create the missing table (example for cdr_audio_transcribe)
CREATE TABLE `cdr_audio_transcribe` (
  `ID` bigint unsigned NOT NULL AUTO_INCREMENT,
  `calldate` datetime NOT NULL,
  `fbasename` varchar(255) DEFAULT NULL,
  `a_language` varchar(10) DEFAULT NULL,
  `b_language` varchar(10) DEFAULT NULL,
  `a_text` mediumtext,
  `b_text` mediumtext,
  PRIMARY KEY (`ID`,`calldate`),
  KEY `fbasename` (`fbasename`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb3
PARTITION BY RANGE COLUMNS(calldate)
(PARTITION p_future VALUES LESS THAN MAXVALUE ENGINE = InnoDB);

Then restart: systemctl restart voipmonitor

See Also

AI Summary for RAG

Summary: Guide for upgrading/downgrading VoIPmonitor sensor. Two methods: (1) GUI upgrade - Settings → Sensors → UPGRADE button, includes scheduling to avoid 429 rate-limiting errors by setting different auto-upgrade datetime per sensor group. (2) Manual CLI - stop service, wget binary, backup old, copy new to /usr/local/sbin/, chmod +x, start. Covers offline upgrade (SCP transfer), fresh install after OS upgrade (backup config, run install-script.sh, restore config). Deprecated options in v2025.09.1: vxlan→udp_port_vxlan, sipdefrag→internal, interface_snaplen→snaplen. Troubleshooting: duplicate Manager IP causes multi-sensor upgrade, default local sensor needs manual replacement for auto-upgrade, "need AES" fix with delete_aes_key or manager_enable_unencrypted, noexec /tmp fix with remount, missing chmod +x, curlproxy for network issues, upgrade_try_http_if_https_fail for TLS errors, manual CREATE TABLE for missing DB tables.

Keywords: upgrade, downgrade, sniffer, sensor, GUI upgrade, manual upgrade, wget, systemctl, chmod, version check, Manager API, OS upgrade, reinstall, rate limiting, 429 error, schedule upgrades, auto-upgrade datetime, need AES, delete_aes_key, manager_enable_unencrypted, deprecated options, 2025.09.1, permission denied, noexec, curlproxy, TLS error, upgrade_try_http_if_https_fail, missing table

Key Questions:

  • How do I upgrade the VoIPmonitor sniffer via GUI or CLI?
  • How can I downgrade the sensor to a previous version?
  • How do I avoid "429 Too Many Requests" errors when upgrading many sensors?
  • How do I schedule sensor upgrades to prevent rate limiting?
  • Why can I not enable auto-upgrade for the default local sensor?
  • What should I do after upgrading the operating system?
  • Why does upgrading one sensor upgrade multiple sensors?
  • How do I fix "sniffer error: need AES!" after upgrade?
  • Which configuration options are deprecated in version 2025.09.1?
  • How do I fix "Permission denied" during sensor upgrade?
  • How do I fix "Could not resolve host" during GUI upgrade?
  • How do I fix SSL/TLS protocol version error during upgrade?
  • How do I fix missing database table error after upgrade?
Retrieved from "https://www.voipmonitor.org/doc/index.php?title=Sniffer_upgrade&oldid=10108"