Call Us Today! 877.742.2583




Page tree
Skip to end of metadata
Go to start of metadata

 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 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
ZRTP-PASSTHRU true
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
/quit


These all result in disconnecting from the FreeSWITCH command line.

/quit

/bye

/bye

/exit

/exit

/event


Subscribe to FreeSWITCH events.

/event allThis command corresponds to the event command in mod_event_socket.

/noevents


Unsubscribe from all events (previously subscribed to using /event).

/noeventsThis 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./nologThis 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
/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 
/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

OptionDescriptionExample
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 | falseDisable logging
retry => true | false Retry connection on failure every two seconds until connected (or until 2 minutes has passed)
reconnect => true | falseReconnect if disconnected
debug => <0 .. 7> Debug Level (0 - 7)
batchmode => true | false 

Batch mode

TODO 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-bindings

F1 = 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

1 Comment

  1. See this JIRA for an issue I faced: FS-7718 - Getting issue details... STATUS

    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.