View Source

0. About

The fs_cli program is a Command-Line Interface that allows a user to connect to a running instance. The fs_cli program can connect to the 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 's Event Socket Library (ESL) to tap into '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 , whether it has been started as a service () or on the console (either background or foreground) (), regardless of operating system.

1. Requirements

fs_cli requires mod_event_socket to be loaded in order to connect to the 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 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 server.

To build:

make current
cd libs/esl
make

To run:

./fs_cli

3. Usage

3.1 Available switches

  -?,-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" command Description Examples Notes

/quit

These all result in disconnecting from the FreeSWITCH command line.

/quit

/bye

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

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.)

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

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`

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

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 mode

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.

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.