SIP Session Agents

SIP session agents can include the following:

softswitches
SIP proxies
application servers
SIP gateways
SIP endpoints

In addition to functioning as a single logical next hop for a signaling message (for example, where a SIP INVITE is forwarded), session agents can provide information about next or previous hops for packets in a SIP agent, including providing a list of equivalent next hops.

You can use the session agent to describe one or more SIP next or previous hops. Through the configured carriers list, you can identify the preferred carriers to use for traffic coming from the session agent. This set of carriers will be matched against the local policy for requests coming from the session agent. You can also set constraints for specific hops.

Session Agent Status Based on SIP Response

The Oracle Communications 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 Oracle Communications Session Border Controller 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 Oracle Communications Session Border Controller 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 Oracle Communications Session Border Controller’s ping request.

Details of this feature are as follows:

The Oracle Communications Session Border Controller 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 Oracle Communications Session Border Controller 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 Oracle Communications Session Border Controller 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 a the session agent’s response has a Retry-After header, the Oracle Communications Session Border Controller 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 Oracle Communications Session Border Controller’s ping request. Furthermore, the Oracle Communications Session Border Controller 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 Oracle Communications Session Border Controller’s ping request or any dialog-creating request.

When the Oracle Communications Session Border Controller 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 Oracle Communications Session Border Controller 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 Oracle Communications Session Border Controller ignores the out-of-service list.

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

SIP Session Agent Continuous Ping

You can configure the Oracle Communications 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 Oracle Communications Session Border Controller should route requests to them.

To summarize the two methods:

keep-alive— Oracle Communications Session Border Controller sends a ping message of a type you configure to the session agent in the absence of regular traffic. Available in Release C5.1.0 and in earlier releases.
continuous—The Oracle Communications Session Border Controller sends a ping message regardless of traffic state (regular or irregular); the Oracle Communications Session Border Controller regularly sends a ping sent based on the configured ping interval timer. Available in Release C5.1.1p6 and in later releases.

By sending ping messages, the Oracle Communications Session Border Controller 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 (available in Release C5.1.0 and before), the Oracle Communications Session Border Controller starts sending a configured ping message to a session agent when traffic for that session agent has become irregular. The Oracle Communications Session Border Controller 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 Oracle Communications Session Border Controller considers any SIP response code successful.
Transaction timeout—A transaction timeout happens when the session agent fails to send a response to the Oracle Communications Session Border Controller’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 Oracle Communications Session Border Controller 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 Oracle Communications Session Border Controller 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 Oracle Communications Session Border Controller 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.

By default, if the Oracle Communications Session Border Controller 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 Oracle Communications Session Border Controller 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. For backward compatibility, the default for the ping-send-mode parameter is keep-alive, or the functionality available in Release C5.1.0 and in earlier releases.

To configure the ping mode for a session agent:

In Superuser mode, type configure terminal and press Enter.
```
ORACLE# configure terminal
ORACLE(configure)#
```

Type session-router and press Enter.

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

Type session-agent and press Enter.
```
ORACLE(session-router)# session-agent
ORACLE(session-agent)#
```
If you are adding rate constraints 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.

To configure the ping mode for the session constraints:
In Superuser mode, type configure terminal and press Enter.
```
ORACLE# configure terminal
ORACLE(configure)#
```

Type session-router and press Enter.

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

Type session-constraints and press Enter.
```
ORACLE(session-router)# session-constraints
ORACLE(session-constraints)#
```
If you are adding rate constraints 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.

Ingress Session Agent Identification

The Oracle Communications Session Border Controller uses the Ingress Session Agent Identification to match the incoming requests to its respective Session Agents. CAC (Call Admission Control) is performed for the inbound traffic based on the originating endpoint of the Session Agents regardless of the IP address.

This feature is supported by the session router configuration element: session-agent-id-rule and the Session Agent fields: match-identifier and associated-agents.

The session-agent-id-rule specifies the SIP header (with or without the parameter) within the ingress message, which is used for the identification purposes. The configuration element contains the fields: name, match-header, match-parameter and uri-type. The fields: name and match-header are required fields.

The following actions occur when you configure the specific session-agent identifier elements.

Configured Elements	Identification action performed by the rule
uri-type with values: uri_param, uri_header, uri-user, uri-host, uri-port, uri_user_param, uri-display, uri-user-only, uri-phone-number-only	Identifies using URI values
match-header	Performs case-sensitive match on the entire value of the header
match-header and match-parameter	Finds the value of the parameter within the header and perform a case-sensitive match on the value of the parameter.
match-header and uri-type	Looks up the header and parse it as a sip URI followed by a case-sensitive comparison on the uri element specified by the uri-type.
match-parameter and uri-type with values: uri-user, uri-host, uri-port, uri-display, uri-user-only, uri-phone-number-only	The match-parameter is used to match the SIP header parameter.
match-parameter and uri-type with values: uri_param, uri_header, or uri_user_param	The match-parameter is used to specify the header for the parameter in URI.

The system uses two session-agent configuration fields for session-agent identification: match-identifier and associated-agents . You can configure the match-identifier on the session-agents representing nodes behind the Oracle Communications Session Border Controller. This determines the messages sent from a particular node without having the IP address.

Match-identifier has two fields of its own: identifier-rule and match-value. The identifier-rule is configured with the name of a session-agent-id-rule and the match-value is configured with the (case-sensitive) string value matched with the particular session agent.

About Master Agent and Associated-Agents

The Oracle Communications Session Border Controller acts as the 'master agent' with a list of associated-agents. Associated-agents is a list of the session-agents representing the nodes that sit behind the OCSBC. SR identifies the correct session-agent by iterating through the associate-agent list and looking for a session-agent that has its match-identifier(s) satisfied in the SIP header. Once the exact match is found, it is confirmed that the message arrived from the corresponding node of that session-agent. The agent is now identified and CAC can be successfully be applied at this point.

This look up is performed on the master agent and its associate-agents every time the session or registration constraints are being checked. The system will only attempt to find a match in the selected session-agent's associated-agents list, (i.e. the associated agent list for an associated-agent will not be examined). In the event that no association is found, constraints will be checked and performed on the master session-agent as usual.

Note:

The comparison between actual value of the SIP header parameter and the match-value is an exact and case-sensitive match.

To use this functionality, it is important that the identifiable value be present in all inbound SIP messages intended to be associated with a particular session-agent. The identifiable value can be present in any header or parameter within the SIP header of the SIP message; existing or custom. You can use the same session-agent-id-rules for multiple session agents if you intend to use the same SIP header or parameter to compare the against the match values.

Note:

The session-agents found within the same associated-agents list must have a unique combination of match-identifiers (either identifier-rule or match-value) that distinguishes them from one another.

Session-Agent Identification Example

In the example below, the Oracle Communications Session Border Controller has a session-agent configured for the SBC, which forwards traffic from three IVRs. IVR to IVR calls flow in the fashion depicted. The SR also has session-agents configured which identify the IVRs using DNS lookups. These agents are used when processing off-realm to IVR calls where the SR will send messages to the IVR directly. With this feature, the SR in the IVR to IVR call (shown in red) can apply IVR1's CAC despite SA-SBC being matched by IP address.

Configured Session-Agents on SR

Hostname: SA-SBC
ip: 1.1.1.1
match-identifier: <blank> 
associated-agents:
	IVR1.oracle.com
	IVR2.oracle.com
	IVR3.oracle.com

Hostname: IVR1.oracle.com
match-identifier:
	identifier-rule: SA-SBC-Rule
	match-value: ABC1
match-identifier:
	identifier-rule: SA-SBC-Rule2
	match-value: ABC1
associated-agents:
	<blank>

Hostname: IVR2.oracle.com
match-identifier:
	identifier-rule: SA-SBC-Rule
	match-value: ABC2
match-identifier:
	identifier-rule: SA-SBC-Rule2
	match-value: ABC2
associated-agents:
	<blank>

Hostname: IVR3.oracle.com
match-identifier:
	identifier-rule: SA-SBC-Rule
	match-value: ABC3
match-identifier:
	identifier-rule: SA-SBC-Rule2
	match-value: ABC3
associated-agents:
	<blank>

Legacy Configuration

The following is a sample configuration with the session-agent-id-rules and Session Agents. The configuration can be used to perform CAC on session-agent IVR1.oracle.com behind the session-agent SA-SBC.IVR1.oracle.com. It will be matched using the parameter “test” in P-Identifier in the SIP INVITE.

INVITE sip:12340223285116@1.1.1.1:5060;user=phone SIP/2.0
Via: SIP/2.0/UDP 1.1.1.2:5060;branch=z9hG4bKk25du6204otrbrqbcil0.1
Max-Forwards: 69
From: <sip:3611101@1.1.1.4>;tag=as0bd34e4a
To: <sip:0223285116@1.1.1.3:5060;user=phone>
Contact: <sip:3611101@1.1.1.2:5060;transport=udp>
Call-ID: 6850461b04cf07193b480450247960ba@1.1.1.4:5060
CSeq: 102 INVITE
User-Agent: FPBX-2.11.0(11.17.1)
Allow: INVITE, ACK, CANCEL, OPTIONS, BYE, NOTIFY, INFO
Content-Type: application/sdp
Content-Length: 215
P-Identifier: temp=ABC;test=1234
TestHeader: sip:test User;id=Abc@oracle.com:1101;
P-Asserted-Identity: tel:2265

Session Agent Identifier Rules

Example 1 : Session Agent identifier rule without uri-type

session-agent-id-rule 1               
name               SA-SBC-Rule1
match-header       P-Identifier
match-parameter    test
uri-type

This rule will search the SIP header and retrieve the value "1234" from the parameter "test" in match-header P-Identifier.

Example 2: Session Agent identifier rule with uri-type

session-agent-id-rule 2               
name               SA-SBC-Rule2
match-header       TestHeader
match-parameter    id
uri-type           uri-user-param

This rule will search the SIP header and retrieve the value "Abc" from match-header TestHeader.

Session Agents

The Session Agent is configured with the session-agent-id-rules. You can add multiple match-identifiers. The following configuration contains sample settings for the purpose of providing an example. Your configuration may require different values.

<<Example associate-agent>>             
hostname                              IVR1.oracle.com
ip-address                              
port                                  0
state                                 enabled
app-protocol                          SIP
app-type                                             
transport-method                      StaticTCP
match-identifier
              identifier-rules        SA-SBC-Rule1	
              match-value             1234
match-identifier
              identifier-rules        SA-SBC-Rule2
              match-value             Abc
associated-agents                     <blank>
…
constraints                           enabled
…


<<Example master-agent>>
hostname                               SA-SBC
ip-address                             1.1.1.1
port                                   5060
state                                  enabled
app-protocol                           SIP
app-type                                             
transport-method                       StaticTCP
match-identifier                       <blank>
<<This field will not appear if not configured>>
associated-agents                      IVR1.oracle.com
                                       IVR2.oracle.com
                                       IVR3.oracle.com
…                                           
constraints                            enabled
…

In the above example, the sip-invite/registration is offered by session-agent SA-SBC. To perform CAC, SA-SBC's associated-agents list is looked up for a match between the match-identifiers and the incoming request. Once a match is found for a particular associated-agent, the existing CAC constraint is applied.

Override Alphanumeric Ordering of Session Agents with same IP address

The Oracle Communications Session Border Controller can associate an incoming call with a Session Agent based upon the precedence attribute for systems that have the same IP address, rather than the alphanumeric order of hostname.

To change inbound behavior from an outbound one, customers can configure several Session Agents (SAs) with the same IP address to different hostnames. By default, the system uses alphanumeric order to determine sorting. The attribute precedence provides a user-controlled mechanism to determine order for Session Agents. The rules of precedence are as follows:

The default value is zero. This does not activate precedence.
It is configurable with integer value from 1 to 4,294967,295
The lowest value is considered first, followed by Session Agents with the same IP of increasing values
After SAs with precedence set to a value higher than one are assigned, those with the default of zero are considered (e.g. alphanumeric order sorting is followed)
Should two Session Agents have the same value of precedence, alphanumeric sorting rules apply

This attribute in the Session Agent configuration does not interact with the Session Agent Group construct as the latter is used for egress routing. For this same reason, precedence does not apply to surrogate registration, nor registration refresh.

For example, these settings cause the hosts abb123 and aaa456 to be preferred first and aaa123 last:

SA1: IP=192.168.139.5, hostname-aaa456, precedence=1
SA1: IP=192.168.139.5, hostname-abb123, precedence=1
SA1: IP=192.168.139.5, hostname-abc123, precedence=33
SA1: IP=192.168.139.5, hostname-aaa123, precedence=44

Override Alphanumeric Ordering of Session Agents with Same IP Configuration

Enter the prerequisites here (optional).

Enter the context of your task here (optional).

Access the session-agent configuration element.

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

Select the session-agent object to edit.

ORACLE(session-agent)# select
<hostname>:
1: 192.168.100.101:1813

selection: 1
ORACLE(session-agent)#

precedence—Set the importance level of this IP/hostname combination for Session Agents. To be considered for precedence, a value of 1 or more is required.
- Minimum: 0
- Maximum: 4,294,967,295
- Default: 0
Type done to save your configuration.