GNU SIP Witch: Peer-to-Peer SIP Server
Detailed architecture and operating manual for GNU SIP Witch, the secure peer-to-peer SIP office telephone server designed to route calls directly between endpoints without proxying cleartext media.
Historical Server Manual
GNU SIP Witch is no longer actively maintained. Do not deploy on public production networks without comprehensive security reviews.
§1System Purpose and Philosophy
GNU SIP Witch is a pure SIP-based office telephone server and call routing daemon. Unlike traditional IP-PBX systems such as Asterisk or FreeSWITCH, SIP Witch was deliberately designed not to act as a media proxy or transcoding bridge.
Traditional PBXs terminate every RTP audio stream at the central server, transcode the codecs, and re-transmit the audio to the destination. While necessary when bridging legacy analog telephony cards (FXO/FXS/E1), this architecture introduces serious liabilities in pure IP environments: - Centralized Bottleneck: Audio quality degrades as server CPU loads increase. - Wiretapping Exposure: All calls pass through the central server in cleartext. - Incompatibility with ZRTP: Because the PBX terminates RTP, end-to-end ZRTP key agreement between phones is broken unless the PBX itself is fully trusted.
SIP Witch functions strictly as a SIP registrar, location server, and routing daemon. Once a call is signaled and authenticated, SIP Witch instructs both endpoints to stream RTP media directly to each other peer-to-peer. It enforces end-to-end encryption (ZRTP) without ever holding the decryption keys.
§2Technical Capabilities
Features incorporated into the SIP Witch daemon: - Pure Peer-to-Peer Media Routing: Direct RTP streaming between callers with zero server media overhead. - Decentralized Mesh Capability: Support for peering across multiple independent SIP Witch nodes without centralized master servers. - Low Resource Overhead: Built entirely on GNU uCommon C++, requiring minimal memory (under 15 MB RAM under load). - Pluggable Routing Modules: Lua scripting support for dynamic extension routing, speed dials, and group ringing. - NAT Traversal: Built-in STUN/ICE client support to facilitate direct peer connections across enterprise firewalls. - Provisioning and Virtual Domains: Support for multi-tenant virtual organizations from a single configuration file (`/etc/sipwitch.conf`).
§3Configuration Architecture (/etc/sipwitch.conf)
SIP Witch configurations are structured in XML format. Key sections govern network bindings, SIP user accounts, and routing tables:
<!-- Historical /etc/sipwitch.conf snippet -->
<sipwitch>
<stack>
<realm>telephony.local</realm>
<port>5060</port>
<interface>0.0.0.0</interface>
</stack>
<routing>
<policy direct="true" zrtp="enforce" />
<mapped extension="101" user="alice" />
<mapped extension="102" user="bob" />
</routing>
<provisioning>
<user id="alice">
<secret>HistoricalSecretKey101</secret>
<display>Alice User</display>
</user>
</provisioning>
</sipwitch>This page reconstructs material originally published at gnutelephony.org. It has been formatted and annotated for archival preservation.
Historical source: GNU SIP Witch. Reproduced or adapted under the GNU Free Documentation License (GFDL) 1.2 or later where stated.
Historical revision date: 2007-06-18 (Revised 2012-01-14). Restored to permanent static archive in October 2026.