---
title: "Logging Settings Module Documentation"
description: "Documentation for Log 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 Tabs](#4-configuration-tabs)
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 Logging 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 **Log Settings** (`/settings/pbx/log-files/edit`).
4. Configure global logging verbosity, logfile rotation sizes, log level filters (DEBUG, INFO, NOTICE, WARNING, ERR, CRIT), and click **Save Changes** in the bottom action bar.

---

## Screenshots & Visual Interface

### Logging Configuration Form
Unified log configuration interface allowing administrators to control console verbosity, disk logging policies, file size rotation thresholds, colorization modes, and module-specific log overrides.
![Logging Settings Form](/screenshots/settings/pbx/log-settings-form.png)

---

## 1. Module Overview (Technical)

### What Is Logging Settings?

Logging Settings is a **Telephony Server logging configuration module** that manages console output and file logging. It configures log levels, colorization, file rotation, and module-specific mappings.

### Architecture

```
┌─────────────────────────────────────────────────────────────────┐
│               Logging Settings Architecture                    │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│  Admin Panel                                                    │
│  ┌──────────────────────────────────────────────────────────┐   │
│  │        Logging Settings                                  │   │
│  │                                                          │   │
│  │  Tabs:                                                   │   │
│  │  ├─ Console Logging                                     │   │
│  │  │   ├─ Colorize Output                                 │   │
│  │  │   ├─ Console Log Level                               │   │
│  │  │   └─ Console Mappings                                │   │
│  │  │                                                       │   │
│  │  └─ File Logging                                        │   │
│  │      ├─ Rotate on HUP                                   │   │
│  │      └─ File Logging Profiles                           │   │
│  │                                                          │   │
│  └──────────────────────────────────────────────────────────┘   │
│       │                                                         │
│       ▼ Generates XML                                          │
│  ┌──────────────────────────────────────────────────────────┐   │
│  │  console.conf.xml     logfile.conf.xml                   │   │
│  │                                                          │   │
│  │  <configuration name="console.conf">                     │   │
│  │    <param name="colorize" value="true"/>                │   │
│  │    <param name="loglevel" value="info"/>                │   │
│  │  </configuration>                                        │   │
│  │                                                          │   │
│  └──────────────────────────────────────────────────────────┘   │
│       │                                                         │
│       ▼ Loaded by Telephony Server                                   │
│  ┌──────────────────────────────────────────────────────────┐   │
│  │        Telephony Server Logging                                │   │
│  │                                                          │   │
│  │  Console → Terminal output                              │   │
│  │  File → /var/log/freeswitch/freeswitch.log             │   │
│  │                                                          │   │
│  └──────────────────────────────────────────────────────────┘   │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘
```

---

## 2. Module Overview (Commercial/Business)

### Business Value

Logging Settings provides **centralized log management**:

| Without Logging Settings | With Logging Settings |
|--------------------------|----------------------|
| Edit XML files | Web interface |
| Default levels | Custom per-module |
| Manual rotation | Automatic rotation |
| No filtering | Targeted logging |

### Use Cases

1. **Troubleshooting**
   - Enable debug for specific modules
   - Track call issues

2. **Production Optimization**
   - Reduce log noise
   - Manage log file size

3. **Compliance**
   - Log retention policies
   - UUID tracking

4. **Monitoring Integration**
   - Log rotation for logrotate
   - Structured output

### Feature Highlights

| Feature | Benefit |
|---------|---------|
| **Console Logging** | Terminal output control |
| **File Logging** | Persistent log files |
| **Log Levels** | Filter by severity |
| **Mappings** | Per-module levels |
| **Rotation** | Size-based rollover |
| **UUID Prefix** | Session tracking |

---

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

### What Can You Do?

- Configure console log levels
- Enable/disable colorized output
- Create file logging profiles
- Set log file rotation
- Configure per-module log levels
- Enable UUID prefixes for session tracking
- Preview generated XML

### Logging Settings Interface

```
┌─────────────────────────────────────────────────────────────────┐
│              Logging Settings                                   │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│  Configure Telephony Server console and file logging                  │
│                                                                 │
│  [Console Logging] [File Logging]                               │
│  ─────────────────────────────────────────────────────────────  │
│                                                                 │
│  Console Logging Settings                                       │
│                                                                 │
│  Colorize Output: ✓                                            │
│    Enables ANSI color highlighting in console output.           │
│                                                                 │
│  Console Log Level: [Debug] [Info] [Notice] [Warning] [Error]  │
│    ☐ Debug                                                     │
│    ✓ Info                                                      │
│    ✓ Notice                                                    │
│    ✓ Warning                                                   │
│    ✓ Error                                                     │
│    ✓ Critical                                                  │
│    ✓ Alert                                                     │
│                                                                 │
│  Console Mappings                                               │
│  Configure which log levels are displayed for specific targets. │
│                                                                 │
│  [+ Add Mapping]                                                │
│                                                                 │
│  ┌───────────────────────────────────────────────────────────┐  │
│  │ Mapping Name       │ Log Levels                         │  │
│  ├────────────────────┼────────────────────────────────────┤  │
│  │ all                │ info, notice, warning, err         │  │
│  │ mod_sofia          │ debug, info, notice, warning, err  │  │
│  │ mod_lua            │ warning, err                       │  │
│  └───────────────────────────────────────────────────────────┘  │
│                                                                 │
│  [View XML] [Save]                                              │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘
```

### File Logging Tab

```
┌─────────────────────────────────────────────────────────────────┐
│              Logging Settings                                   │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│  [Console Logging] [File Logging]                               │
│  ─────────────────────────────────────────────────────────────  │
│                                                                 │
│  File Logging Settings                                          │
│                                                                 │
│  Rotate on HUP Signal: ✓                                       │
│    Log file reopened on HUP signal for external rotation.       │
│                                                                 │
│  File Logging Profiles                                          │
│                                                                 │
│  [+ Add Profile]                                                │
│                                                                 │
│  ▼ Profile: mainlog                                             │
│  ├─ Log File Path: [/var/log/freeswitch/freeswitch.log]        │
│  ├─ Rollover (Bytes): [10485760         ] (10MB rollover)     │
│  ├─ Maximum Rotate: [5                  ] (keep 5 files)      │
│  ├─ UUID Prefix: ✓                                             │
│  └─ Mappings:                                                   │
│     ├─ all → info, notice, warning, err, crit, alert           │
│     └─ mod_sofia → debug, info, notice, warning, err           │
│                                                                 │
│  [View XML] [Download console.conf.xml] [Download logfile.conf.xml]│
│                                                                 │
│  [Save]                                                         │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘
```

### Quick Tips

> [!TIP]
> **Debug Module**: Add mapping for specific module with debug level.

> [!TIP]
> **UUID Prefix**: Enable to track logs by call session.

> [!NOTE]
> **Restart Required**: Log configuration changes need FS reload.

---

## 🎯 User Roles & Key Capabilities

| Role | Permissions | Key Capabilities |
|------|-------------|------------------|
| **Super Administrator** | Full Access (`read`, `write`, `export_xml`) | Manage global Telephony Server logging profiles (`console.conf.xml`, `logfile.conf.xml`), configure disk rotation limits (10MB-100MB), and set debug verbosity. |
| **PBX / DevOps Engineer** | Operational Configuration (`read`, `write`) | Enable module-specific debug overrides (e.g. `mod_sofia`, `mod_conference`), configure UUID session prefixes, and inspect rotated logs. |
| **Security Auditor** | Read & Inspection (`read`) | Audit log retention limits, verify console colorization, and check file rotation policies against compliance standards. |
| **Tenant Administrator** | Restricted Read | View tenant-assigned logging parameters in multi-tenant environments. |

---

## 4. Configuration Tabs

### Console Logging Tab

| Field | Description |
|-------|-------------|
| **Colorize Output** | ANSI color highlighting |
| **Console Log Level** | Visible log levels |
| **Console Mappings** | Per-target level overrides |

### File Logging Tab

| Field | Description |
|-------|-------------|
| **Rotate on HUP** | External rotation support |
| **File Logging Profiles** | Log file configurations |

### Profile Settings

| Field | Description |
|-------|-------------|
| **Profile Name** | Identifier |
| **Log File Path** | File location |
| **Rollover** | Max size before rotation (bytes) |
| **Maximum Rotate** | Files to keep |
| **UUID Prefix** | Session UUID in logs |
| **Mappings** | Per-module log levels |

---

## 5. Settings Reference

### Log Levels

| Level | Severity | Use Case |
|-------|----------|----------|
| **Debug** | Lowest | Development, troubleshooting |
| **Info** | Low | Informational messages |
| **Notice** | Normal | Normal conditions |
| **Warning** | Medium | Potential issues |
| **Error** | High | Errors occurred |
| **Critical** | Very High | Critical conditions |
| **Alert** | Highest | Immediate action needed |

### Common Mappings

| Mapping | Purpose |
|---------|---------|
| **all** | Default for all modules |
| **mod_sofia** | SIP signaling |
| **mod_lua** | Lua scripts |
| **mod_dptools** | Dialplan tools |
| **mod_xml_curl** | XML curl requests |

### Rollover Sizes

| Bytes | Human Readable |
|-------|----------------|
| 1048576 | 1 MB |
| 5242880 | 5 MB |
| 10485760 | 10 MB |
| 52428800 | 50 MB |
| 104857600 | 100 MB |

---

## 6. Common Scenarios & Examples

### Scenario 1: Debug SIP Issues

1. Go to Console Logging
2. Add Mapping: mod_sofia = debug, info, notice, warning, err
3. Save
4. Monitor console for SIP debug

### Scenario 2: Production Logging

1. Go to File Logging
2. Set Rollover = 10485760 (10MB)
3. Set Maximum Rotate = 10
4. Enable Rotate on HUP
5. Set "all" mapping = warning, err, crit, alert
6. Save

### Scenario 3: Call Tracking

1. Go to File Logging
2. Enable UUID Prefix
3. Save
4. Logs now include session UUID

### Scenario 4: Minimal Console

1. Go to Console Logging
2. Disable Debug, Info, Notice
3. Keep only Warning, Error, Critical, Alert
4. Save

---

## 7. Limitations & Important Notes

### Technical Notes

> [!NOTE]
> **XML Generation**: Creates console.conf.xml and logfile.conf.xml.

> [!NOTE]
> **HUP Signal**: Used by logrotate for external rotation.

> [!WARNING]
> **Debug in Production**: Avoid debug level in production (high volume).

### Best Practices

1. **Production**: Use Warning+ levels only
2. **Debug Temporarily**: Turn off debug after troubleshooting
3. **Set Rotation**: Prevent disk full issues
4. **UUID for Tracking**: Enable for call troubleshooting
5. **Logrotate Integration**: Enable Rotate on HUP

### Log File Locations

| Distribution | Default Path |
|--------------|--------------|
| **Debian/Ubuntu** | /var/log/freeswitch/freeswitch.log |
| **CentOS/RHEL** | /var/log/freeswitch/freeswitch.log |
| **Custom** | Configure in profile |

---

## 8. Troubleshooting Tips

### Common Issues

| Symptom | Possible Cause | Solution |
|---------|---------------|----------|
| No logs | Profile disabled | Enable profile |
| Disk full | No rotation | Set rollover and maximum |
| Too verbose | Debug enabled | Reduce log levels |
| No colors | Colorize off | Enable Colorize Output |
| Logs too quiet | Levels too strict | Add info, notice levels |

### Check Log Configuration

```bash
# View current log level
fs_cli -x "console loglevel"

# Switch console level temporarily
fs_cli -x "console loglevel debug"

# Check log file
tail -f /var/log/freeswitch/freeswitch.log
```

### View Generated XML

Use "View XML" button to preview configuration before saving.

---

## 9. Glossary

| Term | Definition |
|------|------------|
| **Log Level** | Message severity filter |
| **Mapping** | Per-module log level |
| **Rollover** | Size-based file rotation |
| **HUP Signal** | Unix signal for log rotation |
| **UUID Prefix** | Session ID in log lines |
| **Colorize** | ANSI terminal colors |

---

## Model Context Protocol (MCP) AI Integration

The Ring2All PBX platform integrates deep AI assistance via the Model Context Protocol (MCP). The Logging Settings module allows the PBX AI Copilot to safely query engine logging levels, check log rotation thresholds, and inspect file storage policies to diagnose troubleshooting verbosity without direct console access.

### Available MCP Tools

| Tool Name | Operation Type | RBAC Risk Level | Description |
|-----------|----------------|-----------------|-------------|
| `get_logging_settings` | Read / Query | `low` | Retrieves PBX core logging settings, console log level (DEBUG, INFO, NOTICE, WARNING, ERR), file rotation, and retention policies. |

### Tool Input Schemas & Parameters

#### 1. `get_logging_settings`
```json
{
  "name": "get_logging_settings",
  "description": "Get PBX core logging settings, console log level (DEBUG, INFO, NOTICE, WARNING, ERR), file rotation, and retention policies.",
  "inputSchema": {
    "type": "object",
    "properties": {}
  }
}
```

### Natural Language Prompts

| User Request | Invoked MCP Tool | Expected AI Response |
|--------------|------------------|----------------------|
| *"What is our current Telephony Server console logging verbosity?"* | `get_logging_settings` | Returns active console log levels (e.g. `INFO, NOTICE, WARNING, ERR, CRIT`). |
| *"Check our log file rotation size and retention settings."* | `get_logging_settings` | Details maximum file rollover size (e.g. 10MB) and number of rotated archives preserved (e.g. 5). |
| *"Is UUID session prefixing enabled on our telephony logs?"* | `get_logging_settings` | Reports whether each log line includes the unique call session UUID for correlation. |

### Multi-Tenant & Security Safeguards

- **Tenant Isolation**: Logging profiles are partitioned by `tenant_id` and associated `domain_id`.
- **Disk Protection**: Logfile rollover thresholds are enforced to prevent disk fill-up during verbose debugging.
- **Credential Protection**: Log streams exclude raw authentication passwords; sensitive credentials are automatically sanitized.
- **Audit Logging**: All changes to logging configurations are recorded in the platform security audit logs.

---

*Documentation last updated: January 2026*