GNU SIP Witch is intended to make it both possible and easy for individuals, private organizations, and even national governments to create and deploy network scalable secure VoIP calling networks using the public Internet and free software. GNU SIP Witch is a standards-compliant peer-to-peer SIP call server that can be used to deploy ZRTP-enabled secure VoIP clients such as the Twinkle Softphone and Jitsi (formerly SIP Communicator) which can be found at http://www.jitsi.org/, as well as support conventional SIP softphones. This article explains how to quickly initially setup and deploy GNU SIP Witch using Ubuntu GNU/Linux.
Sip Witch is available in the Ubuntu “Universe” repository. If this repository is not enabled on your system yet, you should add it to the software sources:
sudo add-apt-repository "deb http://archive.ubuntu.com/ubuntu \
$(lsb_release -sc) universe"
Then you can install SIP Witch:
apt-get install sipwitch
or the equivalent from synaptic or from the Software Center... This will also automatically install libucommon2, libosip2, and libexosip2.
First, there is /etc/default/sipwitch:
This should initially have PLUGINS="none" for now. We will
later add PLUGINS="forward" here when we setup for use as a secure
calling domain controller for Asterisk or FreeSwitch.
Then you should add a “sipwitch” group in
/etc/group:
sudo usermod -aG sipwitch your-user-id
This matches the GROUP="sipwitch" line found in
/etc/default/sipwitch. Perhaps the Debian post-installer should
add the group for us in the future.
The primary configuration file is /etc/sipwitch.conf. This
holds information about the SIP stack, the basic dialing plan, and routing.
The most important choice is that of the extension dialing plan that the
given sipwitch instance will handle. This is specified in the
<registry> entry in /etc/sipwitch.conf. If you
want a system that handles 3-digit extension numbers, say extensions 100-699
being possible, you would specify a <prefix> entry of 100,
and a <range> entry of 600.
Also important is the <mapped> entry. This is the maximum
number of user agents that will register with the server. If you plan to have a
dialing plan of 100-699, and plan to have every extension number used by a user
agent, plus perhaps additional user agents for special features, you may want
to specify a <mapped> entry of 700. If you only have a few
user agents, then you can use a much smaller number.
The <realm> entry specifies the registration digest ID.
To use in cross-calling to insecure domains under Asterisk or FreeSwitch, you
should use the same value as the realm that is set in the sip.conf
of your Asterisk server, or the Asterisk default, which I think is
<realm>Asterisk</realm>. Otherwise, set it as you
like. However, it is also tied to the optional user <digest>
entries, so it should not be changed once set.
The <stack> entries in /etc/sipwitch.conf
control basic behavior of the SIP stack. This includes interface to bind on and
port to use for SIP protocol. Most things can be left alone for a simple
default installation.
One entry that is important is <stack>'s
<mapped> entry. This is the maximum number of simultaneous
(concurrent) telephone calls sipwitch will process. Any additional calls that
are offered will receive a SIP temporary busy. If you expect every user agent
to potentially be active at once, then you can take the value of 1/2 the
<registry>'s <mapped> value, since each
call requires two user agents.
You must set the <domain> entry in
<stack>. This is the same as the “domain” entry
in the Twinkle user agent setting. It may be the actual domain of the server,
or even just the hostname that the server is installed on. It
must have a period. The related <localnames> entry can
be used to represent additional host names the server may be reachable as.
SIP Witch can be setup to operate over multiple nodes. This allows one to
have very large site installations, where each server runs part of a dialing
plan. The way this is done is with <routing> entries in
sipwitch.conf. This is not likely a scenario for initial testing,
so I am mostly referencing here that the capability exists.
When routing is used, the SIP call session to a target extension registered on a remote sipwitch instance is “redirected” to the target's server. If we have a 3-digit dialing plan, and a different server handles requests for extension numbers 200-299, we might have a routing entry like:
<routing> <redirect pattern="2xx" server="dracula.local"/> </routing>
You can use a single config file for routing rules, and include your own switch in the routing rules, since the stack prefix and range that the local server handles overrides routing.
Provisioning for individual extensions are found in
/etc/sipwitch.d. A single provision record can hold multiple
extensions. For example, a simple provisioning record for
/etc/sipwitch.d/yoursite.xml might look like:
<provision>
<user id="yourid">
<secret>yourpassword</secret>
<extension>101</extension>
<display>Your full name</display>
</user>
<user id="anotherid">
<secret>anotherpassword</secret>
<extension>102</extension>
<display>Another full name</display>
</user>
</provision>
In this, “id” is the logical user ID (can be from email or login
ID), there is a secret, which is a password that is also used in the user
agent, an extension # in the range of the dialing plan this entry is associated
with, and a display name which appears when that user agent calls another.
There is also other features like call <forward> entries to
set call forwarding, which will be described later...
If you do not want to expose user passwords in the provisioning file, you
can use a <digest>xxx</digest> entry in place of
password. The digest can be computed with the sipdigest utility.
For example:
sipdigest -realm Asterisk yourid yourpassword
will compute a digest value you can use. You would still enter the password
in the authentication part of Twinkle. But at least the server config file will
not have passwords, only digests, just like the /etc/shadow file
has for user logins.
SIP Witch operates as a daemon service. It normally will automatically start when you reboot and can be managed from the standard desktop “services” applet. When you update the sipwitch package through apt, the service is automatically stopped and restarted for you, but this will terminate any active phone calls. You can also change sipwitch configuration files at any time and reload them into the currently running server without any downtime.
The primary interface for controlling the server is with the
sipwitch shell command. This will talk to the running instance of
the daemon. If you are in the “sipwitch” group in
/etc/group, then you will not need to be root to do this.
The list of commands available can be found with man sipwitch.
Yes there is a man page graphics1 . Of particular use is:
sipwitch calls – lists active calls in progress (no output if
none);sipwitch registry – lists registered extensions;sipwitch status – single line state table;sipwitch stats – running call stats (always useful even if
idle...);sipwitch reload – reloads configuration after config files
changed.There are three primary log files:
/var/log/sipwitch.log – basic error and activation logging/var/log/sipwitch.stats – call statistics every hour/var/log/sipwitch.calls – record of each callThese are automatically rotated, based on
/var/logrotate.d/sipwitch.
There is also a /etc/cron.hourly/sipwitch, which generates
hourly statistics.
Any standards-compliant SIP user agent may be used with SIP Witch. The minimum requirement is to configure your SIP Witch server as both the registrar and outbound proxy. Since SIP Witch does no media processing, any audio or video encoding method supported by your user agents may also be used. This document will focus on those clients most commonly found distributed in Ubuntu, and focusing first on those clients that offer secure calling capabilities.
Installing this client on Debian or Ubuntu requires only apt-get
install twinkle.
The client should have a user profile as follows:
xxx, ID used in the
<user id="xxx"> entry;yyy, domain in the main config
<stack><domain>yyy entry.The SIP Authentication should have:
<registry><realm>;xxx, same as
“user name” field;<secret>zzz in
<user> entry;There are a number of priorities in GNU SIP Witch development. These include development of RTP media proxying for automatic NAT penetration, plugins for loading sipwitch extension tables from external database sources, and a front-end management layer for such externalized databases. Any and all community help with SIP Witch development is always welcome.