Name

sipd - SIP redirect, proxy and registration server

Synopsis

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

Platforms

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.

Version

sipd-1.21, released April 5, 2002.

Description

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.

Features

• Full SIP (RFC 2543, RFC 2543bis) implementation;
• supports Record-Route and Route headers, both insertion and processing;
• DNS SRV lookups for outbound requests;
• can simultaneously act as a proxy and redirect server, on a per-request or per-registration basis;
• full logging with the -d option to have all messages sent and received printed out to stderr, along with other trace information;
• forking proxy, redirect and registrar functionality; the proxy server proxies requests with any method other than INVITE, such as INFO and COMET, without being interpreted, under the same rules as are used for BYE requests;
• will proxy REGISTER requests not addressed to the local server and perform proxy authentication;
• support the transport of MIME bodies in SIP packets;
• both IPv4 and IPv6 capable;
• support for SSL/TLS transport;
• proxy between several transport protocols (TCP, TLS, and UDP) (currently, there is a bug if a request without a Content-Length arrives on UDP, as it is proxied unmodified on TCP or TLS, which will typically result in the recipient hanging as it expects an infinitely long body);
• proxy from IPv6 addresses to IPv4 addresses and vice versa;
• external interfaces to user location and name mapping functions;
• can handle spirals and will detect loops;
• can perform request merging;
• registrations stored in SQL database, with in-memory caching, to allow easy user management and failure recovery;
• can use an SQL table for logging, with web-based accounting and rating functionality;
• multicast registrations;
• can use files, pipes, Unix syslog, SQL, or RADIUS for logging, with a configurable log file format;
• addressbook in CINEMA web interface;
• SIP cgi-bin interface according to RFC 3050 allows to create user-specific services using any scripting language (currently, scripting is supporting only for requests other than REGISTER);
• Call Processing Language interface according to the latest Internet-Draft, with some caveats (see the release notes);
• Basic and Digest authentication;
• fully threaded and multi-processor capable;
• portable across a variety of Unix flavors and Win32;
• DNS ENUM interface;
• SNMP SIB-MIB support (not supported on Tru64);
• Forwarding to "tel" URLs using a local dialplan.
• SIP servlets as per initial version published in 1999. Implementation of the standard sip-servlet version 1.0 published in May 2002 will be available later.
• A built-in presence agent.

Planned features include, with approximate release dates:

• SLP gateway location interface (Jan. 2003);

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,

  addsipuser
    -D sql://root:passwd@hostname/sip 
    -u newuser@example.com
    -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.

Options

-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.

-D SQL URL

The URL for the SQL database, in the format sql://user:password@host:port/database, e.g., sql://root:secret@dbserver.example.com:2405/sip. 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.

-v

The server only prints its version number.

-X

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

sipd:example.com:2002-12-31:2002-06-30:ff4fb120281b0eb5c6d264b6896e6b6f

which indicates that the license expires December 31, 2002 and is valid for running the sipd server in the domain example.com. 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 "foo.com"

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 "bar.foo.com").

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 example.com having a proxy server 10.1.2.3 (proxy.example.com), three entries are added by the installer to the domain table namely,

 proxy.example.com, example.com, and
10.1.2.3. 

These tell sipd it should accept registrations for request-uri sip:example.com, sip:10.1.2.3 or sip:proxy.example.com. 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 http://rufus.w3.org. 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 2.7.2.3 is known to cause compilation problem.

See Also

SIP, canonicalize, MySQL

Authors

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

Acknowledgements

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

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

Commercial version and licensing available from SIPquest Inc.

Last updated by Henning Schulzrinne