Bayonne logo

GNU SIP Witch configuration

Contents

Introduction

This article describes GNU SIP Witch configuration on GNU/Linux systems like Debian, and provides an example configuration for an internal network, such as an internal office network or a home network.

I wanted to see if using Fram makes explanation versus configuration clearer for a new user, even though the XML configuration files provided contain a number of helpful comments. Fram is a Mediawiki extension for interspersing explanation with code, and then extracting and concatenating the code into a file for download.

You can download the configuration template sipwitch.conf, as well as the actual configuration file for a simple home network, example 1.

If you want to try GNU SIP Witch from your home directory, you rename the downloaded template to

 .sipwitchrc

Edit the configuration template to suit your own network environment as explained in the next section, and then type

 sipw -x9 -f

to run it as a foreground process. You should see something like this:

 haakon@gnuru:~$ sipw -x9 -f
 sipwitch: loaded config from /home/haakon/.sipwitchrc
 sipwitch: new realm Home
 sipwitch: media proxy configured for 38 ports
 sipwitch: scanning config from /home/haakon/.sipwitch
 sipwitch: adding user haakon
 sipwitch: adding user david
 sipwitch: scanning users and groups
 sipwitch: startup
 sipwitch: starting registry; mapping 200 entries
 sipwitch: starting cdr thread
 sipwitch: starting sip stack; 200 maps and 2 threads at priority 1
 sipwitch: starting event thread 1
 sipwitch: starting event thread 2
 sipwitch: starting media proxy
 sipwitch: starting background thread
 sipwitch: starting media thread
 sipwitch: starting event dispatcher
 sipwitch: starting signal handler
 sipwitch: logfile: server starting 2011-06-07 23:00:18

If you have CSipSimple or similar SIP phone on your Android phone or tablet, you can try register with your local GNU SIP Witch service using the user name and password you put in your configuration file. You should see more output telling you if the user was successfully registered, something like the below.

 sipwitch: sip: event 27; cid=0, did=0, instance=1
 sipwitch: challenge request required
 sipwitch: sip: event 27; cid=0, did=0, instance=2
 sipwitch: challenge request required
 sipwitch: sip: event 27; cid=0, did=0, instance=1
 sipwitch: activating haakon; extension=201
 sipwitch: registering haakon(201) for 300 seconds from 10.0.0.104:37759
 sipwitch: logfile: activating haakon 2011-06-07 23:00:43
 sipwitch: sip: event 27; cid=0, did=0, instance=2
 sipwitch: refreshing haakon(201) for 300 seconds from 10.0.0.104:37759

When the user logs off, you should see something like this

 sipwitch: logfile: activating haakon 2011-06-07 23:24:43
 sipwitch: sip: event 27; cid=0, did=0, instance=2
 sipwitch: registering haakon(201) for 300 seconds from 10.0.0.104:37759
 sipwitch: logfile: activating haakon 2011-06-07 23:29:59
 sipwitch: received signal 14
 sipwitch: system housekeeping

To help you troubleshoot what GNU SIP Witch thinks is its access policy list and peering (published) address after starting, you can type

 sipwitch policy

at a command prompt.

Master configuration file

1. Where to find it

/etc/sipwitch.conf is the master configuration file for the GNU SIP Witch daemon. The default configuration can be overridden with a runtime one stored in /var/run/sipwitch, which can be installed by a management system. If you are using a server executed under “user“ permissions, then this would be ~/.sipwitchrc.

2. How to start

sipwitch.conf is an XML file and starts off like this:

 <?xml version="1.0"?>
 <sipwitch>

3. Provisioning

Allows provisioning to be in main configuration file as well as scattered. This allows you to produce a single configuration file that represents the complete phone system.

We can comment out portions of the configuration by adding <!-- before and --> after an excluded configuration block in the file.

 <provision>
 <!-- 
   <refer id="x"></refer>
   <alias id="test"><contact>sip:xxx@yyy</contact></alias>
   <user id="y"/>
   <gateway id="z"/>
 -->
 </provision>

Example 1

In example 1, we assume a home network with two users. We add a user name, the user's secret password and what to display. The users get the extension 201 and 202.

 <provision>
   <user id="haakon">
     <secret>********</secret>
     <extension>201</extension>
     <display>Haakon Meland Eriksen - HTC Desire</display>
   </user>
   <user id="david">
     <secret>********</secret>
     <extension>202</extension>
     <display>David Sugar - Twinkle Softphone</display>
   </user>
 </provision>

4. Access

Access rules and CIDR definitions. By default 127.0.0.1/::1 are in a pre-generated “loopback” CIDR. Access rule entries are now automatically generated by scanning the network interface, so this is for special overrides or convenience naming.

 <access>
 <!-- 
   <local>172.16.59.0/24</local>
 -->
 </access>

Example 1

In example 1, we assume a home network using the private addresses 10.*.*.*.

 <access>
   <local>10.0.0.0/24</local>
 </access>

5. Stack

Localnames

The effective names this server processes requests for, and an optional list of host or domain names this server will also respond to. The default hostname is always accepted.

 <stack>
 <!-- 
   <localnames>sip.gnutelephony.org, server.local, something somewhere</localnames>
 -->
Stack configuration

Here we restrict all access to the server under the local subnet, and we specify the local subnet is “trusted.” Trusted means that challenge digests will be relaxed for devices that are already registered with the server, and hence reduces the total SIP traffic needed. We map for 200 calls, set 2 dispatch threads for SIP events, and bind to all interfaces.

 <!-- 
   <restricted>local</restricted>
   <trusted>local</trusted>
 -->
   <mapped>200</mapped>
   <threading>2</threading>
   <interface>*</interface>
   <dumping>false</dumping>
Peering

Peering entry used for setting “proxy” IP address for external users when we are behind a NAT. This is used for determining IP address for media proxy in particular. Example entry shown. Can be IP address or resolvable hostname.

 <!-- 
   <peering>www.example.com</peering>
 -->
Special user ID's

The “system” ID is used when the server creates a SIP message that is not on behalf of any registered “user agent”, but rather from the server itself. For example, when feeding an SMS “message” through the control interface, this is generated as a “system” message. Attempts to dial the “system” ID will always return SIP FORBIDDEN. The “anon” ID is used when anonymous messages are generated. These always respond with SIP NOT FOUND if one wishes to contact anon.

   <system>system</system>
   <anon>anonymous</anon>
 </stack>

This concludes the stack.

6. Timers

The timers determine when to make a ringing sound or signal, how many rings to wait before the call is forwarded if there is no answer, and when to reset the call.

 <timers>
   <!-- ring every 4 seconds -->
   <ring>4</ring>
   <!-- call forward no answer after x rings -->
   <cfna>4</cfna>
   <!-- call reset to clear cid in stack, 6 seconds -->
   <reset>6</reset>
 </timers>

7. Registry properties

We specify support for numeric telephone extensions on this machine. This is useful when sharing a common set of user provisioning records over multiple servers which are routed and segmented. Hence if I want to call an extension outside of the range of the server I register with, I initially authenticate since this server has the common provisioning, but I then am referred to the actual target server where the destination user is registered.

Prefix
The prefix property tells sipwitch to support numeric telephone extension, start at a specific extension number. The default is to start at 200.
Range
The range property tells sipwitch how many extensions to support. The default is 100.
Key size
Keysize is used for hash indexing range.
Realm
Realm is just a digest string. In theory it can be anything. In practice, making it the same as domain, and thereby using a valid host|domain|IP address, does make it simpler. Otherwise the two have to be configured separately for a client. Domain is needed so the client knows who to present itself and the userid “as” part of, where realm is needed to compute the authentication digest. Realm is the realm presented for www authentication, but is normally set uuid or in /etc/siprealm.
Mapped
[Needs explanation].
 <!-- we have 2xx numbers plus space for external users -->
 <registry>
 <!-- 
 -->
   <prefix>200</prefix>
   <range>100</range>
   <keysize>77</keysize>
   <mapped>200</mapped>
 <!-- <realm>GNU Telephony</realm> -->
 </registry>

Example 1

In example 1, we assume a simple home network, so we call the realm “Home”. We specify support for numeric telephone extensions on this machine, for 100 extensions starting at extension 200. This is useful when sharing a common set of user provisioning records over multiple servers which are routed and segmented. Hence if I want to call an extension outside of the range of the server I register with, I initially authenticate since this server has the common provisioning, but I then am referred to the actual target server where the destination user is registered.

 <registry>
   <prefix>200</prefix>
   <range>100</range>
   <keysize>77</keysize>
   <mapped>200</mapped>
   <realm>Home</realm>
 </registry>

8. Templates

Templates may be used to set default values for automatically generated user accounts, such as default forwarding or password if not set.

 <!-- 
 <templates>
  <user>
   <secret>123</secret>
   <forwarding>
    <busy>voicemail</busy>
    <na>voicemail</na>
   </forwarding>
  </user>
  <admin>
   <forwarding>
    <busy>operator</busy>
    <na>operator</na>
   </forwarding>
  </admin>
 </templates>
 -->

9. Routing

Routing rules can do all sorts of transforms for dialed numbers. The routing table can also be used to statically redirect ranges of extension numbers to alternate servers. For example, we redirect 1xx numbers to a different server with something like:

 <redirect pattern="1xx" server="server.local"/>

or a range of numbers to a single remote entity URI:

 <redirect pattern="3xx" target="sip:[email protected]"/>

Reject rules can be used to reject with specific error messages, and rewrite rules can add or subtract prefix or suffix codes.

 <routing>
 </routing>

This concludes routing, and we end the main configuration file of GNU SIP Witch with

10. How to end

 </sipwitch>