---
title: "ESL Users Module Documentation"
description: "Documentation for ESL Users"
---

## 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 Fields](#4-configuration-fields)
8. [Common Scenarios & Examples](#5-common-scenarios--examples)
9. [Limitations & Important Notes](#6-limitations--important-notes)
10. [Troubleshooting Tips](#7-troubleshooting-tips)
11. [Glossary](#8-glossary)
12. [Model Context Protocol (MCP) AI Integration](#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 Users List](/screenshots/settings/pbx/esl-users-list.png)

### 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.
![ESL User Form](/screenshots/settings/pbx/esl-users-form.png)

---

## 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

```bash
# Connect via telnet
telnet <freeswitchip> 8021

# Authenticate
auth <password>

# Subscribe to events
events plain ALL

# Send command
api status
```

### Check ESL Users

```sql
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`
```json
{
  "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*