Deploying SIP Witch Clients and Server How To

This document was created to help those using the GNU SIP Witch and Twinkle packages that have been created for use with Ubuntu. This howto is not necessarily Ubuntu-specific but is written from the perspective of a typical Ubuntu sysadmin.

Setting up APT

The GNU Telephony team has a number of packages built for various distributions of Ubuntu (Hardy through Jaunty) on Launchpad which may be directly installed from the team ppa. The ppa also gets updated automatically with new upstream releases. The ppa for the ubuntu package builds 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.

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.

SIP Witch Access Control

This will be added in draft II, relates to trusted subnets and other advanced and unique sipwitch features, but should not be needed for basic install...

SIP Witch Server Providers

To be added when providers module is complete.

SIP Witch, remote users, and NAT

To be added when RTP Proxy module is complete.