|SIP Deployment Notes at University of Hawaii|
Yul Pyun <firstname.lastname@example.org> (April, 2005)
CSPS Installation & Configuration
Hardware and Operating System
Import Subscriber Data
Gateway/PBX Trunk Provisioning
DNS SRV Record(s)
SIP UA Configuration
CSPS Wish List
University of Hawaii (UH) has joined Internet2 SIP.edu initiative to explore and to enhance voice/video communications services to its constituents. UH System comprises 10 campuses and myriad of educational centers and research facilities over 6 islands.
For the purpose of SIP (Sessision Initiation Protocol) deployment, the initial thrust is to provide services to those users on campuses located on Oahu. Presently, we have over 4,500 users reachable via e-mail addresses, and over 10,000 users reachable via PBX extensions. We expect that these numbers will increase significantly as we expand the scope of our project to include non-Oahu campuses and campus specific domains (e.g. uhh.hawaii.edu for University of Hawaii at Hilo).
UH is running two Proxy servers developed by Cisco Systems. Both servers are Cisco SPS v2.2, running on Red Hat Enterprise Linux v3.0. The first server acts as a private server handling registrations and call processing for hawaii.edu domain SIP clients. The second server acts as a public server handling call processing to/from the Internet at large.
The private server's hardware consists of:
Dell Optiplex workstation
1.7Ghz Pentium 4 processor
Dual 40GB 7200 RPM hard disks
The public server's hardware consists of:
Dell PowerEdge 1850
Dual 2.8Ghz Pentium 4 Xeon processors
Dual 73GB 10000 RPM SCSI hard disks
Additionally, UH is running a Cisco 3725 router with a PRI link to the UH-Manoa campus PBX (Nortel Meridian 1 Model 81C).
Typical calls may fall into one of the following (simplified) scenarios:
Alice calls Jane (as indicated by the blue dashed line -----):
Alice calls John (as indicated by the red dashed lines -----):
Jane calls John's PBX phone (as indicated by the green dashed line -----):
Jane calls John's SIP phone (as indicated by the lavender dashed line -----):
CSPS Installation & Configuration
To meet the objectives set forth above, particularly objectives #2 and #3, two sets of hardware, OS, and CSPS are required. CSPS can be run on either Red Hat Enterprise Linux 3.0 or on Sun Solaris operating systems. UH has decided to run CSPS on the RHEL platform. The rest of this section assumes a two server environment.
General outline of CSPS Installation and Configuration:
Hardware and Operating System
Refer to CSPS Installation Guide for details on hardware/software requirements. Pay particular attention to the Administrative Tasks section.
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 to satisfy the objectives previously stated.
During the installation dialog, please choose the following on each of the two CSPS servers:
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.
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.
Again, two servers are required to:
Without the authentication feature, anyone can register themselves with the UH proxy server. e.g. email@example.com can register himself as firstname.lastname@example.org impersonating Jane Doe at hawaii.edu.
However, turning on the authentication feature for registration also turns on authentication for call INVITEs. For example, if email@example.com calls firstname.lastname@example.org, CSPS attempts to authenticate bob against hawaii.edu'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 hawaii.edu domain user registration and call processing (INVITEs). Proxy2 serves as the public proxy and it processes all calls to/from domains external to hawaii.edu. 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 Administrator 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, hawaii.edu 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 email@example.com calls firstname.lastname@example.org, 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 sip:email@example.com will be unconditionally forwarded to sip:firstname.lastname@example.org.
Joe Blow (email@example.com) represents a subscriber on the PBX who has no SIP client. Thus any SIP calls to firstname.lastname@example.org 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 email@example.com, 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 proxy1.hawaii.edu (itself). CSPS then sends the INVITE to the next hop (proxy1.hawaii.edu), 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:
The data in Proxy2's Subscriber table is slightly different than that of Proxy1. The primary difference is that all hawaii.edu SIP clients have CFUNC set to proxy1.hawaii.edu. For example, if a call from the Internet comes in for firstname.lastname@example.org, that call will be forwarded to Proxy1. Please recall that Proxy1 has the registration for hawaii.edu 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 hawaii.edu SIP clients are forwarded to Proxy1. All other calls are forwarded to the gateway.
Gateway/PBX Trunk Provision
At UH, we are using a Cisco 3725 router as a gateway with NM-HDV (High Density Voice Network Module) consisting of:
Voice trunk from the Cisco gateway router to the Nortel PBX is PRI (23 bearer channels + 1 data channel). Thus, the signaling method is ISDN PRI, not analog signaling formats (e.g. FXO/FXS/E&M), not digital T1 with emulated FXO/FXS/E&M, and not T1 CAS (Channel Associated Signaling).
From the gateway's perspective, there are two call legs (span between two voice devices):
The gateway routes traffic to/from the POTS and VoIP call legs by way of dial peers. You can think of dial peers as virtual interfaces through which an incoming and outgoing calls traverse. The gateway chooses the appropriate dial peer by matching the call's digit stream (properly known as information element) against the string defined in the dial peer's 'answer-address' or 'destination-pattern' or 'incoming called-number' commands.
i.e. If a dial peer specifies destination-pattern, then the call's information element is compared against the string defined in the destination-pattern, and if there is a match, then that particular dial peer is used.
When dealing with dial peers, inbound dial peers and outbound dial peers are from the perspective of the gateway router. Thus, calls originating from the PBX/PSTN destined for the SIP client will consist of inbound POTS dial peer and outbound VoIP dial peer. Similarly, calls originating from a SIP client destined for the PBX/PSTN will consist of inbound VoIP dial peer and outbound POTS dial peer.
The inbound dial peer selection is based on matches in the following order:
'Session target' command is ignored in inbound dial peers.
It is important that Direct Inward Dial command be setup in the POTS inbound dial peer. The DID prevents the gateway from presenting a dial tone to the PRI interface, and this makes sense because it is the PBX that collects and passes users' dial string to the gateway. This is called one-stage dialing. The DID also forces gateway to automatically search for a VoIP outbound dial peer using all of the digits that it received from the PBX.
If a destination-pattern command is used in an outbound dial peer, the specified destination-pattern string is compared against the dialed-number (recall, destination-pattern is compared against caller's number in and inbound dial peer). Also, in a POTS outbound dial peer, the matching portion of the dialed string is stripped off and only the excess digits are forwarded to the PBX. For example, suppose the dialed string is 123495551212, and the destination-pattern specification is 12349……., only 5551212 is forwarded to the PBX. Use the command 'no digit-strip' to disable this behavior, or replace the stripped digits with a prefix command. See the sample gateway configuration for examples of these commands and other digit manipulation techniques.
In developing dial peers, it is helpful to lay out the call legs, and for each call leg, list the expected dial strings in each direction. Then apply the 'incoming called-number' or 'destination-pattern' as appropriate.
Relevant portions of gateway configuration:
network-clock-participate slot 2 ! Choose to participate in network clock through slot 2
network-clock-select 1 T1 2/0 ! Set system clocking priority to 1
isdn switch-type primary-dms100 ! PBX switch type (primary-dms100 = PRI to Nortel PBX)
isdn voice-call-failure 0 ! Default cause code for voice call failure
isdn logging ! Enable ISDN event logging
controller T1 2/0 ! Default clock source is line (PBX/PSTN)
pri-group timeslots 1-24 ! Specifies the T1 as PRI time-slots (vs DS0-groups)
description IP-PBX Gateway
description To/From packet network (SIP Proxy Server side)
ip address 10.1.6.20 255.255.255.0
ip access-group no-direct-sip-calls in ! Drop calls from IP side that doesn't come through
! our proxy servers
no ip proxy-arp
ip ospf priority 0
interface Serial2/0:23 ! Configure PRI D channel
description PRI D-Channel
no ip address
isdn switch-type primary-dms100
isdn protocol-emulate network ! Set to 'network' if PBX is set to 'user'
isdn incoming-voice voice ! Treat incoming voice calls as voice (vs data or modem)
isdn T203 30000 ! Max time secs without frames being exchanged, set to 30secs
! to match PBX's T203 timer (default=10secs)
isdn channel-id invert extend-bit
no cdp enable ! Don't run Cisco Discover Protocol
! SIP calls are allowed only from the local proxies.
ip access-list extended no-direct-sip-calls
permit ip host 10.1.6.16 host 10.1.6.20 ! Allow all traffic from the local proxy server
permit ip host 10.1.6.22 host 10.1.6.20 ! Allow all traffic from the local proxy server
deny udp any host 10.1.6.20 eq 5060 log ! Drop any other UDP SIP calls
deny tcp any host 10.1.6.20 eq 5060 log ! Drop any other TCP SIP calls
permit ip any any
voice-port 2/0:23 ! Set the physical voice port characteristics, e.g. echo
! cancellation, timers, etc
dial-peer cor custom ! Custom Class of Restriction (cor); not being used
! Dial peer 101 automatically forwards digit stream in its entirety from the PBX (1-stage dialing)
! for a subsequent match against outgoing VoIP dial peer. The PBX is programmed to route
! only the extensions 60100-60199 to the gateway, so we don't have to worry about
! matching any other dial string.
dial-peer voice 101 pots
description From PBX extensions
application session ! Use 'show call application voice summary' to see the listing.
incoming called-number 601..$ ! $ disables variable length pattern match; the incoming digit
! stream must start with 601 and be exactly 5 digits to match
! this dial peer.
direct-inward-dial ! Turns on the 1-stage dialing
! Dial peer 111 takes the digits forwarded by dial peer 101 and sends the call to the local proxy.
! Dial peer 111 is also used to match incoming calls from the VoIP side (calls made by the
! local SIP UAs destined for the PBX/PSTN. This match is used to determine features such as
! codec type and QoS.
dial-peer voice 111 voip
description To/from local SIP UA
session protocol sipv2
session target dns:proxy1.hawaii.edu ! Used when dial-peer 111 is used as outbound dial peer
! towards the IP network. Session target does not apply
! to inbound dial-peers. Calls originating from inbound
! pots dial peers are transferred to this dial peer and are
! sent to this proxy.
dtmf-relay rtp-nte ! Use Named Telephone Events (NTE) to relay DTMF
! over RTP, as specified in RFC2833 section 3.
! Calls destined for PSTN; by default, outbound pots dial-peers strip off the matching digits
! (123491) in this case and forwards only the excess digits. Thus you need the prefix 91
! "prepended". 1234 represents the access code to the PSTN numbers (91+10 digits)
dial-peer voice 211 pots
description To PSTN toll and toll-free numbers
! Calls destined for local PSTN numbers. 5678 represents the access code to the local PSTN
dial-peer voice 220 pots
description To PSTN local numbers
! Calls destined for PBX extensions. Extensions start with 1 or 2, and are exactly 5 digits long.
! 'no digit-strip' passes all 5 digits to the PBX without stripping off any leading digits.
dial-peer voice 205 pots
description To PBX extensions
In addition to setting up a PRI on the PBX, other configuration changes need to be made on the PBX. These include D-Channel programming, Trunk programming, Route programming, and Distant Steering Code.
You may wish to consider the following Nortel Meridian PBX example and see your friendly neighborhood Telecom Manager/Engineer.
D-Channel Programming considerations:
ADAN DCH 11 ! Config for i/o D-channel 11
DES CISCO ! Description
DCHL 122 ! The PRI card (loop)
IFC SL1 ! Interface (switch type)
SIDE USR ! ISDN side, if set to USR, set the gateway router to Network
Trunk Programming considerations:
DES CISCO ! Description
TN 122 01 ! Terminal block number (loop)
TYPE TIE ! Trunk type
NCOS 5 ! Network Class of Service
RTMP 24 1 ! Route number and member number
Route Data Block Programming considerations:
ROUT 24 ! Route number
DES CISCO ! Description
TKTP TIE ! Trunk type
IFC SL1 ! Interface type for the PRI route
TRMB NO ! Tromboning allowed Yes/No
SIGO STD ! Signaling arrangement
Distant Steering Codes: ! For extensions to the local SIP clients
DSC 6010 ! SIP UA extensions 60100-60109, absence of the last digit is like *
RLI 18 ! Use index 18. TDM users dialing 6010* tells the PBX to lookup RLI
! table to find the destination of the call.
DSC 6011 ! SIP UA extensions 60110-60119, etc.
Route List Index (RLI)
ROUT 24 ! Route number
FRL 0 ! Facility Restriction Level - make sure that this is the same as the
! FRL on the trunk towards the CO
DNS SRV records
SRV records for the public proxy (Proxy2) should be created on the school's domain name server. The DNS record allows external proxy servers to find your proxy server. Proxy1 (private server) should not have a DNS SRV record, however, an A record would be useful for name resolution for local SIP clients.
Please refer to DNS Configuration section of the SIP.edu Cookbook for details on DNS.
SIP Client Configuration
To avoid confusion, the Cisco 79XX hardphone configurations are locked with password. The configuration is gotten from files kept in a TFTP server. Upon bootup, the Cisco hardphones search for a configuration file named SIPmacaddr.cnf, where macaddr is the MAC address of the phone itself.
Many users will be interested in a softphone as a cost-effective entry into the world of SIP. One popular software (freeware) is X-Lite from Xten.com. Below are screen shots of those fields that should be changed to work with the two proxy server architecture.
In the Systems Settings/Network screen:
In the Systems Settings/SIP Proxy/[Default] screen:
In the Advanced System Settings/DTMF Settings screen:
After all of the pieces are in place, a thorough testing should be performed. Consider making the following series of calls and observe Caller ID display, call timeout, and call transfer to voice mail:
Special attention should be paid to the gateway's ACL to make sure it is working properly. For debugging call dialogs, ngrep (easily found on the Internet) is very useful. To troubleshoot problems on a Cisco gateway router, the following debug commands are helpful:
See the Resources section below for links to other debug commands.
University of Hawaii System consists of many campuses located throughout the island chain. Some campuses operate their own email servers within their sub-domain (e.g. uhh.hawaii.edu), and those users are presently not reachable by SIP. Multiple domain support by a proxy server will add significant users to our superset of users.
Some campuses are separated by water and toll charge. We would like to inter-connect these PBXs via VoIP network, thereby increasing the number of SIP reachable users.
CSPS Wish List
Three major features that UH would like to see included in future versions of CSPS are:
IPTEL SIP Tutorial
Cisco Physical and Virtual Voice Interfaces Overview
Cisco IOS Voice Configuration Library, Release 12.3
Cisco Voice Debug Tool (requires CCO Login)
Cisco 3700 Series Routers
Cisco IOS 12.3 Dial Technologies Command Reference