Sniffer upgrade: Difference between revisions

From VoIPmonitor.org
(Add explicit warning that upgrade_try_http_if_https_fail is TEMPORARY workaround, add GUI configuration method, and emphasize disabling after upgrade)
(Rewrite: konsolidace a vylepšení struktury - kompaktnější formát, tabulky, lepší organizace troubleshootingu)
 
(7 intermediate revisions by the same user not shown)
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.'''


== Method 1: Upgrading via the Web GUI (Recommended) ==
<kroki lang="mermaid">
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.
%%{init: {'flowchart': {'nodeSpacing': 15, 'rankSpacing': 30}}}%%
flowchart LR
    START[Need Upgrade?] --> Q1{GUI Available?}
    Q1 -->|Yes| GUI[GUI Upgrade]
    Q1 -->|No| CLI[Manual CLI]
    GUI --> DONE[Verify Version]
    CLI --> DONE
</kroki>


# Navigate to '''Settings -> Sensors''' in the VoIPmonitor GUI.
== Quick Reference ==
# 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.
# 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.


== Method 2: Manual Upgrade/Downgrade (via Command Line) ==
{| class="wikitable"
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.
|-
! Task !! Command
|-
| 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>
|}


=== Step 1: Stop the Running Sniffer ===
== Method 1: GUI Upgrade (Recommended) ==
First, log in to the sensor's server via SSH and stop the service. For modern systems using systemd:
 
<pre>
# Navigate to '''Settings → Sensors'''
systemctl stop voipmonitor
# Click the blue '''UPGRADE''' button next to the sensor
</pre>
# Select the desired version from the dropdown
For older systems using SysV init:
# The GUI handles download and restart automatically
<pre>
 
/etc/init.d/voipmonitor stop
{{Note|This method requires the sensor to be running and connected to the GUI.}}
</pre>
 
''Tip: If the service fails to stop, you may need to terminate the process manually as a last resort: `killall -9 voipmonitor`''
=== Scheduling Upgrades to Avoid Rate-Limiting ===


=== Step 2: Download the Sniffer Archive ===
When upgrading many sensors simultaneously, you may encounter '''429 Too Many Requests''' errors from <code>download.voipmonitor.org</code>.
Download the latest stable static binary from the official VoIPmonitor website. This package contains all necessary files.


<pre>
'''Solution:''' Stagger upgrade times:
# This command downloads the latest stable 64-bit static sniffer
# Click the '''wrench icon''' next to each sensor
wget https://www.voipmonitor.org/current-stable-sniffer-static-64bit.tar.gz -O voipmonitor-sniffer.tar.gz
# Go to the '''UPGRADE''' subtab
</pre>
# Set different '''auto-upgrade datetime''' values for sensor groups


'''Alternative: Direct Gzipped Binary Download'''
{{Tip|Example: Upgrade 10 sensors at 06:30, next 10 at 06:40, etc.}}


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:
== Method 2: Manual CLI Upgrade ==


=== Step 1: Stop Service ===
<syntaxhighlight lang="bash">
<syntaxhighlight lang="bash">
# For a specific version (replace with desired version)
systemctl stop voipmonitor
wget https://download.voipmonitor.org/senzor/download/2025.04.4/voipmonitor.gz.64 -O ./voipmonitor.gz
</syntaxhighlight>


# Unzip the file
=== Step 2: Download Binary ===
gunzip ./voipmonitor.gz
<syntaxhighlight lang="bash">
wget https://www.voipmonitor.org/current-stable-sniffer-static-64bit.tar.gz -O voipmonitor-sniffer.tar.gz
</syntaxhighlight>


# Copy to correct location (preserving executable attributes)
'''Alternative - Direct binary download:'''
<syntaxhighlight lang="bash">
# 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
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 `wget` command.
=== Step 3: Install ===
 
<syntaxhighlight lang="bash">
=== Step 3: Install the New Binary ===
<pre>
# 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
cp ./voipmonitor /usr/local/sbin/voipmonitor
# Ensure the new binary is executable
chmod +x /usr/local/sbin/voipmonitor
chmod +x /usr/local/sbin/voipmonitor
</pre>
</syntaxhighlight>


=== Step 4: Start the Service ===
=== Step 4: Start Service ===
Finally, start the sniffer service again.
<syntaxhighlight lang="bash">
<pre>
systemctl start voipmonitor
systemctl start voipmonitor
</pre>
</syntaxhighlight>
Or for older systems:
<pre>
/etc/init.d/voipmonitor start
</pre>


== Verifying the Version ==
== Offline Upgrade ==
After an upgrade or downgrade, it's important to verify that the correct version is running.


=== Local Check ===
For servers without internet access:
You can check the version directly from the binary on the sensor's server:
<pre>
/usr/local/sbin/voipmonitor --version
</pre>
Or, for more detail:
<pre>
/usr/local/sbin/voipmonitor | head
</pre>


=== Remote Check (via Manager API) ===
# '''On a machine WITH internet:'''
If the sniffer is running, you can query its version remotely using its manager API (default port 5029):
#: <code>wget https://www.voipmonitor.org/current-stable-sniffer-static-64bit.tar.gz</code>
<pre>
# '''Transfer to offline server:'''
echo 'sniffer_version' | nc 127.0.0.1 5029
#: <code>scp voipmonitor-sniffer.tar.gz user@offline-server:/tmp/</code>
</pre>
# '''On offline server:''' Follow Steps 1, 3, 4 from Method 2 above


== Reinstalling After Operating System Upgrades ==
{{Note|1=Restore backup if needed: <code>cp /usr/local/sbin/voipmonitor.backup /usr/local/sbin/voipmonitor</code>}}


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.
== Reinstalling After OS Upgrade ==


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.
After major OS upgrades (e.g., Debian 10→11→12), perform a fresh installation:


=== Fresh Installation After OS Upgrade ===
<syntaxhighlight lang="bash">
 
# 1. Stop and disable old service
Follow these steps to perform a fresh clean installation:
sudo systemctl stop voipmonitor && sudo systemctl disable voipmonitor
 
;1. Stop and disable the old service:
<pre>
sudo systemctl stop voipmonitor
sudo systemctl disable voipmonitor
</pre>


;2. Back up your configuration file (important!):
# 2. Backup configuration
<pre>
sudo cp /etc/voipmonitor.conf /etc/voipmonitor.conf.backup
sudo cp /etc/voipmonitor.conf /etc/voipmonitor.conf.backup
</pre>
This preserves your database connection settings, network interface configuration, and sensor ID.


;3. Download the latest stable static binary:
# 3. Download and install fresh
<pre>
wget https://www.voipmonitor.org/current-stable-sniffer-static-64bit.tar.gz
wget https://www.voipmonitor.org/current-stable-sniffer-static-64bit.tar.gz -O voipmonitor-sniffer.tar.gz
tar xzf voipmonitor-sniffer-*.tar.gz
</pre>
Use the appropriate URL for your architecture (32-bit or ARM) if needed.
 
;4. Extract and run the installation script:
<pre>
tar xzf voipmonitor-sniffer.tar.gz
cd voipmonitor-*-static
cd voipmonitor-*-static
sudo ./install-script.sh
sudo ./install-script.sh
</pre>


;5. Restore your configuration file:
# 4. Restore configuration
<pre>
sudo cp /etc/voipmonitor.conf.backup /etc/voipmonitor.conf
sudo cp /etc/voipmonitor.conf.backup /etc/voipmonitor.conf
</pre>


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


;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).
== Deprecated Options (v2025.09.1+) ==


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.
Remove these obsolete directives from <code>voipmonitor.conf</code>:


== Troubleshooting ==
{| class="wikitable"
|-
! 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
|}


=== Upgrading One Sensor Upgrades Multiple Sensors ===
Verify after cleanup:
<syntaxhighlight lang="bash">
systemctl restart voipmonitor
journalctl -u voipmonitor -n 50 | grep -i "unknown\|option"
</syntaxhighlight>


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.
== Troubleshooting ==


'''Symptoms:'''
=== Upgrading One Sensor Affects Multiple Sensors ===
* 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:'''
'''Cause:''' Multiple sensors share the same Manager IP + Port combination.
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.
'''Fix:'''
# 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


'''Resolution:'''
=== Cannot Enable Auto-Upgrade for Default Local Sensor ===


1. Navigate to '''Settings → Sensors''' in the GUI
The default "local sensor" entry does not support auto-upgrade.
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:'''
'''Solution:''' Create a new sensor entry:
After correcting the configuration, attempt the upgrade again on the target sensor. Verify that only that specific sensor updates its version.
# '''Settings → Sensors → Add new sensor'''
# Set: Sensor ID (unique), Manager IP: <code>127.0.0.1</code>, Manager Port: <code>5029</code>
# Restart service: <code>systemctl restart voipmonitor</code>
# Configure auto-upgrade on the new sensor entry


For more information on configuring sensors, see [[Settings#Sensors|GUI Settings]].
=== "New Sensor Version Available" Notification Persists ===


=== "New Sensor Version Available" Notification Persists After Upgrade ===
'''Cause:''' Development version option is enabled.


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.
'''Fix:''' Disable '''System Configuration → Advanced → "enable upgrade sniffer to development version"'''


'''Symptoms:'''
=== "sniffer error: need AES!" ===
* 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:'''
After upgrade, the GUI cannot communicate with sensor due to encryption key mismatch.
The GUI may be comparing against development/snapshot versions when the development version option is enabled.


'''Resolution:'''
'''Solutions:'''
 
<syntaxhighlight lang="bash">
1. Navigate to '''System Configuration -> Advanced''' in the GUI
# Option 1: Remove old AES key from GUI database
2. Ensure the option "enable upgrade sniffer to development version" is '''disabled'''
cd /var/www/voipmonitor && php php/run.php delete_aes_key
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:'''
# Option 2: Disable encryption in sensor config
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.
echo "manager_enable_unencrypted = yes" >> /etc/voipmonitor.conf
 
=== "sniffer error: need AES!" After Sensor Upgrade ===
 
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.
 
This commonly occurs when:
* You are managing a sensor through a dedicated local GUI rather than the main GUI
* After upgrading the sensor, the encryption requirements or keys have changed
* The local GUI database contains the old encryption key that no longer matches the upgraded sensor
 
'''Symptoms:'''
* 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)'''
 
Remove the AES encryption key from the local GUI database so the GUI can re-establish communication with the sensor:
 
<pre>
# Navigate to the GUI directory
cd /var/www/voipmonitor
 
# Remove the old AES encryption key
php php/run.php delete_aes_key
</pre>
 
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:
 
<pre>
# Edit the sensor's voipmonitor.conf file
nano /etc/voipmonitor.conf
 
# Add this line to disable encryption for the manager API:
manager_enable_unencrypted = yes
 
# Restart the VoIPmonitor sensor service
service voipmonitor restart
</pre>
 
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 `delete_aes_key` 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 `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:
 
* <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 ===
 
After removing deprecated options and adding any needed replacements, restart the sensor and verify it starts without warnings about unknown options:
 
<pre>
systemctl restart voipmonitor
systemctl restart voipmonitor
journalctl -u voipmonitor -n 50 | grep -i "unknown\|option"
</syntaxhighlight>
</pre>


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 `/tmp` directory, this is typically caused by the `/tmp` partition being mounted with the `noexec` flag. Many modern Linux distributions (Debian, Ubuntu, RHEL, CentOS 8+) mount `/tmp` with `noexec` 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 `/tmp`
<syntaxhighlight lang="bash">
* Error occurs immediately after downloading and extracting the archive in `/tmp`
# Temporary fix
* Service fails to restart after the upgrade attempt
 
'''Resolution:'''
 
The proper fix is to remount the `/tmp` partition with execute permissions rather than avoiding `/tmp` entirely:
 
;1. Check the current mount options:
<pre>
mount | grep "/tmp"
</pre>
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):
<pre>
mount -o remount,exec /tmp
mount -o remount,exec /tmp
</pre>


;3. Re-run the upgrade process from Step 3 above:
# Permanent fix: edit /etc/fstab and remove 'noexec' from /tmp line
<pre>
</syntaxhighlight>
cd /tmp/voipmonitor-*-static
cp ./voipmonitor /usr/local/sbin/voipmonitor
chmod +x /usr/local/sbin/voipmonitor
</pre>


;4. Make the change permanent by editing <code>/etc/fstab</code>:
=== Binary Lacks Execute Permission After Upgrade ===
<pre>
sudo nano /etc/fstab
# OR
sudo vi /etc/fstab
</pre>
Find the line corresponding to the `/tmp` mount point and remove the <code>noexec</code> option. For example, change:
<pre>
tmpfs    /tmp    tmpfs    defaults,nosuid,nodev,noexec    0    0
</pre>
To:
<pre>
tmpfs    /tmp    tmpfs    defaults,nosuid,nodev    0    0
</pre>


;5. Apply the permanent fix by remounting all filesystems:
'''Symptom:''' Service fails to start, "Permission denied" on <code>/usr/local/sbin/voipmonitor</code>.
<pre>
sudo mount -a
</pre>


;6. Verify the fix:
'''Fix:'''
<pre>
<syntaxhighlight lang="bash">
mount | grep "/tmp"
# Should no longer show "noexec" in the options
</pre>
 
;7. Start the service:
<pre>
systemctl start voipmonitor
</pre>
 
'''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 `/tmp` 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 `/tmp`, download and extract the archive to an alternative directory like `/usr/src/voipmonitor-upgrade` 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 `/usr/local/sbin/voipmonitor` lacks the execute permission bit. This can happen if the `chmod +x` command was omitted during the upgrade process, or if permissions were not preserved when copying the binary.
 
'''Symptoms:'''
* Service fails to start after running `systemctl start voipmonitor`
* System logs show "Permission denied" when attempting to execute `/usr/local/sbin/voipmonitor`
* The upgrade appears to complete successfully, but the service will not run
* When manually running `/usr/local/sbin/voipmonitor --version`, you get a "Permission denied" error
 
'''Diagnosis:'''
 
Check the file permissions on the binary:
 
<pre>
ls -l /usr/local/sbin/voipmonitor
</pre>
 
Look for the executable flags in the permission string:
* 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:
 
<pre>
# Check which user runs the voipmonitor service
systemctl cat voipmonitor.service | grep "User="
</pre>
 
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:
<pre>
sudo -i
# OR
su -
</pre>
 
;2. Add execute permissions to the binary:
<pre>
chmod +x /usr/local/sbin/voipmonitor
chmod +x /usr/local/sbin/voipmonitor
</pre>
;3. Verify the permissions are correct:
<pre>
ls -l /usr/local/sbin/voipmonitor
# Should now show: -rwxr-xr-x (with 'x' flags)
</pre>
;4. Start the service:
<pre>
systemctl start voipmonitor
systemctl start voipmonitor
systemctl status voipmonitor
</syntaxhighlight>
</pre>
 
;5. Verify the service is running:
<pre>
ps aux | grep voipmonitor
usr/local/sbin/voipmonitor --version
</pre>
 
'''Prevention:'''
 
This issue highlights the importance of including the `chmod +x` step during manual upgrades. When performing manual command-line upgrades, always follow the complete procedure:
 
<pre>
# After copying the new binary:
cp ./voipmonitor /usr/local/sbin/voipmonitor
chmod +x /usr/local/sbin/voipmonitor  # CRITICAL STEP
systemctl start voipmonitor
</pre>
 
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:
=== "Could not resolve host: download.voipmonitor.org" ===


<pre>
'''Solutions:'''
# Edit the sensor's voipmonitor.conf file
nano /etc/voipmonitor.conf


# Add this line to configure the proxy (replace with your proxy address and port)
'''1. Configure proxy (if required):'''
<syntaxhighlight lang="ini">
# In /etc/voipmonitor.conf
curlproxy = http://proxy.example.com:3128
curlproxy = http://proxy.example.com:3128
</syntaxhighlight>


# For authenticated proxy, use: curlproxy = http://username:password@proxy.example.com:3128
'''2. Manual binary copy from another sensor:'''
 
<syntaxhighlight lang="bash">
# Restart the VoIPmonitor service
scp working-sensor:/usr/local/sbin/voipmonitor /tmp/
systemctl restart voipmonitor
</pre>
 
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.
 
'''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:
 
<pre>
# Step 1: Stop the service on the failing sensor
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
</syntaxhighlight>


# Step 5: Start the service
=== SSL/TLS Protocol Error During Upgrade ===
systemctl start voipmonitor
 
# Step 6: Verify the version has updated
/usr/local/sbin/voipmonitor --version
</pre>
 
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:
<pre>
sniffer error: failed download upgrade: error:1409442E:SSL routines:ssl3_read_bytes:tlsv1 alert protocol version
</pre>
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.


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


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


# Restart the VoIPmonitor sensor service
{{Warning|1=Disable this option after upgrade completes. HTTP is less secure than HTTPS.}}
systemctl restart voipmonitor
</pre>


'''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:
 
<pre>
# Edit voipmonitor.conf and remove or comment out this line:
# upgrade_try_http_if_https_fail = yes
 
# Or set it explicitly to no:
upgrade_try_http_if_https_fail = no
 
# Restart the service
systemctl restart voipmonitor
</pre>
 
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:
 
<pre>
# Edit the sensor's voipmonitor.conf file
nano /etc/voipmonitor.conf
 
# Add this line to configure a proxy server
curlproxy = http://proxy.example.com:3128
 
# Restart the VoIPmonitor sensor service
systemctl restart voipmonitor
</pre>
 
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:
<pre>
mysql -h your_db_host -u your_db_user -p voipmonitor
mysql -h your_db_host -u your_db_user -p voipmonitor
</pre>
Replace {{code|your_db_host}} and {{code|your_db_user}} 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}} (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 660: 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>
</syntaxhighlight>


;3. Adjust the partition definitions as needed for your current date:
Then restart: <code>systemctl restart voipmonitor</code>
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}} table
* Ensure the last partition uses {{code|LESS THAN MAXVALUE}} to handle future data automatically
* You can add more partitions as your data grows using {{code|ALTER TABLE ... ADD PARTITION}}


;4. Restart the VoIPmonitor service:
== See Also ==
<pre>
systemctl restart voipmonitor
</pre>
Or on older systems:
<pre>
service voipmonitor restart
</pre>


'''Alternative Solution: Import Complete Schema File'''
* [[Sniffer_installation]] - Initial sensor installation
* [[Sniffer_configuration]] - Configuration parameters
* [[Settings#Sensors]] - GUI sensor management
* [[Systemd_for_voipmonitor_service_management]] - Service management


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:
== AI Summary for RAG ==
 
<pre>
# Import the schema, which will add missing tables
mysql -u root -p voipmonitor < /usr/local/share/voipmonitor/sql/create_tables.sql
</pre>
 
However, this method is generally NOT recommended for production databases because:
* It may try to recreate existing tables (though most SQL scripts use {{code|IF NOT EXISTS}})
* 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:
'''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.


<pre>
'''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
# Check service status
systemctl status voipmonitor
</pre>


You should see output indicating the service is {{code|active (running)}}.
Check the service log to confirm no more table-related errors:
<pre>
journalctl -u voipmonitor -n 50 | grep -i "table\|error"
</pre>
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 ==
'''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 ({{code|systemctl stop voipmonitor}}). 2) Downloading the desired static binary {{code|tar.gz}} package using {{code|wget}}. 3) Backing up the old binary, copying the new one to {{code|/usr/local/sbin/}}, and setting execute permissions with {{code|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), includes a specific section on encountering "Permission denied" errors during manual upgrades when {{code|/tmp}} is mounted with the {{code|noexec}} flag (with resolution steps: check mount options, remount {{code|/tmp}} with {{code|exec}}, edit {{code|/etc/fstab}} to remove {{code|noexec}} permanently), 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 troubleshooting section about the "sniffer error: need AES!" message that can occur after sensor upgrades when using local GUIs. This error happens when the sensor enforces AES encryption for the manager API and the local GUI database contains outdated encryption keys. The solutions are: 1) Run {{code|php php/run.php delete_aes_key}} in the GUI directory to remove the old encryption key, 2) Disable AES encryption via System settings -> System configuration in the GUI, or 3) Add {{code|manager_enable_unencrypted = yes}} to the sensor's {{code|voipmonitor.conf}} file to allow unencrypted manager API communication. To prevent this issue, it is recommended to manage sensors through the main GUI rather than dedicated local GUIs. The document also 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. The document further includes a troubleshooting section for the specific error: "sniffer error: failed download upgrade: Could not resolve host: download.voipmonitor.org". This error indicates the sensor cannot reach the VoIPmonitor download server. There are two workarounds: 1) Use the {{code|curlproxy}} configuration option in {{code|/etc/voipmonitor.conf}} to specify a proxy server for HTTP/HTTPS downloads (syntax: {{code|curlproxy = http://proxy.example.com:3128}} or with authentication). 2) Manually copy the upgraded sniffer binary from another working sensor using {{code|scp}}, then overwrite the old binary on the failing sensor. Troubleshooting tips include checking DNS resolution ({{code|/etc/resolv.conf}}), network connectivity ({{code|ping download.voipmonitor.org}}), and firewall rules (allow HTTPS port 443 to *voipmonitor.org). The document also includes a troubleshooting section for SSL/TLS protocol version errors during sensor upgrades (error message examples: "error:1409442E:SSL routines:ssl3_read_bytes:tlsv1 alert protocol version"). This error occurs when an old sensor binary attempts to connect to the download server using outdated TLS protocols (TLS 1.0/1.1) while the server requires modern protocols (TLS 1.2+). There are three solutions: 1) Enable HTTP fallback by adding {{code|upgrade_try_http_if_https_fail = yes}} to {{code|/etc/voipmonitor.conf}} and restarting the service (or via GUI: Settings -> Sensors -> Edit sensor -> search for option and set to yes) - this allows the sensor to automatically fall back to HTTP if HTTPS fails due to TLS version issues (recommended for old sensors). CRITICAL: This is a TEMPORARY workaround only - you MUST disable this option after the upgrade completes by removing the line from {{code|voipmonitor.conf}} or setting it to {{code|no}} (or via GUI: Settings -> Sensors -> Edit -> set to no). HTTP downloads are less secure than HTTPS and should only be used as a temporary measure. 2) Use the manual upgrade procedure (Method 2) to transfer the binary manually via SCP from another machine. 3) Use the {{code|curlproxy}} option to route connections through a proxy server that supports modern TLS protocols (for corporate networks). The document also includes a troubleshooting section for "Service Fails to Start After Upgrade Due to 'Permission denied'". This error occurs when the installed binary at {{code|/usr/local/sbin/voipmonitor}} lacks the execute permission bit AFTER the upgrade completes, causing the service to fail with Permission denied when starting. This can happen if the {{code|chmod +x}} command was omitted during the upgrade process or if permissions were not preserved when copying the binary. Diagnosis involves checking file permissions with {{code|ls -l /usr/local/sbin/voipmonitor}} (look for missing 'x' flags in {{code|-rw-r--r--}} vs executable {{code|-rwxr-xr-x}}). Resolution steps: 1) Ensure logged in as root ({{code|sudo -i}} or {{code|su -}}), 2) Add execute permissions with {{code|chmod +x /usr/local/sbin/voipmonitor}}, 3) Verify permissions with {{code|ls -l}}, 4) Start service with {{code|systemctl start voipmonitor}}, 5) Verify running with {{code|ps aux | grep voipmonitor}}. Prevention: Always include {{code|chmod +x /usr/local/sbin/voipmonitor}} after copying the binary during manual upgrades. GUI upgrade method handles this automatically. The document also includes a troubleshooting section for "Service Fails to Start After Upgrade Due to Missing Database Table". This error occurs when the service fails after an upgrade with an error like "Table 'voipmonitor.cdr_audio_transcribe' doesn't exist", indicating that new database tables introduced in the upgraded version were not created during the upgrade process. This happens when the sensor binary was manually updated without updating the database schema, the database schema update step was skipped or failed, or a new feature was added that requires a new table (such as audio transcription). Resolution: Connect to the MySQL server used by the sensor host and execute the SQL statement to create the missing table. For example, if the missing table is cdr_audio_transcribe (introduced in version 2024.11.2), create it with the full schema including columns (ID, calldate, fbasename, a_language, b_language, a_text, b_text, a_segments, b_segments), primary key (ID, calldate), KEY on fbasename, ENGINE=InnoDB, DEFAULT CHARSET=utf8mb3, COMPRESSION=lz4, and PARTITION BY RANGE COLUMNS(calldate). Adjust the partition definitions as needed for the current date, creating partitions for historical data periods and ensuring the last partition uses LESS THAN MAXVALUE. Alternatively, import the complete schema file (/usr/local/share/voipmonitor/sql/create_tables.sql), but this is NOT recommended for production databases because it may be slower and gives less control over partition configuration. After creating the table, restart the voipmonitor service. Verification includes checking service status with systemctl status voipmonitor and checking logs with journalctl -u voipmonitor -n 50 | grep -i "table\|error". Prevention: Always follow the complete upgrade procedure including database schema updates, ensure the sensor has database permissions to execute schema updates for GUI upgrades, check release notes for required database changes for manual upgrades, and test upgrades in staging environments first.
'''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, need AES, AES error, AES encryption, encryption key, delete_aes_key, php run.php, local GUI, main GUI, sensor configuration upgrade, manager API, encryption mismatch, 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, permission denied, noexec, /tmp, temporary directory, mount options, remount, exec, fstab, Debian, Ubuntu, RHEL, CentOS, security hardening, manager_enable_unencrypted, unencrypted manager API, Could not resolve host, download.voipmonitor.org, DNS error, network error, proxy configuration, curlproxy, authenticated proxy, manual binary copy, scp, copy from another sensor, offline upgrade, TLS protocol version error, SSL error, tlsv1 alert protocol version, upgrade_try_http_if_https_fail, HTTP fallback, HTTPS download failed, SSL routines:ssl3_read_bytes:tlsv1, certificate error, TLS 1.0, TLS 1.1, TLS 1.2, TLS 1.3, outdated TLS, modern TLS, download server TLS, old sensor, legacy sensor, failed download upgrade, service fails to start after upgrade, permission denied after upgrade, binary lacks execute permissions, chmod +x, /usr/local/sbin/voipmonitor, missing execute bit, file permissions, ls -l, -rwxr-xr-x, -rw-r--r--, executable flags, systemctl start fails, missing database table, table doesn't exist, cdr_audio_transcribe, cdr_whisper, database schema update, CREATE TABLE, MySQL table creation, partition configuration, RANGE COLUMNS, utf8mb3, lz4 compression, InnoDB, manual table creation, database upgrade, schema file, create_tables.sql, 2024.11.2 upgrade, audio transcription table, Whisper table, service startup error, database error, missing table after upgrade
'''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?
* What is the easiest way to update my remote sensors?
* How do I avoid "429 Too Many Requests" errors when upgrading many sensors?
* How do I perform a manual upgrade of the sniffer using the command line?
* How do I schedule sensor upgrades to prevent rate limiting?
* How can I check which version of the sniffer I am currently running?
* Why can I not enable auto-upgrade for the default local sensor?
* Where can I download the latest stable sniffer binary?
* What should I do after upgrading the operating system?
* Why does upgrading one sensor upgrade multiple sensors?
* Why does upgrading one sensor upgrade multiple sensors?
* How do I fix a sensor configured with 127.0.0.1?
* How do I fix "sniffer error: need AES!" after upgrade?
* Why are all sensors updating when I upgrade only one?
* Which configuration options are deprecated in version 2025.09.1?
* What should I do after upgrading the operating system (e.g., Debian 11 to Debian 12)?
* How do I fix "Permission denied" during sensor upgrade?
* How do I fix a "sensor is not registered" error after an OS upgrade?
* How do I fix "Could not resolve host" during GUI upgrade?
* How do I perform a fresh installation of the sniffer after an operating system upgrade?
* How do I fix SSL/TLS protocol version error during upgrade?
* Why does the GUI still show "new sensor version available" after all sensors are updated?
* How do I fix missing database table error after upgrade?
* 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?
* How do I fix "sniffer error: need AES!" after sensor upgrade?
* Why does my local GUI show "need AES!" error after sensor upgrade?
* How do I remove AES encryption key from GUI database?
* What is the delete_aes_key command for?
* How do I fix AES encryption mismatch between GUI and sensor?
* How do I disable encryption for manager API in sensor configuration?
* What is manager_enable_unencrypted used for?
* How do I fix "Could not resolve host: download.voipmonitor.org" during GUI upgrade?
* Why does the sensor upgrade fail with DNS or network errors?
* How do I configure proxy settings for sensor upgrades?
* What is curlproxy used for?
* How do I upgrade a sensor when it cannot download from the internet?
* How do I manually copy the sniffer binary from another sensor?
* Why do I get "Permission denied" errors when upgrading the sniffer?
* How do I fix "Permission denied" during sensor upgrade from /tmp?
* What causes "Permission denied" errors during manual upgrade?
* How do I remount /tmp with exec permissions?
* How do I remove noexec from /tmp mount?
* How do I permanently fix /tmp noexec issue?
* How do I edit fstab to allow execution in /tmp?
* How do I fix SSL/TLS protocol version error during sensor upgrade?
* What does "error:1409442E:SSL routines:ssl3_read_bytes:tlsv1 alert protocol version" mean?
* Why does the sensor upgrade fail with TLS version errors?
* How do I enable HTTP fallback for sensor upgrades?
* What is upgrade_try_http_if_https_fail used for?
* How do I fix tlsv1 alert protocol version error?
* How do I upgrade an old sensor that uses outdated TLS protocols?
* Why does the voipmonitor service fail to start after an upgrade with "Permission denied"?
* How do I fix "Permission denied" when starting voipmonitor service after upgrade?
* What causes service startup failure after sensor upgrade?
* How do I check if the voipmonitor binary has execute permissions?
* How do I add execute permissions to /usr/local/sbin/voipmonitor?
* Why does systemctl start voipmonitor fail with Permission denied after upgrade?
* What file permissions does the voipmonitor binary need?
* Why does my upgraded sniffer binary lack execute permissions?
* How do I fix missing execute bit on voipmonitor binary?
* How do I fix a missing database table error after upgrade?
* What does "Table 'voipmonitor.cdr_audio_transcribe' doesn't exist" mean?
* How do I create the cdr_audio_transcribe table manually?
* What SQL do I run to fix missing table after sensor upgrade?
* Why does the service fail to start after upgrade with missing table?
* How do I create missing database partitions for cdr_audio_transcribe?
* What is the schema for cdr_audio_transcribe table?
* Should I import create_tables.sql after sensor upgrade?
* How do I adjust partition definitions for cdr_audio_transcribe?
* What version introduced cdr_audio_transcribe table?

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"