--- title: "System Cleanup Module Documentation" description: "Documentation for System Maintenance" --- ## Table of Contents 1. [Navigation & Access](#navigation--access) 2. [Screenshots & Visual Interface](#screenshots--visual-interface) 3. [🎯 User Roles & Key Capabilities](#-user-roles--key-capabilities) 4. [Module Overview (Technical)](#1-module-overview-technical) 5. [Module Overview (Commercial/Business)](#2-module-overview-commercialbusiness) 6. [Module Overview (End User/Administrator)](#3-module-overview-end-useradministrator) 7. [Configuration Sections](#4-configuration-sections) 8. [Settings Reference](#5-settings-reference) 9. [Model Context Protocol (MCP) AI Integration](#model-context-protocol-mcp-ai-integration) 10. [Common Scenarios & Examples](#6-common-scenarios--examples) 11. [Limitations & Important Notes](#7-limitations--important-notes) 12. [Troubleshooting Tips](#8-troubleshooting-tips) 13. [Glossary](#9-glossary) --- ## Navigation & Access To access the System Cleanup module: 1. Log in to the Ring2All Web Portal (`https:///login`). 2. In the left navigation sidebar, expand **Administration**. 3. Under **Maintenance**, click **System** (`/admin/maintenance/system`). 4. Monitor tenant maintenance configurations, execution cadence (Daily, Weekly, Monthly), and active operational states. 5. Select the edit icon on any tenant entry to modify data retention rules (CDRs, call recordings, voicemails, log events, SMS messages), audio encoding quality, or invoke the **Execute Now** action (`/admin/maintenance/system/:tenantId`). --- ## Screenshots & Visual Interface ### Multi-Tenant System Maintenance Directory Overview of provisioned tenants, individual cleanup enablement states, active execution intervals, and operational availability indicators. ![System Cleanup Tenant Directory](/screenshots/admin/maintenance/system-maintenance-list.png) ### Tenant System Cleanup & Retention Parameters Detailed data lifecycle controller governing retention periods for CDRs, calls, voicemails, SMS, log streams, automatic audio transcoding (Good 16k, High 32k, Lossless WAV), and immediate execution controls. ![Tenant System Cleanup Parameters](/screenshots/admin/maintenance/system-maintenance-form.png) --- ## 🎯 User Roles & Key Capabilities | Role | Access Level | Responsibilities & Capabilities | | :--- | :--- | :--- | | **PBX Super Administrator** | Full Access (`RW`) | Configure global data retention thresholds, establish audio transcoding rules, audit disk consumption, and trigger emergency cleanup runs. | | **Data Compliance & Governance Lead** | Policy Management (`RW`) | Mandate statutory retention windows for call recordings and CDRs (e.g. 90 days vs 7 years) to comply with telecom regulations. | | **System Operations & SRE** | Monitoring & Maintenance (`RW`) | Prevent disk exhaustion on media storage volumes (`/var/spool/freeswitch/recordings`) and monitor automated cleanup cron executions. | | **AI Platform Copilot / MCP Agent** | Telemetry & Audit (`RO`) | Execute `get_system_cleanup_status` to evaluate active retention limits and audit compliance before executing storage modifications. | --- ## 1. Module Overview (Technical) ### What Is System Cleanup? System Cleanup is a **maintenance module** that automatically removes old system files and data to free up storage space. It supports per-tenant configuration for CDR, recordings, voicemails, SMS, and log events. ### Architecture ``` ┌─────────────────────────────────────────────────────────────────┐ │ System Cleanup Architecture │ ├─────────────────────────────────────────────────────────────────┤ │ │ │ Per-Tenant Cleanup Settings │ │ ┌──────────────────────────────────────────────────────────┐ │ │ │ │ │ │ │ Tenant: Acme Corporation │ │ │ │ ┌────────────────────────────────────────────────────┐ │ │ │ │ │ │ │ │ │ │ │ Delete Oldest CDR: 90 days │ │ │ │ │ │ Delete Oldest Recordings: 30 days │ │ │ │ │ │ Delete Oldest Voicemails: 60 days │ │ │ │ │ │ Delete Short Recordings: < 3 seconds │ │ │ │ │ │ Delete Oldest Log Events: 30 days │ │ │ │ │ │ Delete Oldest SMS: 90 days │ │ │ │ │ │ │ │ │ │ │ │ Schedule: Daily │ │ │ │ │ │ Convert Recordings: Yes (16k quality) │ │ │ │ │ │ │ │ │ │ │ └────────────────────────────────────────────────────┘ │ │ │ │ │ │ │ └──────────────────────────────────────────────────────────┘ │ │ │ │ │ ▼ Scheduled execution │ │ ┌──────────────────────────────────────────────────────────┐ │ │ │ Cleanup Jobs │ │ │ │ │ │ │ │ Daily at 2:00 AM: │ │ │ │ ├─ Delete CDR older than 90 days │ │ │ │ ├─ Delete recordings older than 30 days │ │ │ │ ├─ Delete recordings shorter than 3 seconds │ │ │ │ ├─ Delete voicemails older than 60 days │ │ │ │ ├─ Delete log events older than 30 days │ │ │ │ ├─ Delete SMS older than 90 days │ │ │ │ └─ Convert recordings to efficient format │ │ │ │ │ │ │ └──────────────────────────────────────────────────────────┘ │ │ │ │ │ ▼ Storage freed │ │ ┌──────────────────────────────────────────────────────────┐ │ │ │ Storage Space │ │ │ │ │ │ │ │ Before: █████████████████████ 85% used │ │ │ │ After: ████████ 35% used │ │ │ │ │ │ │ └──────────────────────────────────────────────────────────┘ │ │ │ └─────────────────────────────────────────────────────────────────┘ ``` --- ## 2. Module Overview (Commercial/Business) ### Business Value System Cleanup provides **automated storage management**: | Without Cleanup | With Cleanup | |-----------------|--------------| | Storage fills up | Auto-managed | | Manual deletion | Scheduled jobs | | Compliance risk | Retention policies | | Server slowdown | Optimized storage | ### Use Cases 1. **Storage Management** - Prevent disk full - Automated cleanup 2. **Compliance** - Retention policies - Data lifecycle 3. **Cost Control** - Reduce storage costs - Optimize space 4. **Performance** - Faster queries - Less I/O load ### Feature Highlights | Feature | Benefit | |---------|---------| | **Per-Tenant** | Individual policies | | **Multiple Types** | CDR, recordings, etc. | | **Schedule** | Daily/weekly/monthly | | **Short Recordings** | Remove useless files | | **Audio Conversion** | Save space | | **Execute Now** | Manual trigger | --- ## 3. Module Overview (End User/Administrator) ### What Can You Do? - Configure cleanup per tenant - Set retention days for each data type - Delete short recordings - Schedule automatic cleanup - Convert recordings to save space - Run cleanup manually - Enable/disable cleanup jobs ### System Cleanup - Tenant List ``` ┌─────────────────────────────────────────────────────────────────┐ │ System Cleanup │ ├─────────────────────────────────────────────────────────────────┤ │ │ │ Configure automatic cleanup of old system files and recordings│ │ │ │ [🔍 Search tenants...] │ │ │ │ ┌───────────────────────────────────────────────────────────┐ │ │ │ Tenant Name │ Maintenance State│ Status │ │ │ ├──────────────────┼──────────────────┼────────────────────┤ │ │ │ Acme Corporation │ ● Enabled │ Last: Today 2:00 │ │ │ │ Beta Company │ ● Enabled │ Last: Today 2:00 │ │ │ │ Test Tenant │ ○ Disabled │ Never │ │ │ │ Main │ ● Enabled │ Last: Today 2:00 │ │ │ └───────────────────────────────────────────────────────────┘ │ │ │ │ Click a tenant to configure cleanup settings │ │ │ └─────────────────────────────────────────────────────────────────┘ ``` ### Cleanup Settings ``` ┌─────────────────────────────────────────────────────────────────┐ │ System Cleanup │ ├─────────────────────────────────────────────────────────────────┤ │ │ │ [← List] Tenant: Acme Corporation │ │ │ │ ▼ Cleanup Settings │ │ │ │ ┌─────────────────────────────────────────────────────────────┐│ │ │ ││ │ │ Enabled: ✓ ││ │ │ Enable or disable the automatic cleanup job ││ │ │ ││ │ │ Schedule: [Daily ▼] ││ │ │ None | Daily | Weekly | Monthly ││ │ │ ││ │ │ ────────────────────────────────────────────────────────── ││ │ │ ││ │ │ Delete Oldest CDR: [90 ] days ││ │ │ Delete CDR records older than this many days ││ │ │ (Leave empty to keep all records) ││ │ │ ││ │ │ Delete Oldest Recordings: [30 ] days ││ │ │ Delete call recordings older than this many days ││ │ │ ││ │ │ Delete Oldest Voicemails: [60 ] days ││ │ │ Delete voicemail messages older than this many days ││ │ │ ││ │ │ Delete Short Recordings: [3 ] seconds ││ │ │ Delete recordings shorter than this (removes empty files)││ │ │ ││ │ │ Delete Oldest Log Events: [30 ] days ││ │ │ Delete log events older than this many days ││ │ │ ││ │ │ Delete Oldest SMS: [90 ] days ││ │ │ Delete SMS messages older than this many days ││ │ │ ││ │ │ ────────────────────────────────────────────────────────── ││ │ │ ││ │ │ Convert Recordings: ✓ ││ │ │ Convert recordings to efficient format to save space ││ │ │ ││ │ │ Audio Quality: [Good (16k) ▼] ││ │ │ Good (16k) | High (32k) | Lossless (WAV) ││ │ │ ││ │ └─────────────────────────────────────────────────────────────┘│ │ │ │ [Save] [Execute Now] │ │ │ └─────────────────────────────────────────────────────────────────┘ ``` ### Quick Tips > [!TIP] > **Leave Empty**: Leave days empty to keep all records. > [!TIP] > **Short Recordings**: Set to 3 seconds to remove empty recordings. > [!WARNING] > **Permanent Deletion**: Deleted data cannot be recovered! --- ## 4. Configuration Sections ### Data Type Settings | Field | Description | |-------|-------------| | **Delete Oldest CDR** | CDR retention (days) | | **Delete Oldest Recordings** | Recording retention | | **Delete Oldest Voicemails** | Voicemail retention | | **Delete Short Recordings** | Min duration (seconds) | | **Delete Oldest Log Events** | Log retention | | **Delete Oldest SMS** | SMS retention | ### Schedule Settings | Field | Description | |-------|-------------| | **Enabled** | Job on/off | | **Schedule** | Run frequency | ### Audio Settings | Field | Description | |-------|-------------| | **Convert Recordings** | Enable conversion | | **Audio Quality** | Conversion quality | --- ## 5. Settings Reference ### Schedule Options | Option | Description | |--------|-------------| | **None** | Manual only | | **Daily** | Run every day | | **Weekly** | Run every week | | **Monthly** | Run every month | ### Audio Quality Options | Quality | Bitrate | Use Case | |---------|---------|----------| | **Good (16k)** | 16 kbps | Maximum space saving | | **High (32k)** | 32 kbps | Balance quality/size | | **Lossless (WAV)** | Original | Keep quality | ### Retention Guidelines | Data Type | Minimum | Typical | Compliance | |-----------|---------|---------|------------| | CDR | 30 days | 90 days | 1-7 years | | Recordings | 30 days | 90 days | Per policy | | Voicemails | 30 days | 60 days | 30-90 days | | Log Events | 7 days | 30 days | Per policy | | SMS | 30 days | 90 days | Per policy | ### Storage Impact | Data Type | Size Impact | Cleanup Benefit | |-----------|-------------|-----------------| | Recordings | Largest | Highest savings | | CDR | Medium | Faster queries | | Voicemails | Medium | Good savings | | Logs | Small | Improved performance | | SMS | Small | Minor savings | --- ## Model Context Protocol (MCP) AI Integration The System Cleanup module provides typed status endpoints to the **Model Context Protocol (MCP)**, empowering the Platform Copilot to audit data lifecycle settings, retention horizons, and storage optimization policies. ### Available MCP Tools | Tool Name | Scope | Description | | :--- | :--- | :--- | | `get_system_cleanup_status` | Retention Audit (`RO`) | Retrieves automated retention and cleanup settings for CDR history, call recordings, voicemails, log streams, and audio transcoding. | | `diagnose_system_issue` | Top-Level Triage | Accepts a high-level operational symptom (e.g. "calls dropping", "WebRTC won't connect"), evaluates core telephony engine health, disk storage/inodes, database latency, and dispatches to the exact specialized module diagnostic. | ### Tool Schemas & Payloads #### `get_system_cleanup_status` ```json { "name": "get_system_cleanup_status", "description": "Retrieves automated retention and cleanup settings for CDR history, call recordings, and voicemails.", "parameters": { "type": "object", "properties": {} } } ``` #### `diagnose_system_issue` ```json { "name": "diagnose_system_issue", "description": "Top-level triage tool that evaluates PBX symptoms, checks disk/engine health, and directs to specialized diagnostic tools.", "parameters": { "type": "object", "properties": { "symptom": { "type": "string", "description": "The operational symptom or problem observed (e.g. 'Calls dropping after 30 seconds')" }, "entity": { "type": "string", "description": "Optional entity involved (e.g. extension '1001', trunk 'Telnyx')" } }, "required": ["symptom"] } } ``` **Realistic Execution Response:** ```json { "success": true, "data": { "cleanupPolicy": { "enabled": true, "schedule": "daily", "deleteOldestCdrDays": 180, "deleteOldestRecordingsDays": 90, "deleteOldestVoicemailsDays": 60, "deleteShortRecordingsSec": 3, "deleteOldestLogEventsDays": 30, "deleteOldestSmsDays": 90, "convertRecordings": true, "audioQuality": "good" } } } ``` ### Bilingual Natural Language Prompt Examples #### English Prompts - *"Copilot, show me the current system retention and cleanup policy settings."* - *"How many days of call recordings and CDRs are retained before automatic deletion?"* - *"Is audio recording conversion to 16k mono enabled in the cleanup configuration?"* #### Spanish Prompts - *"Copilot, muéstrame las políticas actuales de retención y limpieza del sistema."* - *"¿Cuántos días de grabaciones y CDRs se conservan antes de su depuración automática?"* - *"Verifica si la limpieza automática está activa y con qué frecuencia se ejecuta."* ### Enterprise Safeguards & Execution Boundaries 1. **Multi-Tenant Retention Isolation:** Retention parameters are bound to numeric `tenant_id`. Sub-tenant policies only purge records belonging to their respective domains. 2. **Safe Minimum Horizons:** Policies prevent setting negative or invalid retention days, shielding against accidental mass deletion of telephony audio. 3. **Audit Trail Compliance:** Every cleanup execution (whether triggered automatically or on-demand) writes a detailed audit entry recording the exact number of deleted files and bytes freed. --- ## 6. Common Scenarios & Examples ### Scenario 1: Standard Cleanup Policy 1. Select tenant 2. Enable = ✓ 3. Schedule = Daily 4. CDR = 90 days 5. Recordings = 30 days 6. Voicemails = 60 days 7. Short recordings = 3 seconds 8. Save ### Scenario 2: Compliance (Keep Long) 1. CDR = 365 days (1 year) 2. Recordings = 365 days 3. Voicemails = 90 days 4. Short recordings = 0 (keep all) 5. Schedule = Weekly 6. Save ### Scenario 3: Space Emergency 1. CDR = 30 days (minimum) 2. Recordings = 7 days (aggressive) 3. Voicemails = 30 days 4. Short recordings = 5 seconds 5. Convert Recordings = ✓ 6. Audio Quality = Good (16k) 7. Save 8. Execute Now ### Scenario 4: Convert Without Deleting 1. CDR = (leave empty) 2. Recordings = (leave empty) 3. Convert Recordings = ✓ 4. Audio Quality = High (32k) 5. Save 6. Only converts, no deletions --- ## 7. Limitations & Important Notes ### Technical Notes > [!NOTE] > **Per-Tenant**: Each tenant has separate settings. > [!NOTE] > **Schedule Time**: Usually runs at 2:00 AM. > [!CAUTION] > **Irreversible**: Deleted data cannot be recovered! ### Best Practices 1. **Backup First**: Ensure backups before aggressive cleanup 2. **Start Conservative**: Begin with longer retention 3. **Monitor Storage**: Watch disk usage trends 4. **Test Execute**: Run Execute Now to verify 5. **Compliance Check**: Verify retention requirements ### Data Types Explained | Data Type | What It Is | |-----------|------------| | CDR | Call Detail Records (metadata) | | Recordings | Audio files of calls | | Voicemails | User voicemail messages | | Log Events | System and audit logs | | SMS | Text messages (if enabled) | --- ## 8. Troubleshooting Tips ### Common Issues | Symptom | Possible Cause | Solution | |---------|---------------|----------| | Disk still full | Short retention | Reduce days | | Job not running | Disabled | Enable cleanup | | Wrong files deleted | Wrong settings | Check config | | Slow cleanup | Many files | Wait or schedule | ### Check Storage ```bash # Check disk usage df -h # Check recordings folder du -sh /var/lib/freeswitch/recordings/ # Check voicemails du -sh /var/lib/freeswitch/voicemail/ # List large files find /var/lib/freeswitch -size +100M -type f ``` ### Check Cleanup Status ```bash # View cleanup log tail -f /var/log/ring2all/cleanup.log # Check cron schedule crontab -l | grep cleanup ``` --- ## 9. Glossary | Term | Definition | |------|------------| | **CDR** | Call Detail Records | | **Retention** | How long to keep data | | **Cleanup** | Automatic deletion | | **Conversion** | Change audio format | | **Execute Now** | Manual cleanup run | --- *Documentation last updated: January 2026*