Apache SIP Module Documenation

This is the documentation page for the Apache SIP module. This module is designed to server as a protocol module. A protocol module is a module that sits at the same level as the HTTP core module, and processes incoming connections in some different protocol than HTTP. In the case of this module, the protocol is SIP, or Session Initiation Protocol. More information about SIP can be found here.

This module was developed to support a subset of the Common Gateway Interface (CGI) protocol proposed by Lennox et. al. to the Internet Engineering Task Force. It creates an environment for executing a simple script in response to a SIP message received by the Apache server.

The script called is determined by the name in the SIP URL. For example, if the message sent is:

INVITE sip:bryan@foo.com:5060;user=IP SIP/2.0
Via: SIP/2.0/TCP 192.168.27.105:5060
From: bryan
To: user
Call-ID: 723425489@192.168.27.104
CSeq: 1 INVITE
Subject: VovidaINVITE
Content-Type: application/sdp
Content-Length: 0

Then the script name to execute will be bryan@foo.com. The path of where this file lives is set in the apache configuration file with the parameter SipDirectory.

The module is turned on and off in the configuration file with another parameter, ProtocolSip. Thus, a complete configuration file to listen on the standard port (80) for HTTP requests and port 5060 for SIP might look like this:

User webuser
Group webgroup
Listen 127.0.0.1:5060
Listen 127.0.0.1:80
LockFile /var/run/apache-lock 
ScriptAlias /cgi-bin /usr/scratch/apache/www/cgi-bin
ServerName orion.private.vovida.com
DocumentRoot /usr/scratch/apache/www/htdocs/

<VirtualHost 127.0.0.1:5060>
ErrorLog /usr/scratch/apache/www/logs/error_log2
TransferLog /usr/scratch/apache/www/logs/trans_log2
SipDirectory /usr/scratch/apache/www/sip-cgi-bin/
ProtocolSip yes
</VirtualHost>

The incoming message is parsed to ensure it is a valid SIP message, that it is a SIP/2.0 message, the requested script exists and that the script is executable. The server may return a SIP error message if this is not true (400, Bad Request; 500, Internal Server Error; or 505, SIP Version Not Supported). The server will try to execute the script "default.cgi" in the SIP directory before giving up and issuing a SIP error message. If there is no error, the script is started as the default user for Apache, and passed the following default parameters as environment variables

REQUEST_METHOD	The method in the SIP message (INVITE, ACK, etc)
REQUEST_URI	The complete SIP URI from the message (such as sip:bryan@foo.com:5060;user=IP
SERVER_PROTOCOL	The protocol by which the message arrived (from the header)
REMOTE_ADDR	IP address of the client that sent the message.
GATEWAY_INTERFACE	Version of SIP CGI being used communicate with the script. In this case, SIP-CGI/1.1.
SERVER_SOFTWARE	Version signature from the Apache server being run.
SERVER_NAME	IP address of server.
SERVER_PORT	The port the connection arrived on (after being forked, so will NOT be 5060)
CONTENT_LENGTH	The length (in octets) of the body of the message
CONTENT_TYPE	Media type of the message body.

If more than 100 headers are provided (compile time limit, see the code), a SIP error message will be returned. It was unclear from the document defining the CGI standard wether or not the headers should still be passes to stdin of the script. The code errs on the side of passing too mcuh information, and passes the headers as stdin. Any body is passed as well. Note that CONTENT-LENGTH and SIP_CONTENT_LENGTH (which have an identical value) refer to the length of the body, not the total number of bytes sent to the script. The script should read to the Content-Length: header of stdin, then read CONTENT_LENGTH octets of the body if it wishes to process standard in.

Here is an example of very simple SIP CGI shell script to do redirection to a particular address:

#!/bin/sh

echo -e "SIP/2.0 302 Moved Temporarily\r"
echo -e "Via: $SIP_VIA\r"
echo -e "From: $SIP_FROM\r"
echo -e "To: $SIP_TO\r"
echo -e "Call-ID: $SIP_CALL_ID\r"
echo -e "CSeq: $SIP_CSEQ\r"
echo -n "Contact: user<sip:"
cat ../cgi-bin/forwardfile
echo -e ":5060>\r"
echo -e "Content-Length: 0\r"