Cisco SIP Proxy Server Version 1.0 Administrator Guide
Configuring the Cisco SIP Proxy Server
Downloads: This chapterpdf (PDF - 265.0KB) | Feedback

Configuring the Cisco SIP Proxy Server

Table Of Contents

Configuring the Cisco SIP Proxy Server

Configuring the Cisco SIP Proxy Server Configuration File

Configuring the Server Global Directives

Configuring the Host-Specific Directives

Configuring the Cisco SIP Proxy Server Core Configuration

Configuring Cisco SIP Module Standard Directives

Configuring MySQL Database Subscriber Table Interface

Configuring Number Expansion

Configuring Authentication and Authorization

Configuring Call Forwarding Unconditional

Configuring Registry Services

Configuring E.164 to Request-URI Address Translation

Configuring the GKTMP Interface

Configuring Next Hop Routing

Configuring Numbering Services

Creating the MySQL Subscriber Table

Starting and Stopping the Cisco SIP Proxy Server

Before Starting the Cisco SIP Proxy Server

Starting the Cisco SIP Proxy Server

Stopping and Restarting the Cisco SIP Proxy Server


Configuring the Cisco SIP Proxy Server


This chapter explains how to configure, start, and stop the Cisco SIP Proxy Server; it contains the following information:

Configuring the Cisco SIP Proxy Server Configuration File

Creating the MySQL Subscriber Table

Starting and Stopping the Cisco SIP Proxy Server

Configuring the Cisco SIP Proxy Server Configuration File

You configure the Cisco SIP Proxy Server by defining directives in a main configuration file. The Cisco SIP Proxy Server main configuration file is sipd.conf. A default sipd.conf configuration file is copied into /usr/local/sip/conf/ when installed on Linux platforms and copied into /opt/sip/conf on Solaris platforms. This default configuration file should be customized to your environment.

Before beginning any of the configuration tasks in this chapter, change to the directory in which the sipd.conf file is located and open the file using vi or any text editor.

Similar to the Apache Server, the Cisco SIP Proxy Server directives can be grouped into major categories. The major categories of Cisco SIP Proxy Server directives are:

Server global directives—Define the overall operation of the Cisco SIP Proxy Server. For information on configuring the Cisco SIP Proxy Server global directives, see the "Configuring the Server Global Directives" section.

Host-specific directives—Define the basic configuration of the main Cisco SIP Proxy Server which will respond to requests that are not handled by a virtual host.

The term virtual host refers to maintaining more than one server on one machine, as differentiated by their hostname. For example, companies sharing a web server can have their own domains (www.company1.com and www.company2.com) and access to the web server. Virtual hosts are not supported in Cisco SIP Proxy Server Version 1.0.

For information on configuring the Cisco SIP Proxy Server host-specific directives, see the "Configuring the Host-Specific Directives" section.

Core SIP server directives—Define the primary SIP functionality of the Cisco SIP Proxy Server; SIP message handling. If a core SIP server directive is not specified, the server will use the default. For information on configuring the Cisco SIP Proxy Server core directives, see the "Configuring the Cisco SIP Proxy Server Core Configuration" section.

SIP server module directives—Define the Cisco SIP Proxy Server interfaces and additional functionality on a per module basis. For information on defining the directives for the Cisco SIP Proxy Server modules, see the "Configuring Cisco SIP Module Standard Directives" section.

Configuring the Server Global Directives

The server global directives are generic server directives that define the overall operation of the server. These directives exclude those that configure protocol specific (HTTP or SIP) details. For example, in the global directive section of the sipd.conf file, you can specify the directory in which the Cisco SIP software resides and how child processes of the Cisco SIP Proxy Server will function.


Note The directives that configure the Cisco SIP Proxy Server global environment are standard Apache directives. If the default for an Apache directive has been changed for the Cisco SIP Proxy Server usage, the new default is documented. For more detail on the Apache directives see www.apache.org.


To configure the server global directives, define values as necessary for the following directives:

ServerRoot—Directory in which the Cisco SIP Proxy Server configuration, error, and log files reside (bin/, conf/ and logs/). On Linux, the default directory for these subdirectories is /usr/local/sip. On Solaris, the default directory is /opt/sip. Do not add a forward slash (/) to the end of the directory path.

LockFile—Path to the lockfile used when the Cisco SIP Proxy Server is compiled with either USE_FCNTL_SERIALIZED_ACCEPT or USE_FLOCK_SERIALIZED_ACCEPT. This directive should normally be left at its default value. The main reason for changing it is if the logs directory is NFS mounted, since the lockfile must be stored on a local disk. The PID of the main server process is automatically appended to the filename. The default is logs/accept.lock.

PidFile—Path and file to which the Cisco SIP Proxy Server records its process ID when it is started. If the filename does not begin with a forward slash (/), it is assumed to be relative to the ServerRoot. The default is logs/sipd.pid.

ScoreBoardFile—Memory-mapped file in which to store internal server process information. The ScoreBoardFile is automatically created if your architecture requires it. If this file is automatically created, ensure that no two servers share the same file. The default is logs/apache_runtime_status.

prefork MPM module—How the Cisco SIP Proxy Server child processes will operate. When configured, child processes are monitored. When necessary, additional child processes are spawned to process incoming SIP requests and responses. When the monitor determines that too few requests and responses are taking place, it tears down some of the idle child processes.


Note The maximum and minimum values for the following prefork MPM module directives are dependent on your available platform resources. Modify as required. The prefork module directives are ignored if the ONE_PROCESS environmental variable has been set as specified in the "Before You Begin" section.


To configure the prefork module, specify values for the following directives:

StartServers—Number of child processes to create when the Cisco SIP Proxy Server starts. The default is 5.

MinSpareServers—Minimum number of idle child processes (not handling requests). The default is 5.

MaxSpareServers—Maximum number of idle child processes (not handling requests). Idle child processes that exceed this number are torn down. Do not set this parameter to a large number. The default is 10.

MaxClients—Maximum number of simultaneous requests that can be supported; not more than this number of child processes will be created. The default is 20.

MaxRequestsPerChild—Maximum number of requests that a child process can process. If this number is exceeded, the child process will be torn down. The default is 0.

Listen—Whether the server should listen to more than one IP address or port; by default it responds to requests on all IP interfaces, but only on the port specified in the Port directive.

Configuring the Host-Specific Directives

The host-specific directives define the basic configuration of the Cisco SIP Proxy Server. The basic configuration consists of values used by the main server which responds to requests that are not handled by a virtual host. The host-specific directives define not only the server access and error logs, but with what frequency logs will be rotated as well.


Note The directives that define the basic configuration of the Cisco SIP Proxy Server environment are standard Apache directives. If the default for an Apache directive has been changed for the Cisco SIP Proxy Server usage, the new default is documented. For more detail on the Apache directives see www.apache.org.


To configure the host-specific directives, define values for the following located in the sipd.conf file:

Port—Port on which the Cisco SIP Proxy Server listens. The default is the well known SIP port 5060. If this directive is set to a value less than 1023, the Cisco SIP Proxy Server (sipd daemon) initially must be run as root.

User—Name or number of the user to run the sipd process as when sipd is started by the root user.

Group—Name or number of the group to run the sipd process as when sipd is started by the root user.

ServerName—Hostname of the server used by clients in Request-URIs that is different than the standard name the server would recognize as its own. If this directive is not specified, the server attempts to deduce it from its IP address.

HostnameLookups—Whether client DNS host names or IP addresses are logged. Valid values are on (log host names) or off (log IP addresses). The default is Off.

ErrorLog—Name of the file to which the Cisco SIP Proxy Server will log debug and error messages. The default is logs/error_log.

LogLevel—Verbosity of messages recorded in the error logs. Valid values (in order of decreasing significance) are:

emerg—Emergencies; system is unusable.

alert—Action must be taken immediately.

crit—Critical conditions.

error—Error conditions.

warn—Warning conditions.

notice—Normal but significant condition.

Info—Informational.

debug—debug-level messages.

The default is warn.

LogFormat—Format of the default logfile named by the CustomLog directive.

CustomLog—Name and location of the access log file. The default is logs/access_log common.

TransferLog—With what frequency (in seconds) to rotate Cisco SIP Proxy Server logs without having to tear down the Cisco SIP Proxy Server (sipd daemon). To specify a value for this directive, specify the path to the log file and the rotation time.

You can specify a value similar to /user/local/sip/bin/rotatelogs /usr/local/sip/logs/request_log 86400 in this directive to have access records such as a REGISTER request logged to both the access_log and request_log.0974732040 (number extension is calculated and added base on the current time stamp and the specified rotation frequency). If the CustomLog directive is commented out, access records are logged to the file specified in the TransferLog directive.

Configuring the Cisco SIP Proxy Server Core Configuration

The Cisco SIP Proxy Server core module implements an RFC 2543 compliant SIP server that can function as a redirect, registrar, or proxy server. If configured to be a proxy, the Cisco SIP Proxy Server can be configured to function as a transaction stateful or stateless server.

In addition to the server type, accounting services are configured via the Cisco SIP Proxy Server core module. The Cisco SIP Proxy Server can be configured to generate and forward transaction or call information to a Radius accounting server. This information is forwarded by the Cisco SIP Proxy Server in the form of a Radius Accounting-Request message that contains standard billing information such as the user name, IP address of the proxy server that set up the call, the message status type, type of port, session time, the ID of the end point that was called and the ID of the end point that called. When the accounting services are enabled and the interface to the Radius server is configured, the Cisco SIP Proxy Server will create and send the Accounting Start record to the Radius server when it receives a SIP 200 OK response to an INVITE request. If the Cisco SIP Proxy Server has been configured to turn on the Record-Route field in the initial INVITE request, the server will also process the SIP BYE request that terminates the call. On receiving the BYE request, the server will create and send an Accounting Stop record to the Radius server.

To define the Cisco SIP Proxy Server core configuration, define values for the following directives in the Cisco SIP Proxy Server Core module (mod_sip):

ProxyDomain—DNS domain of the Cisco SIP Proxy Server. The DNS domain suffix must be entered in a standard Fully Qualified Domain (FQDN) format "mydomain.com" or "company.mydomain.com." There is no default for this directive.

StatefulServer—Whether the Cisco SIP Proxy Server will be a transaction stateful or transaction stateless server.

When configured to function as a stateful server, on receiving a SIP request, the Cisco SIP Proxy Server creates a TCB in which it maintains a transaction state.

As a stateful proxy server, from the time a SIP request is received until the final response is one transaction. Stateful proxy servers do not originate any SIP requests except for the SIP CANCEL request or an ACK for a non-200 OK final response. When configured to function as stateless proxy server, the Cisco SIP Proxy Server forwards every request downstream and every response upstream.

As a stateful redirect server, the Cisco SIP Proxy server looks up its registry database on receiving a SIP request and returns a 302 response upstream. As a stateless redirect server, the Cisco SIP Proxy Server returns a final response on receiving any request and does not forward any response or request.

Valid values are On and Off. The default is On.

SipResolveLocalContactsInRedirectMode—Whether to return next hop routing information when the Cisco SIP Proxy Server is configured to function as a redirect server. A redirect server typically returns the contact location it knows about. However, if this directive is set to On, next hop routing will occur and the contact information possibly updated before returning the SIP 3xx response. Valid values are On and Off. The default is Off.

ServerType—Whether the Cisco SIP Proxy Server will function as a proxy or redirect server. As a proxy server, the Cisco SIP Proxy Server will process and route SIP requests. As a redirect server, the Cisco SIP Proxy Server will provide contact information via SIP redirect responses (3xx). Possible values are Proxy and Redirect. The default is Proxy.

UseCallerPreferences—Whether to use user-defined or administrator-defined preferences when handling requests. Request handling preferences are controlled by a server administrator but can be overridden by a UAC. Preferences include decisions such as whether to proxy or redirect a request, whether to fork a request (sequential or parallel), whether to recursively search, and to which URI to proxy or redirect a request. Valid values are On (use user-defined preferences) or Off (ignore user-defined preferences). The default is On.

Recursive—Whether the Cisco SIP Proxy Server will recursively try addresses returned in a SIP 3xx redirection response or use the lowest-numbered address. Valid values are On (the server will recursively try addresses) or Off (the server will use the lowest-numbered response). The default is On.

MaxForks—Maximum number of branches that can be forked when the Cisco SIP Proxy Server is configured to function as a stateful server. The range is 1 to 6. The default is 5.

NumericUsernameInterpretation—Lookup order for numeric user information in the Request-URI header field when the ";user=usertype" parameter missing.

Valid values are:

IP_164—Process the Request-URI entries as URLs first and then as E.164 numbers.

E164_IP—Process the Request-URI entries as E.164 numbers first and then as URLs.

IP—Process the Request-URI entries as URLs only.

E164—Process the Request-URI entries as E.164 numbers.

The default is E164_IP.

NumericUsernameCharacterSet—Set of characters used to determine whether the user information portion of the Request-URI is in a category of users that will be applied to the "NumericUsernameInterpretation" processing step. The default is +0123456789.-() (global phone number combinations). For more information on this directive, see the sipd.conf file.

SrvForFqdnOnly—Whether to perform DNS Server (SRV) lookups only for hosts that are FQDNs. If the host portion of the Request-URI header field does not contain an IP address, but contains a period, the Cisco SIP Proxy Server determines the host to be an FQDN. Valid values are On (perform DNS SRV lookups only on FQDN hosts) or Off (perform DNS SRV lookups for any host that does not contain a target port). The default is Off.

SipT1InMs—Amount of time (in milliseconds) after which a request is first retransmitted. The default is 500.

SipT2InMs—Amount of time (in milliseconds) after which the backoff interval for non-INVITE requests does not increase exponentially. The default is 4000.

SipT3InMs—Amount of time (in milliseconds) the Cisco SIP Proxy Server will wait after receiving a provisional response when processing an INVITE request. The default value is 60000.

SipMaxT3InMs—Maximum amount of time (in milliseconds) the Cisco SIP Proxy Server will wait after receiving a provisional response when processing an INVITE request. The default value is 180000.

SipT4InMs—Amount of time (in milliseconds) that the TCB will be maintained after a final response to a SIP INVITE is proxied. The default is 32000.

MaxInviteRetxCount—Maximum number of times that a SIP INVITE request can be retransmitted by the Cisco SIP Proxy Server. The range is 0 to 6. The default is 6.

MaxNonInviteRetxCount—Maximum number of times that a SIP request other than an INVITE request can be retransmitted. The range is 0 to 10. The default is 10.

SharedMemorySize—Shared memory size to be allocated for transaction control block (TCB). The valid range is 1,024,000 to the maximum DRAM on the machine. The default is 32 MB.

RegistryCleanupRate—Interval (in milliseconds) at which the entries are deleted from the registry. The default is 180000 milliseconds.

AddRecordRoute—Whether the Cisco SIP Proxy Server will add the Record-Route header field to an initial SIP INVITE message. The Record-Route header field contains a globally reachable Request-URI that identifies that proxy server. When a proxy server adds the Request_URI to the Record-Route field in SIP messages, the proxy server will be kept in the path of subsequent requests for the same call leg. Valid values are On (add the Record-Route field) and Off (do not add the Record-Route field). The default is Off. The ServerType directive must be set to Proxy for this directive to be applied.

Sip_Token_Port—Port that will be used by the sychronization server on the Cisco SIP Proxy Server. This port must be the same for all servers in a farm.The default is 22794.

Sip_Services_Port—Port on the sychronization server. The default is 52931.

Accounting—Whether or not the SIP server will log accounting information on a Radius account server. Possible values are On (accounting is enabled) and Off (accounting is disabled). The default is Off.

AccountingRecordFormat—Record format being used to log accounting information. The valid value is Radius.

PrimaryRadiusAcctIp—IP address or host name of the primary Radius server to be used for accounting.

PrimaryRadiusAcctPort—Destination port number of the primary Radius server to be used for accounting.

PrimaryRadiusAcctSecret—Secret text string shared between the Cisco SIP Proxy Server and the primary Radius account server.

SecondaryRadiusAcctIp—IP address or host name of the secondary Radius server to be used for accounting.

SecondaryRadiusAcctPort—Destination port number of the secondary Radius server to be used for accounting.

SecondaryRadiusAcctSecret—Secret text string shared between the Cisco SIP Proxy Server and the secondary Radius account server.

UseIpAddrInPathHeaders—Whether the server will use its IP address or FQDN in the Via and Record-Route header fields. Possible values are On (use the IP address) and Off (use the FQDN). The default is On.

IPAddrInPathHeaders—Which IP address will be used in the Via and Record-Route header fields when the UserIpAddrInPathHeaders field is set to On. If an address is not defined in this directive, the first value returned via gethostbyname is used.

IgnoreProxyRequire—Proxy-sensitive feature that can be ignored when servicing clients.

SIPStatsLog—Whether the Cisco SIP Proxy Server will print statistics to the stats_log file. The default is On.

SIPStatsInterval—Interval (in seconds) at which statistics are logged. The default is 3600.

DebugFlag—Whether to enable the printing of mod_sip module debug messages to logs/error_log. Valid values are StateMachine On (print messages) or StateMachine Off (do not print messages). The default is StateMachine Off.

Configuring Cisco SIP Module Standard Directives

The Cisco SIP Proxy Server contains eight additional modules that can be used to configure a variety of interfaces and additional features. The following sections describe the interfaces and services you can configure on your Cisco SIP Proxy Server via modules:

Configuring MySQL Database Subscriber Table Interface

Configuring Number Expansion

Configuring Authentication and Authorization

Configuring Call Forwarding Unconditional

Configuring Registry Services

Configuring E.164 to Request-URI Address Translation

Configuring the GKTMP Interface

Configuring Next Hop Routing

Configuring Numbering Services

Configuring MySQL Database Subscriber Table Interface

The Cisco SIP Proxy Server MySQL module (mod_sip_db_mysql) provides the ability to configure an interface to a MySQL database subscriber table to maintain subscriber records for user authentication, authorization, and accounting purposes.

If a MySQL database subscriber table exists in your network, you can use directives in the MySQL module to map the field names used by the Cisco SIP Proxy Server to those used in the MySQL database subscriber table. If a MySQL subscriber table does not already exist in your network, you must create one using the subscriber.sql script before starting the Cisco SIP Proxy Server with the MySQL interface enabled. For information on creating a subscriber table using the subscriber.sql script, see the "Starting and Stopping the Cisco SIP Proxy Server" section.


Note When ";user=phone," the "user" portion of the From header field in the SIP URL is used as the key to query the MySQL database. When ";user=IP," the "user" portion of the From header field, the "@" symbol, and the value specified in the "ProxyDomain" directive in the sipd.conf file are used as the key to query the MySQL database.


To configure the interface to the MySQL database subscriber table and map field names used by the Cisco SIP Proxy Server to an existing MySQL subscriber table, specify values for the following directives in the mod_sip_db_mysql module:

DB_MySQL—Enable or disable the interface to the MySQL database. Enabling the interface will establish a TCP connection with the database. Valid values are On (enable the interface) or Off (disable the interface). The default is Off.

DB_MySQL_HostName—Host name or IP address of the machine on which the MySQL database resides.

DB_MySQL_DB—Name of the database in which the subscriber table is stored and maintained.

DB_MySQL_Username—Login username to the database account.

DB_MySQL_Password—Login password to the database account.

DB_MySQL_SubscriberTable—Name of the table in which the subscriber entries will be stored.

DB_MySQL_XXX_Field—Name equivalent in an existing MySQL database subscriber table. Use these directives as necessary to map the field names being used by the Cisco SIP Proxy Server to the equivalent entry in an existing MySQL subscriber table.

DebugFlag—Whether to enable the printing of all mod-sip-db-mysql debug messages to logs/error_log. Valid values are DBMySQL On (print messages) or DBMySQL Off (do not print messages). The default is DBMySQL Off.


Note For information on working with MySQL databases, see www.mysql.com.


Configuring Number Expansion

The Cisco SIP Proxy Server Version 1.0 supports global number expansion plans. To use number expansion plans, first you must enable the function and then define the global number expansion plan.

Enabling or Disabling Number Expansion

To enable number expansion, specify values for the following directives in the Number Expansion module (mod_sip_numexpand) module:

Cisco_Numexpand—Whether to use number expansion on the Cisco SIP Proxy Server. Valid values are On (use number expansion) or Off (do not use number expansion). The default is Off.

Cisco_Numexpand_DEBUG—Whether to enable the printing of all number expansion-related debug messages. Valid values are On (print messages) or Off (do not print messages). The default is Off.

Configuring the Numbering Plan

After enabling number expansion, define the global number plan. When defining a number plan, note that you can use the period (.) as an "any character" wildcard and the asterisk (*) as a "one or more character" wildcard.

To define the global number plan:


Step 1 Start the number plan by assigning it a unique identifier by specifying the following:

<Number ID>

where ID is the unique identifier of the number plan (for example, global).

Step 2 Specify each number plan using one of the following NumExp directives:

NumExp 2....

NumExp 6....

NumExp 7....

NumExp 4....

NumExp 3....

NumExp 5....

Step 3 End the plan by specifying the following:

</NumberPlan>


The following is an example of a global number expansion plan:

<NumberPlan mycompany.com>
    NumExp    2....    +1919555....
	    NumExp    6....    +1408554....
    NumExp    7....    +1408553....
    NumExp    4....    +1978555....
    NumExp    3....    408556
</NumberPlan>

Configuring Authentication and Authorization

Authentication directives in the Cisco SIP Proxy Server Authentication module (mod_sip_authen) ensure that users are authenticated before a transaction is serviced by the Cisco SIP Proxy Server. Authentication between an end point and the Cisco SIP Proxy Server may be provided via HTTP Digest Authentication (described in RFC 2617) or via CHAP-Password.

By default, all users who are authenticated, are authorized. Pre-configured subscriber records stored in a subscriber table in a MySQL database define the types of services for which a user is authorized.

To enable authentication and authorization, specify values for the following directives in the mod_sip_authen module:

Authentication—Whether the proxy server will require users be authenticated before servicing their transactions. Valid values are On (user must be authenticated) or Off (user does not have to be authenticated). The default is Off.

AuthRealm—Realm used in authentication response headers. The default is Cisco.

AuthScheme—Type of authentication method to be used when users are required to obtain authentication before receiving service from the Cisco SIP Proxy Server. Possible values are HTTP_Digest or HTTP_CHAP. The default is HTTP_Digest.

RadiusAuthSkew—Amount of time (in seconds) that a challenge is valid. The default is 30.

PrimaryRadiusAuthIp—IP address or host name of the primary Radius server to be used for user authentication.

PrimaryRadiusAuthPort—Destination port number of the primary Radius server to be used for user authentication.

PrimaryRadiusAuthSecret—Secret text string shared between the Cisco SIP Proxy Server and the primary RADIUS authentication server.

SecondaryRadiusAuthIp—IP address or host name of the backup Radius server to be used for user authentication.

SecondaryRadiusAuthPort—Destination port number of the backup Radius server to be used for user authentication.

SecondaryRadiusAuthSecret—Secret text string shared between the Cisco SIP Proxy Server and the backup Radius authentication server.

Configuring Call Forwarding Unconditional

The Cisco SIP Proxy Server Call Forwarding module (mod_sip_call_forward) enables or disables call forwarding functionality on your Cisco SIP Proxy Server.


Note Call forwarding support requires a MySQL database.


To configure call forwarding support on your Cisco SIP Proxy Server, specify values for the following directives located in the mod_sip_call_forward module:

CallForwardUnconditional—Whether to forward calls unconditionally. Possible values are On (forward calls unconditionally) or Off (do not forward calls unconditionally).

CallForwardNoAnswer—Whether to forward calls when a call is not answered. Possible values are On (forward calls when a call is not answered) or Off (do not forward calls when a call is not answered).

CallForwardBusy—Whether to forward calls when a SIP 486 Busy Here response is received. Possible values are On (forward calls) or Off (do not forward calls).

CallForwardUnavailable—Whether to forward calls when a UAC is unavailable. Possible values are On (forward calls) or Off (do not forward calls).

CallForwardNoAnswerTimer—Time (in milliseconds) after which to forward a call when a call goes unanswered. The default is 24000. The setting for this directive is valid only when the CallForwardNoAnswer directive is set to On.

CallForwardUnavailableTimer—Time (in milliseconds) after which to forward a call when a UAC is unavailable. The default is 24000. The setting for this directive is only valid when the CallForwardUnavailable directive is enabled.

AddDiversionHeader—Whether the CC-Diversion header will be included in the SIP messages. Inclusion of the CC-Diversion header enables conveying call-redirection information during a call setup phase. Possible values are On (include the CC-Diversion header) and Off (exclude the CC-Diversion header). The default is On if call forwarding is enabled.

Configuring Registry Services

The Cisco SIP Proxy Server Registry module (mod_sip_registry) enables the Cisco SIP Proxy Server to process requests from UACs that have been configured to register their location. When registry services have been configured, the Cisco SIP Proxy Server can:

Add a new registration

Delete an existing registration

Update an existing registration

Delete all registrations of a user

Return a current list of registrations of a user

Periodically purge dated or expired registrations

Enabling for Disabling Registration Services

To enable the registry services and establish a registration database, define values for the following directives in the mod_sip_registry module:

Cisco_Registry—Whether registry services are enabled or disabled on the Cisco SIP Proxy Server. Possible values are On (function as a registrar server) or Off (do not function as a registrar server).

Cisco_Registry_Shared_Memory_Address—Memory location of the registration table. The default is the platform address.

Cisco_Registry_Rendezvous_Name—Rendezvous name of the database containing registration information. The default is a null value.

Cisco_Registry_Rendezvous_Directory—Location of the registration database.

Cisco_Registry_Remote_Update_Port—Port number of the registration database server for all members of a farm of servers. The value for this directive must be the same for all members of the farm. The default is 22913.

Cisco_Registry_Farm_Members—Names of the Cisco SIP Proxy Servers that you wish to be members of the farm of Cisco SIP Proxy Servers. This list must be defined the same on all of the Cisco SIP Proxy Servers identified as part of a farm.

Cisco_Registry_Max_DB_Age_on_Boot—Maximum age (in seconds) of the database backing store file when starting. If the age of the database backing store file exceeds this age, the file will be deleted. The default is 86400. The value specified in this directive must be greater than that specified in the RegistryCleanupRate core directive.

DebugFlag—Whether to enable the printing of mod_sip_registry module debug messages to logs/error_log. Valid values are Registry On (print messages) or Registry Off (do not print messages). The default is Registry Off.

Configuring Static Registry Contact Entries

After enabling registry services, define a registry entry for each default contact point for each user. The registry entries you define will preconfigure the registry database. When defining a registry contact entry, use the period (.) as an "any character" wildcard and the asterisk (*) as a "one or more character" wildcard.

To configure a registry contact entry:


Step 1 Start the registry entry by assigning it a unique identifier by specifying the following:

<StaticRegistry ID>

where ID is the unique identifier of the registry entry.

Step 2 Define values for the following directives:

Static_Registry_User_Type—Type of destination pattern for the entry. Valid values are IP and PHONE. The default is IP.

Static_Registry_User—Registration key.

Static_Registry_Contact—Default contact point for the user indicated in the Static_Registry_User directive. Valid value is user@FQDN or user@ipaddress.

Static_Registry_Contact_User_Type—Type of contact point for the user defined in the user portion of the value in the Static_Registry_Contact directive. Possible values are IP or PHONE. If a value is not specified, the lookup order specified in the NumericUsernameInterpretation directive will be used to determine the type of the contact point.

Static_Registry_ContactPort—Port on the contact point to be used. The default is 5060.

Static_Registry_TransportProtocol—Transport protocol to use when contacting this contact. The valid value is UDP.

Static_Registry_ContactAge—Amount of time (in Unix time of seconds since 1970) this contact registry entry is valid. Valid values are amount of time specified in seconds or Permanent. The default is Permanent.

Static_Registry_Delete_or_Add—Whether to add or delete this registry entry. Possible values are ADD or DELETE. The default is ADD.

Step 3 End the entry by specifying the following:

</StaticRegistry>


The following is an example of a registry entry for an IP phone:

<StaticRegistry 10.1>
Static_Registry_User_Type           IP
Static_Registry_User                jdoe
Static_Registry_Contact             0015155551212@mycompany.com
Static_Registry_Contact_User_Type   PHONE
Static_Registry_ContactPort         5060
Static_Registry_TransportProtocol   UDP
Static_Registry_ContactAge          Permanent
Static_Registry_Delete_or_Add       ADD
</StaticRegistry>

Configuring E.164 to Request-URI Address Translation

The ENUM module (mod_sip_enum) is a translation module that enables the Cisco SIP Proxy Server to translate an E.164 number (or any number in a number plan) into a list of Request-URIs via DNS lookup.

To enable ENUM translation, define values for the following directives located in the mod_sip_enum module:

Cisco_Enum—Whether E.164 to Request-URI translation is enabled. Possible values are On (translate) or Off (do not translate). The default is On.

Cisco_Enum_Domain—Private search domain for a private ENUM number plan. If a Request-URI user begins with the plus (+) character, this directive is not used because the plus character indicates that the number is part of a global ENUM number plan, which is e164.arpa.

Cisco_Enum_Global_Domain—Domain to use when the Request-URI user begins with a plus (+) character (indicating a global domain) or to use when a value is not specified for the Cisco_Enum_Domain directive. The default is to use e164.arpa.

DebugFlag—Whether to enable the printing of mod_sip_enum API debug messages to logs/error_log. Valid values are Enum On (print messages) or Enum Off (do not print messages). The default is Enum Off.

Configuring the GKTMP Interface

The Cisco SIP Proxy Server GKTMP interface module (mod_sip_gktmp) is a translation module that enables the Cisco SIP Proxy Server to translate SIP PDUs to the GKTMP protocol for LNP lookups, 1-800 and 1-900 number translations, and end-point resolutions. When the GKTMP interface is configured, as Cisco SIP Proxy Server processes are started, the processes will initiate a TCP connection with a Network Application Manager (NAM) server via the GKTMP interface.

To configure the GKTMP interface, specify values for the following directives located in the mod_sip_gktmp module:

GktmpConnection—Whether the GKTMP interface is enabled or disabled. Possible values are On (interface is enabled) or Off (interface is disabled). The default is Off.

MasterServerHostname—Hostname of the primary NAM server.

MasterServerIpAddress—IP address of the primary NAM server.

MasterServerPort—Destination port number of the primary NAM server to be used for 800/900 and LNP lookup services.

SecondaryServerHostname—Hostname of the secondary NAM server.

SecondaryServerIpAddress—IP address of the secondary NAM server.

SecondaryServerPort—Destination port number of the secondary NAM server.

Debug Flag—Whether to enable the printing of mod_sip_gktmp module debug messages to logs/error_log. Valid values are Gktmp On (print messages) or Gktmp Off (do not print messages). The default is Gktmp Off.

DebugFlag—Whether to enable the printing of mod_sip_gktmp API debug messages to logs/error_log. Valid values are Gktmp API On (print messages) or GktmpAPI Off (do not print messages). The default is GktmpAPI Off.

Configuring Next Hop Routing

The Cisco SIP Proxy Server Routing module (mod_sip_routing) provides the ability to perform next hop E.164 lookups for final Request-URIs via static route entries. The static routes are configured by parsing directives such as the destination pattern, transport protocol, and target address into a table entry that can be retrieved by the Cisco SIP Proxy Server when necessary.

Enabling Next Hop Routing

To enable next hop routing and establish a routing database, define values for the following directives in the mod_sip_routing module:

Cisco_Routing—Whether next hop routing is enabled or disabled on the Cisco SIP Proxy Server. Possible values are On (next hop routing is enabled) or Off (next hop routing is disabled). The default is On.

Cisco_Routing_Shared_Memory_Address—Memory location of the routing table. If the value of this directive is a null value, the default address of the platform will be used.

Cisco_Routing_Rendezvous_Name—Rendezvous name of the database containing routing information. The default is a null value.

Cisco_Routing_Rendezvous_Directory—Location of the routing database.

Cisco_Routing_Remote_Update_Port—Port number of the routing database server for all members of a farm of servers. The value for this directive must be the same for all members of the farm. The default is 22913.

Cisco_Routing_Use_Domain_Routing—Whether to use domain next hop routing. Domain next hop routing uses the host portion of the Request-URI as the key in obtaining the next hop or hops for a request. Valid values are On (use domain routing) or Off (do not use domain routing). The default is Off.

Cisco_Routing_Max_DB_Age_on_Boot—Maximum age (in seconds) of the database backing store file when starting. If the age of the database backing store file exceeds this age, the file will be deleted. The default is 0.

DebugFlag—Whether to enable the printing of all mod-sip-routing module debug messages to logs/error_log. Valid values are Routing On (print messages) or Routing Off (do not print messages). The default is Routing Off.

Configuring Static Route Entries

After enabling next hop routing, define a route for each single next hop. When defining a static route entry, use the period (.) as an "any character" wildcard and the asterisk (*) as a "one or more character" wildcard.

To configure a static route entry:


Step 1 Assign the route entry a unique identifier by specifying the following:

<StaticRoute ID>

where ID is the unique identifier of the route entry.

Step 2 Define values for the following directives:

Static_Route_DestinationPattern—Destination pattern for the route. The value in this field depends on the route type defined in the Static_Route_Type directive.

For E.164 numbers, this is an International Direct Dial (IDD) that has trailing digits represented by a period (.) as the wildcard digit. The length of the IDD and the number of wildcard digits are specific to the dial plan they represent. For example, each wildcarded IDD destination pattern that has a different length will be a unique dial plan.

An example of an E.164 destination pattern is "+1555666...." which dictates to match all number in the United States at area code 555 with a 666 exchange. If the + did not begin the pattern, it would not be internationally unique.

Static_Route_Type—Type of destination pattern. Valid values are IP or PHONE. The default is IP.

Static_Route_NextHop—Next hop for the destination pattern defined in the Static_Route_DestinationPattern directive. Valid values are the FQDN or IP address of the next hop.

Static_Route_NextHopPort—Port on the next hop to be used. The default is 5060.

Static_Route_TransportProtocol—Transport protocol to use for this route. The valid value is UDP.

Static_Route_Priority—Priority of this static route. This value is a 16-bit integer. The route with the lowest priority will be used over a route with a higher priority. The default is O.

Static_Route_Weight—Weight of this static route. The higher the weight, the higher the probability of selection. This value is a 16-bit integer. The default is 0.

Static_Route_Delete_or_Add—Whether to add or delete this static route entry. Valid values are Add or Delete. The default is Add.

Step 3 End the entry by specifying the following:

</StaticRoute>


The following is an example of a static route definition:

<StaticRoute 1>
Static_Route_Destination Pattern          001555666....
Static_Route_Type                         PHONE
Static_Route_NextHop                      sip_gw1.mycompany.com
Static_Route_NextHopPort                  5060
Static_Route_TransportProtocol            UDP
Static_Route_Delete_or_Add                Add
</StaticRoute>

Configuring Numbering Services

Enabling Numbering Services

To enable the number services functionality and establish a number services database, define values for the following directives located in the mod_sip_numserv module:

Cisco_Number_Services—Whether or not numbering services is enabled or disabled on the Cisco SIP Proxy Server. Possible values are On (enabled) or Off (disabled).

Cisco_Number_Services_Shared_Memory_Address—Memory location of the number services table. The default is the platform address.

Cisco_Number_Services_Rendezvous_Name—Rendezvous name of the number services database. The default is numserv_db.

Cisco_Number_Services_Rendezvous_Directory—Location of the number services database.

Cisco_Number_Services_Remote_Update_Port—TCP port number of the number services for all members of a farm of servers. The value for this directive must be the same for all members of the farm. The default is 22913.

Cisco_Number_Services_Max_DB_Age_on_Boot—Maximum age (in seconds) of the database backing store file when starting. If the age of the database backing store file exceeds this age, the file will be deleted. The default is 0.

DebugFlag—Whether to enable the printing of all mod_sip_numserv module debug messages to logs/error_log. Valid values are Numserv On (print messages) or Numserv Off (do not print messages). The default is Numserv Off.

Configuring Static Numbering Service Entries


Step 1 Assign the special number entry a unique identifier by specifying the following:

<Number_Services ID>

where ID is the unique identifier of the number service being defined.

Step 2 Define values for the following:

Number_Services_Contact—Special number for which you are configuring a target route. For example, 911 or 411.

Number_Services_Priority—Priority level for the special number. Possible values are Emergency or Normal.

Step 3 Begin the definition of the static route for the special number by specifying the following:

<Static_Number_Services_Route ID>

where ID is the unique identifier for the special number static route.

Step 4 Define values for the following:

Static_Number_Services_Route_Target—IP address or FQDN of the gateway to process calls that match this number.

Static_Number_Services_Route_OriginationPattern—Origination pattern to match caller digits.

Static_Number_Services_TransportProtocol—Protocol to be used to contact target. The valid value is UDP.

Static_Number_Services_ContactPort—Port on target to process call. The default is 5060.

Step 5 End the static route for the special number by specifying the following:

</Static_Number_Services>

Step 6 End the special number entry by specifying the following:

</Number_Services>


The following is an example of a special number and static route entry:

<Number_Services 1>
Number_Services_Contact                          911
Number_Services_Priority                         EMERGENCY
<Number_Services_Route 10>
Static_Number_Services_Route_Target              proxyserver@company.com
Static_Number_Services_Route_OriginationPattern  515555
Static_Number_Services_TransportPortocol         UDP
Static_Number_Services_ContactPort               5060
</Number_Services_Route>
</Number_Services>

Creating the MySQL Subscriber Table

If a subscriber table does not already exist in your MySQL database, you can use the subscriber.sql file located in the user/local/sip/conf directory on Linux or the opt/local/sip/conf directory on Solaris to create one via cut and paste.

A MySQL subscriber table for populating SIP subscriber records must be created before the Cisco SIP Proxy Server is turned on with the MySQL module (mod_sip_db_mysql) turned on.


Note When ";user=phone," the "user" portion of the From header field in the SIP URL is used as the key to query the MySQL database. When ";user=IP," the "user" portion of the From header field, the "@" symbol, and the value specified in the "ProxyDomain" directive in the sipd.conf file are used as the key to query the MySQL database.


For information on configuring the interface to the MySQL database, see the "Configuring MySQL Database Subscriber Table Interface" section.


Note For information on working with MySQL databases, see www.mysql.com.


To create the MySQL subscriber table:


Step 1 Using a text editor, open the subscriber.sql file. This file is located in the /user/local/sip/conf directory on Linux platforms and in the opt/local/sip/conf directory on the Solaris platforms.

Step 2 Copy the contents of the file (you will paste the contents at a MySQL prompt as described in Step 4).

Step 3 Telnet to the machine on which your network MySQL database resides.

Step 4 At the MySQL command prompt, paste the contents of the subscriber.sql file and press Enter.

Starting and Stopping the Cisco SIP Proxy Server

There are a number of ways that you can start and restart the Cisco SIP Proxy Server. The following sections describe the different methods of starting the Cisco SIP Proxy Server and environment variables that must be set and conditions that need to be met before starting the server.

Before Starting the Cisco SIP Proxy Server

Before you start the Cisco SIP Proxy Server, ensure that the environment variables are set and the conditions are met as listed below:


Note Preparing to install, installing, and configuring the Cisco SIP Proxy Server requires a working knowledge of Unix commands and Unix shells.



Note The following procedures assume that the server software has been installed in the default location. If you vary the installation, modify the paths appropriately.


1. To run the sipd directly on Linux, the LD_LIBRARY_PATH environment variable is set as follows:

If you use the sh/ksh/zsh/bash:

export LD_LIBRARY_PATH=/usr/local/sip/libexec

If you use csh/tsh:

setenv LD_LIBRARY_PATH /usr/local/sip/libexec

To run the sipd directly on Solaris, the LD_LIBRARY_PATH environment variable is set as follows:

If you used the sh/ksh/zsh/bash:

export LD_LIBRARY_PATH=/opt/sip/libexec

If you used csh/tcsh:

setenv LD_LIBRARY_PATH /opt/sip/libexec


Note Setting the LD_LIBRARY_PATH environment variable is not necessary if you run the sipctl script.


2. The Cisco SIP Proxy Server can be run with a single non-daemon process (single-process mode) or with multiple daemon processes (multi-process mode).

Single-process mode is typically used for debugging and troubleshooting purposes only. When in multi-process mode, the SIP message traces are logged in the logs/error_log file. To enable message traces in either single-process or multi-process mode, set the DebugFlag StateMachine directive in the sipd.conf file to On in the sipd.conf file. The default location of the sipd.conf file is /usr/local/sip/conf/sipd.conf (on Linux) and /opt/sip/conf/sipd.conf (on Solaris).

To run the Cisco SIP Proxy Server in single-process mode, you need to set the ONE_PROCESS environment variable as follows:

If you used the sh/ksh/zsh/bash:

export ONE_PROCESS=true

If you used csh/tcsh:

setenv ONE_PROCESS true

3. If you untarred the Cisco SIP Proxy Server distribution as a root user, ensure you have the correct permissions set to the /usr/local/sip directory (on Linux) or the /opt/sip directory (on Solaris) so that the user who starts the sipd process will have write permissions to the subdirectories under /usr/local/sip (on Linux) or under /opt/sip (on Solaris).

Starting the Cisco SIP Proxy Server

To start the Cisco SIP Proxy Server, issue the following command from the Cisco SIP Proxy Server directory (on Linux, the default location is /usr/local/sip/bin; on Solaris, the location is /opt/sip/bin):

./sipd

No activity will appear if the server initializes without error. However, if errors occur when the Cisco SIP Proxy Server initializes, error messages will display on the screen.

As an alternative, you can use the sipdctl shell script to start the Cisco SIP Proxy Server by issuing the following command from the server directory:

./sipdctl start

Stopping and Restarting the Cisco SIP Proxy Server

Using the sipdctl shell script, there are three ways you can stop and restart the Cisco SIP Proxy Server; hard stop, stop children but not parent, and graceful stop and restart.

Stopping the Cisco SIP Proxy Server

To tear down all Cisco SIP Proxy Server children and then the sipd parent process, issue the following command from the server directory:

./sipdctl stop

Starting the Cisco SIP Proxy Server

To start the sipd process, issue the following command from the server directory:

./sipdctl start

Gracefully Stopping and Restarting the Cisco SIP Proxy Server

To prompt the Cisco SIP Proxy Server parent process (sipd) to tear down child processes as those processes become idle, reread the configuration file, and then spawn new children processes, issue the following command from the server directory:

./sipdctl graceful