Skip to main content

Command Line Interface (fs_cli)


Table of Contents (click to expand)


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" commandDescriptionExamplesNotes
/quitThese all result in disconnecting from the FreeSWITCH command line./quit
/bye/bye
/exit/exit
/eventSubscribe to FreeSWITCH events./event allThis command corresponds to the event command in mod_event_socket.
/noeventsUnsubscribe from all events (previously subscribed to using /event)./noeventsThis command corresponds to the noevents command in mod_event_socket.
/nixeventSuppress 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 HEARTBEATThis command corresponds to the nixevent command in mod_event_socket.
/logSet 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 1This 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.
/nologDisable logging./nologThis command corresponds to the nolog command in mod_event_socket.
/uuidFilter logs for a single call (specified by its UUID)./uuid 6936d2ad-bea3-40b3-9de3-34024404e8d4
/filterSpecify what events to listen to by event header value./filter <EventHeader> <ValueToFilter>/filter Event-Name HEARTBEAT/filter Unique-ID d29a070f-40ff-43d8-8b9d-d369b2389dfeThis command corresponds to the filter command in mod_event_socket.
/filter deleteDelete 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-IDThis 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
/logfilterDisable all logfilters./logfilter
/helpList 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
/debugSame 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.

7. See Also

Comments:

See this JIRA for an issue I faced: FS-7718 -Authenticate to see issue details I was not able to connect to freeswitch on localhost with fs_cli until I copied the example conf file from /usr/src/freeswitch to /usr/loca/freeswitch.Maybe future releases won't require this but I'm writing here so at least I know how to resolve tfs_cli connection issues. Posted by jungleboogie at Jun 23, 2015 22:55