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.
/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.
sipwitch.conf is an XML file and starts off like this:
<?xml version="1.0"?> <sipwitch>
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>
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>
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>
In example 1, we assume a home network using the private addresses
10.*.*.*.
<access> <local>10.0.0.0/24</local> </access>
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> -->
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 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> -->
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.
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>
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.
/etc/siprealm.<!-- 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>
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>
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> -->
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:local@myserver.somewhere"/>
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
</sipwitch>