GNU SIP Witch offers a means for individuals, private organizations, and even national governments to easily configure and deploy secure network scalable peer-to-peer media VoIP solutions using free software.¬† This article offers an easy “howto” to help people get started using GNU SIP Witch with Ubuntu.
Setting up APT
There are already pre-built packages ready for installation for various releases of Ubuntu (Hardy through Jaunty) on Ubuntu Launchpad which may be directly installed from a PPA (Personal Package Archive) that I maintain. This PPA will continue to be updated with new upstream releases and can be found at https://launchpad.net/~gnutelephony/+archive/ppa. Instructions for setting up PPA access can be found at https://help.launchpad.net/Packaging/PPA. My hope is to have these packages archived in Ubuntu and updated normally starting with Karmic.
Server Install
Assuming an apt source is setup, you should use:
apt-get install sipwitch sipwitch-plugin-forward
Or the equivalent from synaptic…
This will also automatically install libucommon2, libosip2-2, and libexosip2-4 or similar.
Server Configuration
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 deb postinst should add the group for us in the future.
SIP Witch Registry
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.
SIP Witch Stack
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 will also want to set the <domain> entry in <stack>. This is the same as the “domain” entry in the twinkle user agent setting. It may typically be the actual domain of the server, or even just the hostname that the server is installed on. The related <localnames> entry can be used to represent additional host names the server may be reachable as.
SIP Witch Routing
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 Users
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.
Running SIP Witch Service
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.
Controlling the Server
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
Server Log Files
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 call
These are automatically rotated based on /var/logrotate.d/sipwitch
There is also a /etc/cron.hourly/sipwitch which generates hourly statistics.
Using SIP clients
Any standard’s compliant SIP user agent may be used with sipwitch. The minimum requirement is to configure your sipwitch 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.
Using Twinkle
Installing this client on Debian or Ubuntu requires only using apt-get install twinkle.
The client should have a user profile as following:
The “user name” is the xxx id used in the <user id=”xxx”> entry.
The “domain” is the yyy domain in the main config <stack><domain>yyy entry.
The SIP Authentication should have:
realm = realm as set in <registry><realm>.
authentication name = <user id=”xx”> entry, same as “User Name” field.
password = value of <secret>zzz in <user> entry
Under security tab, set “Enable ZRTP/SRTP encryption”
Future Directions
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.
