ESL Users Module Documentation

Module Overview (Technical)
Module Overview (Commercial/Business)
Module Overview (End User/Administrator)
Configuration Fields
Common Scenarios & Examples
Limitations & Important Notes
Troubleshooting Tips
Glossary

---

1. Module Overview (Technical)

What Are ESL Users?

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

Architecture

Plaintext

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

Key Tables

Table	Purpose
`public.esl_users`	ESL user credentials and settings

Key Files

File	Description
`modules/eslUsers/`	Frontend module
FreeSWITCH event_socket.conf.xml	Generated configuration

---

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

Real-time Dashboards

- Live call monitoring

- Queue statistics

CRM Integration

- Click-to-call

- Screen pops

Custom Applications

- Call recording control

- IVR automation

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

Plaintext

┌─────────────────────────────────────────────────────────────────┐
│              ESL Users                                          │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│  Manage Event Socket Layer users for FreeSWITCH 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

Plaintext

┌─────────────────────────────────────────────────────────────────┐
│              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 FreeSWITCH)                  │
│    ├─ Outbound (FreeSWITCH connects to clients)                │
│    └─ Embedded (within FreeSWITCH 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 FreeSWITCH 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!

---

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	FreeSWITCH ACL name
Stop on Bind Error	Fail if port unavailable

Metadata Section

Field	Description
Event Filters	FreeSWITCH events to receive
Description	Purpose notes

Access Modes

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

---

5. Common Scenarios & Examples

Scenario 1: Dashboard User

Create new ESL user
Username = dashboard
Set secure password
Allowed IP = dashboard server IP
Access Mode = Inbound
Select events: CHANNEL_ANSWER, CHANNEL_HANGUP
Enable and save

Scenario 2: CRM Integration

Create new ESL user
Username = crm-app
Access Mode = Inbound
Allowed IP = CRM server IP/24
Event Filters = CHANNEL_CREATE, CHANNEL_CALLER_ID
Enable and save

Scenario 3: Development User

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

Scenario 4: Restricted Admin

Create new ESL user
Username = esl-admin
Allowed IP = specific admin workstation
Access Mode = Inbound
Apply Inbound ACL = admin-acl
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 FreeSWITCH control.

Best Practices

Unique Usernames: One per application
Strong Passwords: Use complex passwords
IP Restrictions: Always restrict in production
Minimal Events: Only subscribe to needed events
Disable Unused: Keep unused accounts disabled
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

---

Lua Script Status ℹ️

Configuration Module

Component	Status
ESL Users	ℹ️ Configuration module - generates event_socket.conf.xml

ESL Users is a configuration module. Settings are stored and used to generate FreeSWITCH Event Socket configuration. No Lua handlers are used.

---

Documentation last updated: January 2026

ESL Users Module Documentation

Table of Contents

1. Module Overview (Technical)

What Are ESL Users?

Architecture

Key Tables

Key Files

2. Module Overview (Commercial/Business)

Business Value

Use Cases

Feature Highlights

3. Module Overview (End User/Administrator)

What Can You Do?

ESL Users Interface

User Edit View

Quick Tips

4. Configuration Fields

General Section

Security Section

Metadata Section

Access Modes

5. Common Scenarios & Examples

Scenario 1: Dashboard User

Scenario 2: CRM Integration

Scenario 3: Development User

Scenario 4: Restricted Admin

6. Limitations & Important Notes

Technical Notes

Best Practices

Common Event Filters

7. Troubleshooting Tips

Common Issues

Test ESL Connection

Check ESL Users

8. Glossary

Lua Script Status ℹ️

Configuration Module