Data Cleaning: Difference between revisions

From VoIPmonitor.org
(Simplify cleanspool docs: Remove legacy mode references (cleanspool_use_files). Cleanspool keeps index in memory, .cleanspool_cache in hourly dirs is for fast restart only.)
(Fix incorrect association of _2 parameters with tar_move - they are for spooldir_2 used with capture rules (TP-38))
 
(8 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:
 
<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 ===
 
The sniffer keeps the complete file index '''in memory''' during operation. This allows very fast cleaning operations without database queries.
 
The <code>.cleanspool_cache</code> files stored in '''hourly''' directories serve as a persistent cache for '''faster startup after restart''' - they allow the sniffer to quickly reload the file index without scanning the entire directory structure.
 
Example cache location: <code>/var/spool/voipmonitor/2026-01-01/15/.cleanspool_cache</code>
 
'''Key characteristics:'''
* File index kept entirely in memory - very fast operations
* No MySQL queries needed for file listing
* Cache files enable quick restart without full directory scan
* For recent hours, prefers direct directory reading over cache for accuracy
 
The cleaning process flow:
 
<kroki lang="plantuml">
@startuml
skinparam shadowing false
participant "Sniffer" as S
participant "Cleanspool\nThread" as C
database "In-Memory\nFile Index" as MEM
collections "Filesystem" as FS
 
S -> FS: Write PCAP file\n(into TAR archive)
S -> MEM: Update file index
 
... Every 5 minutes ...
 
C -> MEM: Query oldest files\nwhere age > maxpooldays\nOR total size > maxpoolsize
loop For each file to delete
    C -> FS: DELETE file
    C -> MEM: Remove from index
end
 
note over MEM : Index persisted to\n.cleanspool_cache files\nfor fast restart
@enduml
</kroki>
 
'''Verifying cache files exist:'''
<syntaxhighlight lang="bash">
# Find .cleanspool_cache files in hourly directories
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 in-memory index.


{| class="wikitable"
{| class="wikitable"
|-
|-
! Setting !! Behavior !! Use Case
! Data Type !! Storage !! Cleanup Mechanism !! Key Parameters
|-
| <code>maxpool_clean_obsolete = no</code> (default) || Only delete files that are indexed. Unknown files are ignored. || Safe default - protects manually added files
|-
| <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
| '''PCAP Files''' || Filesystem (spool directory) || Cleanspool process (every 5 min) || <code>maxpoolsize</code>, <code>maxpooldays</code>
|-
|-
| style="vertical-align: top;" | '''Caution:'''
| '''CDR Records''' || MySQL database || Partition dropping (instant) || <code>cleandatabase</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 ===
{{Note|These are '''independent systems''' - filesystem cleanup does not affect database records and vice versa.}}


Before configuring cleanup policies, consider reducing the amount of data captured. This is often the most effective long-term solution for storage management.
=== Quick Reference ===
 
==== 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"
{| class="wikitable"
|-
|-
! Setting !! Storage Impact !! Use Case
! Purpose !! Parameter !! Example
|-
| <code>savertp = yes</code> || High (~10x more) || Requires ability to play back audio from PCAPs
|-
|-
| <code>savertp = header</code> || Low || Only CDR statistics needed, no audio playback required
| Limit total PCAP size || <code>maxpoolsize</code> || <code>maxpoolsize = 512000</code> (500 GB)
|}
 
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%.
 
'''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.
 
{| class="wikitable" style="background-color: #FFF3CD;"
|-
|-
! colspan="2" style="background: #856404; color: white;" | Critical: Distributed Architecture Consideration
| Limit RTP specifically || <code>maxpoolrtpsize</code> || <code>maxpoolrtpsize = 102400</code> (100 GB)
|-
|-
| style="vertical-align: top;" | '''<code>packetbuffer_sender</code> Architecture:'''
| Limit PCAP age || <code>maxpooldays</code> || <code>maxpooldays = 30</code>
|
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.
 
{|
|-
|-
! Architecture !! Where to Apply <code>savertp = header</code>
| CDR retention (days) || <code>cleandatabase</code> || <code>cleandatabase = 30</code>
|-
|-
| <code>packetbuffer_sender = no</code> (Local Processing) || On each sensor/probe's configuration file
| CDR retention (size) || <code>cleandatabase_size</code> || <code>cleandatabase_size = 512000</code> (+ <code>cleandatabase_size_force = true</code>)
|-
|-
| <code>packetbuffer_sender = yes</code> (Packet Mirroring) || On the central server's configuration file (not on sensors)
| Save only RTP stats || <code>savertp</code> || <code>savertp = header</code> (saves ~90% space)
|}
|}


For distributed deployment details, see [[Sniffer_distributed_architecture#Controlling_Packet_Storage_in_Packet_Mirroring_Mode|Client-Server Architecture]].
== Filesystem Cleaning (PCAP Files) ==
|}


==== Enabling Selective Audio Recording with Capture Rules ====
=== How Cleanspool Works ===


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:
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.


'''Workflow:'''
<kroki lang="plantuml">
@startuml
skinparam shadowing false
skinparam defaultFontSize 11
participant "Sniffer" as S
participant "Cleanspool" as C
database "In-Memory\nIndex" as MEM
collections "Filesystem" as FS


1. **Set global default to headers only:**
S -> FS: Write PCAP
<syntaxhighlight lang="ini">
S -> MEM: Update index
savertp = header
... Every 5 minutes ...
</syntaxhighlight>
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>


2. **Create capture rules in the GUI for exceptions:**
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.
  * 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:'''
{{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).}}


{| class="wikitable"
=== Retention Configuration ===
|-
! Scenario !! Configuration !! File Storage
|-
| Legal Holds
| Create IP rule for subject party with <code>recordRTP=ON</code>
| Full audio recorded
|-
| VIP Customers
| Create phone number prefix rules for specific ranges with <code>recordRTP=ON</code>
| Full audio recorded
|-
| All Other Calls
| 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.


For detailed capture rule configuration options, see [[Capture_rules]].
Limits can be set by '''size''' (MB) or '''age''' (days). When both are configured, the first limit reached triggers cleanup.
For more configuration options, see [[Sniffer_configuration#Saving_Options|Sniffer Configuration - Saving Options]].


=== Spool Directory Structure ===
==== Global Limits ====
 
The spool directory uses a hierarchical structure organized by time and data type.


{| class="wikitable"
{| class="wikitable"
|-
|-
! Structure !! Description
! Parameter !! Default !! Description
|-
| <code>maxpoolsize</code> || 102400 (100 GB) || Maximum total size for all PCAP data
|-
|-
| <code>YY-mm-dd/HH/MM/{TYPE}/files...</code> || Date → Hour → Minute → Data Type
| <code>maxpooldays</code> || (unset) || Maximum age in days for all PCAP data
|}
|}


The <code>{TYPE}</code> subdirectory can be:
==== Per-Type Limits ====
* <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"
{| class="wikitable"
|-
|-
! Situation !! Recommended Action
! Data Type !! Size Parameter !! Days Parameter
|-
|-
| <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>
| SIP signaling || <code>maxpoolsipsize</code> || <code>maxpoolsipdays</code>
|-
|-
| Multiple disks available || Use dedicated partition for PCAP storage
| RTP audio || <code>maxpoolrtpsize</code> || <code>maxpoolrtpdays</code>
|-
|-
| GUI on same server || Sync GUI <code>SNIFFER_DATA_PATH</code> to match new <code>spooldir</code>
| Quality graphs || <code>maxpoolgraphsize</code> || <code>maxpoolgraphdays</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
</syntaxhighlight>
maxpoolrtpsize = 102400  # 100 GB limit for RTP
 
maxpoolsize = 512000      # 500 GB overall limit
;Step 4: Update GUI Configuration (Critical)
 
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:
 
* Debian/Ubuntu: <code>/var/www/html/voipmonitor/config/configuration.php</code>
* RHEL/CentOS: <code>/var/www/voipmonitor/config/configuration.php</code>
 
Edit the GUI configuration file:
<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.
 
;Step 5: Restart Services
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>
</syntaxhighlight>


===== Optional: Move Existing Data =====
==== Secondary Storage Limits (spooldir_2) ====


If you want to migrate existing PCAP files to the new location:
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:
<syntaxhighlight lang="bash">
# Stop the sensor to prevent writes during migration
systemctl stop voipmonitor


# Move existing data (this may take a long time)
<code>maxpoolsize_2</code>, <code>maxpooldays_2</code>, <code>maxpoolrtpsize_2</code>, etc.
mv /var/spool/voipmonitor/* /mnt/pcaps/voipmonitor/


# Restart the sensor
{{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.}}
systemctl start voipmonitor
</syntaxhighlight>


=== Retention Mechanism ===
=== Emergency Cleanup ===


The cleaning process runs automatically every 5 minutes and removes data based on the configuration in <code>voipmonitor.conf</code>.
{{Warning|1=Emergency cleanup activates when disk is nearly full and '''ignores all <code>maxpool*</code> settings'''.}}


{| 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 ====
=== Control Parameters ===
 
The <code>autoclean*</code> parameters act as a safety "fuse" to prevent the disk from filling up:


{| 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
|-
| style="vertical-align: top;" | '''Default Behavior:'''
|
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>maxpoolsize</code> || 102400 (100 GB) || The total maximum disk space for '''all''' captured data (SIP, RTP, GRAPH, AUDIO).
|-
| <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>cleanspool</code> || yes || Enable/disable spool cleaning
|-
|-
| <code>maxpoolgraphsize</code> || (unset) || A specific size limit for GRAPH files only.
| <code>cleanspool_enable_fromto</code> || 0-24 || Restrict cleaning to hours (e.g., <code>1-5</code> for 1-5 AM)
|-
|-
| <code>maxpoolgraphdays</code> || (unset) || A specific age limit for GRAPH files only.
| <code>maxpool_clean_obsolete</code> || no || Delete files not in index (use with caution)
|-
|-
| <code>maxpoolaudiosize</code> || (unset) || A specific size limit for converted audio files (WAV/OGG) only.
| <code>all_unlink_log</code> || no || Log all file deletions
|-
| <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
This reduces storage by up to '''90%''' while preserving all quality statistics.
 
# Set overall limit for all data together
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 ===
=== Database Cleaning Parameters ===
 
Manual deletion of files from the spool directory is generally safe, but there are important considerations.
 
==== 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
|-
| Deleting current hour while service running || No risk to service, but may cause errors for active captures if file handles are still open
|-
| Deleting current MINUTE while recording in progress || Not recommended || May cause file descriptor errors temporarily
|}
 
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
|-
|-
! After deleting PCAP files
| <code>cleandatabase</code> || 0 (disabled) || Global retention for CDR, register_state, register_failed, sip_msg
| Database CDR records are NOT automatically deleted. Calls will appear in the GUI but show "File not found" for missing files.
|-
|-
! Solution
| <code>cleandatabase_cdr</code> || 0 || CDR table (includes <code>message</code> table)
| 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_rtp_stat</code> || 2 || RTP statistics table
|-
|-
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_register_state</code> || 0 || Registration state
|}
 
=== 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
| <code>cleandatabase_register_failed</code> || 0 || Failed registrations
|-
|-
| '''Scope''' || Targeted (specific IP, number, filter) || All calls
| <code>cleandatabase_register_time_info</code> || 0 || Registration timing ('''NOT''' covered by global)
|-
|-
| '''Purpose''' || One-time cleanup of existing data || Ongoing automated cleanup
| <code>cleandatabase_sip_msg</code> || 0 || SIP messages (OPTIONS/SUBSCRIBE/NOTIFY)
|-
|-
| '''Configuration''' || GUI with CDR filters || <code>maxpoolsize</code>, <code>maxpooldays</code>
| <code>cleandatabase_ss7</code> || 0 || SS7 records
|-
|-
| '''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) ===
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.
{| 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:'''
=== Multi-Sensor Environments ===
<syntaxhighlight lang="bash">
# Check disk usage
df -h /var/spool/voipmonitor


# Check emergency trigger settings
When multiple sensors share a database, only '''ONE''' sensor should manage partitions:
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:'''
<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
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:'''
<syntaxhighlight lang="ini">
[mysqld]
# 50-70% of server RAM
innodb_buffer_pool_size = 8G


# Fast writes (acceptable data loss risk on crash)
Default: <code>/var/spool/voipmonitor</code>
innodb_flush_log_at_trx_commit = 2
</syntaxhighlight>


=== "low spool disk space" Message ===
Structure: <code>YYYY-MM-DD/HH/MM/{SIP|RTP|GRAPH|AUDIO}/files...</code>


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.
==== Relocating the Spool ====


'''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) ===


The <code>tar_move</code> feature automatically archives PCAP files to secondary storage after they are closed.
Extend retention using secondary storage:


<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 Considerations ====
==== S3 Cloud Storage ====


When using S3 storage, use <code>rclone</code> instead of <code>s3fs</code> to avoid GUI unresponsiveness:
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>
 
== Database Troubleshooting ==
 
=== MySQL Error 28: No Space Left on Device ===
 
If MySQL crashes with Error 28 even when <code>cleandatabase</code> is configured:
 
'''Primary Solution - Enable Size-Based Cleaning:'''
<syntaxhighlight lang="ini">
cleandatabase_size = 512000        # 500 GB limit
cleandatabase_size_force = true    # Required
</syntaxhighlight>
</syntaxhighlight>


'''Alternative Causes:'''
=== MySQL Error 28: No Space Left ===
* '''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">
Enable size-based cleaning:
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">
<syntaxhighlight lang="ini">
[mysqld]
cleandatabase_size = 512000
innodb_file_per_table = 1
cleandatabase_size_force = true
</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,060: 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).
 
'''How cleanspool works:''' The sniffer keeps the complete file index '''in memory''' for fast operations. The <code>.cleanspool_cache</code> files in '''hourly''' directories (e.g., <code>/var/spool/voipmonitor/2026-01-01/15/.cleanspool_cache</code>) serve only as persistent storage for '''fast restart''' - they allow quick index reload without scanning directories.
 
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, maxpool_clean_obsolete, .cleanspool_cache, autocleanspoolminpercent, autocleanmingb, emergency cleanup, tar_move, tiered storage, partitioning, cleandatabase_size, innodb_file_per_table, savertp header, packetbuffer_sender, BIGINT cdr.ID, hourly cache, in-memory index
'''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:'''
* How does cleanspool work?
* How does VoIPmonitor cleanspool work?
* Where are the .cleanspool_cache files located?
* How to configure PCAP file retention?
* Will cleanspool delete files not in the cache?
* How to limit database size?
* What is maxpool_clean_obsolete?
* Why are files being deleted faster than expected?
* Why are PCAP files being deleted faster than expected?
* How to fix MySQL Error 28 no space left?
* How do I fix MySQL Error 28?
* How to reduce storage usage (savertp header)?
* How do I configure size-based database cleaning?
* How to configure tiered storage?
* 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"