---
title: "SIP Profiles Module Documentation"
description: "Documentation for SIP 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 Categories](#4-configuration-categories)
8. [Common Settings Reference](#5-common-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 SIP Profiles (SIP 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 **Technology**, click **SIP Settings** (`/settings/technology/sip`).
4. To modify an existing profile (such as `internal`, `external`, or `webrtc`), click on the profile row or the **Edit** action button (`/settings/technology/sip/:id`).

---

## Screenshots & Visual Interface

### SIP Profiles Directory & Status Overview
Centralized inventory of Telephony Server Sofia SIP profiles, showing profile names, bindings, categories, active RTP media IP bindings, SIP ports, and operational runtime status.
![SIP Profiles List](/screenshots/settings/technology/sip-settings-list.png)

### SIP Profile Configuration & Parameter Management
Full-featured configuration interface providing granular control over Sofia SIP stack parameters including SIP bind IP, port, TLS/WSS encryption, NAT traversal, codec negotiation, ACL filters, and timer parameters.
![SIP Profile Form](/screenshots/settings/technology/sip-settings-form.png)

---

## 1. Module Overview (Technical)

### What Are SIP Profiles?

SIP Profiles is a **Telephony Server configuration module** that manages SIP profile settings. SIP profiles define how Telephony Server handles SIP signaling, including transport protocols, codecs, NAT handling, security, and registration behavior.

### Architecture

```
┌─────────────────────────────────────────────────────────────────┐
│                  SIP Profiles Architecture                      │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│  Admin Panel                                                    │
│  ┌──────────────────────────────────────────────────────────┐   │
│  │        SIP Profiles Page                                 │   │
│  │                                                          │   │
│  │  Profiles: [internal] [external] [custom]                │   │
│  │                                                          │   │
│  │  Categories:                                             │   │
│  │  ├─ General Settings                                     │   │
│  │  ├─ Transport (SIP/TLS)                                  │   │
│  │  ├─ Media & Codecs                                       │   │
│  │  ├─ NAT / ACL                                            │   │
│  │  ├─ Security & Auth                                      │   │
│  │  ├─ Registration                                         │   │
│  │  ├─ Call Handling                                        │   │
│  │  └─ Advanced                                             │   │
│  │                                                          │   │
│  └──────────────────────────────────────────────────────────┘   │
│       │                                                         │
│       ▼ Configuration saved                                     │
│  ┌──────────────────────────────────────────────────────────┐   │
│  │        public.sip_profiles                               │   │
│  │        public.sip_profile_settings                       │   │
│  │                                                          │   │
│  └──────────────────────────────────────────────────────────┘   │
│       │                                                         │
│       ▼ Telephony Server XML generated                               │
│  ┌──────────────────────────────────────────────────────────┐   │
│  │        Telephony Server mod_sofia                              │   │
│  │                                                          │   │
│  │  <profile name="internal">                               │   │
│  │    <param name="sip-port" value="5060"/>                │   │
│  │    <param name="rtp-timeout-sec" value="300"/>          │   │
│  │    ...                                                   │   │
│  │  </profile>                                              │   │
│  │                                                          │   │
│  └──────────────────────────────────────────────────────────┘   │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘
```

---

## 2. Module Overview (Commercial/Business)

### Business Value

SIP Profiles provides **centralized SIP configuration**:

| Without SIP Profiles | With SIP Profiles |
|----------------------|-------------------|
| Manual XML editing | Web interface |
| CLI configuration | Category-based UI |
| Error-prone edits | Validated settings |
| Server access needed | Browser-based |

### Use Cases

1. **Transport Configuration**
   - Configure SIP ports
   - Enable TLS encryption

2. **NAT Handling**
   - Configure STUN/TURN
   - Set external IP

3. **Codec Management**
   - Configure codec preferences
   - Enable/disable codecs

4. **Security Setup**
   - Configure authentication
   - Set registration policies

### Feature Highlights

| Feature | Benefit |
|---------|---------|
| **Web Interface** | No CLI needed |
| **Categories** | Organized settings |
| **Default Values** | Easy reset |
| **Multiple Profiles** | Internal/External |
| **Search** | Find settings fast |
| **Validation** | Prevent errors |

---

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

### What Can You Do?

- Create and manage SIP profiles
- Configure SIP transport settings
- Set media and codec preferences
- Configure NAT traversal
- Set security parameters
- Manage registration behavior
- Configure call handling options

### SIP Profiles Interface

```
┌─────────────────────────────────────────────────────────────────┐
│              SIP Profiles                                       │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│  [+ Create SIP Profile]                                         │
│                                                                 │
│  ┌───────────────────────────────────────────────────────────┐  │
│  │ Profile     │ Description       │ Settings │ Status      │  │
│  ├─────────────┼───────────────────┼──────────┼─────────────┤  │
│  │ internal    │ Internal SIP      │ 45       │ 🟢 Enabled  │  │
│  │ external    │ External/Trunks   │ 52       │ 🟢 Enabled  │  │
│  │ secure      │ TLS-only profile  │ 48       │ 🟢 Enabled  │  │
│  └───────────────────────────────────────────────────────────┘  │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘
```

### Profile Edit View

```
┌─────────────────────────────────────────────────────────────────┐
│              Edit SIP Profile: internal                         │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│  Profile Name: [internal                         ]              │
│  Description: [Internal SIP for extensions       ]              │
│  Enabled: ✓                                                     │
│                                                                 │
│  🔍 [Search settings...                               ]        │
│                                                                 │
│  ▼ General Settings (12 parameters)                             │
│  ├─ context: [default           ] [↺ Reset]                    │
│  ├─ dialplan: [XML              ] [↺ Reset]                    │
│  └─ user-agent: [Ring2All       ] [↺ Reset]                    │
│                                                                 │
│  ▼ Transport (SIP/TLS) (15 parameters)                          │
│  ├─ sip-port: [5060             ] [↺ Reset]                    │
│  ├─ sip-ip: [auto               ] [↺ Reset]                    │
│  ├─ tls: [false                 ] [↺ Reset]                    │
│  └─ tls-cert-dir: [/etc/certs   ] [↺ Reset]                    │
│                                                                 │
│  ▶ Media & Codecs (8 parameters)                                │
│  ▶ NAT / ACL (10 parameters)                                    │
│  ▶ Security & Auth (7 parameters)                               │
│  ▶ Registration (6 parameters)                                  │
│  ▶ Call Handling (5 parameters)                                 │
│  ▶ Advanced (12 parameters)                                     │
│                                                                 │
│  [Save] [Cancel]                                                │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘
```

### Quick Tips

> [!TIP]
> **Reset to Default**: Click ↺ to reset a parameter to its default value.

> [!TIP]
> **Search**: Use search to find specific settings across categories.

> [!CAUTION]
> **Restart Required**: Profile changes require Telephony Server reload.

---

## 🎯 User Roles & Key Capabilities

| Role | Permissions | Key Capabilities |
|------|-------------|------------------|
| **Super Administrator** | Full Access (`read`, `write`, `delete`, `restart`) | Manage Sofia SIP profiles (`internal`, `external`), modify network bind addresses, configure TLS certificates, and restart Sofia profiles. |
| **PBX / VoIP Engineer** | Operational Management (`read`, `write`) | Configure SIP timers, adjust NAT IP rewrites, modify codec lists (OPUS, PCMU, G729), and inspect live profile registration state. |
| **Support Specialist** | Read & Diagnostic (`read`, `status`) | View active bind ports, inspect Sofia status metrics, and execute live SIP trace diagnostics without mutating XML configurations. |
| **Tenant Administrator** | Restricted Read | View assigned technology profile settings in a multi-tenant PBX partition. |

---

## 4. Configuration Categories

### General Settings

| Purpose | Common Parameters |
|---------|-------------------|
| Basic profile behavior | context, dialplan, user-agent |

### Transport (SIP/TLS)

| Purpose | Common Parameters |
|---------|-------------------|
| SIP signaling layer | sip-port, sip-ip, tls, tls-cert-dir |

### Media & Codecs

| Purpose | Common Parameters |
|---------|-------------------|
| Audio/video settings | codec-prefs, rtp-timer-name |

### NAT / ACL

| Purpose | Common Parameters |
|---------|-------------------|
| NAT traversal | ext-rtp-ip, ext-sip-ip, apply-inbound-acl |

### Security & Auth

| Purpose | Common Parameters |
|---------|-------------------|
| Authentication | challenge-realm, auth-calls |

### Registration

| Purpose | Common Parameters |
|---------|-------------------|
| Device registration | accept-blind-reg, disable-register |

### Call Handling

| Purpose | Common Parameters |
|---------|-------------------|
| Call behavior | rtp-timeout-sec, hold-music |

### Advanced

| Purpose | Common Parameters |
|---------|-------------------|
| Expert settings | debug, sip-trace, nonce-ttl |

---

## 5. Common Settings Reference

### Essential Parameters

| Parameter | Default | Description |
|-----------|---------|-------------|
| **context** | default | Dialplan context |
| **sip-port** | 5060 | SIP UDP/TCP port |
| **sip-ip** | auto | Listen IP address |
| **rtp-ip** | auto | RTP media IP |
| **user-agent** | Telephony Server | SIP user agent |

### TLS Settings

| Parameter | Default | Description |
|-----------|---------|-------------|
| **tls** | false | Enable TLS |
| **tls-cert-dir** | | Certificate directory |
| **tls-version** | tlsv1.2 | TLS version |
| **tls-bind-params** | | TLS binding options |
| **ws-binding** | 127.0.0.1:5066 | WebSocket (plain WS) — localhost only for Nginx proxy |
| **wss-binding** | (disabled) | WSS — disabled, TLS handled by Nginx on port 443 |

### NAT Settings

| Parameter | Default | Description |
|-----------|---------|-------------|
| **ext-rtp-ip** | | External RTP IP |
| **ext-sip-ip** | | External SIP IP |
| **local-network-acl** | | Local network ACL |
| **NDLB-force-rport** | | Force rport |

### Timeout Settings

| Parameter | Default | Description |
|-----------|---------|-------------|
| **rtp-timeout-sec** | 300 | RTP inactivity timeout |
| **rtp-hold-timeout-sec** | 1800 | Hold timeout |
| **session-timeout** | 1800 | Session timeout |

---

## 6. Common Scenarios & Examples

### Scenario 1: Enable TLS

1. Edit SIP profile
2. Expand "Transport (SIP/TLS)"
3. Set tls = true
4. Configure tls-cert-dir
5. Save and reload

### Scenario 2: Configure NAT for Cloud

1. Edit profile
2. Expand "NAT / ACL"
3. Set ext-rtp-ip = public IP
4. Set ext-sip-ip = public IP
5. Save and reload

### Scenario 3: Change SIP Port

1. Edit profile
2. Expand "Transport"
3. Change sip-port
4. Save and reload

### Scenario 4: Enable Debug

1. Edit profile
2. Expand "Advanced"
3. Set debug = true
4. Save and reload
5. Check logs

### Scenario 5: WebRTC Configuration

WebRTC uses Nginx as a TLS proxy to Telephony Server:

```
Browser → wss://domain/ws (Nginx, port 443)
       → ws://127.0.0.1:5066 (Telephony Server, plain WS)
```

1. Edit **internal** profile
2. Expand "Transport (SIP/TLS)"
3. Set `ws-binding` = `127.0.0.1:5066` (localhost only)
4. Disable `wss-binding` (Nginx handles TLS termination)
5. Save and reload

> [!NOTE]
> No TLS certificates are needed on Telephony Server for WebRTC. Nginx handles all WSS connections on port 443 and forwards them as plain WebSocket to Telephony Server on localhost.

---

## 7. Limitations & Important Notes

### Technical Notes

> [!NOTE]
> **Profile Restart**: Changes require `sofia profile <name> restart`.

> [!NOTE]
> **Two Profiles**: Typically "internal" and "external" profiles.

> [!WARNING]
> **TLS Certificates**: Must be valid and accessible.

### Best Practices

1. **Backup First**: Export profile before major changes
2. **Test Changes**: Use debug mode
3. **Document Changes**: Track what you modified
4. **Monitor After**: Watch for registration issues
5. **Use Defaults**: Only change what you need

### Common Profiles

| Profile | Purpose |
|---------|---------|
| **internal** | Extensions, internal devices |
| **external** | Gateways, trunks |
| **secure** | TLS-only connections |

---

## 8. Troubleshooting Tips

### Common Issues

| Symptom | Possible Cause | Solution |
|---------|---------------|----------|
| No registrations | Wrong SIP port | Check sip-port setting |
| One-way audio | NAT issues | Configure ext-rtp-ip |
| TLS fails | Bad certificates | Check tls-cert-dir |
| Timeouts | Short timeout values | Increase rtp-timeout-sec |
| Auth failures | Wrong challenge-realm | Check security settings |

### Diagnostic Commands

**Telephony Server CLI:**
```bash
# Show profile status
fs_cli -x "sofia status profile internal"

# View profile settings
fs_cli -x "sofia profile internal gwlist"

# Restart profile
fs_cli -x "sofia profile internal restart reloadxml"

# Enable SIP trace
fs_cli -x "sofia profile internal siptrace on"
```

### Check Profile Settings

```sql
SELECT 
  sp.name,
  sps.setting_name,
  sps.setting_value
FROM public.sip_profiles sp
JOIN public.sip_profile_settings sps ON sp.id = sps.sip_profile_id
WHERE sp.name = 'internal';
```

---

## 9. Glossary

| Term | Definition |
|------|------------|
| **SIP Profile** | Telephony Server SIP endpoint configuration |
| **mod_sofia** | Telephony Server SIP module |
| **TLS** | Transport Layer Security |
| **NAT** | Network Address Translation |
| **RTP** | Real-time Transport Protocol |
| **ACL** | Access Control List |
| **ext-rtp-ip** | External RTP IP for NAT |

---

## Model Context Protocol (MCP) AI Integration

The Ring2All PBX platform integrates deep AI assistance via the Model Context Protocol (MCP). The Sofia SIP technology stack exposes intelligent tools that permit the PBX AI Copilot to safely query profile parameters, inspect real-time SIP engine socket status, and diagnose registration or port binding conflicts.

### Available MCP Tools

| Tool Name | Operation Type | RBAC Risk Level | Description |
|-----------|----------------|-----------------|-------------|
| `list_sip_profiles` | Read / Query | `low` | Lists all base Sofia SIP profiles (e.g. `internal`, `external`) with their IP bindings, SIP ports, TLS bindings, and status. |
| `get_sip_profile_status` | Live Engine Diagnostic | `low` | Retrieves real-time runtime status, SIP URIs, registered endpoints count, and socket metrics directly from Telephony Server CLI (`sofia status profile <name>`). |

### Tool Input Schemas & Parameters

#### 1. `list_sip_profiles`
```json
{
  "name": "list_sip_profiles",
  "description": "List all base Sofia SIP profiles (internal, external, etc.) running on the PBX core engine with bind ports and TLS settings.",
  "inputSchema": {
    "type": "object",
    "properties": {
      "search": {
        "type": "string",
        "description": "Filter profile by name or description (e.g. 'internal', 'external')."
      }
    }
  }
}
```

#### 2. `get_sip_profile_status`
```json
{
  "name": "get_sip_profile_status",
  "description": "Get live runtime status and registration metrics of a Sofia SIP Profile directly from Telephony Server CLI.",
  "inputSchema": {
    "type": "object",
    "properties": {
      "profile": {
        "type": "string",
        "description": "Sofia SIP profile name (e.g. 'internal', 'external')."
      }
    },
    "required": ["profile"]
  }
}
```

### Natural Language Prompts

| User Request | Invoked MCP Tool | Expected AI Response |
|--------------|------------------|----------------------|
| *"Show me all active Sofia SIP profiles and their bind ports."* | `list_sip_profiles` | Returns table of profiles (`internal` on 5060, `external` on 5080) with TLS ports and operational states. |
| *"Check if the internal SIP profile is currently running in Telephony Server."* | `get_sip_profile_status({ profile: "internal" })` | Reports live Telephony Server CLI status, active registrations count, and RTP binding IP. |
| *"Are there any errors on the external SIP trunk profile?"* | `get_sip_profile_status({ profile: "external" })` | Details profile status, external NAT IP, and detects if the socket is bound or in error. |

### Multi-Tenant & Security Safeguards

- **Strict Domain Isolation**: Sofia base profiles operate at the core engine level; access is restricted to authorized administrative tenants and roles.
- **Sanitized Parameter Execution**: Profile names are strictly filtered (`[a-zA-Z0-9_\-]`) before dispatching commands to Telephony Event Socket (ESL), preventing command injection.
- **Read-Only Diagnostics**: Status tools perform diagnostic queries only; destructive profile restarts require elevated Super Admin permissions with explicit confirmation.
- **Audit Logging**: Every AI query into SIP profile telemetry is logged with user ID, tenant ID, and timestamp.

---

*Documentation last updated: January 2026*