SIP Session Agents

Session Agent Status Based on SIP Response

The Oracle® Enterprise Session Border Controller can take session agents out of service based on SIP response codes that you configure, and you can also configure SIP response codes that will keep the session agent in service.

With this feature disabled, the Enterprise SBC determines session agents’ health by sending them ping messages using a SIP method that you configure. Commonly, the method is an OPTIONS request. If it receives any response from the session agent, then the Enterprise SBC deems that session agent available for use.

However, issues can arise when session agents are administratively out of service, but able to respond to OPTIONs requests. A session agent like this might only respond with a 200 OK when in service, and send a 4xx or 5xx message otherwise.

The session agent status feature lets you set the SIP response message that either takes a session agent out of service or allows it to remain in service when it responds to the Enterprise SBC’s ping request.

Details of this feature are as follows:

The Enterprise SBC only considers a session agent in service when it responds to a request method you set with the final response code that you also set. If a final response code is set, then provisional responses are not used for determining whether or not to take a session agent out of service. If the Enterprise SBC receives a final response code that does not match the session agent configuration, it treats the session agent as though it had not responded.
The Enterprise SBC takes a session agent out of service when it receives an error response for dialog creating request with a response code listed in the new out-service-response-codes parameter.

In the case where the session agent’s response has a Retry-After header, the Enterprise SBC tries to bring the session agent back into service after the period of time specified in the header. To do so, it sends another ping request.

There are two lists you can configure in the session agent configuration to determine status:

In-service list—Set in the ACLI ping-in-service-response-codes parameter, this list defines the response codes that keep a session agent in service when they appear in its response to the Enterprise SBC’s ping request. Furthermore, the Enterprise SBC takes the session agent out of service should a response code be used that does not appear on this list.
Out-of-service list—Set in the ACLI out-service-response-codes parameter, this list defines the response codes that take a session agent out of service when they appear in its response to the Enterprise SBC’s ping request or any dialog-creating request.

When the Enterprise SBC receives a session agent’s response to its ping request, it first checks to see if there is an in-service list of responses configured for that session agent. If the list is configured and the Enterprise SBC determines that there is a match, the session agent is deemed in service. Otherwise it takes the session agent out of service. In this way, the in-service list takes precedence over the out-of-service list. If you configure the in-service list, then the Enterprise SBC ignores the out-of-service list.

If there is no list of in-service responses for the session agent, then the Enterprise SBC checks the out of service list. If it is configured and the Enterprise SBC determines that there is a match, the Enterprise SBC removes that session agent from service. If there is no match, then the session agent is deemed in service.

SIP Pings from Multiple Realms to Global SAs

You can configure the Enterprise SBC to send SIP OPTION pings to multiple physical agents through multiple realms using a global session-agent (SA). This feature monitors status of global SA targets on the system, supporting applicable deployments including UCaaS topologies that include multiple tenancies. You enable this feature by configuring the session-agent to act as a global session agent, and each realm to support status monitoring.

You can configure a global session-agent to operate with multiple physical agents instead of a single physical agent using DHCP and/or target lists. This creates a list of targets that can reside in multiple realms for forwarding. Using global session agents can cause problems when the target devices reside in multiple networks, some of which might not be reachable. If the system is unaware of the status of each physical device, it cannot reliably handle all calls to or from each device. You can resolve these problems using this feature.

Note:

This feature can impact system performance due to the system issuing multiple OPTIONS instead of a single OPTION. You can mitigate any performance issues using the ping-interval and contacting Oracle support.

With or without this feature, the Enterprise SBC supports multi-tenancy use cases using nested realms and/or multiple realms. But by default, the Enterprise SBC cannot show the status of the physical session agents devices connected to each realm correctly. Even though a physical session agent might be active, the Enterprise SBC may show it as inactive. Option pings are needed to monitor this status.

This feature allows global session agents to support SIP ping options for both a single SIP interface with nested realms and for multiple realms using their own separate sip-interface:

Nested Realms—These can be multiple child realms within a single parent realm as a hierarchical realm group. In this case, the sip-interface is associated with the parent realm only.
Multiple Realms/sip-interfaces—These are similar to nested realms, with the exception that each customer hosted on the Enterprise SBC is separated, using their own realm, sip-interface, certificate record and so forth.

Feature configuration includes configuring a session-agent as a global Session Agent and defining the list of multiple physical target devices:

Wildcarded (*) realm-id:
- Set the realm-id parameter to the wildcard (*) character. This establishes the element as a global session agent.
- Configure the egress-realm-id with the list of realms that comprise all tenancies. The system sets all realms in the list to an equal priority, ensuring the system sends the ping tests out every realm.
- Enable the ping-method, ping-interval, and ping-all-address configurations.
Using this configuration, the session-agent presents all the egress realms to the system, which pings the physical global session agent through those realms.
FQDN for hostname:
- Configure the hostname parameter with an FQDN.
- Enable ping-method, ping-interval, and ping-all-address configurations.
When the hostname resolves to multiple IP addresses, the system sends SIP OPTIONS via all applicable realms to all the IPs resolved for that hostname.
IP address in address for Nested Realms:
- Configure the egress-realm-id with the list of realms that comprise all tenancies. The system sets all realms in the list to an equal priority, ensuring the system sends the ping tests out every realm.
- Configure the address with a single IP address.
- Enable ping-method, ping-interval, and ping-all-address configurations.
This configuration results in the SA sending out Options from all realms to that IP.

Note:

The system throws a verify-config error if you set an egress-realm-id parameter with a non-existent realm.

All of these configurations allow the Enterprise SBC to use SIP ping (keepalives) between a global session-agent and multiple realms. The system then tracks responses from the target agents in each realm. This information allows the architecture to monitor connection health between the Enterprise SBC and all customer tenancies during call processing.

In addition to status monitoring, the feature supports vendor deployment requirement of multi-tenant UCaaS environments, such as MSFT Teams and Cisco Webex, that require your SIP pings contain the FQDN of the Enterprise SBC in a contact header. Those infrastructures use the FQDN to determine the next hop when sending outbound ping responses. You configure the Enterprise SBC for this on a per-realm basis by setting the multi-tenancy-fqdn parameter in each realm to your desired hostname. These deployments use this information to monitor the connection health between the Enterprise SBC and individual customer tenancies. Because this feature allows the system to generate SIP ping options for multiple realms, each realm can be capable of inserting your configured FQDN for every global session-agent target.

Guidelines for determining which FQDN the system inserts into the contact header include with respect to your teams-fqdn-in-uri configuration include:

If you enable the teams-fqdn-in-uri parameter on the realm and set either the teams-fqdn FQDN or the fqdn-hostname FQDN, the system inserts one of those FQDNs in the applicable contact header. If you set both of these FQDNs, the system uses the fqdn-hostname.
This remains true when using this multi-tenancy-fqdn feature. If you set both the fqdn-hostname and the multi-tenancy-fqdn, the system uses the fqdn-hostname.
Regardless of whether you enable or disable the teams-fqdn-in-uri parameter, if you have only configured the multi-tenancy-fqdn hostname, the system uses the multi-tenancy-fqdn to build the contact header.

Note:

This feature operates such that the system monitors each sip-interface/realm defined in the egress-realm-id list independently. So, although the Global SA shows In-Service if any one realm's connection is active, the system still selects call routes based on the availability between the specific egress realm and the SA.

Note:

The Enterprise SBC rejects calls with a 4xx message if none of the realms in the applicable egress-realm-id parameter are in-service towards the SA.

Note:

To use this feature, avoid configuring a realm in the next-hop parameter of your local-policy. In that case, the Enterprise SBC only tries to use that realm to forward those calls, foregoing the redundancy available from the multiple realms in your egress-realm-id configuration. Henceforth, be careful while configuring multiple realms in egress-realm-id list.

Downgrade Caveat

You should clear all configuration lists from all egress-realm-id parameters prior to downgrading to a version that does not support this feature. If not, older software versions set lists as strings, generating verify-config errors.

Reporting

You can use the show sipd agents <SA> command to verify this feature's operation. This command displays the status of physical targets, including when your connectivity targets multiple realms. The system determines each status by pinging the multiple destinations established by a DNS SRV resolved session-agent or multiple session-agent configurations. The output below shows status for two FQDN-resolved session-agent targets residing within separate realms.

ORACLE#show sipd agents <DNS SRV SA Name>
14:05:10-36
….
Session Agent < DNS SRV SA Name > [Status]
Destination: <IP1>  Source : <Realm1>  <Status>
Destination: <IP1>  Source : <Realm2>  <Status>
Destination: <IP2>  Source : <Realm1>  <Status>
Destination: <IP2>  Source : <Realm2>  <Status>

When deployed in HA mode, this status is replicated on the standby Enterprise SBC.

Note:

Oracle has tested this feature with a moderate range of realms (100-120) along with 10 DNS SRV SA (having a maximum of 4 IP addresses for each of 40 SAs, using a ping-interval 30 secs.

SIP Session Agent Continuous Ping

You can configure the Oracle® Enterprise Session Border Controller to use either a keep-alive or continuous method for pinging SIP session agents to determine their health—i.e., whether or not the Enterprise SBC should route requests to them.

To summarize the two methods:

keep-alive— Enterprise SBC sends a ping message of a type you configure to the session agent in the absence of regular traffic.
continuous—The Enterprise SBC sends a ping message regardless of traffic state (regular or irregular); the Enterprise SBC regularly sends a ping sent based on the configured ping interval timer.

By sending ping messages, the Enterprise SBC monitors session agents’ health and can determine whether or not to take a session out of service (OOS), leave it in service, or bring it back into service after being OOS.

When you set it to use the keep-alive mode of pinging, the Enterprise SBC starts sending a configured ping message to a session agent when traffic for that session agent has become irregular. The Enterprise SBC only sends the ping if there are no SIP transactions with a session agent over a configurable period of time, to which the session agent’s response can have one of the following results:

Successful response—A successful response is either any SIP response code or any response code not found in the out-service-response-codes parameter; these leave the session agent in service. In addition, any successful response or any response in the ping-in-service-response-codes parameter can bring a session agent from OOS to in-service status.
Unsuccessful response—An unsuccessful response is any SIP response code configured in the out-service-response-codes parameter and takes the session agent sending it OOS. Because this parameter is blank by default, the Enterprise SBC considers any SIP response code successful.
Transaction timeout—A transaction timeout happens when the session agent fails to send a response to the Enterprise SBC’s request, resulting in the session agent’s being taken OOS.

Despite the fact that the keep-alive ping mode is a powerful tool for monitoring session agents’ health, you might want to use the continuous ping method if you are concerned about the Enterprise SBC not distinguishing between unsuccessful responses from next-hop session agents and ones from devices downstream from the next-hop session agent. For example, if a SIP hop beyond the session agent responds with a 503 Service Unavailable, the Enterprise SBC does not detect whether a session agent or the device beyond it generated the response.

When you use the continuous ping method, only the next-hop session agent responds—preventing the request from being sent to downstream devices. The Enterprise SBC also sends the ping in regular traffic conditions when in continuous ping mode, so it is certain the response comes from the next hop associated with the session agent. And in continuous ping mode, only entries for the ping-out-service-response-codes parameter and transaction timeouts bring session agents OOS.

Note:

The Enterprise SBC also brings a Session Agent from OOS to in-service if it receives any SIP request from the session agent device.

By default, if the Enterprise SBC does not receive a response to the ping from the session-agent, it marks it as out-of-service. You can configure the number of ping failures that the Enterprise SBC can receive before it marks the session-agent as out-of-service. This is achieved by configuring the OPTIONS parameter in the session-agent with a ping-failure value, where value is the number of ping response failures. This is true for both the keep-alive and continuous-ping modes.

For example, set the Options parameter by typing options, followed by a Space, the option name: ping-failure-count=N (where N is the number of ping response failures before the SA is set to OOS) and press Enter. You may prepend the option parameter with a plus sign to add and not replace this option to the existing realm-config option list.

ORACLE (session-agent) #options +ping-failure-count=3

The session-agent is set out of service after the third ping response failure.

To remove the ping-failure-count option configuration, enter options -ping

ORACLE (session-agent) #options –ping

SIP SA Continuous Ping Configuration

You can set the ping mode in the session agent or session constraints configuration. The default for the ping-send-mode parameter is keep-alive.

Configure Ping Mode for Session Agents

Access the session-agent configuration element.

ORACLE# configure terminal
ORACLE(configure)# session-router
ORACLE(session-router)# session-agent
ORACLE(session-agent)

If you are adding to an existing configuration, then you will need to select the configuration you want to edit.
ping-send-mode—If to want to use continuous ping mode to send ping messages to session agents in regular traffic conditions, set this parameter to continuous. If you want to use the keep-alive mode, leave this parameter set to keep-alive (default).
Save and activate your configuration.

Configure Ping Mode for Session Constraints

Access the session-constraints configuration element.

ORACLE# configure terminal
ORACLE(configure)# session-router
ORACLE(session-router)# session-constraints
ORACLE(session-constraints)

If you are adding to an existing configuration, then you will need to select the configuration you want to edit.
ping-send-mode—If to want to use continuous ping mode to send ping messages to session agents in regular traffic conditions, set this parameter to continuous. If you want to use the keep-alive mode, leave this parameter set to keep-alive (default).
Save and activate your configuration.