Ctrl K
ring2all.com

Gateways Module Documentation

Table of Contents

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

---

1. Module Overview (Technical)

What Are Gateways?

Gateways define SIP trunk connections to external carriers, ITSPs, or other PBX systems. Each gateway represents a configured connection with authentication, registration, and routing settings.

Architecture

Plaintext
┌─────────────────────────────────────────────────────────────────┐
│                    Gateway System                               │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│  Gateway SIP Profile: "Standard Carrier"                        │
│  ┌────────────────────────────────────────────────────────────┐ │
│  │ Transport: UDP   │ DTMF: RFC2833   │ Codec: G711, G729    │ │
│  │ NAT: Enabled     │ TLS: Disabled   │ Media: Proxy         │ │
│  └────────────────────────────────────────────────────────────┘ │
│                          │                                      │
│            Assigned to Gateways:                                │
│                          │                                      │
│  ┌──────────────────┐    │    ┌──────────────────┐              │
│  │ Gateway: CarrierA│    │    │ Gateway: CarrierB│              │
│  │ Proxy: sip.a.com │◄───┼────▶ Proxy: sip.b.com │              │
│  │ Username: user1  │    │    │ Username: user2  │              │
│  │ Register: Yes    │    │    │ Register: Yes    │              │
│  │ Channels: 30     │    │    │ Channels: 20     │              │
│  │ Failover: B      │    │    │ Failover: None   │              │
│  └──────────────────┘         └──────────────────┘              │
│                                                                 │
│  Used by:                                                       │
│  ├─ Outbound Routes (dial patterns → gateway selection)        │
│  ├─ Inbound Routes (gateway → destination1)                    │
│  └─ ARS Profiles (time-based gateway selection)                │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘

Key Tables

TablePurpose
public.sip_gatewaysGateway definitions
public.gateway_sip_profilesShared profile settings
public.gateway_settingsPer-gateway settings

Key Files

FileDescription
admin/apps/web/src/modules/gateways/Gateway frontend
admin/apps/web/src/modules/gatewaySipProfiles/SIP Profiles frontend
admin/apps/web/src/i18n/en/gateways.jsonGateway translations
admin/apps/web/src/i18n/en/gatewaySipProfiles.jsonProfile translations

Integration with FreeSWITCH

Gateways are translated into FreeSWITCH XML configuration:

Xml
<gateway name="carrier_a">
  <param name="username" value="user1"/>
  <param name="password" value="secret"/>
  <param name="proxy" value="sip.carrier-a.com"/>
  <param name="register" value="true"/>
  ...
</gateway>

---

2. Module Overview (Commercial/Business)

Business Value

Gateways enable external telephony connectivity:

Without GatewaysWith Gateways
Internal calls onlyExternal PSTN/SIP calls
No carrier integrationMultiple carrier support
No failoverAutomatic failover
Single pathLoad balancing

Use Cases

  1. PSTN Connectivity

- Connect to telco carriers

- Terminate calls to phone numbers

  1. SIP Trunking

- Connect to VoIP providers

- Cost-effective calling

  1. Multi-Carrier Routing

- Primary/backup carriers

- Least-cost routing

  1. PBX Interconnection

- Connect branch offices

- Legacy system integration

Feature Highlights

FeatureBenefit
Gateway SIP ProfilesReusable carrier settings
RegistrationDynamic registration with carriers
AuthenticationUsername/password, realm support
NAT TraversalWorks behind firewalls
FailoverAutomatic backup gateway
Channel LimitsConcurrent call control
Codec SelectionAudio/video codec preference
TLS/SRTPSecure signaling and media
---

3. Module Overview (End User/Administrator)

What Can You Do?

Gateways:
  • Create SIP trunk connections
  • Configure authentication
  • Set registration parameters
  • Define channel limits
  • Configure failover cascades

Gateway SIP Profiles:
  • Create reusable settings templates
  • Configure transport and codecs
  • Set NAT/security options
  • Apply to multiple gateways

Administrator Workflow

Plaintext
┌─────────────────────────────────────────────────────────────────┐
│              Creating a Gateway                                 │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│  Basic Information                                              │
│  ├─ Gateway Name: "carrier_main"                               │
│  ├─ Description: "Primary VoIP Carrier"                        │
│  ├─ Gateway SIP Profile: Standard Carrier                      │
│  └─ Enabled: ✓                                                 │
│                                                                 │
│  Authentication & Connection                                    │
│  ├─ Proxy: sip.carrier.com                                     │
│  ├─ Username: account123                                       │
│  ├─ Password: ●●●●●●●●                                         │
│  └─ Realm: carrier.com                                         │
│                                                                 │
│  Registration & Keepalive                                       │
│  ├─ Register: ✓                                                │
│  ├─ Expire Seconds: 3600                                       │
│  ├─ Retry Seconds: 30                                          │
│  └─ Ping Interval: 25                                          │
│                                                                 │
│  Routing & Limits                                               │
│  ├─ Context: public                                            │
│  ├─ Max Channels: 30                                           │
│  └─ Failover Gateway: carrier_backup                           │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘

Quick Tips

TIP
Use SIP Profiles: Create profiles for common carrier types to reuse settings.
TIP
Set Failover: Always configure a backup gateway for reliability.
CAUTION
Channel Limits: Set realistic limits to prevent carrier billing surprises.

---

4. Configuration Fields Reference

Gateway Fields

Basic Information

FieldDescriptionExample
Gateway NameUnique identifiercarrier_main
DescriptionOptional descriptionPrimary VoIP Carrier
Gateway SIP ProfileInherited settingsStandard Carrier
Dial ProfileReusable template to apply call variables and behaviorsOffice Default
EnabledGateway active statusOn/Off

Authentication & Connection

FieldDescriptionExample
ProxyCarrier SIP addresssip.carrier.com
UsernameSIP authentication useraccount123
PasswordSIP password●●●●●●●●
Auth UsernameAlternative auth user(optional)
RealmAuthentication realmcarrier.com
Outbound ProxySeparate signaling path(optional)
Register ProxySeparate registration(optional)
Register TransportUDP/TCP/TLSUDP

Registration & Keepalive

FieldDescriptionDefault
RegisterEnable registrationOn
Expire SecondsRegistration period3600
Retry SecondsRetry on failure30
Ping IntervalOPTIONS ping interval25
Ping Min/MaxUp/down thresholds1/5
Contact in PingInclude Contact headerOff

Media & Overrides

FieldDescription
Audio CodecsPreferred codec list
Video CodecsVideo codec list
Allow VideoEnable video calls
Packetization TimeRTP packet size
T.38 SupportFax relay support

Routing & Limits

FieldDescriptionDefault
ContextInbound dialplan contextpublic
ExtensionDefault inbound extension-
Max ChannelsConcurrent call limit0 (unlimited)
Failover GatewayBackup gatewayNone
---

5. Gateway SIP Profiles

Purpose

Gateway SIP Profiles are reusable configuration templates that define:

  • Transport settings (UDP/TCP/TLS)
  • DTMF mode
  • Codec preferences
  • NAT handling
  • TLS/SRTP security

Profile Sections

Signaling & Transport

FieldOptionsDescription
TransportUDP, TCP, TLSSIP transport
DTMF ModeRFC2833, INFO, InbandDTMF signaling
INVITE Formatuser@domain, E.164URI format
Caller ID PolicyFrom, PAI, RPIDCID header
NAT MappingOn/OffContact rewrite
Register TransportUDP, TCP, TLSRegistration transport

Media & Codecs

FieldDescription
Audio CodecsPCMU, PCMA, G729, G722, OPUS
Video CodecsVP8, H264, H263, AV1
Allow VideoEnable video negotiation
RTP ProxyForce media through PBX
Packetization Time10, 20, 30, 40 ms
T.38 SupportFax relay

Security / TLS

FieldDescription
TLS EnabledEnable TLS signaling
TLS Verify PolicyCertificate verification
TLS VersionMinimum TLS version
SRTP ModeAlways, Optional, Never
Require Secure MediaReject non-SRTP
---

6. Common Scenarios & Examples

Scenario 1: Basic ITSP Connection

Gateway: "voip_carrier"
SettingValue
Proxysip.voip-carrier.com
Username12345678
Password●●●●●●●●
RegisterYes
TransportUDP
CodecsPCMU, PCMA, G729

Scenario 2: Primary + Backup Carriers

Gateway: "carrier_primary"
SettingValue
Proxysip.carrier-a.com
Max Channels30
Failovercarrier_backup
Gateway: "carrier_backup"
SettingValue
Proxysip.carrier-b.com
Max Channels20
FailoverNone

Scenario 3: Secure TLS Trunk

Gateway SIP Profile: "Secure Carrier"
SettingValue
TransportTLS
TLS Version1.2
TLS VerifyPeer
SRTP ModeAlways
Gateway: "secure_trunk"
SettingValue
Gateway SIP ProfileSecure Carrier
Proxysips.carrier.com:5061
---

7. Limitations & Important Notes

Technical Notes

NOTE
Configuration Module: Gateways are configuration entities. Settings are translated to FreeSWITCH XML by the configuration generator.
WARNING
Reload Required: Gateway changes require FreeSWITCH sofia profile reload.
WARNING
NAT Considerations: Enable NAT mapping when PBX is behind firewall.

Best Practices

  1. Use Profiles: Create profiles for common carrier types
  2. Set Channel Limits: Prevent unexpected charges
  3. Configure Failover: Always have a backup
  4. Test Registration: Verify gateway registers successfully
  5. Monitor Status: Check gateway status regularly
  6. Secure Credentials: Use strong passwords

---

8. Troubleshooting Tips

Common Issues

SymptomPossible CauseSolution
Not registeredWrong credentialsVerify username/password
Registration timeoutFirewall blockingCheck ports 5060/5061
Calls failWrong proxyVerify proxy address
One-way audioNAT issueEnable NAT mapping
No audioCodec mismatchCheck codec preferences
TLS errorsCertificate issueVerify TLS settings

FreeSWITCH Commands

Bash
# List all sofia profiles
sofia status

# Show gateway status
sofia status gateway carrier_main

# Reload gateway
sofia profile external restart gateway carrier_main

# Kill gateway registration
sofia profile external killgw carrier_main

# Show registrations
sofia status profile external reg

Diagnostic SQL

List gateways:

Sql
SELECT id, name, proxy, username, enabled, register
FROM public.sip_gateways
ORDER BY name;

Check gateway settings:

Sql
SELECT g.name, s.name as setting, s.value
FROM public.sip_gateways g
JOIN public.gateway_settings s ON g.id = s.gateway_id
WHERE g.name = 'carrier_main';

---

9. Glossary

TermDefinition
GatewaySIP trunk connection to external carrier
SIP ProfileReusable configuration template
RegistrationProcess of registering with carrier
ProxyCarrier's SIP server address
RealmAuthentication domain
FailoverAutomatic switch to backup gateway
ITSPInternet Telephony Service Provider
NATNetwork Address Translation
SRTPSecure Real-time Transport Protocol
---

Lua Handler Status

⚡ No Dedicated Handler Required

Gateways are configuration entities:

  • Stored in public.sip_gateways, public.gateway_sip_profiles
  • Translated to FreeSWITCH XML by configuration generator
  • Used by outbound/inbound routes for call routing

No Lua fixes needed!

---

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?