--- title: "Log File Viewer Module Documentation" description: "Documentation for Log File Viewer" --- ## 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-commercial--business) 5. [Module Overview (End User / Administrator)](#3-module-overview-end-user--administrator) 6. [Supported Log Types & File Locations](#4-supported-log-types--file-locations) 7. [Log Levels & Severity Filtering](#5-log-levels--severity-filtering) 8. [Viewer Controls, Search & Actions](#6-viewer-controls-search--actions) 9. [Common Scenarios & Troubleshooting Workflows](#7-common-scenarios--troubleshooting-workflows) 10. [Limitations & Best Practices](#8-limitations--best-practices) 11. [Model Context Protocol (MCP) AI Integration](#9-model-context-protocol-mcp-ai-integration) 12. [Troubleshooting Tips](#10-troubleshooting-tips) 13. [Glossary](#11-glossary) --- ## Navigation & Access To access the Log File Viewer: 1. Log in to the Ring2All Web Portal (`https:///login`). 2. In the left navigation sidebar, expand **PBX Engine**. 3. Under **PBX Tools**, click **Log File Viewer** (`/pbx/tools/log-viewer`). 4. Select the desired log source (Telephony Server or Fail2ban) and filter by severity or keyword. --- ## Screenshots & Visual Interface ### Log File Viewer Interface Web-based log stream reader featuring multi-log source selection (Telephony Server / Fail2ban), severity level filter badges, keyword search, line count limit selector, log download button, and clear log tool. ![Log File Viewer View](/screenshots/pbx/tools/log-viewer-list.png) --- ## 1. Module Overview (Technical) ### What is the Log File Viewer? The **Log File Viewer** is a real-time, browser-native diagnostic tool that allows authorized system administrators to inspect, search, and download low-level daemon log files directly from the host operating system without opening an SSH terminal session. ### Technical Architecture - **Log Streaming Backend**: The Fastify API endpoint (`GET /api/telephony/log-viewer/entries`) accesses local system log files using buffered reverse-seeking file streams (reading the most recent lines from EOF backwards). - **Log Parsing Engine**: Each raw log line is parsed through regular expressions to extract timestamps, log levels (`DEBUG`, `INFO`, `NOTICE`, `WARNING`, `ERR`, `CRIT`), thread IDs, source filenames, and message payloads. - **Log Source Isolation**: File access is strictly locked to an approved whitelist of server log paths (`/var/log/freeswitch/freeswitch.log` and `/var/log/fail2ban.log`), completely eliminating Path Traversal vulnerabilities (CWE-22). - **Client Rendering**: Renders formatted log entries with syntax-colored level badges, monospace font for technical readability, and instant client-side text filtering. ``` ┌─────────────────────────────────────────────────────────────────┐ │ Log File Viewer Architecture │ ├─────────────────────────────────────────────────────────────────┤ │ │ │ Browser UI (LogViewerPage.tsx) │ │ ┌──────────────────────────────────────────────────────────┐ │ │ │ Filter Bar: [Telephony Server / Fail2ban] [Level: ERR] [Search]│ │ │ │ Table: [Timestamp] [Level] [Source / Message Text] │ │ │ └──────────────────────────────────────────────────────────┘ │ │ ▲ │ │ │ REST API / JSON │ │ ▼ │ │ Fastify Log Service (/api/telephony/log-viewer) │ │ ┌──────────────────────────────────────────────────────────┐ │ │ │ Buffered Reverse Reader (Tail N lines) │ │ │ │ Whitelist Path Validation & RegEx Parser │ │ │ └─────────────────────────────┬────────────────────────────┘ │ │ │ Local OS Filesystem │ │ ▼ │ │ Host Log Files: │ │ ├─ /var/log/freeswitch/freeswitch.log │ │ └─ /var/log/fail2ban.log │ └─────────────────────────────────────────────────────────────────┘ ``` --- ## 2. Module Overview (Commercial / Business) ### Business Value & Accelerated Support - **Rapid Time-to-Resolution (MTTR)**: Support engineers can diagnose SIP registration failures, codec negotiation mismatches, and call routing errors within seconds rather than opening support tickets for server shell access. - **Auditing & Compliance**: Eliminates the security risk of sharing root SSH credentials among Tier-1 and Tier-2 support technicians. - **Security Awareness**: Instant visibility into Fail2ban jail blocks reveals brute-force SIP attacks, helping teams proactively safeguard customer infrastructure. --- ## 3. Module Overview (End User / Administrator) ### Administrator Experience - Select between **Telephony Core** and **Fail2ban Security** logs. - Choose how many lines to fetch (100, 250, 500, or 1000 lines). - Filter out verbose `DEBUG` noise to focus exclusively on `WARNING` and `ERR` events. - Download complete unparsed log files with a single click for vendor escalation. --- ## 4. Supported Log Types & File Locations | Log Source | Default Server Path | Description | Typical Use Case | |:---|:---|:---|:---| | **Telephony Core** | `/var/log/freeswitch/freeswitch.log` | Core telephony engine, Sofia SIP signaling, media bridging, dialplan execution. | Investigating call drops, media errors, IVR issues, SIP gateway timeouts. | | **Fail2ban Security** | `/var/log/fail2ban.log` | Intrusion prevention daemon, IP ban and unban events across SIP and SSH jails. | Identifying malicious brute-force IP addresses and unbanning legitimate clients. | --- ## 5. Log Levels & Severity Filtering Entries are categorized and color-coded based on Telephony Server log levels: | Level | Badge Style | Severity | Explanation | |:---|:---|:---:|:---| | **DEBUG** | Gray | Low | High-frequency trace messages, variable evaluations, and internal state changes. | | **INFO** | Blue | Normal | Routine events such as call setup, hangup, registration, and profile rescans. | | **NOTICE** | Cyan | Normal | Important non-error milestones (e.g., XML reload completion). | | **WARNING** | Yellow | Medium | Minor protocol anomalies, non-critical timeouts, or fallback route triggers. | | **ERR / ERROR**| Red | High | Call failure, media stream failure, database query errors, or SIP 4xx/5xx responses. | | **CRIT** | Dark Red | Critical | Subsystem crash or unrecoverable driver failure requiring immediate attention. | --- ## 6. Viewer Controls, Search & Actions - **Log Selector Tabs**: Toggle effortlessly between *Telephony Server* and *Fail2ban* without losing page context. - **Level Filter**: Dropdown menu allowing filtering by a specific severity (e.g., show only `ERR` and `WARNING`). - **Keyword Search**: Type any string (e.g. extension number `2000`, phone number `+17863643150`, or SIP call ID) to filter matching entries in real time. - **Download Log**: Downloads the active log file directly to your desktop for offline analysis. - **Clear Log**: Truncates the active log file on disk after confirmation, helpful when clearing old noise prior to reproducing an issue. - **Auto-Refresh**: Automatically re-fetches recent log entries at configurable intervals (5s, 10s, 30s). --- ## 7. Common Scenarios & Troubleshooting Workflows ### Scenario 1: Troubleshooting Failed Outbound Calls 1. Open **PBX Tools → Log File Viewer**. 2. Select **Telephony Server** log. 3. In the search box, enter the destination number (e.g., `18005550190`). 4. Set the Level filter to **WARNING** or **ERR**. 5. Inspect the SIP response code returned by the gateway (e.g., `SIP/2.0 503 Service Unavailable` or `486 Busy Here`). ### Scenario 2: Verifying a Blocked Remote Worker IP 1. Select **Fail2ban** log. 2. Search for the remote worker's public IP address. 3. Check for lines reading `[freeswitch-ip] Ban `. 4. Proceed to the Firewall module to whitelist or unban the IP address. --- ## 8. Limitations & Best Practices - **Log File Rotation**: Server log files are automatically rotated by `logrotate` daily. Historical logs from previous days reside in compressed files (`.log.1`, `.log.2.gz`) on the server. - **Buffer Limit**: The viewer displays up to the last 1,000 lines to preserve browser DOM rendering performance and memory efficiency. - **Truncate Caution**: The **Clear Log** button permanently truncates the log file on disk. Ensure critical troubleshooting data has been downloaded first. --- ## 9. Model Context Protocol (MCP) AI Integration The Ring2All Platform Copilot connects to system log streams via the Model Context Protocol (MCP), enabling rapid conversational log analysis, automated failure root-cause detection, and security audit log inspection. ### Exposed MCP Tools | Tool Name | Operation | Primary Parameters | Description | |:---|:---|:---|:---| | `view_telephony_logs` | Real-Time Telephony Log Stream | `lines` (number), `level` (string), `search` (string) | Retrieves recent lines from the Telephony Server telephony log, with optional severity level (`DEBUG`, `INFO`, `NOTICE`, `WARNING`, `ERR`, `CRIT`) and text filtering. | | `query_audit_logs` | Administrative Audit Logs | `action` (string), `resource` (string), `search` (string), `limit` (number) | Searches administrative actions (logins, extension updates, dialplan changes, trunk additions) with timestamps and originating IP. | | `execute_fs_cli_command` | Live Trace Execution | `command` (string) | Runs diagnostic commands like `sofia loglevel all 9` or `show channels` to generate targeted log output. | ### AI Safety Safeguards & Privacy Rules - **PII & Credential Masking**: Password hashes, SIP authentication nonces, and SIP digest passwords are redacted before log lines are sent to the AI Copilot. - **Buffer Bound**: Returns a maximum of 200 lines per call to maintain sub-second response times. - **Read-Only Scope**: The MCP log tools cannot truncate or alter log files on disk (the destructive "Clear Log" operation is restricted to authenticated Web UI users). ### Example MCP Payloads #### 1. Inspecting Recent Telephony Engine Errors (`view_telephony_logs`) ```json { "lines": 25, "level": "ERR", "search": "gateway" } ``` *Response:* ```json { "success": true, "data": { "totalReturned": 1, "filter": { "level": "ERR", "search": "gateway" }, "logs": [ "[ERR] mod_sofia.c:5984 Gateway 'gw_telnyx' authentication failed (SIP/2.0 403 Forbidden)" ] } } ``` #### 2. Querying Administrative Change Logs (`query_audit_logs`) ```json { "resource": "sip_extensions", "action": "UPDATE", "limit": 5 } ``` ### Copilot Natural Language Prompts - *"Check the telephony logs for any error messages during the last 10 minutes."* - *"Search the logs for SIP gateway errors related to gw_telnyx."* - *"Why did call to 18005550199 fail? Search the Telephony Server log for that number."* - *"Show me who modified extension 1004 in the audit logs."* --- ## 10. Troubleshooting Tips | Symptom | Probable Cause | Corrective Action | |:---|:---|:---| | **Viewer displays "Log file not found"** | File path does not exist on server | Verify Telephony Server logging path in `switch.conf.xml`. | | **Permission Denied error** | Web API user cannot read log file | Ensure `/var/log/freeswitch/` has read permissions (`644`) for user `softswitch`. | | **No new entries appear** | Logging verbosity set too low | Increase Sofia SIP or Telephony Server loglevel in PBX CLI via `fsctl loglevel 6`. | --- ## 11. Glossary - **Fail2ban**: Automated daemon that scans log files and blocks IP addresses exhibiting suspicious behavior. - **Logrotate**: System utility designed to rotate, compress, and archive system log files. - **EOF**: End of File. - **Sofia SIP Trace**: Verbose logging of raw SIP packet headers transmitted and received over the wire.