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/98/2000, Compaq Tru64 Unix, with other Unix platforms available upon request.
sipd-1.19, released October 15, 2001.
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 intosipd
's cache.
Planned features include, with approximate release dates:
- 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 -v 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 the INFO and COMET methods, and indeed any other "unknown" method. They are proxied without being interpreted, under the same rules as are used for BYE requests. INFO and COMET generally only need to have special handling at end systems.
- support the transport of MIME bodies in SIP packets;
- proxy from TCP to UDP and vice versa (currently, there is a bug if a request without a Content-Length arrives on UDP, as it is proxied unmodified on TCP, which will typically result in the recipient hanging as it expects an infinitely long body.)
- external interfaces to user location and name mapping functions;
- will proxy REGISTER requests not addresses to the local server and perform proxy authentication;
- 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;
- Optional in-memory registration database to reduce database lookup latency;
- multicast registrations;
- can use files, pipes and Unix syslog 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);
- Basic and Digest authentication;
- fully threaded and multi-processor capable;
- portable across a variety of Unix flavors and Windows NT;
- DNS ENUM interface (Solaris and Linux only);
- SNMP SIB-MIB support (not supported on Tru64);
- Forwarding to "tel" URLs using a local dialplan.
- IPv6 support (Nov. 2001);
- TLS support (Nov. 2001);
- CPL implementation (Nov. 2001);
- SIP servlets (Nov. 2001);
- SLP gateway location interface (December 2001);
- RADIUS accounting;
-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.
'-s'
or on
the command line. If none, change to '$prefix/sipd'
, where
$prefix is determined at configure time. (Usually /usr/local.)
canonicalize
code.
-X
flag is specified on the command line.
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 realmAlternatively, 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.
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 );Thewhen
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
andsip_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.
The server extract 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.
- -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.
- Set the PATH and LD_LIBRARY_PATH to include the mysql bin and lib dirs respectively.
- Start mysql.
$ cd /usr/local/mysql $ ./bin/safe_mysql &- Start Apache web server.
$ cd /usr/local/apache/bin $ ./apachectl start- Start sipd
$ cd /usr/local/cinema/sipd $ 2>&1 ./sipd -v -X -s . > sipd_errlog &The sipd log will be in file sipd_errlog.
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.
- 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 isexample.com:2001-06-30:ff4fb120281b0eb5c6d264b6896e6b6fwhich 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 thesipd
-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 asDomain ((cs\.columbia\.edu) |(10\.1\.2\.3))which tellssipd
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 -1you are runningsipd
as root, but have not set the 'user' and 'group' fields insipd.conf
. Generally it is not a good idea (or necessary) to runsipd
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 withrpm -q glibcFor FreeBSD, sipd works with gcc and g++ 2.95.2 or higher. gcc version 2.7.2.3 is known to cause compilation problem.
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.
Copyright 1998-2001 by Columbia University; all rights reserved
Sipd
is subject to licensing.
Last updated by Henning Schulzrinne