Command Line Interface (fs_cli)
0. About
The fs_cli program is a Command-Line Interface that allows a user to connect to a running FreeSWITCH™ instance. The fs_cli program can connect to the FreeSWITCH™ process on the local machine or on a remote system. (Network connectivity to the remote system is, of course, required.)
The fs_cli program uses FreeSWITCH™ 's Event Socket Library (ESL) to tap into FreeSWITCH™'s event system to send commands issued by the user, and to collect the server responses to send to the display. The Event Socket Library (ESL), a C-based socket library, was developed for use with fs_cli, although a programmer could use this library for any C language program that needs to connect to the event socket. With the -x switch (see below) fs_cli can issue a command to the server, get a response, and then disconnect.
The fs_cli program can connect to FreeSWITCH™, whether it has been started as a service (TODO) or on the console (either background or foreground) (TODO), regardless of operating system.
1. Requirements
fs_cli requires mod_event_socket to be loaded in order to connect to the FreeSWITCH™ server.
Normally, the easiest way to check if a module is loaded is to use fs_cli
$ fs_cli
freeswitch@tr2> module_exists mod_event_socket
true
# or
$ fs_cli -x 'module_exists mod_event_socket'
true
but in this case, for obvious reasons, check whether the mod_event_socket is enabled in modules.conf.xml (see Configuring FreeSWITCH).
The default mod_event_socket configuration binds to :: (i.e., to listen to connections from any host), which will work on IPv4 or IPv6.
:: means that mod_event_socket will listen to connections from any host (see vanilla <conf_dir>/autoload_configs/[event_socket.conf.xml](https://github.com/signalwire/freeswitch/blob/a5cecbfc2a5e0ea2d3f45489f2681a67e32ce955/conf/vanilla/autoload%5Fconfigs/event%5Fsocket.conf.xml) configuration file in the SignalWire GitHub repository). There are obvious security risks, so one would want to change this (e.g., to localhost only, ::1 ), and perhaps also limit access via a firewall and/or ACL, as well as never using the default password.
2. Install
2.1 Server
The FreeSWITCH™ server will build and install the fs_cli client by default.
2.2 Client
The client can also be built without needing to build the entire FreeSWITCH™ server.
To build:
make current
cd libs/esl
make
To run:
./fs_cli
3. Usage
3.1 Available switches
command syntax
-?,-h --help Usage Information
-H, --host=hostname Host to connect (default is 127.0.0.1)
-P, --port=port Port to connect (default is "8021")
-u, --user=user@domain user@domain
-p, --password=password Password (default is "ClueCon")
-i, --interrupt Allow Control-c to interrupt
-x, --execute=command Execute Command and Exit
-l, --loglevel=command Log Level (default is debug)
-U, --log-uuid Include UUID in log output
-S, --log-uuid-short Include shortened UUID in log output
-q, --quiet Disable logging
-r, --retry Retry connection on failure every two seconds until connected (or until 2 minutes has passed)
-R, --reconnect Reconnect if disconnected
-d, --debug=level Debug Level (0 - 7)
-b, --batchmode Batch mode
-t, --timeout Timeout for API commands (in miliseconds)
-T, --connect-timeout Timeout for socket connection (in miliseconds)
-n, --no-color Disable color
3.2 Examples
3.2.1 Simple
fs_cli
fs_cli which connects to local machine using default username, password, and debug level.
3.2.2 Using profiles
fs_cli my_profile
Launches fs_cli using profile named "my_profile" found in .fs_cli_conf file (see section 5.3 below).
3.2.3 Sending a command and then logging off
fs_cli -x "sofia status profile internal"
Launches fs_cli and sends a command before logging off. The output of the above command looks like this:
$ fs_cli -x "sofia status profile internal"
=================================================================================================
Name internal
Domain Name N/A
Auto-NAT false
DBName sofia_reg_internal
Pres Hosts 10.0.0.5,10.0.0.5
Dialplan XML
Context public
Challenge Realm auto_from
RTP-IP 10.0.0.5
SIP-IP 10.0.0.5
URL sip:mod_sofia@10.0.0.5:5060
BIND-URL sip:mod_sofia@10.0.0.5:5060;transport=udp,tcp
WS-BIND-URL sip:mod_sofia@10.0.0.5:5066;transport=ws
WSS-BIND-URL sips:mod_sofia@10.0.0.5:7443;transport=wss
HOLD-MUSIC local_stream://moh
OUTBOUND-PROXY N/A
CODECS IN OPUS,G722,PCMU,PCMA,VP8
CODECS OUT OPUS,G722,PCMU,PCMA,VP8
TEL-EVENT 101
DTMF-MODE rfc2833
CNG 13
SESSION-TO 0
MAX-DIALOG 0
NOMEDIA false
LATE-NEG true
PROXY-MEDIA false
AGGRESSIVENAT false
CALLS-IN 0
FAILED-CALLS-IN 0
CALLS-OUT 0
FAILED-CALLS-OUT 0
REGISTRATIONS 0
4. Available commands
4.1 FreeSWITCH API
While connected, the user can issue any command in the FreeSWITCH API - which are all the commands exposed in the enabled modules and mod_commands.
See the console commands for example, exposed by mod_console .
freeswitch@tr2> console
USAGE:
--------------------------------------------------------------------------------
console help
console loglevel [[0-7] | <loglevel_string>]
console uuid [on|off|toggle]
console json [on|off|toggle]
console colorize [on|off|toggle]
-------------------------------------------------------------------------------
4.2 Forward slash (/) commands
Additionally, there are several commands that can be issued using a forward slash (/) character.
| "slash" command | Description | Examples | Notes |
|---|---|---|---|
| /quit | These all result in disconnecting from the FreeSWITCH command line. | /quit | |
| /bye | /bye | ||
| /exit | /exit | ||
| /event | Subscribe to FreeSWITCH events. | /event all | This command corresponds to the event command in mod_event_socket. |
| /noevents | Unsubscribe from all events (previously subscribed to using /event). | /noevents | This command corresponds to the noevents command in mod_event_socket. |
| /nixevent | Suppress the specified type of event. Useful when you want to allow /event all followed by nixevent <some_event> to see all but one type of event. | /nixevent HEARTBEAT | This command corresponds to the nixevent command in mod_event_socket. |
| /log | Set log level of the FreeSWITCH deamon.0 - CONSOLE 1 - ALERT 2 - CRIT 3 - ERR 4 - WARNING 5 - NOTICE 6 - INFO 7 - DEBUG | /log alert/log 1 | This command corresponds to the log command in mod_event_socket.TODO So what is the point of console loglevel <level> ? The default log level is stated when fs_cli is started (which is 7 for debug), but console loglevel will report NOTICE (i.e., 5).However it is, /log seems to take precedence over the console commands. |
| /nolog | Disable logging. | /nolog | This command corresponds to the nolog command in mod_event_socket. |
| /uuid | Filter logs for a single call (specified by its UUID). | /uuid 6936d2ad-bea3-40b3-9de3-34024404e8d4 | |
| /filter | Specify what events to listen to by event header value./filter <EventHeader> <ValueToFilter> | /filter Event-Name HEARTBEAT/filter Unique-ID d29a070f-40ff-43d8-8b9d-d369b2389dfe | This command corresponds to the filter command in mod_event_socket. |
| /filter delete | Delete previously set event filters./filter delete <EventHeader> <ValueToFilter>If <ValueToFilter> is omitted, the command will delete all filters previously set for the specified event header. | /filter delete Event-Name HEARTBEAT/filter delete Unique-ID d29a070f-40ff-43d8-8b9d-d369b2389dfe/filter delete Unique-ID | This command corresponds to the filter delete command in mod_event_socket. |
| /logfilter <string> | Filter the logs by the given <string> . (The log levels are set by /log , see above.)TODO What is the exact syntax? Does it accept regexes as well? I know that it takes anything that follows /logfilter literally, because adding double quotes to a string with space will actually look for double quotes in the log entries. | /logfilter Codec Activated | |
| /logfilter | Disable all logfilters. | /logfilter | |
| /help | List available fs_cli commands. | /help | |
| /debug <debug_level> | There are 8 debug levels (from 0 to 7) and the higher the number the more verbose the logs will become./debug <debug_level> is equivalent to /log 7 /debug <debug_level> | /debug 3 | |
| /debug | Same as /debug 0 | /debug |
For command-line editing, see "Command-Line Editing" section of mod_console. The details are the same as of SVN r13964.
5. Configuration
TODO The statements in this section need confirmation. For example, tried to de-colorize the console logs by setting the relevant section to false in console.conf.xml (see mod_console) and in switch.conf.xml, while having no fs_cli.conf anywhere in the system after a vanilla FreeSWITCH install.
5.1 switch.conf.xml
switch.conf.xml contains the core FreeSWITC configuration, see more there.
5.2 mod_console
mod_console and its configuration file, console.conf.xml also affect fs_cli, and some of the options are redundant with switch.conf.xml.
5.3 /etc/fs_cli.conf and ~/.fs_cli
TODO This section definitely needs confirmation; the vanilla FreeSWITCH install doesn't have any fs_cli.conf (only ~/.fs_cli_history ), and the only intact fs_cli.conf file I could find is this.
Use fs_cli.conf to override existing configuration (/etc/fs_cli.conf for system-wide settings and ~/.fs_cli_conf for user-specific settings).
5.3.1 Format
The config file uses a simple INI-style layout and allows for multiple profiles. This allows one to access many FreeSWITCH™ systems from a single workstation.
[default]
; Put me in /etc/fs_cli.conf or ~/.fs_cli_conf
;overide any default options here
loglevel => 6
log-uuid => false
quiet => false
key_f1 => help
key_f2 => status
key_f3 => show channels
key_f4 => show calls
key_f5 => sofia status
key_f6 => reloadxml
key_f7 => /log console
key_f8 => /log debug
key_f9 => sofia status profile internal
key_f10 => sofia global siptrace on
key_f11 => sofia global siptrace off
key_f12 => version
[profile1]
host => 192.168.1.10
port => 8021
password => secret_password
debug => 7
[profile2]
host => 192.168.1.11
port => 8021
password => someother_password
loglevel => info
[my_profile]
5.3.2 Configuration options
| Option | Description | Example | | | | | | | | --------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------- | ------- | ------ | ---- | ----- | -------------------------------- | | | host => <hostname> | Host to connect (default is 127.0.0.1) | host => 127.0.0.1 | | | | | | | | port => <port> | Port to connect (default is 8021) | port => 8021 | | | | | | | | user => <username> | user@domain | | | | | | | | | password => <password> | Password (default is "ClueCon") | password => ClueCon | | | | | | | | interrupt => true | false | Allow Control-c to interrupt | | | | | | | | | execute => <command> | Execute command and exit | | | | | | | | | loglevel => console | alert | crit | err | warning | notice | info | debug | Set log Level (default is debug) | | | log-uuid => true | false | Include UUID in log output | | | | | | | | | log-uuid-short => true | false | Include shortened UUID in log output | | | | | | | | | quiet => true | false | Disable logging | | | | | | | | | retry => true | false | Retry connection on failure every two seconds until connected (or until 2 minutes has passed) | | | | | | | | | reconnect => true | false | Reconnect if disconnected | | | | | | | | | debug => <0 .. 7> | Debug Level (0 - 7) | | | | | | | | | batchmode => true | false | Batch modeTODO What does this mean? | | | | | | | | | timeout => <milliseconds> | Timeout for API commands (in miliseconds) | | | | | | | | | connect-timeout => <milliseconds> | Timeout for socket connection (in miliseconds) | | | | | | | | | no-color => true | false | Disable color | | | | | | | | | key_f<n> | Set F1 - F12 keys for a certain functionality.Default key-bindingsF1 = help F2 = status F3 = show channels F4 = show calls F5 = sofia status F6 = reloadxml F7 = console loglevel 0 F8 = console loglevel 7 F9 = sofia status profile internal F10 = sofia profile internal siptrace on F11 = sofia profile internal siptrace off F12 = version | See example at 5.3.1 Format above. | | | | | | |
6. Wish List
- Option to see all output to include FS console output.
- Option to see all output from all fs_cli instances connected to the FS box, plus the console.
- Option to connect to more than one FS box.