SIP Header and Parameter Manipulation Configuration

HMR Configuration

To configure SIP header and parameter manipulation, first create a SIP header manipulation ruleset. Then create the header manipulation rules and optional header element rules for that ruleset to contain. Then configure a session agent or a SIP interface to use the SIP header and parameter manipulation ruleset in the inbound and outbound directions.

Testing Pattern Rules

Use test-pattern-rule to test the effect of your regex patterns.

Access the test-pattern-rule configuration element.

ORACLE# configure terminal
ORACLE(configure)# session-router
ORACLE(session-router)# test-pattern-rule
ORACLE(test-pattern-rule)#

expression—Enter the regular expression to test.
string—Enter the string against which you want to compare the regular expression.
show—View the test pattern, the string, and the matches.

ORACLE(test-pattern-rule)# expression ".*(;tgid=(.+)).*"
expression made 0 matches against string
ORACLE(test-pattern-rule)# string "sip:+17024260002@KCMGGWC;user=phone SIP/2.0;tgid=Trunk1"
expression made 3 matches against string
ORACLE(test-pattern-rule)# show
Pattern Rule:
        Expression : .*(;tgid=(.+)).*
        String     : sip:+17024260002@KCMGGWC;user=phone SIP/2.0;tgid=Trunk1
        Matched    : TRUE
        Matches:
$0 sip:+17024260002@KCMGGWC;user=phone SIP/2.0;tgid=Trunk1
$1 ;tgid=Trunk1
$2 Trunk1

ORACLE(test-pattern-rule)#

Creating Header Manipulation Rulesets

First create a header rule and then create element rules within that header rule.

Access the sip-manipulation configuration element.

ORACLE# configure terminal
ORACLE(configure)# session-router
ORACLE(session-router)# sip-manipulation
ORACLE(sip-manipulation)#

name—Enter the name you want to use for this ruleset.

Access the header-rules configuration element.

ORACLE(sip-manipulation)# header-rules
ORACLE(sip-header-rules)#

name—Enter a unique name for this rule.
header-name—Enter the name of the header to which this rule applies.
The name entered here is a case-insensitive string that must match a header name. Create a rule using the long form of the header name and a rule using the compact form of the header name.

Note:
The Request-URI header is identified as request-uri.
action—Enter the action you want applied to the header specified in the name parameter.
The default value is none. Valid options are:
- add—Add a new header, if that header does not already exist.
- delete—Delete the header, if it exists.
- manipulate—Elements of this header will be manipulated according to the element rules configured.
- store—Store the header.
- none—No action to be taken.
match-value—Enter the value to be matched (only an exact match is supported) with a header value.
The action specified is only performed if the header value matches.
msg-type—Enter the message type to which this header rule applies.
The default value is any. Valid options are:
- any—Both Requests and Reply messages
- request—Request messages only
- reply—Reply messages only
methods—Enter the SIP method names to which you want to apply this header rule. If entering multiple method names, separate them with commas. For example:
```
INVITE,ACK,BYE
```
Leaving the method field empty applies the header-rule to all methods.
Access the element-rules configuration element.
The element-rules configuration element defines the element rules, which are executed on those elements of the header specified by the header rule.
```
ORACLE(sip-header-rules)# element-rules
ORACLE(sip-element-rules)#
```
1. name—Enter the name of the element to which this rule applies.
  
  Note:
  The name parameter usage depends on the element type you enter in step 6. For uri-param, uri-user-param, and header-param it is the parameter name to be added, replaced, or deleted. For all other types, it serves to identify the element rule and any name can be used.
2. type—Enter the type of element on which to perform the action.
  The default value is none. Valid options are:
  - header-value—Enter value of the header.
  - header-param-name—Header parameter name.
  - header-param—Parameter portion of the header.
  - uri-display—Display of the SIP URI.
  - uri-user—User portion of the SIP URI.
  - uri-host—Host portion of the SIP URI.
  - uri-port—Port number portion of the SIP URI.
  - uri-param-name—Name of the SIP URI param.
  - uri-param—Parameter included in the SIP URI.
  - uri-header-name—SIP URI header name
  - uri-header—Header included in a request constructed from the URI.
  - uri-user-param—User parameter of the SIP URI.
3. action—Enter the action you want applied to the element specified in the name parameter, if there is a match value.
  The default value is none. Valid options are:
  - none—No action is taken.
  - add—Add a new element, if it does not already exist.
  - store—Store the elements.
  - replace—Replace the elements
  - delete-element—Delete the specified element if it exists.
  - delete-header—Delete the specified header, if it exists.
4. match-val-type—Enter the type of value that needs to be matched to the match-field entry for the action to be performed.
  The default value is ANY. Valid options are:
  - IP—Element value in the SIP message must be a valid IP address to be compared to the match-value field entry. If the match-value field is empty, any valid IP address is considered a match. If the element value is not a valid IP address, it is not considered a match.
  - FQDN—Element value in the SIP message must be a valid FQDN to be compared to the match-value field entry. If the match-value field is empty, any valid FQDN is considered a match. If the element value is not a valid FQDN, it is not considered a match.
  - ANY—Element value in the SIP message is compared with the match-value field entry. If the match-value field is empty, all values are considered a match.
5. match-value-—Enter the value you want to match against the element value for an action to be performed.
6. new-value-—Enter the value for a new element or to replace a value for an existing element. You can enter an expression that includes a combination of absolute values, pre-defined parameters, and operators
  
  Note:
  Absolute values, with which you can use double quotes for clarity. You must escape all double quotes and back slashes that are part of an absolute value, and enclose the absolute value in double quotes.
  Examples of entries for the new-value field.
```
sip:"+$TRUNK_GROUP+".$TRUNK_GROUP_CONTEXT
$ORIGINAL+acme
$ORIGINAL+”my name is john”
$ORIGINAL+”my name is \”john\””
$ORIGINAL-^781+^617
```
7. Type done and exit to save the rule and return to the header-rules configuration element.
Type done and exit to save the rule and return to the sip-manipulation configuration element.

Configuring SIP Header Manipulation Rules

To configure dynamic SIP header manipulation rules:

Access the header-rules configuration element.

ORACLE# configure terminal
ORACLE(configure)# session-router
ORACLE(session-router)# sip-manipulation
ORACLE(sip-manipulation)# header-rules
ORACLE(sip-header-rules)#

name—Enter the unique identifier for this SIP HMR.
This configuration element has no default value.
header-name—Enter the name of the header on which to operate.
This configuration element has no default value.
Set this parameter to @status-line to prevent undesired matches with header having the name status-code.
msg-type—Specify the type of message to which this SIP HMR will be applied.
The default value is any. Valid values are:
- any
- request
- reply
methods—Enter the method type on which to operate.
When you do not set the method, the OCSBC applies the rule across all SIP methods. Valid values are:
- INVITE
- ACK
- CANCEL
comparison-type—Enter the way in which the OCSBC will process match rules against SIP headers.
The default is refer-case-sensitive. The valid values are:
- boolean
- refer-case-sensitive
- pattern-rule
- case-sensitive
- case-insensitive
action—Enter the action to perform on the SIP header.
The default value is none. The valid values are:
- add
- delete
- manipulate
- store
- none
Note:
Remember that you should enter rules with the action type store before you enter rules with other types of actions.

If the action type is set to store, the OCSBC treats the match value as a regular expression. As a default, the regular expression used for the match value is .+ (which indicates a match value of at least one character), unless you set a more specific regular expression match value.
match-value—Enter the value to match against the header value.
The OCSBC matches these against the entire SIP header value. This is where you can enter values to match using regular expressions. Your entries can contain Boolean operators.
When you configure HMR (using SIP manipulation rules, elements rules, etc.), you can use escape characters to support escaping Boolean and string manipulation operators.
new-value—When the action parameter is set to add or to manipulate, enter the new value that you want to substitute for the entire header value.

This is where you can set stored regular expression values for the OCSBC to use when it adds or manipulates SIP headers.

Configuring SIP Header Manipulation Element Rules

Element rules are a subset of the SIP header manipulation rules and are applied at the element type level rather than at the entire header value.

To configure dynamic SIP header manipulation rules:

Access the element-rules configuration element.

ORACLE# configure terminal
ORACLE(configure)# session-router
ORACLE(session-router)# sip-manipulation
ORACLE(sip-manipulation)# header-rules
ORACLE(sip-header-rules)# element-rules
ORACLE(sip-element-rules)#

name—Enter the unique identifier for this element rule.
There is no default value.
parameter-name—Enter the SIP header parameter or element on which to operate.
There is no default value.
type—Specify the type of parameter to which this element rule will be applied.
The default value is none. The valid values are:
- header-value
- header-param-name
- header-param
- uri-display
- uri-user
- uri-user-param
- uri-host
- uri-port
- uri-param-name
- uri-param
- uri-header-name
- uri-header
To configure HMR so that only the status-line is affected, set comparison-type to one of the following:
- status-code—Designates the status code of the response line; accepts any string, but during the manipulation process only recognizes the range from 1 to 699.
- reason-phrase—Designates the reason of the response line; accepts any string.
match-val-type—Enter the value type that you want to match when this rule is applied.
The default value is ANY. Valid values are:
- IP
- FQDN
- ANY
comparison-type—Enter the way that you want SIP headers to be compared from one of the available.
This choice dictates how the OCSBC processes the match rules against the SIP header parameter/element. The default is refer-case-sensitive.
- boolean
- refer-case-sensitive
- refer-case-insensitive
- pattern-rule
action—Enter the action that you want this rule to perform on the SIP header parameter/element.
The default is none. The valid rules are:
- add
- replace
- delete-element
- delete-header
- store
- none
Remember that you should enter rules with the action type store before you enter rules with other types of actions.

When you set the action type to store, the OCSBC always treats the match value you enter as a regular expression. As a default, the regular expression is uses for the match value is .+ (which indicates a match value of at least one character), unless you set a more specific regular expression match value.
match-value—Enter the value to match against the header value in SIP packets.
The OCSBC matches these against the value of the parameter/element. This is where you can enter values to match using regular expression values, or stored pattern matches. Your entries can contain Boolean operators.
new-value—When the action parameter is set to add or to manipulate, enter the new value that you want to substitute for the entire header value.

This is where you can set stored regular expression values for the OCSBC to use when it adds or manipulates parameters/elements.

Status-Line Manipulation and Value Matching

The Oracle Communications Session Border Controller’s HMR feature has been enhanced to support the ability to change the status code or reason phrase in SIP responses. This addition—the ability to edit status-lines in responses—builds on HMR’s existing ability to edit response headers or the Request-URI in a request.

This section shows you how to configure SIP HMR when you want the Oracle Communications Session Border Controller to drop a 183 Session Progress response when it does not have SDP, though flexibility is built into this feature so that you can use it to achieve other ends. In addition, you can now set the SIP manipulation’s match-value parameter with Boolean parameters (AND or OR).

Set the Header Name

Set the header-name to @status-line to modify the status code or reason phrase in SIP responses.

Access the header-rules configuration element.

ORACLE# configure terminal
ORACLE(configure)# session-router
ORACLE(session-router)# sip-manipulation
ORACLE(sip-manipulation)# header-rules
ORACLE(sip-header-rules)#

header-name—Enter @status-line.

ORACLE(sip-header-rules)# header-name @status-line
ORACLE(sip-header-rules)#

Set the Element Type

In the element-rules configuration element, set the type parameter to either status-code or reason-phrase.

status-code—Designates the status code of the response line. Accepts any string, but during the manipulation process only recognizes the range from 1 to 699.
reason-phrase—Designates the reason of the response line. Accepts any string.

Note:

Like other rule types, the Oracle Communications Session Border Controller matches against the value for these using case-sensitive, case-insensitive, or pattern-rule matching (set in the comparison-type parameter for the element rule).

Access the element-rules configuration element.

ORACLE# configure terminal
ORACLE(configure)# session-router
ORACLE(session-router)# sip-manipulation
ORACLE(sip-manipulation)# header-rules
ORACLE(sip-header-rules)# element-rules
ORACLE(sip-element-rules)#

type—Enter either status-code or reason-phrase.
```
ORACLE(sip-element-rules)# type status-code
```
The OCSBC uses the value of comparison-type to determine matching.

Set the Match Value

Set the match value in either the header-rules configuration element or the element-rules configuration element

Set the Header Rules Match Value

Set a match value in the header-rules configuration element.

Access the header-rules configuration element.

ORACLE# configure terminal
ORACLE(configure)# session-router
ORACLE(session-router)# sip-manipulation
ORACLE(sip-manipulation)# header-rules
ORACLE(sip-header-rules)#

match-value—Enter the value to match against the header value.
The Oracle Communications Session Border Controller matches these against the entire SIP header value. This is where you can enter values to match using regular expression values; your entries can contain Boolean operators.

Set the Element Rules Match Value

Set a match value in the element-rules configuration element.

Access the element-rules configuration element.

ORACLE# configure terminal
ORACLE(configure)# session-router
ORACLE(session-router)# sip-manipulation
ORACLE(sip-manipulation)# header-rules
ORACLE(sip-header-rules)# element-rules
ORACLE(sip-element-rules)#

match-value—Enter the value to match against the header value.
The Oracle Communications Session Border Controller matches these against the entire SIP header value. This is where you can enter values to match using regular expression values; your entries can contain Boolean operators.

Set the Response Code Block

Enable SIP response blocking to keep the Oracle Communications Session Border Controller from sending the designated response.

Note:

This example sets the dropResponse option to 699, where 699 is an arbitrary code used to later match the HMR.

Access the sip-interface configuration element.

ORACLE# configure terminal
ORACLE(configure)# session-router
ORACLE(session-router)# sip-interface
ORACLE(sip-interface)#

Select the sip-interface object to edit.

ORACLE(sip-interface)# select
<RealmID>:
1: realm01 172.172.30.31:5060

selection: 1
ORACLE(sip-interface)#

options—Enter options +dropResponse=<response code> where <response code> is the code(s) or range(s) to block. Separate multiple entries with a colon.
```
ORACLE(sip-interface)# options +dropResponse=699
```
WARNING:
Typing the option without the plus sign will overwrite previously configured options. To append the options to this configuration’s options list, prepend the option with a plus sign.
Save and activate your configuration.

Configuring SIP HMR Sets

To enable HMR sets, set the action configuration element to sip-manip.

Access the element-rules configuration element.

ORACLE# configure terminal
ORACLE(configure)# session-router
ORACLE(session-router)# sip-manipulation
ORACLE(sip-manipulation)# header-rules
ORACLE(sip-header-rules)# element-rules
ORACLE(sip-element-rules)#

action—Enter sip-manip value to enable use this rule for a SIP HMR set. This value then invoke the rule identified in the new-value parameter.
new-value—Enter the name of the manipulation rule you want invoked for the set.
Type done to save your configuration.
Run verify-config to detect invalid or circular references.
Save and activate your configuration.

Configuring a Session Agent

Configure a session agent to use a SIP header manipulation ruleset.

Access the session-agent configuration element.

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

in-manipulationid—Enter the name of the SIP header manipulation ruleset you want to apply to inbound SIP packets.
```
ORACLE(session-agent)# in-manipulationid route-stripper
```
out-manipulationid—Enter the name of the SIP header manipulation ruleset you want to apply to outbound SIP packets.
```
ORACLE(session-agent)# out-manipulationid route-stripper
```
Type done to save your configuration.

Configuring a SIP Interface

Configure a interface to use a SIP header manipulation ruleset.

Access the sip-interface configuration element.

ORACLE# configure terminal
ORACLE(configure)# session-router
ORACLE(session-router)# sip-interface
ORACLE(sip-interface)#

in-manipulationid—Enter the name of the SIP header manipulation ruleset to apply to SIP packets in the ingress direction.
```
ORACLE(sip-interface)# in-manipulationid topology-hiding
```
out-manipulationid—Enter the name of the SIP header manipulation ruleset to apply to SIP packets in the egress direction.
```
ORACLE(sip-interface)# out-manipulationid topology-hiding
```
Type done to save your configuration.

Example 1 Stripping All Route Headers

This example explains how to strip all route headers from a SIP packet. First, you create a header manipulation ruleset, in the example it is called route-stripper. Then you configure the list of header manipulation rules you need to strip route headers. In this case, you only need one rule named Route (to match the Route header name) with the action set to Delete.

ORACLE# configure terminal
ORACLE(configure)# session-router
ORACLE(session-router)# sip-manipulation
ORACLE(sip-manipulation)# name route-stripper
ORACLE(sip-manipulation)# header-rules
ORACLE(sip-header-rules)# name Route
ORACLE(sip-header-rules)# action Delete
ORACLE(sip-header-rules)# done
header-rule
        name                           Route
        action                         delete
        match-value
        msg-type                       any
ORACLE(sip-header-rules)# ex
ORACLE(sip-manipulation)# done
sip-manipulation
        name                           route-stripper
        header-rule
                name                           Route
                action                         delete
                match-value
                msg-type                       any

Example 2 Stripping an Existing Parameter and Adding a New One

This example explains how to strip the user parameter from the Contact header URI and add the acme parameter with value as LOCAL IP, only for requests. First you create a header manipulation ruleset, in the example it is called param-stripper1. You then configure a list of header rules you need. In this case, you only need one rule named Contact (to match the Contact header name), with action set to manipulate (indicating the elements of this header would be manipulated). Next, you configure a list of element rules for the Contact header rule.

In this case you configure two element rules; one to strip the uri parameter user (the rule name user matches the param name user) and the other to add the uri parameter acme (the rule name acme matches the param name acme).

ORACLE# configure terminal
ORACLE(configure)# session-router
ORACLE(session-router)# sip-manipulation
ORACLE(sip-manipulation)# name param-stripper1
ORACLE(sip-manipulation)# header-rules
ORACLE(sip-header-rules)# name Contact
ORACLE(sip-header-rules)# action manipulate
ORACLE(sip-header-rules)# msg-type request
ORACLE(sip-header-rules)# element-rules
ORACLE(sip-element-rules)# name user
ORACLE(sip-element-rules)# type uri-param
ORACLE(sip-element-rules)# action delete-element
ORACLE(sip-element-rules)# done
element-rule
        name                           user
        type                           uri-param
        action                         delete-element
        match-val-type                 any
        match-value
        new-value
ORACLE(sip-element-rules)# name acme
ORACLE(sip-element-rules)# action add
ORACLE(sip-element-rules)# type uri-param
ORACLE(sip-element-rules)# new-value "$LOCAL_IP"
ORACLE(sip-element-rules)# done
element-rule
        name                           acme
        type                           uri-param
        action                         add
        match-val-type                 any
        match-value
        new-value                      "$LOCAL_IP"
ORACLE(sip-element-rules)# ex
ORACLE(sip-header-rules)# done
header-rule
        name                           Contact
        action                         manipulate
        match-value
        msg-type                       request
        element-rule
                name                           user
                type                           uri-param
                action                         delete-element
                match-val-type                 any
                match-value
                new-value
        element-rule
                name                           acme
                type                           uri-param
                action                         add
                match-val-type                 any
                match-value
                new-value                      "$LOCAL_IP"
ORACLE(sip-header-rules)# ex
ORACLE(sip-manipulation)# done
sip-manipulation
        name                           param-stripper1
        header-rule
                name                           Contact
                action                         manipulate
                match-value
                msg-type                       request
                element-rule
                        name                           user
                        type                           uri-param
                        action                         delete-element
                        match-val-type                 any
                        match-value
                        new-value
element-rule
                name                           acme
                type                           uri-param
                action                         add
                match-val-type                 any
                match-value
                new-value                      "$LOCAL_IP"

For example, if the IP address of the SIP interface ($LOCAL_IP) is 10.1.2.3 and the Oracle Communications Session Border Controller receives the following Contact header:

Contact: <sip:1234@10.4.5.6;user=phone>

The header rule is applied to strip the user parameter from the Contact header URI and add the acme parameter with the value 10.1.2.3:

Contact: <sip:1234@10.4.5.6;acme=10.1.2.3>