FRRD FR18949 - SIP OPTIONS Ping.doc

Terminology

The verb "shall" indicates the requirement is mandatory for implementation. The verb "may," "might" and "should" indicate the text is recommendation and/or optional for implementation. The verb "will" expresses a future expectation of a requirement, or is used to reference details provided for informational purposes h8.Acronyms

Product Issue Description

In order to build efficient and robust SIP networks, it’s sometimes necessary for one SIP endpoint to know the status of another SIP endpoint. Having this knowledge can better enable intelligent routing of messages when establishing a dialog. This knowledge may also be used to alert network administrators to potential problems with SIP endpoints so that corrective action can be taken to maintain a healthy SIP infrastructure with expected service performance.

The SIP specification defines the REGISTER method that enables a SIP user agent to register with a registrar and to send periodic registration (“refresh”) messages. The purpose for the REGISTER message is to add and remove bindings, though it may also serve as a type of "keep-alive" mechanism to assist in determining whether a user agent is presently available. However, a REGISTER message is not the appropriate method to communicate SIP endpoint status between any two SIP endpoints, such as between two SIP proxy servers or between a Back-to-Back User Agent (B2BUA) and any number of peer B2BUAs that help facilitate communication between administrative domains.

One use of the SIP OPTIONS method is to enable a SIP endpoint to query for the capabilities of a remote SIP endpoint in advance of establishing a dialog, which may help in selecting an appropriate target user agent. By extending the scope of this method it’s possible to enable any SIP endpoint to query for the operational status of another SIP endpoint, thereby achieving the objective of equipping SIP endpoints with more knowledge about the operational status of peer endpoints. 

The use of SIP OPTIONS to determine the operational status of peer SIP endpoints is widely used today by numerous equipment manufacturers and is informally referred to as an “OPTIONS ping”.

Overall Feature Description

FR18949 will provide SIP OPTIONS Ping feature support that will allow a user to configure up to four SIP Gateways for the Dialogic Brooktrout SIP stack.  The Dialogic Brooktrout SIP stack will periodically transmit SIP OPTIONS requests (i.e. ping) each of these SIP Gateways to determine their operational status.  When the highest priority SIP Gateway is determined to be “DOWN” or unavailable to process SIP calls, then the Dialogic Brooktrout SIP stack will automatically route all new outbound SIP calls to the next SIP Gateway in the priority list whose current status is “UP”.

A new Dialogic Brooktrout BFV API function will be introduced as part of this feature to allow BFV applications to receive notification of SIP Gateway status changes along with the most recent responses to SIP OPTIONS Ping requests transmitted by the Dialogic Brooktrout SIP stack.  This new function can be passed a pointer to a callback function that will be invoked whenever an operational status change is detected on any of the SIP Gateways that are configured in the callctrl.cfg configuration file.  In addition to this, if a value of NULL is specified for the callback function pointer when the new BFV API function is called,  the current status of all the configured SIP Gateways will be immediately returned to the application.

Assumptions

• None

Feature Limitations, Caveats, or Restrictions

• None

Customer Use-Case

• • The callctrl.cfg configuration file is populated with 4 SIP Gateway entries and the Boston Host Service is initialized.
  • SIP OPTIONS Ping requests are transmitted to each of the SIP Gateways with a periodic interval defined by the “UP” interval timer parameter specified in the callctrl.cfg configuration file.
  • Each of the SIP Gateways respond to the SIP OPTIONS Ping requests with SIP 200 OKs.
  • A Dialogic Brooktrout BFV application calls the new BFV API function specifying that it wants to be notified of SIP Gateway status changes and passing in a pointer to a callback function.
  • Outbound SIP gateway calls are routed to the SIP Gateway specified by the sip_default_gateway parameter in the callctrl.cfg configuration file.
  • After some time, the SIP Gateway referenced by sip_default_gateway stops responding to the SIP OPTIONS Ping requests.
  • The callback function passed to the new BFV API function is invoked and information is passed to it that indicates that the first SIP Gateway is DOWN but the remaining three SIP Gateways are still UP.
  • SIP OPTIONS Ping requests are transmitted to the SIP Gateway referenced by sip_default_gateway with a periodic interval defined by the “DOWN” interval timer parameter specified in the callctrl.cfg configuration file
  • SIP OPTIONS Ping requests are transmitted to each of the remaining SIP Gateways with a periodic interval defined by the “UP” interval timer parameter.
  • All new outbound SIP gateway calls are now routed to SIP Gateway #2 (the next highest priority SIP Gateway) as specified in the callctrl.cfg configuration file.
  • After some time, the SIP Gateway referenced by sip_default_gateway resumes responding to the SIP OPTIONS Ping requests with SIP 200 OK responses.
  • The callback function passed to the new BFV API function is invoked and information is passed to it that now indicates that all four of the SIP Gateways are “UP”.
  • All new outbound SIP gateway calls are now routed to the SIP Gateway referenced by sip_default_gateway.
  • SIP OPTIONS Ping requests are now transmitted to all of the SIP Gateways with a periodic interval defined by the “UP” interval timer parameter.

Architectural Description

N/A

Requirements

MRD/FR Requirements/Mapping

N/A

Reference List

RFC 3261 - SIP: Session Initiation Protocol (http://www.ietf.org/rfc/rfc3261.txt)

Packetizer Open Community Specification POCS-1 – Using OPTIONS to Query for Operational Status in the Session Initiation Protocol (SIP) (http://hive1.hive.packetizer.com/users/packetizer/pocs/POCS-1.pdf)

Product Areas Affected

• This feature will only affect the SIP protocol.

API/Library Change(s):

• A new BFV API function will be introduced for this feature to allow enabling SIP Gateway Status change notifications as well as reporting information regarding the SIP Gateway status changes.
• New #defines will be added for use with the new BFV API function.
• A new structure will be added for use with the new BFV API function.
• No changes to any 3^rd party components are required for this feature request.

Documentation Change(s)

• The Dialogic Brooktrout Bfv APIs Reference Manual will be updated to document the new BFV API function introduced for this feature and will illustrate how to enable SIP Gateway status change notifications and also how to interpret data returned for a SIP Gateway status change notification.

Configuration Change(s)

The following configuration file changes required to support this feature are as follows:

1. New parameter settings in the callctrl.cfg file to allow users to specify multiple SIP Gateways.
2. A new parameter setting in the callctrl.cfg file to allow users to specify the interval time to send periodic SIP OPTIONS requests when the status of a gateway is “UP”.
3. A new parameter setting in the callctrl.cfg file to allow users to specify the interval time to send periodic SIP OPTIONS requests when the status of a gateway is “DOWN”.

For each of the parameters listed above, there are four items that will be defined in order to provide CONFIGTOOL.EXE support:

1. The name of the parameter that is in the callctrl.cfg file.
2. The long description that goes into the help file for the item.
   (Most of the time the help file is the API documentation)
3. The short description that goes into the ConfigTool form.
4. The tooltip text that's shown when the cursor is over the input or selection box for the item.

The specific information defined for each of the parameters listed above will be defined in the High Level Design document for this feature.

Build and Installation Change(s)

• None

Specific Product Deliverables

*This feature will be implemented on the Windows Linux and Solaris Operating Systems (OSs).  However, testing of this feature will be limited to Windows and Linux OSs.  Testing of this feature on the Solaris OS will not be performed.

Required Purchases

• None

Product SKUs and Materials

• None

Test Scenario(s)

The developer test plan will document the full description of the test cases below along with the results of the developer testing. This testing shall, at a minimum, contain the following test cases: 

• Single SIP Gateway Configured:

This test case verifies that when a user configures the Dialogic Brooktrout SIP Stack with a single SIP Gateway, FR18949 functionality is not enabled and no SIP OPTIONS Ping requests are transmitted. In addition to this, this test verifies that outbound SIP Gateway calls can be successfully established with the configured SIP Gateway.

• Multiple SIP Gateways Configured: All Gateways “UP”

This test case verifies that when a user configures the Dialogic Brooktrout SIP Stack with multiple SIP Gateways, FR18949 functionality is enabled and SIP OPTIONS Ping requests are successfully transmitted to each of the configured SIP Gateways at the specified “UP” interval in the callctrl.cfg configuration file. In addition to this, this test verifies that the new BFV API function  introduced for this feature can be used to successfully return the current status of each of the configured SIP Gateways and that outbound SIP Gateway calls can be successfully established with the highest priority SIP Gateway whose status is “UP”.

• Multiple SIP Gateways Configured: Some Gateways “DOWN”

This test case verifies that when a user configures the Dialogic Brooktrout SIP Stack with multiple SIP Gateways, FR18949 functionality is enabled and SIP OPTIONS Ping requests are successfully transmitted to each of the configured SIP Gateways at the specified “UP” or “DOWN” intervals in the callctrl.cfg configuration file, as appropriate. In addition to this, this test verifies that the new BFV API function  introduced for this feature can be used to successfully return the current status of each of the configured SIP Gateways and that outbound SIP Gateway calls can be successfully established with the highest priority SIP Gateway whose status is “UP”.

• Multiple SIP Gateways Configured: All Gateways “DOWN”

This test case verifies that when a user configures the Dialogic Brooktrout SIP Stack with multiple SIP Gateways, FR18949 functionality is enabled and that, once the status of all of the SIP Gateways is “DOWN”, SIP OPTIONS Ping requests are successfully transmitted to each of the configured SIP Gateways at the specified “DOWN” interval in the callctrl.cfg configuration file. In addition to this, this test verifies that the new BFV API function  introduced for this feature can be used to successfully return the current status of each of the configured SIP Gateways and that outbound SIP Gateway calls immediately fail with an appropriate error returned in the BFV API RES results structure.

Planning Information

Deliverables required during planning

The following development or management process artifacts are required for this feature during planning and Implementation. This should be taken into consideration when developing estimates.

Target Release: SDK 6.7mnt

Backward propagation Release(s): None

Risks: None