Logo  Cookbook Internet2  



Getting Started




User Agents

Directory Considerations

Security Considerations




Related Links

CSPS Installation & Configuration

Yul Pyun <>


Two sets of hardware, OS, and CSPS are required for a installation.  CSPS can be run on either Red Hat Enterprise Linux 3.0 or on Sun Solaris operating systems. 

General outline of CSPS Installation and Configuration:

  1. Hardware and Operating System
  2. CSPS Installation
  3. CSPS Configuration
  4. Import Subscriber Data

Hardware and Operating System

Refer to CSPS Installation Guide for details on hardware/software requirements.  Pay particular attention to the Administrative Tasks section.

CSPS Installation

CSPS distribution CD consists of CSPS software (RPM), database conversion scripts, and CSPS GUI client.  The GUI client is the recommended software to configure and manage the proxy servers, and may be installed on Linux, Solaris, and/or Windows.

Follow the Installation Guide to unpackage and install the proxy server.  Although the CSPS can be configured to function in a server farm architecture, we are employing two stand-alone CSPS.

During the installation dialog, please choose the following on each of the two CSPS servers:

  1. Install a stand-alone SPS
  2. Enter the Proxy Domain (the domain for which this server is responsible for; e.g.


When the installation is complete, make sure that the shared memory specified in /proc/sys/kernel/shmmax agrees with CSPS shared memory.  For instance, a minimum of 128MB is required, and 128MB is represented as 134217728 in /proc/sys/kernel/shmmax (128 * 1024 * 1024).  If the numbers do not agree, see the Installation Guide’s How to Install a New System section for details on how to correct the problem.

Install the CSPS GUI client.  Do NOT choose “Typical” installation, instead, choose “All”.  Typical installation will not install License management GUI, and without the GUI, manual license management has shown to be problematic.  CSPS GUI client may be installed on a Windows 2000 or a Windows XP platform.

CSPS Configuration

It is recommended that the CSPS configuration be done using the GUI client.  Any manual configuration changes in the sipd.conf file will be overridden by the values set in the GUI client.

When you start up the GUI client for the first time, please make sure to change the cspsuser user password.

Two servers are required to:

  • Allow only the domain users to be authenticated and registered
  • Allow anyone to call users

Without the authentication feature, anyone can register themselves with the UH proxy server.  e.g. can register himself as impersonating Jane Doe at

However, turning on the authentication feature for registration also turns on authentication for call INVITEs.  For example, if calls, CSPS attempts to authenticate bob against’s database.  This, of course, does not scale in an enterprise environment and goes against the objective of being able to receive calls from anyone.

To work around this shortcoming, UH is using two CSPS servers.  Proxy1 serves as the internal private proxy, and takes on the duties of domain user registration and call processing (INVITEs).  Proxy2 serves as the public proxy and it processes all calls to/from domains external to  Proxy2 therefore does not have registration service nor authentication service.

The following are screen shots of CSPS Farm/Proxies.  Only the screens that require configuration change from the default values are presented.  Please refer to CSPS Administrator Guide for details on administrative tasks.


Change the values as shown in red.

Of significance is the Add Record Route Header.  Setting this value to On forces the proxy to insert itself in the call path.  In other words, all requests in a call dialog must go through the proxy.  A good use of this feature is with calls from a SIP UA to a PBX/PSTN number.  The SIP/PBX gateway will typically have an access control list (ACL) that would allow calls to the PBX/PSTN only from trusted sources, e.g. the proxy server.  Without the Record-Route header, such calls will be dropped by the gateway’s ACL.


Turn on the Access Control and Authentication.

‘Access Order=Allow,Deny’ means that the Allow list is examined before the Deny list, and that those not in the Allow list are denied by default.

‘Satisfy=Any’ means that as long as the access control is satisfied OR authentication is passed, the incoming packet is accepted.

Allow list can be domain name (full or partial), network/nnn CIDR specification, or IP address (full or partial) formats.  If domain name is used, then a reverse DNS lookup is performed against the incoming INVITE or Registration, and that result is compared against the domain specified in the Allow list.  For other format options, please refer to the CSPS Administrative Guide or click on the Help button.

In the example above, we are accepting requests from Proxy2 as well as from the SIP/PBX gateway router.  And since Satisfy is set to Any, users’ requests are granted provided they are authenticated i.e. the user provides valid AuthUser and Password.

On Proxy2, Registry, Access Control and Authentication are turned off (default).  Attempts to register with Proxy2 fails since the Registrar is not running.  All INVITEs are processed since there are no restrictions from Access Control and Authentication.


Call Forward: Unconditional must be set to On…calls from a SIP client to an extension on the PBX must be unconditionally forwarded to the gateway.

Call Forward: No Answer, Busy, and Unavailable can be turned On or Off, depending on the requirements of the school.  For example, if calls, and if Jane is on the phone, you would want to re-route that call to her voice mail box located on the PBX.  Note that the Diversion is On by default, and this feature is required to direct the call to the proper voice mail box.

Call Forwarding conditions are programmed in the Subscriber table (see Import Subscriber Data section below).

At UH, No Answer Timer is set to 20000ms, and it seems to be just the right amount of wait-time (approximately 4 rings), but your mileage may vary.

We do not use Number Expansion so this feature is turned Off.


Use of ‘Domain Routing=On’ makes entries in the Routes database such as .com or .edu destination patterns to function.  Without it, routing only works with phone number destination patterns.

Because Proxy1 (private) requires Authentication and has ACL, outbound INVITES must go through Proxy2 (public).  Routing entry such as .com or .edu has the effect of a default route for that TLD.

Registry feature (Registrar) must be turned on for the private proxy (Proxy1) for the reasons given earlier.


UH is presently not supporting multiple domains so this feature is turned Off.

Log rotation is a good thing.  Rather than letting the logs continue to grow, let CSPS create new log files with date/time stamps.  The smaller logs can then be backed up to an external backup device.  Remember to specify the complete path for the logs.

Import Subscriber Data

Subscriber Table, part of the SIP database (MySQL), is consulted for Authentication and Call Forwarding conditions.  The subscriber record contains the username, password, and call forward URL in case of Busy, No Answer, etc.  Caution: password is not encrypted. Anyone with read access to the database will have access to the password.

CSPS does not support LDAP; however, a campus persons database can be imported into the SIP database.  At UH, we have developed our own shell and perl scripts to extract, massage, and populate the Subscriber table.


In the example above, extension 1111 is the voice-mail access number.  A call to will be unconditionally forwarded to

Joe Blow ( represents a subscriber on the PBX who has no SIP client.  Thus any SIP calls to should be unconditionally forwarded to the gateway.


Notes on Call Processing:

If CFUNC is empty, CSPS uses the most specific pattern match entry in the Routes database to forward the INVITE to the device specified in the Next Hop field.  If there is no pattern match, then CSPS looks-up the Registry database.


Continuing with the example of a SIP call to, the Registry at this point should be consulted and the call forwarded to the two entries found here for user 1234.  However, CSPS looks at the Routes database instead (Cisco BugID CSCee55874).


Notes on Registry:

If a call is made to a user with 3 or more registry entries (e.g. entry for a hard phone such as Cisco 7960, entry for a soft phone on a laptop, and a permanent entry for TDM phone), CSPS returns ‘500 Server Internal Error’ (Cisco BugID CSCee33125).  Keep the registry entry to no more than 2 per user.


A static route for destination 1234 is required and is used (the most specific destination pattern is used), and the next hop that it points to is (itself).  CSPS then sends the INVITE to the next hop (, which causes registry look-up.  It finds the two entries for 1234, and forwards the call to John's PBX phone and to his SIP client.

Notes on Routes database:

·        Routes with domain name destination pattern (e.g. .com or .edu) are used for requests for domains that are not served by the proxy.  Note that the Type=IP.  If the Request-URI's domain is not in the Routes database, then the proxy does a DNS lookup and forwards the request.  Farm/Proxies ‘Use Domain Routing’ must be set to On.

·        We want to use Domain Routing because we want all SIP calls destined for domains outside of to egress from our public server (proxy2).  The reason behind this is that the private server (proxy1) does not accept calls from the public.

·        1… and 2… forces the CSPS to route any calls destined for 4-digit extensions that start with 1 or 2, and that are not in the Subscriber table, to the next hop (

·        CSPS does not support ‘Class of Service’.  It is desirable to allow SIP clients to call the PBX extensions, and/or PSTN numbers, and/or long distance numbers.  A short-term fix is to use access-code (AKA prefix).  For example, if 888 is the access-code for the local PSTN calls, a SIP client may enter 88895551212 to reach the local carrier’s directory service.


The data in Proxy2’s Subscriber table is slightly different than that of Proxy1.  The primary difference is that all SIP clients have CFUNC set to  For example, if a call from the Internet comes in for, that call will be forwarded to Proxy1.  Please recall that Proxy1 has the registration for users.

All other calls are unconditionally forwarded to the gateway.


Proxy2’s Routes database is also slightly different than that of Proxy1.  In particular, calls from the Internet destined for SIP clients are forwarded to Proxy1.  All other calls are forwarded to the gateway.