Ctrl K
ring2all.com

PBX CLI Module Documentation

Table of Contents

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

---

1. Module Overview (Technical)

What Is PBX CLI?

PBX CLI is a web-based terminal interface that provides remote access to the FreeSWITCH CLI (fs_cli) and system commands directly from the admin panel. It includes customizable quick-access buttons for common commands.

Architecture

Plaintext
┌─────────────────────────────────────────────────────────────────┐
│                      PBX CLI Architecture                       │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│  Admin Browser                         PBX Server               │
│  ┌────────────────┐                   ┌────────────────────┐   │
│  │  PBX CLI UI    │◄───WebSocket────►│  Backend API       │   │
│  │                │                   │  ┌────────────────┐│   │
│  │  ┌──────────┐  │                   │  │  SSH/Process   ││   │
│  │  │ Terminal │  │                   │  │  Executor      ││   │
│  │  └──────────┘  │                   │  └───────┬────────┘│   │
│  │                │                   │          │         │   │
│  │  Quick Buttons │                   │          ▼         │   │
│  │  [Status]      │                   │  ┌────────────────┐│   │
│  │  [Channels]    │                   │  │  FreeSWITCH    ││   │
│  │  [Calls]       │                   │  │  fs_cli        ││   │
│  │  [Reload XML]  │                   │  └────────────────┘│   │
│  │                │                   │                     │   │
│  └────────────────┘                   └────────────────────┘   │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘

Key Features

FeatureDescription
Web TerminalBrowser-based CLI access
WebSocketReal-time command/response
Quick ButtonsCustomizable command shortcuts
Command HistoryNavigate with up/down arrows
Tab CompletionAuto-complete commands

Key Tables

TablePurpose
public.pbx_cli_button_configsCustom button configurations

Key Files

FileDescription
admin/apps/web/src/modules/pbxCli/Frontend module
admin/apps/web/src/i18n/en/pbxCli.jsonTranslations
---

2. Module Overview (Commercial/Business)

Business Value

PBX CLI provides remote system administration:

Without PBX CLIWith PBX CLI
SSH requiredBrowser access
Command-line onlyVisual terminal
Manual commandsQuick buttons
No shortcutsCustomizable buttons

Use Cases

  1. System Monitoring

- Check FreeSWITCH status

- View active calls and channels

  1. Configuration Management

- Reload XML dialplan

- List loaded modules

  1. Troubleshooting

- View logs in real-time

- Enable SIP tracing

  1. Quick Diagnostics

- Sofia status

- Active media bugs

Feature Highlights

FeatureBenefit
Browser-BasedNo SSH client needed
Quick ButtonsOne-click commands
Custom ButtonsTenant-specific shortcuts
Live OutputReal-time command results
Log TailingFollow logs in browser
---

3. Module Overview (End User/Administrator)

What Can You Do?

  • Execute FreeSWITCH CLI commands
  • Run system commands
  • Use quick-access buttons
  • Configure custom buttons
  • Navigate command history
  • View real-time logs

Administrator Interface

Plaintext
┌─────────────────────────────────────────────────────────────────┐
│                       PBX CLI Terminal                          │
├─────────────────────────────────────────────────────────────────┤
│  [Status] [Sofia Status] [Show Channels] [Show Calls]           │
│  [Reload XML] [Modules List] [Tail Log] [Edit Buttons]          │
├─────────────────────────────────────────────────────────────────┤
│  ┌──────────────────────────────────────────────────────────┐   │
│  │ $ fs_cli -x "status"                                     │   │
│  │                                                          │   │
│  │ FreeSWITCH (Version 1.10.11 -release 64bit) is ready     │   │
│  │ - UP 5 years, 2 days, 3 hours, 45 minutes, 12 seconds    │   │
│  │ - FreeSWITCH is ready                                    │   │
│  │ - 47 session(s) since startup                            │   │
│  │ - 2 session(s) - peak 15, last 5min 3                    │   │
│  │ - 0 session(s) per Sec out of max 30, peak 12            │   │
│  │ - 2 session(s) max                                       │   │
│  │ - min idle cpu 0.00/99.85                                │   │
│  │                                                          │   │
│  │ $ _                                                      │   │
│  │                                                          │   │
│  └──────────────────────────────────────────────────────────┘   │
│  ● Connected                                    [Help] [Clear]  │
└─────────────────────────────────────────────────────────────────┘

Quick Tips

TIP
Arrow Keys: Use Up/Down to navigate command history.
TIP
Tab Completion: Press Tab for command autocomplete.
CAUTION
Sensitive Commands: Be careful with commands that modify system state.

---

4. Terminal Commands Reference

System & Core Commands

CommandDescription
fs_cli -x "status"FreeSWITCH system status
fs_cli -x "version"Build version and libraries
fs_cli -x "uptime"How long FreeSWITCH running
fs_cli -x "modules list"List loaded modules
fs_cli -x "reloadxml"Reload dialplan/XML config

SIP & Sofia Commands

CommandDescription
fs_cli -x "sofia status"All SIP profiles status
fs_cli -x "sofia status profile internal"Internal profile status
fs_cli -x "sofia status profile external"External profile status
fs_cli -x "sofia global siptrace on"Enable SIP tracing
fs_cli -x "sofia global siptrace off"Disable SIP tracing

Calls & Channels Commands

CommandDescription
fs_cli -x "show calls"List active calls
fs_cli -x "show channels"Show active channels
fs_cli -x "show media_bugs"Active recordings/taps
fs_cli -x "show calls count"Call statistics

Log Commands

CommandDescription
tail -n 50 /var/log/freeswitch/freeswitch.logLast 50 log lines
tail -f /var/log/freeswitch/freeswitch.logFollow log file
---

5. Button Configuration

Default Buttons

ButtonCommandDescription
Statusfs_cli -x "status"System status
Sofia Statusfs_cli -x "sofia status"SIP profiles
Show Channelsfs_cli -x "show channels"Active channels
Show Callsfs_cli -x "show calls"Active calls
Reload XMLfs_cli -x "reloadxml"Reload config
Modules Listfs_cli -x "modules list"Loaded modules
Tail Logtail -n 50 ...Recent logs
Tail Followtail -f ...Follow logs

Custom Button Configuration

Plaintext
┌─────────────────────────────────────────────────────────────────┐
│              Button Configuration                               │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│  Label: Gateway Status                                          │
│  Tooltip: Show all gateway registrations                        │
│  Command: fs_cli -x "sofia status gateway"                      │
│  Order Index: 10                                                │
│  Enabled: ✓                                                     │
│                                                                 │
│  [Save] [Cancel]                                                │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘

Button Fields

FieldDescriptionExample
LabelButton textGateway Status
TooltipHover descriptionShow gateway registrations
CommandCommand to executefs_cli -x "sofia status gateway"
Order IndexButton position10 (lower = first)
EnabledButton activeOn/Off
---

6. Common Scenarios & Examples

Scenario 1: Check Active Calls

Command: fs_cli -x "show calls" Output:

Plaintext
uuid,direction,created,created_epoch,name,state,...
a1b2c3d4-...,inbound,2026-01-16 10:30:00,-,sofia/internal/1001@domain,CS_EXECUTE,...

Scenario 2: Reload Dialplan After Changes

Command: fs_cli -x "reloadxml" Output:

Plaintext
+OK [Success]

Scenario 3: Troubleshoot SIP Registration

Commands:
  1. fs_cli -x "sofia status profile internal" - Check profile
  2. fs_cli -x "sofia global siptrace on" - Enable tracing
  3. (reproduce issue)
  4. fs_cli -x "sofia global siptrace off" - Disable tracing

Scenario 4: Monitor Call Volume

Button: "Call Stats"
SettingValue
LabelCall Stats
Commandfs_cli -x "show calls count"
Order5
---

7. Limitations & Important Notes

Technical Notes

NOTE
WebSocket Required: Terminal requires active WebSocket connection.
WARNING
System Access: Commands execute with backend permissions. Be careful with destructive commands.
WARNING
Log Following: tail -f runs until manually stopped.

Security Considerations

  1. Access Control: Only admin users should access PBX CLI
  2. Audit Logging: Commands may be logged for audit
  3. Read-Only vs Write: Be careful with state-changing commands
  4. Production Safety: Test commands in non-production first

Best Practices

  1. Use Quick Buttons: For common tasks
  2. Avoid Long Commands: Terminal may timeout
  3. Stop Follow Commands: Use Ctrl+C or close terminal
  4. Document Custom Buttons: Keep track of custom configurations
  5. Test Before Production: Verify commands work as expected

---

8. Troubleshooting Tips

Common Issues

SymptomPossible CauseSolution
DisconnectedWebSocket errorRefresh page
No outputCommand timeoutTry simpler command
Auth errorToken expiredRe-login
Command failsInvalid syntaxCheck fs_cli format
Buttons missingConfig issueCheck button configs

Connection Messages

MessageMeaning
ConnectedWebSocket active
DisconnectedConnection lost
Connection errorWebSocket failed
Auth missingToken not found

WebSocket Debugging

Javascript
// Browser console
ws.readyState 
// 0 = CONNECTING, 1 = OPEN, 2 = CLOSING, 3 = CLOSED

---

9. Glossary

TermDefinition
fs_cliFreeSWITCH CLI tool
SofiaSIP module in FreeSWITCH
ChannelMedia connection instance
ProfileSIP endpoint configuration
WebSocketReal-time browser connection
TerminalCommand-line interface
---

Lua Script Status ℹ️

No Lua Handler Required

ComponentStatus
PBX CLIℹ️ Frontend terminal module - commands executed by backend via fs_cli
PBX CLI is a web interface module. Commands are executed on the server via fs_cli or system shell, not through Lua handlers.

---

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?