Bayonne logo

How to Deploy SIP Witch On Ubuntu



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, as well as support conventional SIP softphones. This article explains how to quickly initially setup and deploy GNU SIP Witch using Ubuntu GNU/Linux.

Server Install

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 \
     $(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.

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 Debian post-installer 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 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 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:

   <redirect pattern="2xx" server="dracula.local"/>

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:

   <user id="yourid">
     <display>Your full name</display>
   <user id="anotherid">
     <display>Another full name</display>

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:

Server Log Files

There are three primary log files:

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

Using Twinkle

Installing this client on Debian or Ubuntu requires only apt-get install twinkle.

The client should have a user profile as follows:

The SIP Authentication should have:

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.