ESL Users Module Documentation

Table of Contents

1. Navigation & Access
2. Screenshots & Visual Interface
3. Module Overview (Technical)
4. Module Overview (Commercial/Business)
5. Module Overview (End User/Administrator)
6. User Roles & Key Capabilities
7. Configuration Fields
8. Common Scenarios & Examples
9. Limitations & Important Notes
10. Troubleshooting Tips
11. Glossary
12. Model Context Protocol (MCP) AI Integration

---

Navigation & Access

To access the ESL Users 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 ESL Users (/settings/pbx/esl-users).
4. To provision a new Event Socket Layer client credential, click + Add ESL User (/settings/pbx/esl-users/new). To edit an existing connection, click on the row or the Edit action button.

---

Screenshots & Visual Interface

ESL Users Directory

Directory of Telephony Event Socket Layer programmatic users, showing username, access mode (inbound/outbound), allowed CIDR IP ranges, listening socket IP and port, and default profile indicators.

ESL User Configuration Form

Administrative setup form for securing Event Socket connections, configuring authentication passwords, IP whitelist masks, inbound ACL rules, NAT mapping options, and automatic error handling behaviors.

---

1. Module Overview (Technical)

What Are ESL Users?

ESL Users is a Telephony Event Socket Layer configuration module that manages users who can connect to Telephony Server via the Event Socket interface. ESL provides programmatic access to Telephony Server for sending commands and receiving real-time events.

Architecture

┌─────────────────────────────────────────────────────────────────┐
│                   ESL Users Architecture                       │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│  External Applications                                          │
│  ┌──────────────────────────────────────────────────────────┐   │
│  │  Call Center Dashboard                                   │   │
│  │  Real-time Monitoring                                    │   │
│  │  Custom Integrations                                     │   │
│  │  Third-party CRM                                         │   │
│  └──────────────────────────────────────────────────────────┘   │
│       │ ESL Connection                                         │
│       ▼                                                         │
│  ┌──────────────────────────────────────────────────────────┐   │
│  │        Telephony Event Socket                           │   │
│  │                                                          │   │
│  │  Listen IP: :: (all interfaces)                         │   │
│  │  Listen Port: 8021                                       │   │
│  │                                                          │   │
│  │  Authentication:                                         │   │
│  │  ├─ Username / Password                                 │   │
│  │  ├─ Allowed IP / CIDR Range                             │   │
│  │  └─ ACL Restrictions                                     │   │
│  │                                                          │   │
│  └──────────────────────────────────────────────────────────┘   │
│       │                                                         │
│       ▼ Events & Commands                                      │
│  ┌──────────────────────────────────────────────────────────┐   │
│  │        Telephony Core                                   │   │
│  │                                                          │   │
│  │  Channel Events → ESL Client                            │   │
│  │  Commands ← ESL Client                                   │   │
│  │  API Responses → ESL Client                             │   │
│  │                                                          │   │
│  └──────────────────────────────────────────────────────────┘   │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘

---

2. Module Overview (Commercial/Business)

Business Value

ESL Users provides secure programmatic access:

Without ESL Users	With ESL Users
Single password	Per-user credentials
No IP restriction	IP-based security
All events	Filtered events
No audit trail	User tracking

Use Cases

1. Real-time Dashboards

   • Live call monitoring
   • Queue statistics

2. CRM Integration

   • Click-to-call
   • Screen pops

3. Custom Applications

   • Call recording control
   • IVR automation

4. Third-party Tools

   • Billing systems
   • Reporting tools

Feature Highlights

Feature	Benefit
Per-User Auth	Individual credentials
IP Restrictions	Network security
Access Modes	Inbound/Outbound/Embedded
Event Filters	Limit events received
ACL Support	Telephony Server ACL integration
Enable/Disable	Quick access control

---

3. Module Overview (End User/Administrator)

What Can You Do?

• Create ESL user accounts
• Set username/password credentials
• Configure allowed IP addresses
• Select access mode
• Filter event subscriptions
• Configure listen IP/port
• Enable/disable users

ESL Users Interface

┌─────────────────────────────────────────────────────────────────┐
│              ESL Users                                          │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│  Manage Event Socket Layer users for Telephony Server connections.   │
│                                                                 │
│  [+ Add]                                                        │
│                                                                 │
│  ┌───────────────────────────────────────────────────────────┐  │
│  │ Username    │ Access Mode │ Allowed IP   │ Enabled │ Updated│ │
│  ├─────────────┼─────────────┼──────────────┼─────────┼───────┤  │
│  │ dashboard   │ Inbound     │ 192.168.1.0/24│ ✓      │ 2h ago│  │
│  │ crm-app     │ Inbound     │ 10.0.0.50    │ ✓      │ 1d ago│  │
│  │ billing     │ Inbound     │ 0.0.0.0/0    │ ☐      │ 5d ago│  │
│  └───────────────────────────────────────────────────────────┘  │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘

User Edit View

┌─────────────────────────────────────────────────────────────────┐
│              Edit ESL User                                      │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│  General                                                        │
│                                                                 │
│  Username: [dashboard                      ]                   │
│    ESL login name for Event Socket connection.                  │
│                                                                 │
│  Password: [••••••••••                     ]                   │
│    Leave empty to keep current password.                        │
│                                                                 │
│  Access Mode: [Inbound ▼]                                      │
│    ├─ Inbound (clients connect to Telephony Server)                  │
│    ├─ Outbound (Telephony Server connects to clients)                │
│    └─ Embedded (within Telephony process)                     │
│                                                                 │
│  Allowed IP / Range: [192.168.1.0/24       ]                   │
│    IP address or CIDR range allowed to connect.                 │
│                                                                 │
│  Enabled: ✓                                                     │
│                                                                 │
│  ──────────────────────────────────────────────────────────────│
│                                                                 │
│  Security                                                       │
│                                                                 │
│  Listen IP: [::                           ]                    │
│    IP address where ESL listener binds.                         │
│                                                                 │
│  Listen Port: [8021                       ]                    │
│    Port number used by ESL listener.                            │
│                                                                 │
│  NAT Map: ☐                                                    │
│  Apply Inbound ACL: [default               ]                   │
│  Stop on Bind Error: ✓                                         │
│                                                                 │
│  ──────────────────────────────────────────────────────────────│
│                                                                 │
│  Event Filters: [🔧 Select Telephony Server events ]                 │
│    12 event(s) selected.                                        │
│                                                                 │
│  Description: [Dashboard real-time monitoring]                 │
│                                                                 │
│  [Save] [Cancel]                                                │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘

Quick Tips

[!TIP] IP Restriction: Always restrict IPs in production.

[!TIP] Event Filters: Only subscribe to needed events.

[!WARNING] Security: ESL provides full system access - protect credentials!

---

🎯 User Roles & Key Capabilities

Role	Permissions	Key Capabilities
Super Administrator	Full Access (read, write, delete)	Provision programmatic Event Socket Layer credentials, define network binding ports (8021), and manage master ACL filters.
Integrations / DevOps Engineer	Developer Access (read, write)	Generate dedicated ESL accounts for CRM popups, CTI wallboards, call recording collectors, and Telephony Server event streams.
Security Auditor	Read & Compliance (read)	Verify IP whitelist restrictions (CIDR masks), audit active socket credentials, and ensure no accounts use wildcard 0.0.0.0/0 in production.
Tenant Administrator	Restricted Read	View tenant-assigned ESL socket users in multi-tenant environments.

---

4. Configuration Fields

General Section

Field	Description
Username	ESL login name (unique)
Password	Authentication password
Access Mode	Inbound, Outbound, Embedded
Allowed IP / Range	CIDR or specific IP
Enabled	Account active/inactive

Security Section

Field	Description
Listen IP	Bind address (:: = all)
Listen Port	ESL port (default 8021)
NAT Map	Enable NAT mapping
Apply Inbound ACL	Telephony Server ACL name
Stop on Bind Error	Fail if port unavailable

Metadata Section

Field	Description
Event Filters	Telephony Server events to receive
Description	Purpose notes

Access Modes

Mode	Description
Inbound	Clients connect to Telephony Server
Outbound	Telephony Server connects to external server
Embedded	Within Telephony process

---

5. Common Scenarios & Examples

Scenario 1: Dashboard User

1. Create new ESL user
2. Username = dashboard
3. Set secure password
4. Allowed IP = dashboard server IP
5. Access Mode = Inbound
6. Select events: CHANNEL_ANSWER, CHANNEL_HANGUP
7. Enable and save

Scenario 2: CRM Integration

1. Create new ESL user
2. Username = crm-app
3. Access Mode = Inbound
4. Allowed IP = CRM server IP/24
5. Event Filters = CHANNEL_CREATE, CHANNEL_CALLER_ID
6. Enable and save

Scenario 3: Development User

1. Create new ESL user
2. Username = dev-test
3. Allowed IP = 0.0.0.0/0 (open for dev)
4. Event Filters = All events
5. Save but keep Disabled until needed

Scenario 4: Restricted Admin

1. Create new ESL user
2. Username = esl-admin
3. Allowed IP = specific admin workstation
4. Access Mode = Inbound
5. Apply Inbound ACL = admin-acl
6. Enable and save

---

6. Limitations & Important Notes

Technical Notes

[!NOTE] Default Port: ESL uses port 8021 by default.

[!NOTE] Generate XML: ESL config generates event_socket.conf.xml.

[!WARNING] Security Critical: ESL provides full Telephony Server control.

Best Practices

1. Unique Usernames: One per application
2. Strong Passwords: Use complex passwords
3. IP Restrictions: Always restrict in production
4. Minimal Events: Only subscribe to needed events
5. Disable Unused: Keep unused accounts disabled
6. Monitor Access: Review ESL connections regularly

Common Event Filters

Event	Purpose
CHANNEL_CREATE	New call started
CHANNEL_ANSWER	Call answered
CHANNEL_HANGUP	Call ended
CHANNEL_BRIDGE	Calls connected
DTMF	Key presses
RECORD_START	Recording began
RECORD_STOP	Recording ended

---

7. Troubleshooting Tips

Common Issues

Symptom	Possible Cause	Solution
Connection refused	Port blocked	Check firewall
Auth failed	Wrong password	Verify credentials
Connection denied	IP not allowed	Check Allowed IP
No events	Filters too strict	Add event filters
Already in use	Port conflict	Change Listen Port

Test ESL Connection

# Connect via telnet
telnet <freeswitchip> 8021

# Authenticate
auth <password>

# Subscribe to events
events plain ALL

# Send command
api status

Check ESL Users

SELECT
  username,
  access_mode,
  allowed_ip,
  enabled
FROM public.esl_users
WHERE enabled = true;

---

8. Glossary

Term	Definition
ESL	Event Socket Layer
Inbound	Clients connect to FS
Outbound	FS connects to clients
ACL	Access Control List
CIDR	IP range notation
Event Filter	Subscribed event types
Listen Port	ESL connection port

---

Model Context Protocol (MCP) AI Integration

The Ring2All PBX platform integrates deep AI assistance via the Model Context Protocol (MCP). The ESL Users module allows the PBX AI Copilot to query configured Event Socket users, inspect IP whitelist masks, and audit CTI integrations for security compliance.

Available MCP Tools

Tool Name	Operation Type	RBAC Risk Level	Description
list_esl_users	Read / Query	low	Lists Event Socket Layer (ESL) authenticated users, network ACLs, and permission levels with passwords securely masked.

Tool Input Schemas & Parameters

1. list_esl_users

{
  "name": "list_esl_users",
  "description": "List Event Socket Layer (ESL) authenticated users, network ACLs, and permission levels for external CTI / Telephony Server socket integrations.",
  "inputSchema": {
    "type": "object",
    "properties": {
      "search": {
        "type": "string",
        "description": "Filter ESL users by username or allowed IP."
      }
    }
  }
}

Natural Language Prompts

User Request	Invoked MCP Tool	Expected AI Response
“List all Event Socket Layer (ESL) accounts configured in the system.”	list_esl_users	Returns list of ESL accounts with allowed CIDRs and account status (passwords redacted).
“Is there an ESL user provisioned for our CRM wallboard?”	list_esl_users({ search: "wallboard" })	Checks matching user credentials and reports allowed connection IP range.
“Audit ESL accounts for insecure open IP configurations.”	list_esl_users	Identifies accounts with unrestricted IP masks and warns about security exposure.

Multi-Tenant & Security Safeguards

• Domain Isolation: ESL accounts are scoped strictly to the requesting tenant’s domain ID.
• Strict Password Redaction: Authentication passwords are encrypted and never returned in plaintext in tool results.
• CIDR Mask Enforcement: ESL accounts must have explicit IP subnet masks defined before connection is accepted by the daemon.
• Audit Logging: All ESL user queries and credential modifications are logged with administrator ID and timestamp.

---

Documentation last updated: January 2026