---
title: "CDR Settings Module Documentation"
description: "Documentation for CDR Settings"
---

## Table of Contents
1. [Navigation & Access](#navigation--access)
2. [Screenshots & Visual Interface](#screenshots--visual-interface)
3. [Module Overview (Technical)](#1-module-overview-technical)
4. [Module Overview (Commercial/Business)](#2-module-overview-commercialbusiness)
5. [Module Overview (End User/Administrator)](#3-module-overview-end-useradministrator)
6. [User Roles & Key Capabilities](#-user-roles--key-capabilities)
7. [Configuration Sections](#4-configuration-sections)
8. [Settings Reference](#5-settings-reference)
9. [Common Scenarios & Examples](#6-common-scenarios--examples)
10. [Limitations & Important Notes](#7-limitations--important-notes)
11. [Troubleshooting Tips](#8-troubleshooting-tips)
12. [Glossary](#9-glossary)
13. [Model Context Protocol (MCP) AI Integration](#model-context-protocol-mcp-ai-integration)
---

## Navigation & Access

To access the CDR Settings configuration module:
1. Log in to the Ring2All Web Portal (`https://<domain-or-ip>/login`).
2. In the left navigation sidebar, expand **Settings**.
3. Under **PBX**, click **CDR Settings** (`/settings/pbx/cdr-settings`).
4. Configure database target connections, spool directory paths, CSV export formats, and customized field mappings, then click **Save Changes** in the bottom action bar.

---

## Screenshots & Visual Interface

### CDR Configuration & Schema Mapping Form
Central administrative interface for configuring PostgreSQL real-time CDR insertion, spool path fallbacks, and drag-and-drop custom column schema mappings with live XML preview and node sync.
![CDR Settings Form](/screenshots/settings/pbx/cdr-settings-form.png)

---

## 1. Module Overview (Technical)

### What Is CDR Settings?

CDR Settings is a **Telephony Server mod_cdr_pg_csv configuration module** that manages Call Detail Record export to PostgreSQL. It configures database connection, field mappings, and export options for real-time CDR storage.

### Architecture

```
┌─────────────────────────────────────────────────────────────────┐
│                  CDR Settings Architecture                     │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│  Admin Panel                                                    │
│  ┌──────────────────────────────────────────────────────────┐   │
│  │        CDR Settings                                      │   │
│  │                                                          │   │
│  │  General Settings:                                       │   │
│  │  ├─ Database Connection                                 │   │
│  │  ├─ Table Name                                          │   │
│  │  ├─ Legs to Log                                         │   │
│  │  └─ Spool Format                                        │   │
│  │                                                          │   │
│  │  CDR Fields:                                             │   │
│  │  ├─ uuid → call_uuid                                    │   │
│  │  ├─ caller_id_number → caller_number                    │   │
│  │  ├─ duration → duration                                 │   │
│  │  └─ (custom fields)                                     │   │
│  │                                                          │   │
│  └──────────────────────────────────────────────────────────┘   │
│       │                                                         │
│       ▼ Generates XML                                          │
│  ┌──────────────────────────────────────────────────────────┐   │
│  │        cdr_pg_csv.conf.xml                               │   │
│  │                                                          │   │
│  │  <configuration name="cdr_pg_csv.conf">                  │   │
│  │    <db-info>                                             │   │
│  │      <db-host>127.0.0.1</db-host>                       │   │
│  │      <db-name>r2a_cdr</db-name>                         │   │
│  │    </db-info>                                            │   │
│  │    <field-list>                                          │   │
│  │      <field var="uuid" column="call_uuid"/>              │   │
│  │    </field-list>                                         │   │
│  │  </configuration>                                        │   │
│  │                                                          │   │
│  └──────────────────────────────────────────────────────────┘   │
│       │                                                         │
│       ▼ Used by Telephony Server                                     │
│  ┌──────────────────────────────────────────────────────────┐   │
│  │        mod_cdr_pg_csv                                    │   │
│  │                                                          │   │
│  │  Call ends → Extract fields → INSERT into PostgreSQL    │   │
│  │                                                          │   │
│  └──────────────────────────────────────────────────────────┘   │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘
```

---

## 2. Module Overview (Commercial/Business)

### Business Value

CDR Settings provides **configurable CDR export**:

| Without CDR Settings | With CDR Settings |
|----------------------|------------------|
| Default fields only | Custom field mapping |
| Fixed schema | Flexible columns |
| Manual XML editing | Web interface |
| No field control | Enable/disable fields |

### Use Cases

1. **Custom Reporting**
   - Export specific fields
   - Custom column names

2. **Data Integration**
   - Map to existing schema
   - Third-party billing

3. **Storage Optimization**
   - Export only needed fields
   - Reduce database size

4. **Compliance**
   - Log required fields
   - Track specific data

### Feature Highlights

| Feature | Benefit |
|---------|---------|
| **Database Config** | PostgreSQL connection |
| **Field Mapping** | Variable to column |
| **Legs Selection** | A, B, or both |
| **Spool Fallback** | CSV/SQL backup |
| **Custom Fields** | Add any variable |
| **XML Preview** | Verify before deploy |

---

## 3. Module Overview (End User/Administrator)

### What Can You Do?

- Configure PostgreSQL connection
- Map Telephony Server variables to columns
- Select which call legs to log
- Enable/disable individual fields
- Set column aliases
- Configure spool fallback format
- Preview generated XML

### CDR Settings Interface

```
┌─────────────────────────────────────────────────────────────────┐
│              CDR Settings                                       │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│  Configure CDR export to PostgreSQL and manage exported fields. │
│                                                                 │
│  ▼ General Settings                                             │
│                                                                 │
│  Host: [127.0.0.1              ]                               │
│  Port: [5432                    ]                               │
│  Database Name: [r2a_cdr              ]                        │
│  User: [r2a_user               ]                               │
│  Password: [••••••••             ]                             │
│  CDR Table Name: [cdr                   ]                      │
│                                                                 │
│  Connect Timeout (s): [10                ]                     │
│  Additional Options: [sslmode=require     ]                    │
│                                                                 │
│  Legs to Log: [Both Legs ▼]                                    │
│    ├─ Leg A (Caller)                                           │
│    ├─ Leg B (Callee)                                           │
│    └─ Both Legs                                                │
│                                                                 │
│  Spool Format: [CSV ▼]                                         │
│  Rotate on HUP: ✓                                              │
│  Debug Mode: ☐                                                 │
│                                                                 │
│  [Save Settings] [Preview XML] [Apply to Nodes]                 │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘
```

### CDR Fields Section

```
┌─────────────────────────────────────────────────────────────────┐
│              CDR Settings - Fields                              │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│  ▼ CDR Fields                                                   │
│                                                                 │
│  [+ Add Field]                                                  │
│                                                                 │
│  ┌─────────────────────────────────────────────────────────────┐│
│  │ Order │ Variable Name      │ Alias          │ Quote │ On  ││
│  ├───────┼────────────────────┼────────────────┼───────┼─────┤│
│  │ 1     │ uuid               │ call_uuid      │ ✓     │ ✓   ││
│  │ 2     │ caller_id_number   │ caller_number  │ ✓     │ ✓   ││
│  │ 3     │ destination_number │ called_number  │ ✓     │ ✓   ││
│  │ 4     │ start_stamp        │ start_time     │ ✓     │ ✓   ││
│  │ 5     │ answer_stamp       │ answer_time    │ ✓     │ ✓   ││
│  │ 6     │ end_stamp          │ end_time       │ ✓     │ ✓   ││
│  │ 7     │ duration           │ duration       │ ☐     │ ✓   ││
│  │ 8     │ billsec            │ billsec        │ ☐     │ ✓   ││
│  │ 9     │ hangup_cause       │ hangup_cause   │ ✓     │ ✓   ││
│  │ 10    │ accountcode        │ account_code   │ ✓     │ ☐   ││
│  └─────────────────────────────────────────────────────────────┘│
│                                                                 │
│  [Save Fields]                                                  │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘
```

### Quick Tips

> [!TIP]
> **Quote Text Fields**: Enable Quote for string/text values.

> [!TIP]
> **Disable Unused**: Turn off fields you don't need.

> [!NOTE]
> **System Fields**: Some fields are required and cannot be removed.

---

## 🎯 User Roles & Key Capabilities

| Role | Permissions | Key Capabilities |
|------|-------------|------------------|
| **Super Administrator** | Full Access (`read`, `write`, `apply`) | Configure PostgreSQL real-time CDR insertion endpoints, disk spool directories, and apply generated `cdr_pg_csv.conf.xml` directly to the telephony core. |
| **Billing & Telecom Engineer** | Schema Management (`read`, `write`) | Customize exported CDR fields (account codes, MOS QoS scores, carrier rates, hangup causes), configure text quoting, and adjust field column aliases. |
| **Database Auditor** | Read & Diagnostic (`read`, `preview`) | Inspect active CDR database schema mappings, preview raw XML configuration, and verify spool fallback directory health. |
| **Tenant Administrator** | Restricted Read | View tenant-level CDR export mappings and column structures. |

---

## 4. Configuration Sections

### General Settings

| Field | Description |
|-------|-------------|
| **Host** | PostgreSQL server address |
| **Port** | PostgreSQL port (5432) |
| **Database Name** | Target database |
| **User** | Database username |
| **Password** | Database password |
| **CDR Table Name** | Destination table |
| **Connect Timeout** | Connection timeout (seconds) |
| **Additional Options** | Extra connection parameters |

### Export Options

| Field | Description |
|-------|-------------|
| **Legs to Log** | Leg A, Leg B, or Both |
| **Spool Format** | CSV or SQL fallback |
| **Rotate on HUP** | Reload on signal |
| **Debug Mode** | Verbose logging |

### CDR Fields

| Field | Description |
|-------|-------------|
| **Variable Name** | Telephony Server channel variable |
| **Alias** | Database column name |
| **Quote** | Wrap value in quotes |
| **Enabled** | Include in export |
| **Order** | Column order in schema |

---

## 5. Settings Reference

### Common CDR Variables

| Variable | Description |
|----------|-------------|
| **uuid** | Call unique ID |
| **caller_id_number** | Caller's number |
| **caller_id_name** | Caller's name |
| **destination_number** | Called number |
| **start_stamp** | Call start time |
| **answer_stamp** | Call answer time |
| **end_stamp** | Call end time |
| **duration** | Total duration (seconds) |
| **billsec** | Billable seconds |
| **hangup_cause** | Hangup reason |
| **accountcode** | Account code |

### Legs Options

| Option | Description |
|--------|-------------|
| **Leg A** | Caller/originating leg |
| **Leg B** | Callee/terminating leg |
| **Both** | Both legs recorded |

### Spool Formats

| Format | Use Case |
|--------|----------|
| **CSV** | Comma-separated fallback |
| **SQL** | SQL INSERT statements |

---

## 6. Common Scenarios & Examples

### Scenario 1: Basic CDR Export

1. Configure database connection
2. Set table name = cdr
3. Enable default fields
4. Legs = Both Legs
5. Save and apply

### Scenario 2: Custom Billing Fields

1. Add field: accountcode → account_code
2. Add field: billsec → billable_seconds
3. Add field: rate → billing_rate
4. Enable Quote for text fields
5. Save

### Scenario 3: Minimal CDR

1. Disable non-essential fields
2. Keep: uuid, caller, destination, duration, hangup_cause
3. Save (reduces storage)

### Scenario 4: SSL Connection

1. Set Additional Options = sslmode=require
2. Configure database connection
3. Save and apply

---

## 7. Limitations & Important Notes

### Technical Notes

> [!NOTE]
> **mod_cdr_pg_csv**: Uses Telephony Server PostgreSQL CDR module.

> [!NOTE]
> **Spool Fallback**: If database unavailable, records spool to file.

> [!WARNING]
> **Schema Match**: Field aliases must match database columns.

### Best Practices

1. **Test Connection**: Verify database connectivity
2. **Match Schema**: Ensure aliases match table columns
3. **Quote Text**: Use Quote for string fields
4. **Enable Essentials**: Always log uuid, duration, hangup_cause
5. **Monitor Spool**: Check for spooled files

### Required Fields

| Field | Why Required |
|-------|--------------|
| **uuid** | Unique call identifier |
| **start_stamp** | Call timing |
| **end_stamp** | Call timing |
| **hangup_cause** | Call result |

---

## 8. Troubleshooting Tips

### Common Issues

| Symptom | Possible Cause | Solution |
|---------|---------------|----------|
| No CDR records | Connection failed | Check database settings |
| Column mismatch | Wrong alias | Match alias to column |
| Spool files growing | DB unavailable | Fix database connection |
| Null values | Quoting issue | Check Quote setting |
| Missing field | Not enabled | Enable field |

### Test Database Connection

```bash
# Test PostgreSQL connection
psql -h <host> -p <port> -U <user> -d <database>

# Check CDR table
SELECT * FROM cdr ORDER BY start_stamp DESC LIMIT 10;
```

### Check Spooled Files

```bash
# Check for spooled CDR files
ls -la /var/log/freeswitch/cdr-csv/
ls -la /var/log/freeswitch/cdr-pg-csv/
```

### Verify Configuration

Use "Preview XML" to verify generated configuration before applying.

---

## 9. Glossary

| Term | Definition |
|------|------------|
| **CDR** | Call Detail Record |
| **mod_cdr_pg_csv** | Telephony Server PostgreSQL CDR module |
| **Leg A** | Caller/originating leg |
| **Leg B** | Callee/terminating leg |
| **Spool** | File-based fallback storage |
| **Alias** | Database column name |
| **Quote** | Text value quoting |

---

## Model Context Protocol (MCP) AI Integration

The Ring2All PBX platform integrates deep AI assistance via the Model Context Protocol (MCP). The CDR Settings module allows the PBX AI Copilot to safely query Call Detail Record database parameters, inspect spool directories, and verify exported schema fields without accessing backend configuration files directly.

### Available MCP Tools

| Tool Name | Operation Type | RBAC Risk Level | Description |
|-----------|----------------|-----------------|-------------|
| `get_cdr_settings` | Read / Query | `low` | Retrieves CDR (Call Detail Record) storage engine configuration, mod_cdr_pg_csv / cdr_csv parameters, and active export fields. |

### Tool Input Schemas & Parameters

#### 1. `get_cdr_settings`
```json
{
  "name": "get_cdr_settings",
  "description": "Get CDR (Call Detail Record) storage engine configuration, mod_cdr_pg_csv / cdr_csv parameters, and active export fields.",
  "inputSchema": {
    "type": "object",
    "properties": {}
  }
}
```

### Natural Language Prompts

| User Request | Invoked MCP Tool | Expected AI Response |
|--------------|------------------|----------------------|
| *"Show me our CDR database configuration and active export fields."* | `get_cdr_settings` | Returns database host, table name, spool directory, and list of enabled column mappings. |
| *"Are call quality MOS scores and packet loss fields enabled in our CDRs?"* | `get_cdr_settings` | Checks mapped fields for `rtp_audio_in_mos`, `rtp_audio_in_quality_percentage`, and reporting status. |
| *"Where are CDR records spooled when the database is unreachable?"* | `get_cdr_settings` | Reports fallback disk spool directory path (e.g. `/var/log/freeswitch/cdr-pg-csv`). |

### Multi-Tenant & Security Safeguards

- **Engine Level Protection**: CDR export engine configuration operates at the core PBX level; database credentials and passwords are strictly redacted from AI tool responses.
- **Read-Only Verification**: Copilot queries are strictly read-only; schema changes require explicit administrative approval and confirmation.
- **Fail-Safe Spooling**: Spool directory paths are verified against system storage permissions to prevent data loss during database maintenance.
- **Audit Logging**: All CDR settings inquiries are recorded in the central platform audit log.

---

*Documentation last updated: January 2026*