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/98/2000, Compaq Tru64 Unix, with other Unix platforms available upon request.

Version

sipd-1.19, released October 15, 2001.

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

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. Open all files. All relative filenames are thus relative to the configuration's server root parameter, regardless of the order of the fields in the configuration file. Also invoke logging processes.
  5. Load and execute canonicalize code.
  6. 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 AuthMethod none is specified in the configuration file. 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 and an SQL database. 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 extract 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
Makes the server print out debugging information to stdout.
-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.
-n
Do not attempt to perform reverse name lookup on the local IP address to find the local hostname. Affects the host string used for licensing, and the default value of the string the server uses to describe itself to other hosts.

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

Run-time settings

At startup, sipd loads libcanon, a dynamically loadable shared library that implements canonicalization functionality. In both source and binary distributions, libcanon (libcanon.so in Unix, libcanon.dll in Windows) is present in the same directory as the canonicalize program. The LD_LIBRARY_PATH (Unix) and PATH (Windows) environment variables must be set to include this directory.

Notes and Frequently Asked Questions

How do I configure a PSTN gateway with sipd?
You set up the dialplan file for canonicalize (-D option) to map phone numbers to their canonical form. 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 file 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 software licensing work?
The license string is inserted into the database specified via the -l commandline parameter. An example of such a string is
example.com:2001-06-30:ff4fb120281b0eb5c6d264b6896e6b6f
which indicates that the license expires June 30, 2001 and is valid for running the server in the domain example.com.

If you get the error

check_license: ./sipd.license:1: The local hostname "bar" does not match the domain ".edu"
check_license: ./sipd.license:1: The local hostname "bar" does not match the domain ".edu.au"
check_license: ./sipd.license:1: The local hostname "bar" does not match the domain ".ac.uk"
check_license: ./sipd.license:1: The local hostname "bar" does not match the domain ".columbia.edu"
check_license: ./sipd.license:1: 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. Use the sipd -n commandline flag to enable the use of numeric IP addresses instead..
My phone sends a registration to sip:a.b.c.d and gets a 403 back - why?
The Domain configuration parameter in the configuration file 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, the parameter should be configured as
  Domain ((cs\.columbia\.edu) |(10\.1\.2\.3))
which tells sipd that it should accept registrations for the request-uri sip:cs.columbia.edu or sip:10.1.2.3.
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-2001 by Columbia University; all rights reserved
Sipd is subject to licensing.


Last updated by Henning Schulzrinne