Ctrl K
ring2all.com

Telephony Domains Module Documentation

Table of Contents

  1. Module Overview (Technical)
  2. Module Overview (Commercial/Business)
  3. Module Overview (End User/Administrator)
  4. Configuration Sections
  5. Settings Reference
  6. Common Scenarios & Examples
  7. Limitations & Important Notes
  8. Troubleshooting Tips
  9. Glossary

---

1. Module Overview (Technical)

What Are Telephony Domains?

Telephony Domains is a SIP domain management module that configures FreeSWITCH realms for call routing and registration. Each domain defines the SIP namespace, localization settings, TLS certificate binding, and can have aliases for IP-based access.

Architecture

Plaintext
┌─────────────────────────────────────────────────────────────────┐
│             Telephony Domains Architecture                     │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│  Domain Definition                                              │
│  ┌──────────────────────────────────────────────────────────┐   │
│  │        Domain: pbx.company.com                           │   │
│  │                                                          │   │
│  │  Configuration:                                          │   │
│  │  ├─ Tenant: Acme Corporation                            │   │
│  │  ├─ Language: English                                   │   │
│  │  ├─ Timezone: America/New_York                          │   │
│  │  ├─ Country Code: +1 (US)                               │   │
│  │  ├─ TLS Certificate: Production SSL                     │   │
│  │  └─ Status: Enabled                                      │   │
│  │                                                          │   │
│  │  Aliases:                                                │   │
│  │  ├─ 192.168.1.100                                       │   │
│  │  └─ sip.company.local                                   │   │
│  │                                                          │   │
│  └──────────────────────────────────────────────────────────┘   │
│       │                                                         │
│       ▼ Applied to FreeSWITCH                                  │
│  ┌──────────────────────────────────────────────────────────┐   │
│  │        FreeSWITCH Domain Context                         │   │
│  │                                                          │   │
│  │  SIP Registration:                                       │   │
│  │  ├─ user@pbx.company.com                                │   │
│  │  ├─ user@192.168.1.100 (alias)                          │   │
│  │  └─ user@sip.company.local (alias)                      │   │
│  │                                                          │   │
│  │  Dialplan Context: pbx.company.com                      │   │
│  │  Voice Prompts: English                                  │   │
│  │  Call Logs: America/New_York timezone                   │   │
│  │                                                          │   │
│  └──────────────────────────────────────────────────────────┘   │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘

Key Tables

TablePurpose
telephony.domainsDomain records
telephony.domain_aliasesAlias mappings

Key Files

FileDescription
modules/telephonyDomains/Frontend module
FreeSWITCH directoryDomain XML config
---

2. Module Overview (Commercial/Business)

Business Value

Telephony Domains provides SIP namespace management:

Without DomainsWith Domains
Single realmMultiple realms
Fixed settingsPer-domain config
No localizationVoice language
No SSL/TLSCertificate binding

Use Cases

  1. Multi-Tenant Telephony

- Separate SIP realms

- Tenant isolation

  1. Localization

- Voice prompts language

- Timezone for logs

  1. IP-Based Registration

- Domain aliases

- LAN registrations

  1. HTTPS/TLS

- Certificate binding

- Secure web access

Feature Highlights

FeatureBenefit
SIP DomainUnique realm
Tenant BindingMulti-tenant
Voice LanguageLocalized prompts
TimezoneAccurate timestamps
TLS CertificateHTTPS security
AliasesIP-based access
---

3. Module Overview (End User/Administrator)

What Can You Do?

  • Create SIP domains
  • Assign domains to tenants
  • Set voice language
  • Configure timezone
  • Bind TLS certificates
  • Add domain aliases
  • Apply SSL configuration
  • Enable/disable domains

Telephony Domains Interface

Plaintext
┌─────────────────────────────────────────────────────────────────┐
│              Telephony Domains                                  │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│  [+ Create Domain]  [Apply SSL Configuration]                   │
│                                                                 │
│  [🔍 Search domains...]                                         │
│                                                                 │
│  ┌───────────────────────────────────────────────────────────┐  │
│  │ Domain Name       │ Tenant    │ Language │ Status│ Primary│ │
│  ├───────────────────┼───────────┼──────────┼───────┼────────┤ │
│  │ main.local ⭐     │ Main      │ English  │ ●     │ ⭐     │ │
│  │ pbx.company.com   │ Acme Corp │ English  │ ●     │        │ │
│  │ pbx.europe.com    │ Beta Inc  │ Spanish  │ ●     │        │ │
│  │ test.local        │ Test      │ English  │ ○     │        │ │
│  └───────────────────────────────────────────────────────────┘  │
│                                                                 │
│  ⭐ = Primary Domain (cannot be deleted)                        │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘

Create/Edit Domain

Plaintext
┌─────────────────────────────────────────────────────────────────┐
│              Edit Domain: pbx.company.com                       │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│  Domain Name: [pbx.company.com               ]                 │
│    Unique SIP domain (realm) for registration and routing      │
│                                                                 │
│  Description: [Company headquarters PBX      ]                 │
│    Brief description for identification                         │
│                                                                 │
│  Tenant: [Acme Corporation ▼]                                  │
│    Select the tenant that owns this domain                      │
│                                                                 │
│  Enabled: ✓                                                    │
│    Enables or disables this domain and all related dialplans   │
│                                                                 │
│  ──────────────────────────────────────────────────────────────│
│                                                                 │
│  Default Language: [English ▼]                                 │
│    Language for voice prompts, announcements, and voicemail    │
│                                                                 │
│  Default Time Zone: [America/New_York ▼]                       │
│    Sets the local time zone for voicemail and call logs        │
│                                                                 │
│  Default Country Code: [+1 (United States) ▼]                  │
│    Used for caller ID and dialing normalization (E.164)        │
│                                                                 │
│  ──────────────────────────────────────────────────────────────│
│                                                                 │
│  TLS Certificate: [Production SSL ▼]                           │
│    TLS certificate for HTTPS and secure services               │
│    (Certificates are created in the Certificates module)       │
│                                                                 │
│  ──────────────────────────────────────────────────────────────│
│                                                                 │
│  ▼ Domain Aliases                                               │
│                                                                 │
│  [+ Add Alias]                                                  │
│                                                                 │
│  ┌───────────────────────────────────────────────────────────┐  │
│  │ Alias             │ Description      │ Status │ Actions  │  │
│  ├───────────────────┼──────────────────┼────────┼──────────┤  │
│  │ 192.168.1.100     │ LAN IP address   │ Active │ [✏️] [🗑️] │  │
│  │ sip.company.local │ Internal DNS     │ Active │ [✏️] [🗑️] │  │
│  └───────────────────────────────────────────────────────────┘  │
│                                                                 │
│  [Save] [Cancel]                                                │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘

Add Alias Modal

Plaintext
┌─────────────────────────────────────────────────────────────────┐
│              Add Alias                                          │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│  Alias: [192.168.1.100                       ]                 │
│    e.g., 192.168.10.17                                          │
│                                                                 │
│  Description: [Server LAN IP                 ]                 │
│    Optional description                                         │
│                                                                 │
│  [Add] [Cancel]                                                 │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘

Quick Tips

TIP
Aliases: Add IP addresses for phones that register by IP.
TIP
Apply SSL: Click "Apply SSL Configuration" after certificate changes.
WARNING
Primary Domain: Cannot be deleted.

---

4. Configuration Sections

Domain Configuration

FieldDescription
Domain NameSIP realm (unique)
DescriptionOptional notes
TenantOwner tenant
EnabledActive/Inactive

Localization

FieldDescription
Default LanguageVoice prompt language
Default Time ZoneTimestamp timezone
Default Country CodeE.164 normalization

Security

FieldDescription
TLS CertificateHTTPS/SIP TLS certificate

Domain Aliases

FieldDescription
AliasAlternative name/IP
DescriptionAlias purpose

Why Domain Aliases Matter

When a SIP client (phone, softphone, or gateway) registers with FreeSWITCH, it sends the domain name in the SIP To header and the Request-URI. FreeSWITCH must recognize this domain to route the registration correctly.

The Problem: Many SIP devices register using the server's IP address instead of the domain name:
  • IP phones often default to the server's IP address
  • Legacy devices may not support DNS resolution
  • LAN environments often use IP-based configuration

The Solution: Domain Aliases allow you to map alternative names (IP addresses, internal hostnames, etc.) to a single domain. When FreeSWITCH receives a registration to an alias, it treats it as if it were sent to the main domain.

How Aliases Work in FreeSWITCH

Plaintext
┌────────────────────────────────────────────────────────────────────┐
│                     SIP Registration Flow                          │
├────────────────────────────────────────────────────────────────────┤
│                                                                    │
│  Phone 1:   REGISTER -> pbx.company.com    ─┐                     │
│                                              │                     │
│  Phone 2:   REGISTER -> 192.168.10.17      ───> Same Domain       │
│                                              │   Context!          │
│  Phone 3:   REGISTER -> sip.company.local  ─┘                     │
│                                                                    │
│  FreeSWITCH domain.xml:                                            │
│  ┌──────────────────────────────────────────────────────────────┐ │
│  │ <domain name="pbx.company.com">                               │ │
│  │   <params>                                                    │ │
│  │     <param name="alias" value="192.168.10.17" />              │ │
│  │     <param name="alias" value="sip.company.local" />          │ │
│  │   </params>                                                   │ │
│  │ </domain>                                                     │ │
│  └──────────────────────────────────────────────────────────────┘ │
│                                                                    │
└────────────────────────────────────────────────────────────────────┘

Common Alias Use Cases

Use CaseAlias ValueDescription
LAN IP Registration192.168.10.17Phones configured with server IP
Public IP203.0.113.50External registrations by IP
Internal DNSsip.company.localInternal hostname
Legacy Supportpbx.internalOld device configurations
Multi-NIC Server10.0.0.1Secondary network interface

Best Practices for Aliases

TIP
Add the server's IP address as an alias. Most phones default to IP-based registration.
TIP
Add all network interfaces if your server has multiple NICs.
WARNING
Avoid duplicate aliases across domains. Each alias must map to exactly one domain.
NOTE
Aliases are case-insensitive. 192.168.10.17 and 192.168.10.17 are treated the same.

---

5. Settings Reference

Common Domain Formats

FormatExampleUse Case
FQDNpbx.company.comPublic access
Internalcompany.localLAN only
IP-based192.168.1.100Direct IP

Voice Languages

LanguageCodeRegion
Englishen-USNorth America
Spanishes-ESSpain
Spanishes-MXLatin America
Frenchfr-FRFrance
Germande-DEGermany
Portuguesept-BRBrazil

Country Codes

CountryCodeFormat
United States+1+1XXXXXXXXXX
United Kingdom+44+44XXXXXXXXXX
Germany+49+49XXXXXXXXXX
Spain+34+34XXXXXXXXX
Mexico+52+52XXXXXXXXXX
---

6. Common Scenarios & Examples

Scenario 1: Create Production Domain

  1. Click Create Domain
  2. Domain Name = pbx.company.com
  3. Select tenant
  4. Enable = ✓
  5. Set language, timezone, country
  6. Select TLS certificate
  7. Save

Scenario 2: Add IP Alias

  1. Edit domain
  2. Click Add Alias
  3. Alias = 192.168.1.100
  4. Description = "LAN IP"
  5. Add
  6. Save domain

Scenario 3: Apply SSL Certificate

  1. In Certificates module, create/upload certificate
  2. Edit domain
  3. Select TLS Certificate
  4. Save
  5. Click "Apply SSL Configuration"
  6. Wait for Nginx reload

Scenario 4: Create Regional Domain

  1. Create Domain
  2. Domain Name = pbx.europe.company.com
  3. Language = Spanish (Spain)
  4. Timezone = Europe/Madrid
  5. Country Code = +34
  6. Save

---

7. Limitations & Important Notes

Technical Notes

NOTE
Primary Domain: Cannot be deleted or disabled.
NOTE
Unique Names: Domain names must be unique.
WARNING
Apply SSL: Must click after certificate changes.

Best Practices

  1. Meaningful Names: Use FQDN format
  2. Add Aliases: For IP-based registration
  3. Match Localization: Language + timezone + country
  4. Apply SSL: After any certificate change
  5. Test Registration: Verify SIP access

Domain vs. Tenant

DomainTenant
SIP realmOrganization
FreeSWITCH contextAdmin panel
Multiple per tenantOne per organization
Telephony focusPlatform focus
---

8. Troubleshooting Tips

Common Issues

SymptomPossible CauseSolution
Registration failsWrong domainCheck SIP settings
Alias not workingNot savedSave domain
SSL not appliedNeed reloadClick Apply SSL
Wrong promptsLanguage mismatchSet correct language

Check Domain

Sql
SELECT 
  domain,
  description,
  language,
  timezone,
  is_enabled
FROM telephony.domains
WHERE domain = 'pbx.company.com';

Check Aliases

Sql
SELECT 
  alias,
  description
FROM telephony.domain_aliases
WHERE domain_id = 'domain-uuid';

Test SIP Registration

Bash
# Test domain resolution
nslookup pbx.company.com

# Test SIP port
nc -zv pbx.company.com 5060

# Test TLS port
nc -zv pbx.company.com 5061

---

9. Glossary

TermDefinition
DomainSIP realm/namespace
RealmAuthentication scope
AliasAlternative domain name
FQDNFully Qualified Domain Name
E.164International phone format
ContextFreeSWITCH dialplan scope
---

Lua Script Status ℹ️

Infrastructure Module

ComponentStatus
Telephony Domainsℹ️ SIP domain management - no Lua handler required
Telephony Domains is an infrastructure configuration module. It manages FreeSWITCH domain contexts. No Lua handlers are used - domain configuration is applied to FreeSWITCH by the backend service.

---

Documentation last updated: January 2026
AI Assistant

👋 Hello! I'm your Ring2All documentation assistant. I can help you find information about configuring and using the Ring2All PBX platform.

How can I help you today?