sipd - SIP redirect, proxy and registration server
sipd [-s ServerRoot] [-l LicenseFile] [-f ConfigFile] [-v] [-X] [-n]
Binary and source distribution are available. The code runs on Solaris, FreeBSD 3.x and 4.x, Linux (tested on RedHat 6.1), Windows NT/95/98/2000, Tru64 Unix (Compaq/Digital), with other Unix platforms available upon request.
sipd-1.18, released July 16, 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.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, digest and PGP 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 is configured through a configuration file, by default
sipd.conf
. The location of the configuration file can be specified via the -s command line parameter.
Planned features include
- Full SIP (RFC 2543) 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 to allow easy user management and failure recovery;
- 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;
- can use an SQL table for logging, with web-based accounting and rating functionality;
- 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);
- Apache-style configuration file;
- Basic, Digest and PGP 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.
- TRIP interface (once local access protocol is clarified);
Thesipd.conf
file can contain the following directives:
- AgentxSocketPath ip:port
- The ip address and port to use for contacting the SNMP daemon. Default is
127.0.0.1:5062
, i.e., port 5062 on the local host.- AuthMethod value
- The type of authentication the server will request, in those situations in which it wants authentication. Possible values are
basic
,digest
, andnone
.- CGITimeout timeout
- Time, in seconds, that program waits for CGI script to return an answer. Default to 15 seconds.
- Canonicalize "arguments"
- Arguments to pass to the canonicalizer. The canonicalizer transforms usernames into a canonical form for database lookup. This is normally the shared library libcanon. See the canonicalize program's documentation for a description of the format in which requests are sent and received. See also Run-Time settings.
- DefaultReg proxy | redirect
- If a registration contains a Contact header that does not have an action parameter, fill in this action. Default is redirect.
- DisplayAmbiguous true | false
- This flag determines whether the server will return the contacts list in case of ambiguous response (more than one match). Defaults to 'false'.
- Domain regex
- A regular expression defining the domains that the server accepts registrations from. If the host part of the To header does not match the regular expression, the server returns a status of 404 (Not Found). All hosts which match this regular expression are considered to be equivalent to ServerName.
- ErrorLog logfile
- The error log directive sets the name of the file to which the server will log any errors it encounters. If the logfile does not begin with a slash (/), then it is assumed to be relative to the ServerRoot. If the logfile begins with a pipe (|) then it is assumed to be a command to spawn to handle the error log. The default is stderr.
Using syslog instead of a filename enables logging via syslogd(8) if the system supports it. The filename stderr directs output to stderr.
- EnumRoot domainname
- The EnumRoot directive defines the top level domain to be used for resolving telephone numbers using ENUM.
- Expires seconds
- Registrations expire after the number of seconds given in the Expires configuration option. The default is 3600 (1 hour).
- ForeignDomain proxy | redirect | reject
- If the request contains a URI with a domain that does not match the Domain regular expression, the server can either proxy the request, redirect it (possibly substituting the IP address for the host name) or reject the request. If the value is proxy, proxy-authentication is demanded if AuthMethod is set.
- GatewayMap map-file
- A file describing a static map from telephone numbers to telephony gateways. The format is similar to the dialplan map of canonicalize, with an additional second field listing a comma-separated set of gateway classes. Every user registered in the database may have a gateway class assigned; only users in a particular class may access a gateway described by that class. The special class
*
matches all classes, except the NULL class.This gateway mapping is applied after canonicalization and after script processing. It is only used for tel URIs. The mapping is only applied if the tel URI is not contained in the local user table.
Below is a sample file:
# Sample gateways file -- Columbia University Computer Science department # Conference URL (+12129397139) student,phd,faculty,staff sip:test@128.59.19.196 # Department calls (+1212939)7[01]?? student,phd,faculty,staff sip:$@itgw1.cs.columbia.edu # University calls (+121285)4???? student,phd,faculty,staff sip:$@itgw1.cs.columbia.edu # NYC calls -- 212 (+1212)??????? phd,faculty,staff sip:8$@itgw1.cs.columbia.edu # NYC calls -- other area codes (+1){347,646,718,917}??????? phd,faculty,staff sip:81$@itgw1.cs.columbia.edu- Group unix-group
- The Group directive sets the group under which the server will answer requests. In order to use this directive, the stand-alone server must be run initially as root. Unix-group is one of:
- A group name
- Refers to the given group by name.
- # followed by a group number.
- Refers to a group by its number.
It is recommended that you set up a new group specifically for running the server. Some admins use user nobody, but this is not always possible or desirable.
Note: if you start the server as a non-root user, it will fail to change to the specified group, and will instead continue to run as the group of the original user.
- HelpResolve true | false
- The server returns redirect responses with numeric (dotted-quad) IP addresses instead of host names, relieving the client from doing name resolution. Defaults to 'false'.
- LogCondition condition
- The condition is a comma-separated list of methods and status codes that indicates when the following RequestLog item should be excecuted. The item is executed if the request uses one of the methods listed and returns one of the status codes listed. For example, the condition "INVITE,BYE,200" means that the request is logged if it is a successful INVITE or BYE request.
- LogFormat format
- The format is a string containing literal text and the following special escape sequences, borrowed from the Apache log file configuration:
%a Remote IP-address %{env}e The contents of the environment variable env. %h Remote host name (currently also the IP address). %{header}i The input (request) header with name header. %{header}o The output (response) header with name header. %P The process ID of the child that serviced the request. %r First line of request. %s Status of response. %U The Request-URI. %u Remote user if authentication is used, "-" otherwise. %{timeformat}t The current time, in the form given by timeformat, which should be in a form acceptable to strftime(3). The timeformat defaults to the common log file date format, i.e., "[day/month/year:hour:minute:second zone]", for example [02/Aug/1998:20:05:35 -0400]. %T The time taken to serve the request, in seconds, with a resolution of 1/100 second. The format can be omitted and defaults to "%h %l %u %t \"%r\" %s %b".
- PidFile filename
- The PidFile directive sets the file to which the server records the process id of the daemon. If the filename does not begin with a slash (/), then it is assumed to be relative to the ServerRoot.
It is often useful to be able to send the server a signal, so that it closes and then reopens its ErrorLog and TransferLog, and re-reads its configuration files. This is done by sending a SIGHUP (kill -1) signal to the process id listed in the PidFile.
- Port portnumber
- The port number the server listens on for both TCP and UDP. Default is 5060.
- PrivateKey key
- The key for digest authentication.
- ProxyName hostname
- The hostname which this machine should put in its Via headers. Default is the canonicalized local hostname. This must be a name which DNS resolves to this server.
- ProxyRecursion true | false
- The flag determines whether the server should recursively process 3xx-responses containing Contact headers with sip URI's when proxying, or just return 3xx responses to the originator the same way any other failure status would be returned. The default is false.
- RecordRoute true | false
- The flag determines whether the proxy server automatically inserts a Record-Route header in requests that it processes. The default is true.
- RequestLog file||pipe|@facility.severity
- Each RequestLog entry creates one request log destination. The first argument gives the name of the file to log to, the second the format to be used. If the name starts with a '|', it is assumed to be the name of a program that will receive, via stdin, the log file output. If the name starts with a '@', requests are logged via syslog, with the facility name facility and the severity name severity. Facility names are kern, user, mail, daemon, auth, lpr, news, uucp, cron, local0, local1, local2, local3, local4, local5, local6, local7. Severity names are emergency, alert, critical, warning, notice, info, debug.
The request log can also be recorded in a SQL table by specifying the name
sql://user:password@hostname/database.Note that the database part must be specified.- ScriptBase dir
- Directory where user scripts are stored, such as CPL and cgi scripts. By default, ServerRoot/scripts. The directory must be readable, writeable and executable by the user User.
Within the repository, subdirectories are named by users, in the same format as is used for database keys (e.g., alice@example.com). Within each user's directory, subdirectories are named for each Content-Disposition specified for a script, canonicalized to all lower case. Within that directory, several files appear:
- SCRIPT
- contains the script.
- CONTENT-TYPE
- contains the MIME media type of the script.
- tmpscXXXXXX
- contains temporary copies of the script.
- ServerName FQDN
- Defines the domain name of the server, e.g., cs.columbia.edu
- ServerRoot directory
- Defines the location of the server configuration files.
- StartSnmp true | false
- Whether the server should start the snmp service. Defaults to
false
. Takes effect in all platforms except Tru64.- ThirdPartyReg true | false
- Whether the server should allow third parties to register each other, or insist that users only register themselves.
- ThreadPoolSize count
- The number of threads to be included in the pool of worker threads. The default is 128 and normally does not need to be adjusted. Specifying too large a number may cause the system to run out of threads; too small a number may limit the peak processing rate.
- TimeOut seconds
- The TimeOut directive defines the amount of time
sipd
will wait for completion of a batch of proxied requests. A batch are all requests with similar quality (q) values. Default is 30 seconds.- TryStateless true | false
- The TryStateless directive defines whether
sipd
should try to statelessly proxy the requests and responses.- UseThreadPool true | false
- The flag determines whether the system uses a pool of threads or just allocates new ones for each request. The default is true; performance is much better if a thread pool is uses, so this should not normally be changed.
- User unix-userid
- The User directive sets the userid as which the server will answer requests. In order to use this directive, the standalone server must be run initially as root. Unix-userid is one of:
- A username
- Refers to the given user by name.
- # followed by a user number.
- Refers to a user by their number.
The user should have no privileges which result in it being able to access files which are not intended to be visible to the outside world, and similarly, the user should not be able to execute code which is not meant for
sipd
requests. It is recommended that you set up a new user and group specifically for running the server. Some admins use usernobody
, but this is not always possible or desirable.Notes: If you start the server as a non-root user, it will fail to change to the lesser privileged user, and will instead continue to run as that original user.
- UserConfig
- sql://user:password@hostname/database
- sql indicates an SQL server will be used (rather than a flat file), 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, and is given after the host of the sql server (e.g., sql://root:TooR@sqlserver.cs.acme.org:2405/sip).- fastsql://user:password@hostname/database?REFRESH=refresh_period
- fastsql indicates an SQL server will be used, rather than a flat file. user, password, hostname, port have the same meaning as above. FastSql indicates that
sipd
will fetch 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. refresh_period is the time elapsed, in seconds, between cache refreshes. During a cache refresh,sipd
will update its cache. Modified user data will get reflected intosipd
's cache. The recommended value is 900 (e.g., fastsql://root:TooR@sqlserver.cs.acme.org:2405/sip?REFRESH=900).An example configuration file:
ServerRoot . ServerName cs.columbia.edu Domain cs.columbia.edu Expires 7200 LogCondition INVITE,200 RequestLog |/usr/local/bin/charging "%t %u" RequestLog @user.info "%t %{From}i" RequestLog sql://admin:secret@db.example.com/sip ErrorLog logs/syslog User root DisplayAmbiguous true UserConfig sql://admin:secret@db.example.com/sip
'-s'
or
'-d'
(Apache's option, a synonym) on the command line. If
none, change to '$prefix/sipd'
, where $prefix is determined
at configure time. (Usually /usr/local.)
'-l'
or './sipd.license'
to check for a valid
license. (-l may specify a relative or absolute path. If it is
relative, it is (automatically) relative to the to the -[sd] argument.)
-f
, or
'./sipd.conf'
. Do not perform any actions; just fill in
the 'config' global structure. If -f specified a relative path, it is
(automatically) relative to the -[sd]
argument.
ServerRoot
,
change to that directory. If it is a relative path, change to it
relative to the -[sd]
argument.
ServerRoot
, regardless of the order of
the fields in the configuration file. Also invoke logging processes.
canonicalize
code.
User
, unless
-X
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, but other SQL servers can be used with minor modifications of the internal interface code.
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 uses a license file named sipd.license, that is by default located in the same directory as sipd.conf, or in the file specified by the
-l
command line argument. The license file contains a number of license lines, each of which specifies a DNS domain, an expiration date, and a validation code.Binary and source licenses can be obtained via a web interface.
- -s ServerRoot
- Sets ServerRoot, the directory where the server expects to find the configuration and license files. This may be a full path name, or a relative path name to the current working directory. If not specified, it will default to
/usr/local/sipd
. NOTE: This is a change from earlier (pre-2001) versions of sipd.- -d ServerRoot
- The same as -d ServerRoot.
- -l LicenseFile
- The file containing sipd's license information. The default is
sipd.license
in ServerRoot- -f ConfigFile
- The file containing sipd's configuration information. The default is
sipd.conf
in ServerRoot- -v
- Makes the server print out debugging information to stdout.
- -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.
- After the trial period, you must set the SIPD_REGCODE enviroment variable to the value provided to you. sipd will run on any server within the same class-B or class-C network. For example,
setenv SIPD_REGCODE 3d71c61ec7d967acbb6a466300c676b8(This does not apply to U.S. educational institutions.)- 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").- 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.
- If the following error appears in the log file:
Error in daemon: Invalid argument (22): unable to change uid to -1 Error in daemon: Invalid argument (22): unable to set group id -1You're running sipd as root, but you haven't set the 'user' and 'group' fields in sipd.conf. Generally it is not a good idea (or necessary) to run sipd as root.- For Linux, sipd works with glibc-2.0.7-29, 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 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
Henning Schulzrinne, Akis Alexiou, Wenyu Jiang, Jonathan Lennox, 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.
Copyright 1998-1999 by Columbia University; all rights reserved
Sipd
is subject to licensing.Permission to use, copy, modify, and distribute this software and its documentation for not-for-profit research and educational purposes and without fee is hereby granted, provided that the above copyright notice appear in all copies and that both that the copyright notice and warranty disclaimer appear in supporting documentation, and that the names of the copyright holders or any of their entities not be used in advertising or publicity pertaining to distribution of the software without specific, written prior permission. Use of this software in whole or in parts for commercial advantage and by for-profit organizations requires a license.
The copyright holders disclaim all warranties with regard to this software, including all implied warranties of merchantability and fitness. In no event shall the copyright holders be liable for any special, indirect or consequential damages or any damages whatsoever resulting from loss of use, data or profits, whether in an action of contract, negligence or other tortuous action, arising out of or in connection with the use or performance of this software.
Last updated by Henning Schulzrinne