Skip to main content

Mod ssh


This document covers information about mod_ssh.

Click here to expand Table of Contents


This module is still in development, it may or may not work as expected and features may be missing


This is an external module and not part of the FreeSWITCH package.


mod_ssh is a Secure-SHell (SSH) remote console module based on (a modified version of) libssh.


  • Multiple user accounts
  • Password authentication (public-key method is not supported by libssh at the moment)
  • Passwords stored in cleartext or MD5/SHA1 hashed
  • Basic line-editing capabilities
  • API commands to list accounts, active sessions, kick users and (temporarily) lock accounts
  • Login/Logout events


  • Command history
  • More advanced line-editing
  • Per-Session threads (mostly done, still experimental, disabled for now)
  • Log output
  • Handle window-resize event


In development (alpha release coming soon)


You need GIT to get the current development snapshot.

git clone

cd mod_ssh
make install


The configuration consists of several sections:

  • "users" section, containing accounts and their passwords
  • "settings" section for global parameters like bind ip and port
  • "cli-keybindings" section for console keybindings for function keys (F1-F12)


<configuration name="ssh.conf" description="SSH Console">
<!-- user accounts -->
Example: plaintext pw
<user name="test" pass="test"/>

Example: sha1 hashed pw
<user name="test" sha1="a94a8fe5ccb19ba61c4c0873d391e987982fbbd3"/>

Example: md5 hashed pw
<user name="test" md5="098f6bcd4621d373cade4e832627b4f6"/>

Q: How to create hashed passwords?
A: Use one of the following methods:

echo -n mypassword | sha1sum
echo -n mypassword | md5sum

echo -n mypassword | openssl sha1
echo -n mypassword | openssl md5

(Note: the -n (= no newline) parameter to echo is important!)

<!-- module settings -->
<!-- port and ip to listen on -->
<param name="port" value="2222"/>
<param name="ip" value=""/>
<!-- connection timeout (seconds) -->
<param name="timeout" value="300"/>
<!-- generate events? (on user login/logout) -->
<param name="events" value="yes"/>
<!-- customize terminal prompt -->
<param name="prompt" value="freeswitch/%u@%h %%"/>
Q: What are the possible format tags for the prompt?
%h Hostname (e.g. "fsbox")
%d Date (2008-12-03)
%D Full date including time (2008-12-03 13:35:14)
%t Time (13:35:14)
%u Username (e.g. "test")
%p PID of the freeswitch process (e.g. 1234)
%% Literal %


Format Final prompt

"freeswitch/%u@%h %%" ==> "freeswitch/test@fsbox %"
"%h[%p] %d >" ==> "fsbox[1234] 2008-12-03 >"


<!-- function key bindings -->
<key name="1" value="help"/>
<key name="2" value="status"/>
<key name="3" value="show channels"/>
<key name="4" value="show calls"/>
<key name="5" value="sofia status"/>
<key name="6" value="reloadxml"/>
<key name="7" value="console loglevel 0"/>
<key name="8" value="console loglevel 7"/>
<key name="9" value="sofia status profile internal"/>
<key name="10" value="fsctl pause"/>
<key name="11" value="fsctl resume"/>
<key name="12" value="version"/>


Configure and load the module, then use a ssh client (openssh tested and works) to connect to FreeSWITCH on the configured ip and port.



API commands

  • ssh version - Display mod_ssh version string

  • ssh help - List of supported commands

  • ssh account [list] - Outputs list of configured useraccounts

  • ssh account disable <account> - Lock the specified account (user can not log in)

  • ssh account enable <account> - Unlock the account

  • ssh session [list] - Lists currently active sessions

  • ssh session kick <name> - Kick session (forced log out)


If enabled in ssh.conf.xml (parameter "events"):

  • ssh::login - after a user successfully logged in
  • ssh::logout - after a user logged out

Channel Variables


Known Bugs

A session executing a long running command will block other SSH sessions, this will be fixed by the (still experimental) per-session thread support.

Log output is not supported.

Libedit can not be used multiple times in a task (even though it's API seems to be able to), a custom terminal library had to be written, this code is still in an early stage...