Data Cleaning: Difference between revisions

From VoIPmonitor.org
(Fix cleanspool modes: Modern mode (.cleanspool_cache in hourly dirs) is default, Legacy mode (MySQL files table) is deprecated. Cache files are in hourly directories like /2026-01-01/15/.cleanspool_cache)
(Fix incorrect association of _2 parameters with tar_move - they are for spooldir_2 used with capture rules (TP-38))
 
(10 intermediate revisions by the same user not shown)
Line 1: Line 1:
This guide explains how VoIPmonitor manages data retention for both captured packets (PCAP files) and Call Detail Records (CDRs) in the database. Proper configuration is essential for managing disk space and maintaining long-term database performance.
{{DISPLAYTITLE:Data Cleaning and Retention}}
[[Category:Configuration]]
[[Category:Administration]]
 
This guide explains how VoIPmonitor manages data retention for PCAP files and database records.


== Overview ==
== Overview ==


VoIPmonitor generates two primary types of data that require periodic cleaning:
VoIPmonitor generates two types of data requiring periodic cleanup:
* '''PCAP Files:''' Raw packet captures of SIP/RTP/GRAPH data stored on the filesystem in the spool directory. These can consume significant disk space.
* '''CDR Data:''' Call metadata stored in the MySQL database. Large tables can slow down GUI performance if not managed properly.


The system uses two separate, independent mechanisms to manage the retention of this data:
{| class="wikitable"
 
<kroki lang="plantuml">
@startuml
skinparam shadowing false
skinparam defaultFontName Arial
skinparam rectangle {
  BorderColor #4A90E2
  BackgroundColor #FFFFFF
}
 
rectangle "VoIPmonitor Sensor" as sensor
 
package "Filesystem Storage" {
  folder "/var/spool/voipmonitor" as spool {
    file "SIP PCAPs" as sip
    file "RTP PCAPs" as rtp
    file "GRAPH files" as graph
    file "AUDIO files" as audio
  }
}
 
database "MySQL Database" {
  collections "cdr" as cdr
  collections "cdr_next" as cdrnext
  collections "register_state" as reg
  collections "sip_msg" as sipmsg
  collections "files" as filesdb
}
 
sensor --> spool : writes
sensor --> cdr : writes
sensor --> filesdb : indexes files
 
rectangle "Filesystem Cleaner\n(maxpoolsize/maxpooldays)" as fscleaner #E8F5E9
rectangle "Database Cleaner\n(cleandatabase)" as dbcleaner #E3F2FD
 
fscleaner --> spool : deletes old files
fscleaner --> filesdb : reads file index
dbcleaner --> cdr : drops partitions
 
note bottom of fscleaner : Runs every 5 minutes\nDeletes oldest data first
note bottom of dbcleaner : Daily partition drop\nInstant operation
@enduml
</kroki>
 
== Filesystem Cleaning (PCAP Spool Directory) ==
 
The sensor stores captured call data in a structured directory tree on the local filesystem.
 
=== How Cleanspool Works: Modern vs Legacy Mode ===
 
VoIPmonitor has two distinct modes for tracking and cleaning PCAP files. Understanding which mode your installation uses is critical for troubleshooting cleaning issues.
 
{| class="wikitable" style="background-color: #E8F5E9;"
|-
|-
! colspan="2" style="background: #4CAF50; color: white;" | Cleanspool Modes
! Data Type !! Storage !! Cleanup Mechanism !! Key Parameters
|-
|-
| style="vertical-align: top;" | '''Modern Mode (Default):'''
| '''PCAP Files''' || Filesystem (spool directory) || Cleanspool process (every 5 min) || <code>maxpoolsize</code>, <code>maxpooldays</code>
|
<code>cleanspool_use_files = no</code>
 
Uses filesystem-based cache files (<code>.cleanspool_cache</code>) stored in '''hourly''' directories within the spool. This allows fast direct reading of file lists without querying MySQL.
 
Example cache location: <code>/var/spool/voipmonitor/2026-01-01/15/.cleanspool_cache</code>
 
'''Why this is the default:''' The <code>pcap_dump_tar = yes</code> setting (TAR archive mode) is enabled by default. When TAR mode is active, VoIPmonitor automatically uses this faster filesystem-based caching.
 
'''Advantages:'''
* Faster - no MySQL queries needed for file listing
* More reliable - no dependency on <code>id_sensor</code> configuration
* Better performance when scanning TAR archives
|-
|-
| style="vertical-align: top;" | '''Legacy Mode (Database-Indexed):'''
| '''CDR Records''' || MySQL database || Partition dropping (instant) || <code>cleandatabase</code>
|
<code>cleanspool_use_files = yes</code>
 
Uses the MySQL <code>files</code> table to track all created PCAP files. This older method had reliability issues, particularly in multi-sensor deployments where <code>id_sensor</code> configuration inconsistencies could cause the file index to fail.
 
'''Note:''' This mode is deprecated and should generally not be used. It remains available for backwards compatibility only.
|}
|}


==== How Modern Mode Works (Default) ====
{{Note|These are '''independent systems''' - filesystem cleanup does not affect database records and vice versa.}}
 
In modern mode (<code>cleanspool_use_files = no</code>), which is active by default when TAR mode is enabled:
 
<kroki lang="plantuml">
@startuml
skinparam shadowing false
participant "Sniffer" as S
participant "Cleanspool\nThread" as C
collections "Filesystem" as FS
file ".cleanspool_cache\n(in hourly dirs)" as Cache
 
S -> FS: Write PCAP file\n(into TAR archive)
S -> Cache: Update hourly cache
 
... Every 5 minutes ...
 
C -> Cache: Read file lists from\nhourly .cleanspool_cache files
C -> Cache: Find oldest files\nwhere age > maxpooldays\nOR total size > maxpoolsize
loop For each file
    C -> FS: DELETE file
    C -> Cache: Update cache
end
@enduml
</kroki>
 
'''Characteristics of Modern Mode:'''
* Uses <code>.cleanspool_cache</code> files in '''hourly''' directories (e.g., <code>/var/spool/voipmonitor/2026-01-01/15/.cleanspool_cache</code>)
* Fast direct reading without MySQL queries
* Default behavior when <code>pcap_dump_tar = yes</code> (TAR archive mode is default)
* For recent hours, prefers direct directory reading over cache for accuracy
 
'''Checking which mode is active:'''
<syntaxhighlight lang="bash">
# Check TAR mode (if yes, modern cleanspool is active)
grep pcap_dump_tar /etc/voipmonitor.conf
 
# Check explicit cleanspool_use_files setting
grep cleanspool_use_files /etc/voipmonitor.conf
 
# Find .cleanspool_cache files in hourly directories (modern mode)
find /var/spool/voipmonitor -name ".cleanspool_cache" -type f | head -5
</syntaxhighlight>
 
==== The maxpool_clean_obsolete Parameter ====


This parameter controls how cleanspool handles files that exist on the filesystem but are NOT in its index (either database <code>files</code> table or <code>.cleanspool_cache</code>).
=== Quick Reference ===


{| class="wikitable"
{| class="wikitable"
|-
|-
! Setting !! Behavior !! Use Case
! Purpose !! Parameter !! Example
|-
|-
| <code>maxpool_clean_obsolete = no</code> (default) || Only delete files that are indexed. Unknown files are ignored. || Safe default - protects manually added files
| Limit total PCAP size || <code>maxpoolsize</code> || <code>maxpoolsize = 512000</code> (500 GB)
|-
| <code>maxpool_clean_obsolete = yes</code> || Delete ALL files in spool directory, including those not in index || Clean up orphaned files, recover from index corruption
|}
 
{| class="wikitable" style="background-color: #FFF3CD;"
|-
|-
! colspan="2" style="background: #856404; color: white;" | Warning: maxpool_clean_obsolete
| Limit RTP specifically || <code>maxpoolrtpsize</code> || <code>maxpoolrtpsize = 102400</code> (100 GB)
|-
|-
| style="vertical-align: top;" | '''Caution:'''
| Limit PCAP age || <code>maxpooldays</code> || <code>maxpooldays = 30</code>
|
When <code>maxpool_clean_obsolete = yes</code> is enabled, cleanspool will scan the entire filesystem and delete any files not found in its index. This includes:
* Files manually copied into the spool directory
* Files from backup restores
* Files from other sensors (in shared storage scenarios)
 
Only enable this if you understand the implications and want aggressive cleanup of unindexed files.
|}
 
=== Reducing Data Collection at Source ===
 
Before configuring cleanup policies, consider reducing the amount of data captured. This is often the most effective long-term solution for storage management.
 
==== Save Only RTP Headers (Major Space Saver) ====
 
RTP packets typically contain the full audio payload, which consumes the majority of disk space. If you only need call quality statistics (MOS, jitter, packet loss) and not actual audio playback, switch to saving RTP headers only.
 
Edit <code>/etc/voipmonitor.conf</code>:
 
<syntaxhighlight lang="ini">
# Change from full RTP to headers only
savertp = header
</syntaxhighlight>
 
{| class="wikitable"
|-
|-
! Setting !! Storage Impact !! Use Case
| CDR retention (days) || <code>cleandatabase</code> || <code>cleandatabase = 30</code>
|-
|-
| <code>savertp = yes</code> || High (~10x more) || Requires ability to play back audio from PCAPs
| CDR retention (size) || <code>cleandatabase_size</code> || <code>cleandatabase_size = 512000</code> (+ <code>cleandatabase_size_force = true</code>)
|-
|-
| <code>savertp = header</code> || Low || Only CDR statistics needed, no audio playback required
| Save only RTP stats || <code>savertp</code> || <code>savertp = header</code> (saves ~90% space)
|}
|}


With <code>savertp = header</code>, VoIPmonitor still captures all necessary metadata for MOS scoring, jitter analysis, packet loss statistics, and quality graphs, but does not store the actual audio payload. This can reduce storage consumption by up to 90%.
== Filesystem Cleaning (PCAP Files) ==


'''Important:''' After changing from <code>savertp = yes</code> to <code>savertp = header</code>, existing PCAP files will remain playable. New calls will only contain RTP headers.
=== How Cleanspool Works ===


{| class="wikitable" style="background-color: #FFF3CD;"
The sniffer maintains a file index '''in memory'''. Every 5 minutes, the cleanspool thread checks retention limits and deletes the oldest files when limits are exceeded.
|-
! colspan="2" style="background: #856404; color: white;" | Critical: Distributed Architecture Consideration
|-
| style="vertical-align: top;" | '''<code>packetbuffer_sender</code> Architecture:'''
|
If you are using the Packet Mirroring/Client-Server mode (<code>packetbuffer_sender=yes</code> on remote sensors), the <code>savertp</code> setting must be applied on the '''central server''' where packet analysis is performed, not on the individual sensors.


{|
<kroki lang="plantuml">
|-
@startuml
! Architecture !! Where to Apply <code>savertp = header</code>
skinparam shadowing false
|-
skinparam defaultFontSize 11
| <code>packetbuffer_sender = no</code> (Local Processing) || On each sensor/probe's configuration file
participant "Sniffer" as S
|-
participant "Cleanspool" as C
| <code>packetbuffer_sender = yes</code> (Packet Mirroring) || On the central server's configuration file (not on sensors)
database "In-Memory\nIndex" as MEM
|}
collections "Filesystem" as FS


For distributed deployment details, see [[Sniffer_distributed_architecture#Controlling_Packet_Storage_in_Packet_Mirroring_Mode|Client-Server Architecture]].
S -> FS: Write PCAP
|}
S -> MEM: Update index
... Every 5 minutes ...
C -> MEM: Find oldest files\nexceeding limits
loop Delete old files
    C -> FS: DELETE
    C -> MEM: Remove entry
end
note over MEM : Persisted to\n.cleanspool_cache
@enduml
</kroki>


==== Enabling Selective Audio Recording with Capture Rules ====
The <code>.cleanspool_cache</code> files in hourly directories serve as '''persistent storage for fast restart''' - they allow quick index reload without scanning the entire filesystem.


For compliance scenarios where you need to record full audio for specific calls while keeping most calls with headers only (or disabled), use GUI capture rules to create exceptions:
{{Note|1='''Legacy Indexing:''' Old VoIPmonitor versions stored metadata in MySQL <code>files</code> table. This can be enabled with <code>cleanspool_use_files = yes</code> (deprecated, do not use).}}


'''Workflow:'''
=== Retention Configuration ===
 
1. **Set global default to headers only:**
<syntaxhighlight lang="ini">
savertp = header
</syntaxhighlight>


2. **Create capture rules in the GUI for exceptions:**
Limits can be set by '''size''' (MB) or '''age''' (days). When both are configured, the first limit reached triggers cleanup.
  * Navigate to '''Control Panel''' > '''Capture Rules'''
  * For selective audio recording, set the '''recordRTP''' option to '''ON'''
  * Rules with <code>recordRTP=ON</code> will capture full RTP audio, overriding the global <code>savertp=header</code> setting for matched calls


'''Use Cases:'''
==== Global Limits ====


{| class="wikitable"
{| class="wikitable"
|-
|-
! Scenario !! Configuration !! File Storage
! Parameter !! Default !! Description
|-
| Legal Holds
| Create IP rule for subject party with <code>recordRTP=ON</code>
| Full audio recorded
|-
|-
| VIP Customers
| <code>maxpoolsize</code> || 102400 (100 GB) || Maximum total size for all PCAP data
| Create phone number prefix rules for specific ranges with <code>recordRTP=ON</code>
| Full audio recorded
|-
|-
| All Other Calls
| <code>maxpooldays</code> || (unset) || Maximum age in days for all PCAP data
| Global <code>savertp = header</code>
| Headers only (no audio)
|}
|}


This approach allows you to comply with data retention laws (e.g., GDPR) by minimizing audio recording while still meeting specific legal or business requirements for certain call categories.
==== Per-Type Limits ====
 
For detailed capture rule configuration options, see [[Capture_rules]].
For more configuration options, see [[Sniffer_configuration#Saving_Options|Sniffer Configuration - Saving Options]].
 
=== Spool Directory Structure ===
 
The spool directory uses a hierarchical structure organized by time and data type.


{| class="wikitable"
{| class="wikitable"
|-
|-
! Structure !! Description
! Data Type !! Size Parameter !! Days Parameter
|-
| <code>YY-mm-dd/HH/MM/{TYPE}/files...</code> || Date → Hour → Minute → Data Type
|}
 
The <code>{TYPE}</code> subdirectory can be:
* <code>SIP</code> - SIP signaling PCAP files
* <code>RTP</code> - RTP audio PCAP files
* <code>AUDIO</code> - Converted audio files (WAV/OGG)
* <code>GRAPH</code> - Quality graph image files
 
Example path:
<syntaxhighlight lang="text">
/var/spool/voipmonitor/25-01-06/10/45/RTP/rtp_2025-01-06-10-45.tar
</syntaxhighlight>
 
The timestamps are based on UTC or the timezone configured in <code>voipmonitor.conf</code>.
 
'''Important:''' The cleanup process operates at the '''minute level''', not hour level. When cleaning is triggered, it removes the oldest minute's worth of data (e.g., <code>25-01-06/08/57/</code>) rather than deleting an entire hour's worth of data at once.
 
=== Spool Directory Location ===
 
By default, all data is stored in <code>/var/spool/voipmonitor</code>. This location can be changed by setting the <code>spooldir</code> option in <code>voipmonitor.conf</code>.
 
==== Relocating the Spool Directory to a Different Partition ====
 
If your default partition is running out of space, you can move the spool directory to a larger partition or dedicated disk. This is particularly useful when MySQL Error 28 ("No space left on device") occurs despite retention settings being in place.
 
{| class="wikitable"
|-
|-
! Situation !! Recommended Action
| SIP signaling || <code>maxpoolsipsize</code> || <code>maxpoolsipdays</code>
|-
|-
| <code>/var/lib/mysql</code> full but other partitions available || Move spool to larger partition and update <code>spooldir</code> in <code>voipmonitor.conf</code>
| RTP audio || <code>maxpoolrtpsize</code> || <code>maxpoolrtpdays</code>
|-
|-
| Multiple disks available || Use dedicated partition for PCAP storage
| Quality graphs || <code>maxpoolgraphsize</code> || <code>maxpoolgraphdays</code>
|-
|-
| GUI on same server || Sync GUI <code>SNIFFER_DATA_PATH</code> to match new <code>spooldir</code>
| Converted audio (WAV/OGG) || <code>maxpoolaudiosize</code> || <code>maxpoolaudiodays</code>
|}
|}


===== Procedure to Relocate Spooldir =====
==== Recommended Configuration ====


;Step 1: Identify Available Space
Limit RTP (largest files) while keeping SIP longer for troubleshooting:
Check all partitions to find a suitable location:
<syntaxhighlight lang="bash">
df -h
</syntaxhighlight>


;Step 2: Create New Spool Directory
Create the directory on the destination partition:
<syntaxhighlight lang="bash">
# Example: Use /mnt/pcaps partition
mkdir -p /mnt/pcaps/voipmonitor
# Set correct ownership for both sniffer and GUI access
chown voipmonitor:voipmonitor /mnt/pcaps/voipmonitor
chmod 755 /mnt/pcaps/voipmonitor
</syntaxhighlight>
;Step 3: Update VoIPmonitor Configuration
Edit <code>/etc/voipmonitor.conf</code> to point to the new location:
<syntaxhighlight lang="ini">
<syntaxhighlight lang="ini">
spooldir = /mnt/pcaps/voipmonitor
# /etc/voipmonitor.conf
maxpoolrtpsize = 102400  # 100 GB limit for RTP
maxpoolsize = 512000      # 500 GB overall limit
</syntaxhighlight>
</syntaxhighlight>


;Step 4: Update GUI Configuration (Critical)
==== Secondary Storage Limits (spooldir_2) ====


If the GUI runs on the same server, you MUST update the path the GUI uses to access the spool. This is defined in the GUI configuration file:
When using <code>spooldir_2</code> for secondary storage (configured via [[Capture_rules|capture rules]] with "Store pcaps to second spooldir" enabled), use <code>_2</code> suffix parameters for cleaning:


* Debian/Ubuntu: <code>/var/www/html/voipmonitor/config/configuration.php</code>
<code>maxpoolsize_2</code>, <code>maxpooldays_2</code>, <code>maxpoolrtpsize_2</code>, etc.
* RHEL/CentOS: <code>/var/www/voipmonitor/config/configuration.php</code>


Edit the GUI configuration file:
{{Note|1=<code>spooldir_2</code> is '''independent''' from <code>tar_move</code>. The <code>_2</code> suffix parameters apply only to the secondary spooldir configured via capture rules, not to <code>tar_move</code> destination storage.}}
<syntaxhighlight lang="php">
// Find and update this line to match your new spooldir
define('SNIFFER_DATA_PATH', '/mnt/pcaps/voipmonitor');
</syntaxhighlight>


'''Important:''' The <code>SNIFFER_DATA_PATH</code> in the GUI config MUST match the <code>spooldir</code> setting in <code>voipmonitor.conf</code>. If these are mismatched, the GUI will be unable to locate and display call recordings.
=== Emergency Cleanup ===


;Step 5: Restart Services
{{Warning|1=Emergency cleanup activates when disk is nearly full and '''ignores all <code>maxpool*</code> settings'''.}}
Apply all changes by restarting the services:
<syntaxhighlight lang="bash">
# Restart the VoIPmonitor sensor
systemctl restart voipmonitor
 
# If using Apache/Nginx, reload web server
systemctl reload apache2    # Debian/Ubuntu
# or
systemctl reload nginx      # RHEL/CentOS
</syntaxhighlight>
 
;Step 6: Verify Configuration
<syntaxhighlight lang="bash">
# Check if new spool directory is being used
ls -ld /mnt/pcaps/voipmonitor
 
# Verify GUI can access the path
grep SNIFFER_DATA_PATH /path/to/gui/config/configuration.php
 
# Check sensor logs for any spool-related errors
tail -f /var/log/voipmonitor.log
</syntaxhighlight>
 
===== Optional: Move Existing Data =====
 
If you want to migrate existing PCAP files to the new location:
<syntaxhighlight lang="bash">
# Stop the sensor to prevent writes during migration
systemctl stop voipmonitor
 
# Move existing data (this may take a long time)
mv /var/spool/voipmonitor/* /mnt/pcaps/voipmonitor/
 
# Restart the sensor
systemctl start voipmonitor
</syntaxhighlight>
 
=== Retention Mechanism ===
 
The cleaning process runs automatically every 5 minutes and removes data based on the configuration in <code>voipmonitor.conf</code>.


{| class="wikitable"
{| class="wikitable"
|-
|-
! Mechanism !! Check Interval !! Purpose
! Parameter !! Default !! Triggers When
|-
|-
| '''Retention Policy (<code>maxpool*</code>)''' || Every 5 minutes || Capacity control - maintains storage below configured limits
| <code>autocleanspoolminpercent</code> || 1 || Disk usage reaches 99%
|-
|-
| '''Emergency Cleanup (<code>autoclean*</code>)''' || Every 5 minutes || Disk space "fuse" - prevents disk exhaustion when free space falls below threshold
| <code>autocleanmingb</code> || 5 || Free space below 5 GB
|}
|}


==== Retention Policy: maxpool* Parameters ====
When triggered, oldest data is deleted aggressively until thresholds are cleared. The <code>cleanspool_enable_fromto</code> time window is ignored.
 
When triggered by a <code>maxpool*</code> setting (e.g., <code>maxpoolsize</code>, <code>maxpoolrtpsize</code>):
 
1. The cleanup identifies the oldest minute of data
2. It removes the entire <code>YY-mm-dd/HH/MM/</code> directory tree (e.g., <code>25-01-06/08/57/</code>)
3. If <code>maxpoolsize</code> is used (overall limit), it removes all data types from that minute
4. If type-specific limits are used (e.g., <code>maxpoolaudiosize</code>), it removes only that data type
 
'''Important: The cleanup removes ONE minute of data at a time, not an entire hour's worth. This ensures gradual, controlled cleanup instead of sudden large deletions.'''
 
==== Emergency Cleanup: autoclean* Parameters ====


The <code>autoclean*</code> parameters act as a safety "fuse" to prevent the disk from filling up:
=== Control Parameters ===


{| class="wikitable"
{| class="wikitable"
|-
|-
! Parameter !! Default !! Behavior
! Parameter !! Default !! Description
|-
| <code>autocleanspoolminpercent</code> || 1 || When disk usage reaches 99%, trigger emergency cleanup regardless of <code>maxpool*</code> settings
|-
| <code>autocleanmingb</code> || 5 || When free space falls below 5 GB, trigger emergency cleanup
|}
 
When either threshold is breached:
* Oldest data is deleted AGGRESSIVELY until free space is restored
* This happens regardless of your <code>maxpool*</code> or <code>maxpooldays</code> settings
* Normal retention behavior resumes once thresholds are cleared
 
==== Performance Warning: maxpoolaudiosize ====
 
The <code>maxpoolaudiosize</code> parameter controls the size of converted audio files (WAV/OGG) when <code>saveaudio</code> is enabled.
 
{| class="wikitable" style="background-color: #FFF3CD;"
|-
! colspan="2" style="background: #856404; color: white;" | Performance Consideration
|-
! Warning
| Audio conversion (PCAP → WAV/OGG) is CPU-intensive. For deployments with high call volumes (>200 concurrent calls or high CPS), using <code>saveaudio</code> can overload the system and cause packet loss or performance degradation.
|}
 
* '''Recommended:''' For high-volume deployments, use <code>savertp = yes</code> and convert on-demand via the GUI instead
* '''Alternative:''' Consider <code>savertp = header</code> if you only need statistics, not audio playback
 
=== Retention Configuration ===
 
The cleaning configuration allows you to set limits based on total size (in Megabytes) or age (in days).
 
{| class="wikitable" style="background-color: #E8F5E9;"
|-
|-
! colspan="2" style="background: #4CAF50; color: white;" | Important: Default Retention Behavior
| <code>cleanspool</code> || yes || Enable/disable spool cleaning
|-
|-
| style="vertical-align: top;" | '''Default Behavior:'''
| <code>cleanspool_enable_fromto</code> || 0-24 || Restrict cleaning to hours (e.g., <code>1-5</code> for 1-5 AM)
|
By default, PCAP files are deleted based on '''size only''' (using <code>maxpoolsize</code>), not based on time. The default <code>maxpoolsize</code> is 100 GB (102400 MB). When the spool directory reaches 100 GB, the oldest PCAP files are automatically deleted to free up space.
 
Time-based retention (<code>maxpooldays</code>) is '''disabled by default''' and must be explicitly configured if you want to limit retention by days instead of size.
|}
 
You can set limits based on total size (in Megabytes) or age (in days). If both a size and day limit are set for the same data type, the first limit that is reached will trigger the cleaning.
 
{| class="wikitable"
|-
|-
! Parameter !! Default Value !! Description
| <code>maxpool_clean_obsolete</code> || no || Delete files not in index (use with caution)
|-
|-
| <code>maxpoolsize</code> || 102400 (100 GB) || The total maximum disk space for '''all''' captured data (SIP, RTP, GRAPH, AUDIO).
| <code>all_unlink_log</code> || no || Log all file deletions
|-
| <code>maxpooldays</code> || (unset) || The maximum number of days to keep '''all''' captured data.
|-
| <code>maxpoolsipsize</code> || (unset) || A specific size limit for SIP PCAP files only.
|-
| <code>maxpoolsipdays</code> || (unset) || A specific age limit for SIP PCAP files only.
|-
| <code>maxpoolrtpsize</code> || (unset) || A specific size limit for RTP PCAP files only.
|-
| <code>maxpoolrtpdays</code> || (unset) || A specific age limit for RTP PCAP files only.
|-
| <code>maxpoolgraphsize</code> || (unset) || A specific size limit for GRAPH files only.
|-
| <code>maxpoolgraphdays</code> || (unset) || A specific age limit for GRAPH files only.
|-
| <code>maxpoolaudiosize</code> || (unset) || A specific size limit for converted audio files (WAV/OGG) only.
|-
| <code>maxpoolaudiodays</code> || (unset) || An age limit for converted audio files (WAV/OGG) only.
|}
|}


=== Recommended Configuration Strategy: Mixed Size-Based Retention ===
=== Reducing Data at Source ===


For optimal disk space management while preserving SIP signaling for long-term analysis, use a **mixed retention strategy**:
==== Save RTP Headers Only ====


{| class="wikitable"
If you only need quality metrics (MOS, jitter, packet loss) without audio playback:
|-
! Data Type !! Recommended Setting !! Rationale
|-
| RTP (audio payload) || Size-based (<code>maxpoolrtpsize</code>) || RTP consumes most disk space (5-10x more than SIP)
|-
| SIP (signaling) || Overall only (<code>maxpoolsize</code>, no <code>maxpoolsipdays</code>) || SIP files are small; keep as long as total space allows
|-
| Charts/Audio || Overall only (<code>maxpoolsize</code>) || Supplementary data, keep as space permits
|}


{| class="wikitable" style="background-color: #E3F2FD;"
|-
! colspan="2" style="background: #1976D2; color: white;" | Configuration Example: Long-Term SIP with Limited RTP
|-
| style="vertical-align: top;" | Scenario:
| You want to keep SIP signaling and charts for as long as possible, but limit RTP (audio) to a reasonable size to prevent disk exhaustion.
|-
| style="vertical-align: top;" | Configuration:
| Edit <code>/etc/voipmonitor.conf</code>:
<syntaxhighlight lang="ini">
<syntaxhighlight lang="ini">
# Set size limit for RTP only (keeps audio limited)
savertp = header
maxpoolrtpsize = 102400    # 100 GB for RTP
</syntaxhighlight>
 
# DO NOT set maxpoolsipdays - let SIP be controlled by maxpoolsize only


# Set overall limit for all data together
This reduces storage by up to '''90%''' while preserving all quality statistics.
maxpoolsize = 512000      # 500 GB total limit (includes SIP + RTP + GRAPH + AUDIO)
</syntaxhighlight>
|-
| style="vertical-align: top;" | Behavior:
| RTP is deleted when it exceeds <code>maxpoolrtpsize</code> (100 GB). SIP, chart, and audio files are kept as long as the total <code>maxpoolsize</code> (500 GB) allows. If the disk fills up (total exceeds 500 GB), oldest data is deleted regardless of type.
|-
| style="vertical-align: top;" | Why this works:
| RTP files are huge (GBs per day) but rarely needed for troubleshooting. SIP files are small (MBs per day) and essential for analyzing call setup/teardown, call flows, and configuration issues. By limiting RTP size but not SIP size, you maximize useful long-term data retention.
|}


=== Alternative Configuration: Time-Based Retention ===


If you need to keep data for a specific number of days (such as compliance requirements), you can use time-based retention parameters.


{| class="wikitable" style="background-color: #FFF3CD;"
==== Disable RTP Entirely ====
|-
! colspan="2" style="background: #856404; color: white;" | Important: Time-Based Retention Basics
|-
| style="vertical-align: top;" | '''Understanding Maximum vs Minimum''':
| <code>maxpoolsipdays</code> sets a '''maximum''' retention period for SIP files, not a guaranteed minimum. To ensure files are kept for at least the specified period, you must allocate sufficient disk space using <code>maxpoolsize</code> to accommodate the expected volume of data for that period.
|}


==== Configuration Example: 14-Day SIP Retention ====
If SIP signaling retention is the priority and you do not need RTP data at all:


{| class="wikitable"
|-
! Scenario !! Configuration !! Behavior
|-
! Keep SIP for 14 days, limit RTP
| Edit <code>/etc/voipmonitor.conf</code>:
<syntaxhighlight lang="ini">
<syntaxhighlight lang="ini">
# Set maximum age for SIP files
savertp = no
maxpoolsipdays = 14
maxpoolgraphdays = 14
 
# Set maximum age for RTP files (can be different)
maxpoolrtpdays = 7
 
# OR set maximum size for RTP files
maxpoolrtpsize = 102400
 
# Allocate sufficient disk space to accommodate 14 days of data
maxpoolsize = 300000    # Ensure this is large enough for 14 days of SIP + graph data
</syntaxhighlight>
</syntaxhighlight>
| SIP files are deleted after 14 days (maximum). RTP files are deleted after 7 days (if using <code>maxpoolrtpdays</code>) or when <code>maxpoolrtpsize</code> limit is reached. If <code>maxpoolsize</code> is reached before the 14-day period, data may be deleted regardless of age. Monitor disk usage to ensure <code>maxpoolsize</code> is sufficient.
|}


==== Verifying Which Cleaning Rule is Active ====
This disables RTP packet storage entirely, reducing PCAP size by approximately '''20x'''. Use this when:
* Storage limits are insufficient for even header-only RTP
* SIP troubleshooting is the primary need (no audio analysis required)
* You need to retain SIP signaling for much longer periods


To debug which cleaning rule is currently applied and confirm your configuration is working:
{{Warning|Setting <code>savertp = no</code> removes all RTP data including quality statistics. Use <code>savertp = header</code> instead if you need MOS, jitter, or packet loss metrics.}}
==== Selective Recording ====


<syntaxhighlight lang="bash">
To record full audio only for specific calls:
# Check systemd journal for clean triggers
# Set <code>savertp = header</code> globally
journalctl -u voipmonitor --since='YYYY-MM-DD' | grep clean -i
# Create capture rules with <code>recordRTP=ON</code> for exceptions
</syntaxhighlight>


The log messages indicate which rule triggered cleanup:
See [[Capture_rules]] for details.
* <code>clean_maxpoolsize</code> - Cleaning triggered by total size limit
* <code>clean_maxpooldays</code> - Cleaning triggered by overall age limit
* <code>clean_maxpoolsipdays</code> - Cleaning triggered by SIP age limit
* <code>clean_maxpoolrtpdays</code> - Cleaning triggered by RTP age limit


If you see multiple triggers, VoIPmonitor applies the first limit that is reached, deleting data until all limits are satisfied.
== Database Cleaning (CDR Records) ==


==== Best Practice: Configure maxpoolsize with Disk Capacity Buffer ====
=== Partitioning Method ===


When setting <code>maxpoolsize</code>, configure a buffer below the total disk capacity. This ensures there is sufficient space during periods when the cleaning process is not active (such as when <code>cleanspool_enable_fromto</code> restricts cleaning to specific hours).
VoIPmonitor uses daily partitioning. Dropping old partitions is instant (milliseconds) regardless of row count.


{| class="wikitable" style="background-color: #FFF3CD;"
|-
! colspan="2" style="background: #856404; color: white;" | Important: Disk Capacity Buffer
|-
| style="vertical-align: top;" | '''Why a Buffer is Needed:'''
|
The cleaning process runs every 5 minutes, but <code>cleanspool_enable_fromto</code> may restrict cleaning to specific hours (e.g., 1-5 AM). During non-cleaning hours, data will continue to accumulate. Setting <code>maxpoolsize</code> close to total disk capacity risks filling the disk outside the active cleaning window.
|-
| style="vertical-align: top;" | '''Recommended Configuration:'''
|
Set <code>maxpoolsize</code> to approximately 90-95% of total disk capacity to create a buffer.
|-
| style="vertical-align: top;" | '''Example:'''
|
For a 7 TB disk:
<syntaxhighlight lang="ini">
<syntaxhighlight lang="ini">
# 6.5 TB = 6656000 MB (approximately 93% of 7 TB)
# Keep CDR records for 30 days
maxpoolsize = 6656000
cleandatabase = 30
 
# Restrict cleaning to 1-5 AM to avoid I/O impact during peak traffic
cleanspool_enable_fromto = 1-5
</syntaxhighlight>
</syntaxhighlight>
This configuration provides a 0.5 TB buffer for data accumulation during the 19-hour cleaning-off window.
|}
=== Manual File Deletion ===


Manual deletion of files from the spool directory is generally safe, but there are important considerations.
=== Database Cleaning Parameters ===
 
==== Is It Safe? ====


{| class="wikitable"
{| class="wikitable"
|-
|-
! Scenario !! Safe? !! Notes
! Parameter !! Default !! Description
|-
|-
| Deleting old directories (prior days/hours) || Yes || The index is recomputed automatically
| <code>cleandatabase</code> || 0 (disabled) || Global retention for CDR, register_state, register_failed, sip_msg
|-
|-
| Deleting current hour while service running || No risk to service, but may cause errors for active captures if file handles are still open
| <code>cleandatabase_cdr</code> || 0 || CDR table (includes <code>message</code> table)
|-
|-
| Deleting current MINUTE while recording in progress || Not recommended || May cause file descriptor errors temporarily
| <code>cleandatabase_rtp_stat</code> || 2 || RTP statistics table
|}
 
When you manually delete files:
* In '''modern mode''' (<code>cleanspool_use_files = yes</code>): The <code>files</code> database table still contains records for deleted files. These orphaned records are cleaned up during the next cleanup cycle.
* In '''legacy mode''': The <code>.cleanspool_cache</code> is recomputed automatically during the next cleanup cycle.
 
==== Orphaned Database Records ====
 
When you manually delete PCAP files, the corresponding records in the MySQL database (CDR tables) remain. This means:
* You will see calls in the GUI
* Clicking "Play" or "Download" will show "File not found" errors
 
{| class="wikitable" style="background-color: #E3F2FD;"
|-
|-
! colspan="2" style="background: #1976D2; color: white;" | Manual Deletion: Database Records Remain
| <code>cleandatabase_register_state</code> || 0 || Registration state
|-
|-
! After deleting PCAP files
| <code>cleandatabase_register_failed</code> || 0 || Failed registrations
| Database CDR records are NOT automatically deleted. Calls will appear in the GUI but show "File not found" for missing files.
|-
|-
! Solution
| <code>cleandatabase_register_time_info</code> || 0 || Registration timing ('''NOT''' covered by global)
| To clean orphaned records, run the database cleaner: <code>voipmonitor --clean-db</code> or use the GUI "Maintenance" tab.
|}
 
==== When Is Manual Deletion Recommended? ====
 
* **Emergency Space Recovery:** If disk is 99% full and autoclean is not processing fast enough, manually deleting old directories (e.g., yesterday's folders) provides immediate space relief
* **Compliance Requests:** Legal requests requiring immediate data removal without waiting for automated cleanup
* **Targeted Cleanup:** Removing data for specific dates/time periods
 
==== Recovering from Index Issues ====
 
If the cleanspool index becomes corrupted or out of sync:
 
'''For Modern Mode (cleanspool_use_files = yes):'''
 
The <code>files</code> table can be rebuilt by rescanning the spool directory:
<syntaxhighlight lang="bash">
# Trigger a reindex via manager API
echo 'manager_file start /tmp/vmsck' | nc 127.0.0.1 5029
echo reindexfiles | nc -U /tmp/vmsck
rm /tmp/vmsck
</syntaxhighlight>
 
'''For Legacy Mode (.cleanspool_cache):'''
 
If the <code>.cleanspool_cache</code> file is deleted or corrupted:
<syntaxhighlight lang="bash">
# Same reindex command works for legacy mode
echo 'manager_file start /tmp/vmsck' | nc 127.0.0.1 5029
echo reindexfiles | nc -U /tmp/vmsck
rm /tmp/vmsck
</syntaxhighlight>
 
The <code>reindexfiles</code> command rescans the spool directory structure and rebuilds the index.
 
{| class="wikitable" style="background-color: #FFF3CD;"
|-
|-
! colspan="2" style="background: #856404; color: white;" | Alternative: Secured Manager API
| <code>cleandatabase_sip_msg</code> || 0 || SIP messages (OPTIONS/SUBSCRIBE/NOTIFY)
|-
|-
If your deployment uses the secured manager API with SSL/TLS, use the secured endpoint instead of the Unix socket method. See [[Encryption_in_manager_api_customer|Manager API documentation]] for the secured API usage.
| <code>cleandatabase_ss7</code> || 0 || SS7 records
|}
 
=== Custom Autocleaning: One-Time Cleanup with Filters ===
 
The GUI provides a '''custom autocleaning''' feature that allows you to perform one-time cleanup of existing recordings based on specific criteria, such as IP address or telephone number. This is useful when you need to clean up data for a specific subset of calls without affecting global retention settings.
 
==== Use Case: Cleaning Old Recordings for a Specific IP ====
 
After configuring [[Capture_rules|capture rules]] to stop recording future calls from a specific IP address, you may still have existing RTP recordings from that IP. Custom autocleaning allows you to remove these old recordings.
 
Example scenario:
* You configured a capture rule to discard RTP for IP <code>192.168.1.50</code>
* Only new calls will be affected by this rule
* Existing recordings for this IP must be cleaned up manually
 
GUI cleanup steps:
# Navigate to '''Settings > Custom Autocleaning'''
# Create a new autocleaning rule
# Set the criteria (e.g., "Delete RTP older than 1 day")
# In the '''Common Filter''' section, specify the target IP address (<code>192.168.1.50</code>)
# Save and apply the rule
# Once the cleanup is complete, remove the autocleaning rule
 
This rule will run once and clean up all matching old recordings, then the capture rule will prevent future recordings.
 
==== Comparison with Global Retention ====
 
{| class="wikitable"
|-
! Feature !! Custom Autocleaning !! Global Retention
|-
| '''Scope''' || Targeted (specific IP, number, filter) || All calls
|-
| '''Purpose''' || One-time cleanup of existing data || Ongoing automated cleanup
|-
| '''Configuration''' || GUI with CDR filters || <code>maxpoolsize</code>, <code>maxpooldays</code>
|-
|-
| '''Flexibility''' || High - can use any CDR filter criteria || Low - time/size only
| <code>partition_operations_enable_fromto</code> || 1-5 || Time window for partition operations (24h format)
|}
|}


=== Diagnosing Disk Space Usage ===
{{Warning|1=<code>register_time_info</code> is NOT covered by global <code>cleandatabase</code>. Set <code>cleandatabase_register_time_info</code> explicitly.}}


To properly configure retention limits, first analyze your actual disk usage:
=== Size-Based Cleaning ===


;Check total disk space
To limit database by size instead of time:
<syntaxhighlight lang="bash">
df -h
</syntaxhighlight>


;Check total spool directory size
<syntaxhighlight lang="ini">
<syntaxhighlight lang="bash">
cleandatabase_size = 512000        # 500 GB limit in MB
du -hs /var/spool/voipmonitor
cleandatabase_size_force = true   # Required to enable
</syntaxhighlight>
 
;Analyze per-day utilization (helps identify growth patterns)
<syntaxhighlight lang="bash">
du -h --max-depth=1 /var/spool/voipmonitor | sort -k2,2
</syntaxhighlight>
 
Example output interpretation:
<syntaxhighlight lang="text">
# 80G   ./2024-12
# 120G  ./2024-11
# 150G  ./2024-10
</syntaxhighlight>
</syntaxhighlight>
This shows recent months consume 80-150 GB of data. Use this data to estimate appropriate size limits.


=== Understanding Directory Size Differences (SIP vs RTP Retention) ===
=== Multi-Sensor Environments ===


If you notice significant size differences between directories in your spool, this is usually expected behavior when you have different retention periods for SIP and RTP data.
When multiple sensors share a database, only '''ONE''' sensor should manage partitions:


{| class="wikitable"
|-
! Age of Directory !! Contents !! Size
|-
| 0-30 days || Both SIP and RTP PCAP files || Large
|-
| 30-90 days || SIP PCAP files only (RTP deleted) || Smaller
|-
| 90+ days || None (both SIP and RTP deleted) || Empty or absent
|}
This behavior is '''expected and by design''' when using different retention periods (e.g., <code>maxpoolsipdays = 90</code> and <code>maxpoolrtpdays = 30</code>).
==== Why RTP Directories Exist After Disabling RTP Saving ====
If you have configured <code>savertp = no</code> or <code>savertp = header</code> but still see <code>RTP</code> subdirectories, this occurs because:
* When <code>savertcp = yes</code>, RTCP (RTP Control Protocol) packets are saved in the <code>rtp_YYYY-MM-DD-HH-MM.tar</code> files
* The <code>RTP</code> directory name refers to the broad UDP port range used for RTP/RTCP traffic
* These files contain RTCP control traffic (receiver reports, sender reports) but not the full RTP audio payload
{| class="wikitable"
|-
! Configuration !! Result !! Expected Directory Size
|-
| <code>savertp = yes</code> + <code>savertcp = yes</code> || Full RTP audio + RTCP controls saved || Very large (GBs)
|-
| <code>savertp = no</code> + <code>savertcp = yes</code> || Only RTCP controls saved || Small (MBs)
|-
| <code>savertp = header</code> + <code>savertcp = yes</code> || RTP headers + RTCP controls saved || Small (MBs)
|}
== Filesystem Troubleshooting ==
=== Files Disappearing Faster Than Expected ===
If PCAP files are being deleted sooner than your <code>maxpooldays</code> setting suggests, check for these common causes:
==== Emergency Cleanup Triggers ====
Emergency cleanup can override your retention settings:
{| class="wikitable"
|-
! Parameter !! Default !! Triggers When
|-
| <code>autocleanspoolminpercent</code> || 1 || Disk usage reaches 99%
|-
| <code>autocleanmingb</code> || 5 || Free space falls below 5 GB
|}
'''Diagnosis:'''
<syntaxhighlight lang="bash">
# Check disk usage
df -h /var/spool/voipmonitor
# Check emergency trigger settings
grep -E "autocleanspoolminpercent|autocleanmingb" /etc/voipmonitor.conf
</syntaxhighlight>
'''Resolution:'''
<syntaxhighlight lang="ini">
<syntaxhighlight lang="ini">
# Increase emergency thresholds (allow more data before emergency cleanup)
# On all sensors EXCEPT one:
autocleanspoolminpercent = 5  # Allow 95% usage before emergency
disable_partition_operations = yes
autocleanmingb = 20            # Trigger at 20 GB free instead of 5 GB
</syntaxhighlight>


==== GUI Configuration Override ====
# On the designated sensor:
 
partition_operations_enable_fromto = 4-6
If <code>mysqlloadconfig = yes</code> (default), GUI sensor settings override <code>voipmonitor.conf</code>:
 
'''Diagnosis:'''
<syntaxhighlight lang="bash">
# Check if database config is enabled
grep mysqlloadconfig /etc/voipmonitor.conf
 
# Check GUI: Settings > Sensors > wrench icon > search "maxpool"
</syntaxhighlight>
</syntaxhighlight>


'''Resolution:''' Update settings via GUI, or set <code>mysqlloadconfig = no</code> to use file-based config only.
=== Limits ===


==== Diagnostic Checklist ====
* '''MySQL/MariaDB partition limit:''' ~8000 partitions per table (~22 years with daily partitioning)
* '''Aurora DB partition limit:''' ~800 partitions per table - much lower than standard MySQL
* '''CDR record limit:''' No practical limit - uses BIGINT


Before applying fixes, run through this diagnostic checklist:
=== Aurora DB / Limited Partition Environments ===


<syntaxhighlight lang="bash">
For databases with low partition limits (like Amazon Aurora), you can pre-create partitions before starting the sniffer and prevent runtime partition creation:
# 1. Check all retention-related settings
cat /etc/voipmonitor.conf | grep -E '^spooldir|^maxpool|^cleandatabase|^autoclean'


# 2. Measure total spool usage
<syntaxhighlight lang="ini">
du -hs /var/spool/voipmonitor
# Pre-create partitions up to a specific date before starting
create_new_partitions_until = 2026-01-31


# 3. Analyze per-day usage patterns
# Disable only partition creation (dropping still works for cleanup)
du -h --max-depth=1 /var/spool/voipmonitor | sort -k2,2
disable_partition_operations_create = yes


# 4. Check disk capacity
# Or disable only partition dropping (creation still works)
df -h
# disable_partition_operations_drop = yes


# 5. Check for emergency cleanup in logs
# Number of partitions to create ahead (default 2)
journalctl -u voipmonitor | grep -i "clean\|autoclean"
create_new_partitions = 2
</syntaxhighlight>
</syntaxhighlight>


=== Spool Directory Filling Due to Database Performance ===
{{Note|1=For Aurora DB with ~800 partition limit: with daily partitions, this gives ~2 years of data. Plan retention accordingly using <code>cleandatabase</code>.}}


If <code>/var/spool/voipmonitor/</code> is filling up rapidly after a disk swap, MySQL upgrade, or configuration change, the issue may be caused by database performance problems.
== Advanced Topics ==


{| class="wikitable" style="background:#fff3cd; border:1px solid #ffc107;"
=== Spool Directory Location ===
|-
! colspan="2" style="background:#ffc107;" | Root Cause: Slow Database Causing Query File Queuing
|-
! Symptoms
| Spool directory fills exponentially, sometimes within hours, even with correct <code>maxpoolsize</code> settings.
|-
! Root Cause
| MySQL cannot process database writes quickly enough, causing query files to queue.
|}


'''Diagnosis:'''
Default: <code>/var/spool/voipmonitor</code>
<syntaxhighlight lang="bash">
# Watch for SQLq (SQL queue) metrics in real-time
tail -f /var/log/syslog | grep voipmonitor | grep SQLq


# Check MySQL InnoDB settings
Structure: <code>YYYY-MM-DD/HH/MM/{SIP|RTP|GRAPH|AUDIO}/files...</code>
mysql -u root -p -e "SHOW VARIABLES LIKE 'innodb_flush_log_at_trx_commit';"
mysql -u root -p -e "SHOW VARIABLES LIKE 'innodb_buffer_pool_size';"
</syntaxhighlight>


'''Solution - Tune MySQL:'''
==== Relocating the Spool ====
<syntaxhighlight lang="ini">
[mysqld]
# 50-70% of server RAM
innodb_buffer_pool_size = 8G


# Fast writes (acceptable data loss risk on crash)
innodb_flush_log_at_trx_commit = 2
</syntaxhighlight>
=== "low spool disk space" Message ===
This message indicates that your configured <code>maxpoolsize</code> exceeds the physical disk capacity. VoIPmonitor may automatically adjust <code>maxpoolsize</code> to a lower value.
'''Resolution:'''
<syntaxhighlight lang="bash">
<syntaxhighlight lang="bash">
# Check actual disk capacity
# 1. Create new directory
df -h /var/spool/voipmonitor
mkdir -p /mnt/storage/voipmonitor
chown voipmonitor:voipmonitor /mnt/storage/voipmonitor


# Set realistic maxpoolsize (leave 5-10% buffer)
# 2. Update sniffer config
# For a 500 GB partition, use ~450 GB:
# /etc/voipmonitor.conf:
maxpoolsize = 460800
# spooldir = /mnt/storage/voipmonitor
</syntaxhighlight>


=== Missing Data Due to NFS/Storage Server Issues ===
# 3. Update GUI config (config/configuration.php):
# define('SNIFFER_DATA_PATH', '/mnt/storage/voipmonitor');


If using remote storage (NFS, SSHFS), missing data may be caused by network connectivity issues rather than retention policies.
# 4. Restart
 
systemctl restart voipmonitor
'''Diagnosis:'''
<syntaxhighlight lang="bash">
# Check system logs for NFS errors
grep -i "nfs" /var/log/syslog | grep "not responding\|timed out"
 
# Test connectivity
ping nfs-server.example.com
nc -zv nfs-server.example.com 2049
</syntaxhighlight>
</syntaxhighlight>


== Tiered Storage and Archival Options ==
=== Tiered Storage (tar_move) ===
 
If you need to extend PCAP retention beyond your fast local disk capacity, there are three recommended approaches.


=== Option 1: Use tar_move Feature (Recommended) ===
Extend retention using secondary storage:
 
The <code>tar_move</code> feature automatically archives PCAP files to secondary storage after they are closed.


<syntaxhighlight lang="ini">
<syntaxhighlight lang="ini">
# Use local fast storage for live capture
spooldir = /var/spool/voipmonitor
spooldir = /var/spool/voipmonitor
# Enable automatic archival
tar_move = yes
tar_move = yes
tar_move_destination_path = /mnt/archive/voipmonitor
tar_move_destination_path = /mnt/archive/voipmonitor
tar_move_max_threads = 2
</syntaxhighlight>
</syntaxhighlight>


{| class="wikitable"
Files in secondary storage remain accessible via GUI.
|-
! Parameter !! Description
|-
| <code>tar_move = yes</code> || Move files to archive after capture completes
|-
| <code>tar_move = copy</code> || Copy files (keep original)
|-
| <code>tar_move_destination_path</code> || Target directory for archived files
|}


'''Important:''' Files in <code>tar_move_destination_path</code> remain accessible via GUI. VoIPmonitor searches both local spooldir and tar_move_destination_path.
==== S3 Cloud Storage ====


==== S3 Cloud Storage Considerations ====
Use <code>rclone</code> instead of <code>s3fs</code> to avoid GUI unresponsiveness:
 
When using S3 storage, use <code>rclone</code> instead of <code>s3fs</code> to avoid GUI unresponsiveness:


<syntaxhighlight lang="bash">
<syntaxhighlight lang="bash">
# Recommended: rclone mount
rclone mount bucket-name /mnt/s3-archive \
/usr/bin/rclone mount bucket-name /mnt/s3-archive \
   --allow-other --dir-cache-time 30s --vfs-cache-mode off
   --allow-other --dir-cache-time 30s --poll-interval 0 \
  --vfs-cache-mode off --buffer-size 0 --use-server-modtime \
  --no-modtime --s3-no-head --log-level INFO
</syntaxhighlight>
</syntaxhighlight>


=== Option 2: Manual Archival with Additional Spool Directories ===
=== Custom Autocleaning (GUI) ===


Move old files manually and configure GUI to access multiple directories:
For one-time cleanup of specific recordings (by IP, phone number, etc.):
# Navigate to Settings > Custom Autocleaning
# Create rule with filters
# Apply and remove rule after completion


# Create archive script to move files older than X days
== Troubleshooting ==
# Add archive path to GUI: '''Settings > System configuration > Basic > Additional spool directories'''


=== Option 3: LVM Single Logical Volume ===
=== Files Disappearing Faster Than Expected ===


Combine fast SSD + large HDD into a single logical volume using LVM. VoIPmonitor sees only one spool directory.
;1. Check if emergency cleanup is active
 
<syntaxhighlight lang="bash">
== Database Cleaning (CDR Retention) ==
df -h /var/spool/voipmonitor
 
# If >95% full, emergency cleanup is running
Managing the size of the <code>cdr</code> table and other large tables is critical for GUI performance.
 
=== Partitioning Method (Recommended) ===
 
Since version 7, VoIPmonitor uses '''database partitioning''', which splits large tables into smaller, daily segments.
 
{| class="wikitable"
|-
! Aspect !! Description
|-
| '''How it works''' || Set <code>cleandatabase = 30</code> to keep the last 30 days of data
|-
| '''Why it's better''' || Dropping old partitions is instantaneous (milliseconds), regardless of row count
|-
| '''Partition limit''' || ~8000 partitions per table (~22 years with daily partitioning)
|-
| '''CDR record limit''' || No practical limit - modern installations use <code>BIGINT</code> for <code>cdr.ID</code> (up to 18 quintillion records). See [[Upgrade_to_bigint|Migrating to BIGINT]].
|}
 
==== Quick Start: Global Retention ====
 
<syntaxhighlight lang="ini">
# Keep all records for 30 days
cleandatabase = 30
</syntaxhighlight>
</syntaxhighlight>


==== Retention Parameters ====
;2. Check GUI configuration override
 
When <code>mysqlloadconfig = yes</code> (default), GUI settings override config file. Check: Settings > Sensors > wrench icon.
{| class="wikitable"
|-
! Parameter !! Default !! Description
|-
| <code>cleandatabase</code> || 0 (disabled) || Master retention setting in days
|-
| <code>cleandatabase_cdr</code> || 0 || Specific retention for CDR tables
|-
| <code>cleandatabase_rtp_stat</code> || 2 || Retention for RTP statistics
|-
| <code>cleandatabase_sip_msg</code> || 0 || Retention for SIP messages
|-
| <code>cleandatabase_register_state</code> || 0 || Retention for registration states
|-
| <code>cleandatabase_register_time_info</code> || 0 || '''Must be set explicitly''' (not covered by global setting)
|-
| <code>cleandatabase_size</code> || (unset) || Size-based limit in MB
|-
| <code>cleandatabase_size_force</code> || false || Required for size-based cleanup
|-
| <code>partition_operations_enable_fromto</code> || 1-5 || Time window for partition operations
|}
 
{| class="wikitable" style="background-color: #FFF3CD;"
|-
! colspan="2" style="background: #856404; color: white;" | Important: register_time_info Table
|-
| style="vertical-align: top;" | '''Critical:'''
| The <code>register_time_info</code> table is NOT covered by the global <code>cleandatabase</code> setting. You MUST configure <code>cleandatabase_register_time_info</code> explicitly.
|}


==== Size-Based Database Cleaning ====
;3. Set appropriate limits
Set <code>maxpoolsize</code> to 90-95% of disk capacity to leave buffer for growth.


Use <code>cleandatabase_size</code> to limit database by size rather than time:
=== Disk Space Not Reclaimed After Database Cleanup ===


<syntaxhighlight lang="ini">
Check <code>innodb_file_per_table</code>:
# Limit database to 50 GB
cleandatabase_size = 51200
cleandatabase_size_force = true


# Optional: Start cleaning when disk free space drops below threshold
<syntaxhighlight lang="sql">
cleandatabase_min_free_size = 30720
SHOW GLOBAL VARIABLES LIKE 'innodb_file_per_table';
</syntaxhighlight>
</syntaxhighlight>


==== Multi-Sniffer Environments ====
If OFF, enable in <code>my.cnf</code>:
 
When multiple sensors share the same database, partition operations should be managed by only ONE sensor:


<syntaxhighlight lang="ini">
<syntaxhighlight lang="ini">
# On all sniffers EXCEPT one:
[mysqld]
disable_partition_operations = yes
innodb_file_per_table = 1
 
# On the ONE designated sniffer:
partition_operations_enable_fromto = 4-6
</syntaxhighlight>
</syntaxhighlight>


== Database Troubleshooting ==
=== MySQL Error 28: No Space Left ===


=== MySQL Error 28: No Space Left on Device ===
Enable size-based cleaning:


If MySQL crashes with Error 28 even when <code>cleandatabase</code> is configured:
'''Primary Solution - Enable Size-Based Cleaning:'''
<syntaxhighlight lang="ini">
<syntaxhighlight lang="ini">
cleandatabase_size = 512000       # 500 GB limit
cleandatabase_size = 512000
cleandatabase_size_force = true   # Required
cleandatabase_size_force = true
</syntaxhighlight>
 
'''Alternative Causes:'''
* '''Inode exhaustion:''' Check with <code>df -i</code>
* '''MySQL tmpdir full:''' Check with <code>mysql -e "SHOW VARIABLES LIKE 'tmpdir';"</code>
 
=== Disk Space Not Reclaimed After Cleanup ===
 
Check <code>innodb_file_per_table</code> setting:
 
<syntaxhighlight lang="sql">
SHOW GLOBAL VARIABLES LIKE 'innodb_file_per_table';
</syntaxhighlight>
 
If OFF, space is not reclaimed when partitions are dropped. Enable for future tables:
<syntaxhighlight lang="ini">
[mysqld]
innodb_file_per_table = 1
</syntaxhighlight>
</syntaxhighlight>


=== Database Not Cleaning (Verify Partitioning) ===
Other causes: Inode exhaustion (<code>df -i</code>), MySQL tmpdir full.


Before assuming cleaning is broken, verify tables are partitioned:
=== Verify Database Cleaning ===


<syntaxhighlight lang="sql">
<syntaxhighlight lang="sql">
-- Check if CDR table is partitioned
SHOW CREATE TABLE cdr\G
-- Check partition list and row counts
SELECT PARTITION_NAME, TABLE_ROWS
SELECT PARTITION_NAME, TABLE_ROWS
FROM information_schema.PARTITIONS
FROM information_schema.PARTITIONS
Line 1,091: Line 375:
</syntaxhighlight>
</syntaxhighlight>


If only expected partitions exist (matching your <code>cleandatabase</code> setting), cleaning IS working - you may simply have high data volume.
If partition count matches your <code>cleandatabase</code> setting, cleaning IS working.


== MySQL Performance Settings ==
For SQL queue issues and database performance, see [[Database_troubleshooting]].


For high-performance operation:
== See Also ==
 
<syntaxhighlight lang="ini">
[mysqld]
# Use 50-70% of available RAM for caching
innodb_buffer_pool_size = 4G
 
# Flush logs to OS every second (faster, safe for VoIPmonitor)
innodb_flush_log_at_trx_commit = 2


# Enable per-table filespace for easy space reclamation
* [[Sniffer_configuration]] - Full parameter reference
innodb_file_per_table = 1
* [[Database_troubleshooting]] - SQL queue, performance issues
</syntaxhighlight>
* [[Scaling]] - Performance tuning
* [[Capture_rules]] - Selective recording


== See Also ==


* [[Sniffer_configuration|Sniffer Configuration Reference]]
* [[Scaling|Scaling and Performance Guide]]
* [[SQL_queue_is_growing_in_a_peaktime|SQL Queue Troubleshooting]]
* [[Sniffer_troubleshooting|Sniffer Troubleshooting]]


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


'''Summary:''' VoIPmonitor has two independent data retention systems: (1) Filesystem cleaning for PCAP files using <code>maxpoolsize</code>/<code>maxpooldays</code> parameters, running every 5 minutes; (2) Database cleaning using <code>cleandatabase</code> with daily partitioning for instant partition drops.
'''Summary:''' VoIPmonitor has two independent data retention systems: (1) Cleanspool for PCAP files using <code>maxpoolsize</code>/<code>maxpooldays</code> parameters, running every 5 minutes with in-memory file index; (2) Database cleaning using <code>cleandatabase</code> with instant partition dropping. Key space-saving option: <code>savertp = header</code> reduces storage by 90% while keeping quality metrics. Emergency cleanup (<code>autocleanspoolminpercent=1</code>, <code>autocleanmingb=5</code>) activates when disk nearly full and ignores normal limits. GUI settings override config file when <code>mysqlloadconfig=yes</code>. Size-based database cleaning requires BOTH <code>cleandatabase_size</code> AND <code>cleandatabase_size_force=true</code>. In multi-sensor environments, only one sensor should manage partitions (<code>disable_partition_operations=yes</code> on others).
 
'''Cleanspool modes:''' By default, VoIPmonitor uses '''modern mode''' (<code>cleanspool_use_files=no</code>) with <code>.cleanspool_cache</code> files stored in '''hourly''' directories (e.g., <code>/var/spool/voipmonitor/2026-01-01/15/.cleanspool_cache</code>). This is activated automatically when <code>pcap_dump_tar=yes</code> (TAR archive mode, which is the default). The modern mode is faster and more reliable as it doesn't depend on MySQL. The '''legacy mode''' (<code>cleanspool_use_files=yes</code>) uses MySQL <code>files</code> table but is deprecated due to reliability issues with <code>id_sensor</code> configuration in multi-sensor deployments.
 
The <code>maxpool_clean_obsolete</code> parameter (default: no) controls whether files not in the index are deleted. Emergency cleanup (<code>autocleanspoolminpercent=1</code>, <code>autocleanmingb=5</code>) can override retention settings when disk is nearly full. GUI settings via <code>mysqlloadconfig=yes</code> override <code>voipmonitor.conf</code>. For tiered storage, use <code>tar_move</code> to archive to secondary storage. Database partition limit is ~8000 per table (~22 years); CDR record count uses BIGINT (18 quintillion limit). Size-based database cleaning requires <code>cleandatabase_size</code> AND <code>cleandatabase_size_force=true</code>.


'''Keywords:''' data retention, cleaning, maxpoolsize, maxpooldays, cleandatabase, cleanspool_use_files, maxpool_clean_obsolete, files table, .cleanspool_cache, pcap_dump_tar, autocleanspoolminpercent, autocleanmingb, emergency cleanup, tar_move, tiered storage, partitioning, cleandatabase_size, innodb_file_per_table, savertp header, packetbuffer_sender, BIGINT cdr.ID, hourly cache
'''Keywords:''' data retention, maxpoolsize, maxpooldays, maxpoolrtpsize, cleandatabase, cleandatabase_size, cleandatabase_size_force, cleanspool, autocleanspoolminpercent, autocleanmingb, tar_move, tiered storage, savertp header, innodb_file_per_table, partition dropping, emergency cleanup, mysqlloadconfig, disable_partition_operations


'''Key Questions:'''
'''Key Questions:'''
* What is the default cleanspool mode and why?
* How does VoIPmonitor cleanspool work?
* How does modern cleanspool (.cleanspool_cache in hourly dirs) differ from legacy mode (MySQL files table)?
* How to configure PCAP file retention?
* What is cleanspool_use_files?
* How to limit database size?
* Where are the .cleanspool_cache files located?
* Why are files being deleted faster than expected?
* Will cleanspool delete files not in the cache?
* How to fix MySQL Error 28 no space left?
* What is maxpool_clean_obsolete?
* How to reduce storage usage (savertp header)?
* Why are PCAP files being deleted faster than expected?
* How to configure tiered storage?
* How do I fix MySQL Error 28?
* How do I configure size-based database cleaning?
* How do I extend retention with tiered storage?
* Why is disk space not reclaimed after cleanup?
* Why is disk space not reclaimed after cleanup?
* How do I check if database partitioning is working?
* How to manage partitions in multi-sensor environment?

Latest revision as of 12:10, 22 January 2026


This guide explains how VoIPmonitor manages data retention for PCAP files and database records.

Overview

VoIPmonitor generates two types of data requiring periodic cleanup:

Data Type Storage Cleanup Mechanism Key Parameters
PCAP Files Filesystem (spool directory) Cleanspool process (every 5 min) maxpoolsize, maxpooldays
CDR Records MySQL database Partition dropping (instant) cleandatabase

ℹ️ Note: These are independent systems - filesystem cleanup does not affect database records and vice versa.

Quick Reference

Purpose Parameter Example
Limit total PCAP size maxpoolsize maxpoolsize = 512000 (500 GB)
Limit RTP specifically maxpoolrtpsize maxpoolrtpsize = 102400 (100 GB)
Limit PCAP age maxpooldays maxpooldays = 30
CDR retention (days) cleandatabase cleandatabase = 30
CDR retention (size) cleandatabase_size cleandatabase_size = 512000 (+ cleandatabase_size_force = true)
Save only RTP stats savertp savertp = header (saves ~90% space)

Filesystem Cleaning (PCAP Files)

How Cleanspool Works

The sniffer maintains a file index in memory. Every 5 minutes, the cleanspool thread checks retention limits and deletes the oldest files when limits are exceeded.

The .cleanspool_cache files in hourly directories serve as persistent storage for fast restart - they allow quick index reload without scanning the entire filesystem.

ℹ️ Note: Legacy Indexing: Old VoIPmonitor versions stored metadata in MySQL files table. This can be enabled with cleanspool_use_files = yes (deprecated, do not use).

Retention Configuration

Limits can be set by size (MB) or age (days). When both are configured, the first limit reached triggers cleanup.

Global Limits

Parameter Default Description
maxpoolsize 102400 (100 GB) Maximum total size for all PCAP data
maxpooldays (unset) Maximum age in days for all PCAP data

Per-Type Limits

Data Type Size Parameter Days Parameter
SIP signaling maxpoolsipsize maxpoolsipdays
RTP audio maxpoolrtpsize maxpoolrtpdays
Quality graphs maxpoolgraphsize maxpoolgraphdays
Converted audio (WAV/OGG) maxpoolaudiosize maxpoolaudiodays

Recommended Configuration

Limit RTP (largest files) while keeping SIP longer for troubleshooting: 

# /etc/voipmonitor.conf
maxpoolrtpsize = 102400   # 100 GB limit for RTP
maxpoolsize = 512000      # 500 GB overall limit

Secondary Storage Limits (spooldir_2)

When using spooldir_2 for secondary storage (configured via capture rules with "Store pcaps to second spooldir" enabled), use _2 suffix parameters for cleaning:

maxpoolsize_2, maxpooldays_2, maxpoolrtpsize_2, etc.

ℹ️ Note: spooldir_2 is independent from tar_move. The _2 suffix parameters apply only to the secondary spooldir configured via capture rules, not to tar_move destination storage.

Emergency Cleanup

⚠️ Warning: Emergency cleanup activates when disk is nearly full and ignores all maxpool* settings.

Parameter Default Triggers When
autocleanspoolminpercent 1 Disk usage reaches 99%
autocleanmingb 5 Free space below 5 GB

When triggered, oldest data is deleted aggressively until thresholds are cleared. The cleanspool_enable_fromto time window is ignored.

Control Parameters

Parameter Default Description
cleanspool yes Enable/disable spool cleaning
cleanspool_enable_fromto 0-24 Restrict cleaning to hours (e.g., 1-5 for 1-5 AM)
maxpool_clean_obsolete no Delete files not in index (use with caution)
all_unlink_log no Log all file deletions

Reducing Data at Source

Save RTP Headers Only

If you only need quality metrics (MOS, jitter, packet loss) without audio playback: 

savertp = header

This reduces storage by up to 90% while preserving all quality statistics.


Disable RTP Entirely

If SIP signaling retention is the priority and you do not need RTP data at all: 

savertp = no

This disables RTP packet storage entirely, reducing PCAP size by approximately 20x. Use this when:

  • Storage limits are insufficient for even header-only RTP
  • SIP troubleshooting is the primary need (no audio analysis required)
  • You need to retain SIP signaling for much longer periods

⚠️ Warning:

Selective Recording

To record full audio only for specific calls:

  1. Set savertp = header globally
  2. Create capture rules with recordRTP=ON for exceptions

See Capture_rules for details.

Database Cleaning (CDR Records)

Partitioning Method

VoIPmonitor uses daily partitioning. Dropping old partitions is instant (milliseconds) regardless of row count. 

# Keep CDR records for 30 days
cleandatabase = 30

Database Cleaning Parameters

Parameter Default Description
cleandatabase 0 (disabled) Global retention for CDR, register_state, register_failed, sip_msg
cleandatabase_cdr 0 CDR table (includes message table)
cleandatabase_rtp_stat 2 RTP statistics table
cleandatabase_register_state 0 Registration state
cleandatabase_register_failed 0 Failed registrations
cleandatabase_register_time_info 0 Registration timing (NOT covered by global)
cleandatabase_sip_msg 0 SIP messages (OPTIONS/SUBSCRIBE/NOTIFY)
cleandatabase_ss7 0 SS7 records
partition_operations_enable_fromto 1-5 Time window for partition operations (24h format)

⚠️ Warning: register_time_info is NOT covered by global cleandatabase. Set cleandatabase_register_time_info explicitly.

Size-Based Cleaning

To limit database by size instead of time: 

cleandatabase_size = 512000        # 500 GB limit in MB
cleandatabase_size_force = true    # Required to enable

Multi-Sensor Environments

When multiple sensors share a database, only ONE sensor should manage partitions: 

# On all sensors EXCEPT one:
disable_partition_operations = yes

# On the designated sensor:
partition_operations_enable_fromto = 4-6

Limits

  • MySQL/MariaDB partition limit: ~8000 partitions per table (~22 years with daily partitioning)
  • Aurora DB partition limit: ~800 partitions per table - much lower than standard MySQL
  • CDR record limit: No practical limit - uses BIGINT

Aurora DB / Limited Partition Environments

For databases with low partition limits (like Amazon Aurora), you can pre-create partitions before starting the sniffer and prevent runtime partition creation: 

# Pre-create partitions up to a specific date before starting
create_new_partitions_until = 2026-01-31

# Disable only partition creation (dropping still works for cleanup)
disable_partition_operations_create = yes

# Or disable only partition dropping (creation still works)
# disable_partition_operations_drop = yes

# Number of partitions to create ahead (default 2)
create_new_partitions = 2

ℹ️ Note: For Aurora DB with ~800 partition limit: with daily partitions, this gives ~2 years of data. Plan retention accordingly using cleandatabase.

Advanced Topics

Spool Directory Location

Default: /var/spool/voipmonitor

Structure: YYYY-MM-DD/HH/MM/{SIP|RTP|GRAPH|AUDIO}/files...

Relocating the Spool

# 1. Create new directory
mkdir -p /mnt/storage/voipmonitor
chown voipmonitor:voipmonitor /mnt/storage/voipmonitor

# 2. Update sniffer config
# /etc/voipmonitor.conf:
# spooldir = /mnt/storage/voipmonitor

# 3. Update GUI config (config/configuration.php):
# define('SNIFFER_DATA_PATH', '/mnt/storage/voipmonitor');

# 4. Restart
systemctl restart voipmonitor

Tiered Storage (tar_move)

Extend retention using secondary storage: 

spooldir = /var/spool/voipmonitor
tar_move = yes
tar_move_destination_path = /mnt/archive/voipmonitor

Files in secondary storage remain accessible via GUI.

S3 Cloud Storage

Use rclone instead of s3fs to avoid GUI unresponsiveness: 

rclone mount bucket-name /mnt/s3-archive \
  --allow-other --dir-cache-time 30s --vfs-cache-mode off

Custom Autocleaning (GUI)

For one-time cleanup of specific recordings (by IP, phone number, etc.):

  1. Navigate to Settings > Custom Autocleaning
  2. Create rule with filters
  3. Apply and remove rule after completion

Troubleshooting

Files Disappearing Faster Than Expected

1. Check if emergency cleanup is active
df -h /var/spool/voipmonitor
# If >95% full, emergency cleanup is running
2. Check GUI configuration override

When mysqlloadconfig = yes (default), GUI settings override config file. Check: Settings > Sensors > wrench icon.

3. Set appropriate limits

Set maxpoolsize to 90-95% of disk capacity to leave buffer for growth.

Disk Space Not Reclaimed After Database Cleanup

Check innodb_file_per_table: 

SHOW GLOBAL VARIABLES LIKE 'innodb_file_per_table';

If OFF, enable in my.cnf: 

[mysqld]
innodb_file_per_table = 1

MySQL Error 28: No Space Left

Enable size-based cleaning: 

cleandatabase_size = 512000
cleandatabase_size_force = true

Other causes: Inode exhaustion (df -i), MySQL tmpdir full.

Verify Database Cleaning

SELECT PARTITION_NAME, TABLE_ROWS
FROM information_schema.PARTITIONS
WHERE TABLE_NAME = 'cdr'
ORDER BY PARTITION_ORDINAL_POSITION DESC
LIMIT 10;

If partition count matches your cleandatabase setting, cleaning IS working.

For SQL queue issues and database performance, see Database_troubleshooting.

See Also


AI Summary for RAG

Summary: VoIPmonitor has two independent data retention systems: (1) Cleanspool for PCAP files using maxpoolsize/maxpooldays parameters, running every 5 minutes with in-memory file index; (2) Database cleaning using cleandatabase with instant partition dropping. Key space-saving option: savertp = header reduces storage by 90% while keeping quality metrics. Emergency cleanup (autocleanspoolminpercent=1, autocleanmingb=5) activates when disk nearly full and ignores normal limits. GUI settings override config file when mysqlloadconfig=yes. Size-based database cleaning requires BOTH cleandatabase_size AND cleandatabase_size_force=true. In multi-sensor environments, only one sensor should manage partitions (disable_partition_operations=yes on others).

Keywords: data retention, maxpoolsize, maxpooldays, maxpoolrtpsize, cleandatabase, cleandatabase_size, cleandatabase_size_force, cleanspool, autocleanspoolminpercent, autocleanmingb, tar_move, tiered storage, savertp header, innodb_file_per_table, partition dropping, emergency cleanup, mysqlloadconfig, disable_partition_operations

Key Questions:

  • How does VoIPmonitor cleanspool work?
  • How to configure PCAP file retention?
  • How to limit database size?
  • Why are files being deleted faster than expected?
  • How to fix MySQL Error 28 no space left?
  • How to reduce storage usage (savertp header)?
  • How to configure tiered storage?
  • Why is disk space not reclaimed after cleanup?
  • How to manage partitions in multi-sensor environment?
Retrieved from "https://www.voipmonitor.org/doc/index.php?title=Data_Cleaning&oldid=11005"