Name

sipd - SIP redirect, proxy and registration server

Synopsis

sipd [-s ServerRoot] [-l LicenseFile] [-f ConfigFile] [-v] [-X] [-n]

Availability

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.

Version

sipd-1.18, released July 16, 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.

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.

Features

Planned features include

Configuration

The sipd.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, and none.
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 user nobody, 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 into sipd'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

Server Initialization

  1. Change directory to directory specified with '-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.)
  2. If compiled with licensing, open the file specified with '-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.)
  3. Read the file specified with -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.
  4. If the configuration file specified a ServerRoot, change to that directory. If it is a relative path, change to it relative to the -[sd] argument.
  5. Open all files. All relative filenames are thus relative to the configuration file's ServerRoot, regardless of the order of the fields in the configuration file. Also invoke logging processes.
  6. Load and execute canonicalize code.
  7. Daemonize, and change to user User, unless -X 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, 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 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 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.

Options

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

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

See Also

SIP, canonicalize, MySQL

Authors

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

Acknowledgements

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

Copyright

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