|
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" command | Description | Examples | Notes |
|---|---|---|---|
/quit | These all result in disconnecting from the FreeSWITCH command line. | /quit | |
| /bye | ||
| /exit | ||
| Subscribe to FreeSWITCH events. | /event all | This command corresponds to the event command in mod_event_socket. |
| Unsubscribe from all events (previously subscribed to using | /noevents | This command corresponds to the noevents command in mod_event_socket. |
| Suppress the specified type of event. Useful when you want to allow | /nixevent HEARTBEAT | This command corresponds to the |
| Set log level of the FreeSWITCH deamon. 0 - CONSOLE 1 - ALERT 2 - CRIT 3 - ERR 4 - WARNING 5 - NOTICE 6 - INFO 7 - DEBUG |
| This command corresponds to the TODO So what is the point of |
| Disable logging. | /nolog | This command corresponds to the nolog command in mod_event_socket. |
| Filter logs for a single call (specified by its UUID). | /uuid 6936d2ad-bea3-40b3-9de3-34024404e8d4 | |
| Specify what events to listen to by event header value.
|
/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 | /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 TODO What is the exact syntax? Does it accept regexes as well? I know that it takes anything that follows | /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.
/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 |
| 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 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.
1 Comment
sean
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.