sipd - SIP redirect, proxy and registration server


sipd [-S servername] [-D sql://] [-f cinema_db.conf] [-v] [-d] [-X]


The code runs on Solaris 5.8, FreeBSD 3.x and 4.x, Linux (tested on RedHat 6.1 and 7.1), OpenBSD, Windows NT/2000/XP, Compaq Tru64 Unix, with other Unix platforms available upon request.


sipd-1.21, released April 5, 2002.


sipd is a SIP redirect, forking proxy and registration server that provides name mapping, user location and scripting services. It can use external routines to do the actual work of resolving aliases (including group names), mapping names and locating users. It also allows users to register their current location with the server. Users can be registered at multiple locations. Each user can register a script in any scripting language or executable format understood by the server that will be executed when receiving a call. The scripting interface conforms to the SIP cgi-bin interface (RFC 3050).

The server currently understands the ACK, BYE, CANCEL, INVITE, OPTIONS and REGISTER requests, but can proxy and redirect any SIP request method. Invitations and registrations can be authenticated using basic, and digest authentication.

If the user is not registered or cannot be found using the dynamic user location program, the server returns 480 (Temporarily unavailable).

The server configuration is stored in a set of SQL tables, configured through a web interface or other means. The SQL database can be specified via the -f or -D command line parameter.

sipd fetches the database tables and caches them in main memory. Database requests will occur only when the needed data is not in cache. This significantly boosts performance. During a cache refresh, sipd will update its cache. Modified user data will get reflected into sipd's cache.


Planned features include, with approximate release dates:

Server Initialization

  1. Open the SQL database specified with the -D commandline argument, or, if missing, read the configuration file specified with the -f commandline argument. If neither is specified, look in /etc/cinema_db.conf and ./cinema_db.conf.
  2. Check licensing information from database.
  3. Change directory to directory specified with '-s' or on the command line. If none, change to '$prefix/sipd', where $prefix is determined at configure time. (Usually /usr/local.)
  4. Determine if IPv6 is present and usable. Try to auto-detect IPv6 hostname and address. If unable to get the IPv6 hostname, check whether one is specified in configuration table.
  5. Determine if TLS should be used as a transport service. Load certificates, keys, and random parameters and start the TLS transport service.
  6. Open all files. All relative filenames are thus relative to the configuration's server root parameter. Also invoke logging processes.
  7. Daemonize, and change to user specified in the database, unless the -X flag is specified on the command line.

Registering Users

User information is maintained in an SQL database, with tables initially created with the script createsip.sql. Currently, mySQL is used as the database engine.

User lists are maintained in an SQL database. Each user that sends a SIP REGISTER request must first be registered in that database. Users can be added to the database via a script, addsipuser,

    -D sql://root:passwd@hostname/sip 
    -p newpassword 
    -r realm

Alternatively, a web interface may be used to manage users. All registrations and outbound proxy requests are authenticated, unless the requested type of user authentication is set to "none" in the sipd configuration table. Authentication can be never, requested or required. If a user's authentication parameter is set to "never", authentication will not be requested for non-REGISTER methods. If authentication is "requested", the call will proceed even if the password or secret is wrong or missing, but any scripts will identify the call as being unauthenticated. If authentication is "required", the request must be properly authenticated or it will be rejected with a 401 or 407 SIP status response. Users can designate third parties that can register for them, but these third parties also have to be authenticated.

Logging and Accounting

Requests can be logged to any number of destinations, including files, pipes, syslog, an SQL database, and an external RADIUS server. These logs can then be used for accounting. The SQL table contains the following definition:
create table requestlog(
  request_time datetime,
  method varchar(100),
  sip_status int(3) unsigned not null,
  request_url varchar(255),
  sip_callid varchar(255),
  sip_from varchar(255),
  sip_to varchar(255),
  period datetime
The when field records the time of the request, method the SIP request method, sip_status the response status, request_url the request URL, sip_callid the SIP Call-ID header, sip_from and sip_to the URLs contained in the To and From header fields. Finally, period is not written by the server, but meant for accounting. It records the accounting period that this request was assigned to, ensuring that each request is "rated" only once.

License file

The server extracts licensing information from the database.


-S servername
The server will use the servername configuration from the database. If the parameter is omitted and there is only one entry, it is used. If there are several records, -S must be specified.
The URL for the SQL database, in the format sql://user:password@host:port/database, e.g., sql:// If both the -f flag and the -D flag is specified, XXX.

In general, a CINEMA database url is of the form sql://user:password@host:port/database.

user is the sql user name that sipd uses to connect to the SQL server, password is the password of the SQL user, and hostname is the host on which the mySQL server is running. The port of the TCP connection to the SQL server is optional.

All CINEMA programs requiring access to MySQL database accept a parameter -Ddatabase-uri. The -D parameter is optional. If it is not present, CINEMA will look for a file named cinema_db.conf in its working directory. Additionally, on Unix systems it will try to use the data contained in the file /etc/cinema_db.conf. This file should contain a valid CINEMA database URL. Normally, these files are automatically created during installation by CINEMA setup programs and hence, they need not be modified. On Windows systems, CINEMA will also try locating the database url by querying the Windows registry. The key used to store the database uri is HKLM\Columbia University\IRT\CINEMA\CINEMA_DB.

-f cinema_db.conf
The file containing the SQL URL for sipd. It contains a single line, listing the SQL URL for the server, as described for the -D parameter.
-d category
Makes the software print out debugging information to stdout for the particular category. Currently supported categories are all, sql, net, sdp, misc. The option can be repeated to allow debugging multiple categories. In addition, debug specifiers can also be specified in database and override any command line specifiers.
The server only prints its version number.
Run in single-process mode, for internal debugging purposes only; the daemon does not detach from the terminal.

Additionally, time zones for <time-switch> nodes in CPL scripts are resolved to zoneinfo files, based on the tz database of time zone information. The code normally uses the host operating system's list of time zone names for this purpose; however, an alternate directory can be chosen by setting the environment variable TZDIR to the directory in which the files can be found. A future version of sipd will make this setting procedure more straightforward.

Starting the Application

  1. Set the PATH and LD_LIBRARY_PATH to include the mysql bin and lib dirs respectively.
  2. Start mysql.
      $ cd /usr/local/mysql
      $ ./bin/safe_mysql &
  3. Start Apache web server.
      $ cd /usr/local/apache/bin
      $ ./apachectl start
  4. Start sipd
      $ cd /usr/local/cinema/sipd
      $ 2>&1 ./sipd -v -X -s . > sipd_errlog &
    The sipd log will be in the file sipd_errlog.

Notes and Frequently Asked Questions

How do I configure a PSTN gateway with sipd?
You set up the dialplan configuration for the dialplan database table for canonicalize to map phone numbers to their canonical form (Sample Dialplan page). Then, each user should be assigned a gateway class that determines his privileges. The gateway class is maintained in the primary user table and can be edited through the web interface. Finally, the gatewaymap table determines the rewriting of tel: and telephone-number SIP URLs to SIP URLs routed to one or more different PSTN gateways. The gateway chosen can depend on the PSTN (E.164) number and the caller's gateway class.
How does proxying work?
Requests are sent to the contacts with the highest q value in the registration first. If two contacts have roughly the same q value, they are contacted simultaneously (in parallel). Currently, registrations are considered to be similar if their q value is within 0.05 of each other. If there has been no response from some existing branch after a time out (30 seconds), sipd starts another branch, but doesn't cancel the existing ones. q values should be between 0 and 1.
How does software licensing work?
The license string is inserted into the database specified via the -l commandline parameter. An example of such a string is
which indicates that the license expires December 31, 2002 and is valid for running the sipd server in the domain It also indicates that further versions of sipd server with release dates before June 30, 2002 will accept the same license string.

If you get the error

check_license: The local hostname "bar" does not match the domain ""
where foo is the name of your organization and bar the name of the host the software is running on, it means that your local host is not configured to report its local hostname as a fully qualified domain name. The server does a forward lookup on the locally-known hostname to get an IP address; it then does a reverse lookup to obtain a publically-resolvable name. If the name resolution is mis-configured, however, it may return the short form of the name (i.e., "bar", rather than "").
Why doesn't sipd work with Cisco phones?
Some Cisco 7960 phones cannot handle DNS names in Via headers. Enable the use numeric IP addresses flag in the sipd proxy configuration page instead.
My phone sends a registration to sip:a.b.c.d and gets a 403 back - why?
The Domain configuration table determines which requests are considered to be meant for the local domain and thus looked up in the database. For example, for a domain having a proxy server (, three entries are added by the installer to the domain table namely,,, and 
These tell sipd it should accept registrations for request-uri, sip: or Other entries can be added through the Domain configuration page. This configuration also affects which requests are mapped to local addresses and which are proxied to another SIP server (sipd acts as an outbound proxy).
Why doesn't sipd work when I telnet to the server?
Care is needed when cutting and pasting SIP messages using telnet. Blank lines always acquire an extra blank when cutting and pasting, interfering with the header/body boundary detection.
What does the error 'unable to change uid' mean?
If you are getting an error message such as
Error in daemon: Invalid argument (22): unable to change uid to -1
Error in daemon: Invalid argument (22): unable to set group id -1
you are running sipd as root, but have not set the 'user' and 'group' fields in sipd.conf. Generally it is not a good idea (or necessary) to run sipd as root.
What Linux libraries do I need?
For Linux, sipd works with glibc-2.0.7-29 and later, available from glibc-2.0.7-19 and glibc-2.0.7-13 cause sipd to suffer a segmentation fault due to their lack of multithreading support. For Linux kernels 2.2 and later, the standard libraries work. You can find out your current library version with
rpm -q glibc

For FreeBSD, sipd works with gcc and g++ 2.95.2 or higher. gcc version is known to cause compilation problem.

See Also

SIP, canonicalize, MySQL


Akis Alexiou, Wenyu Jiang, Jonathan Lennox, Sankaran Narayanan, Henning Schulzrinne, Panagiotis Sebos, Kundan Singh, Tarun Kapoor, Aleksandr Voskoboynik, Xiaotao Wu, and Yan Xu, at Columbia University, Department of Computer Science


sipd contains LDAP code from the University of Michigan at Ann Arbor, copyright (c) 1992-1996 Regents of the University of Michigan.

sipd uses the mySQL client library, copyright (c) 2001 by MySQL AB.

The sipd web interface uses fbsql and Tcl.


Copyright 1998-2002 by Columbia University; all rights reserved
Sipd is subject to licensing.

Commercial version and licensing available from SIPquest Inc. SIPquest

Last updated by Henning Schulzrinne