HMR Components

Relationship Between Rulesets and Its Rules

The relationship between manipulation rules and manipulation rulesets is created once you load your configuration. The order in which you enter rulesets does not matter. It also means that the SBC cannot dynamically perform validation as you enter rules, so you should use the verify-config command to confirm your manipulation rules contain neither invalid nor circular references. Invalid references are those that point to SIP manipulation rules that do not exist, and circular references are those that create endless loops of manipulation rules being carried out over and over.

Ruleset Guidelines

Keep the following guidelines in mind when creating rulesets:

One ruleset per inbound message
One ruleset per outbound message
Header or element rules can call another HMR
An HMR can have multiple header rules
A header rule can have multiple header rules

Ruleset Components

The following table lists ruleset components.

Component	Description
header-rule	Header rules form the basis of rulesets. Used to operate on one or more SIP headers within the SIP message; operations performed at this level work on the entire header value, excluding the label. Within a ruleset, each HR is performed in order. Typically one performs regular expression "store" action HRs before manipulation ones, although there are exceptions depending on the needs. There is no hard limit to the number of HR elements included in a ruleset, although in practical terms one would probably not configure thousands of them.
match-value	Used to perform a matching comparison to decide whether to store values, add a header, or delete a header. The type of matching comparison performed is based on the comparison-type field. If the match-value is left blank, the action is performed regardless. Therefore, if the header rule action is "delete", "add", or "manipulate", and the match value is left blank, the action will be performed on the header. If the header rule action is "store" and the match value is left blank, the SBC automatically stores everything, as if the match value were `.+` which means match at least one character, as many times as possible. Note that any whitespace after the first non-whitespace character is kept as well.
element-rule	Used to operate on specific portions of a SIP header, such as components of a URI value within the header or the parameters of the header; if the header value contains a URI, then this class operates only on the specified portion (i.e., URI user or header parameter); this class does not operate on headers with multiple header values.
mime-rule	Used to operate on any MIME part within a SIP message (SDP, test, or some other proprietary body type); used as a general facility to operate on the entire body as a single continuous string.
mime-header-rule	Used to operate on the SIP headers within a body part; the body part contains headers only when the MIME content is contained in a multi-part message; when used to operate on a MIME body that is not multi-part, then this class operates as through it were a header-rule.
mime-isup rule	Special type of mime-rule because it expects the MIME content of the specified body to be part of a valid binary ISDN User Part (ISUP) format.
isup-param-rule	Used to perform operations on the parameters contained in an ISUP body.
mime-sdp-rule	Special kind of mime-rule that is used to operate on the SDP MIME content of a SIP message; at this level, the rule operates on the entire SDP as a single contiguous string.
sdp-session-rule	Used to operate on only the session portion of the SDP content consists of all the characters starting from the beginning until the first media line.
sdp-media-rule	Used to operate on only a specific media portion of the SDP content; consists of all the characters starting from the beginning of the specified m-line until the next m-line or the end of the SDP.
sdp-line-rule	Used to operate on a single descriptor line within either the session or media portion of the SDP.

Guidelines for Header and Element Rules

Header rules and element rules share these guidelines:

References to groupings that do not exist result in an empty string.
References to element rule names alone result in a Boolean condition of whether the expression matched or not.
A maximum of ten matches are allowed for a regular expression. Match 0 (grouping 0) is always the match of the entire matching string; subsequent numbers are the results for other groups that match.
Rule names must start with a letter, and then can contain any number of letters, numbers, or underscores.
All uppercase rule names are not allowed because this syntax is reserved for variables.
To avoid being interpreted as a minus operator, dashes are not permitted in rule names.

Guidelines for Header Rules

Header rules guidelines include:

Header names must be unique in a given HMR.
Each header rule operates on one header.
Multiple header rules can operate on the same header.
Header rules can contain multiple element rules.

Guidelines for Element Rules

Element rule guidelines include:

Element rule names must be unique within a header rule
Each element rule operates on one component of the header
Multiple element rules can operate on the same component

Duplicate Header Names

If more than one header exists for a configured header-name, the SBC stores each value in an array whose index starts at 0. To reference those values, use the syntax $<header-name>[<index>].

Add a trailing [<index>] value after the header-name parameter to represent the specific instance of the header on which to operate. Additional stored header values are indexed in the order in which they appear within the SIP message, and there is no limit to the index. The SBC takes no action if the header does not exist.

Use index 0 to reference the first header. In addition to numerical values, possible index values are:

* The SBC references all headers.
^ The SBC references the last stored header in the header rule.

Note that the header instance functionality has no impact on HMR’s add action, and you cannot use this feature to insert headers into a specific location. Headers are added to the end of the list, except that Via headers are added to the top.

SIP Header Pre-Processing HMR

By default, the SBC performs in-bound SIP manipulations after it carries out header validation. Adding the inmanip-before-validate option in the global SIP configuration allows the SBC to perform HMR on received requests prior to header validation. Because there are occasional issues with other SIP implementations—causing invalid headers to be used in messages they send to the SBC—it can be beneficial to use HMR to remove or repair these faulty headers before the request bearing them is rejected.

When configured to do so, the SBC performs pre-validation header manipulation immediately after it executes the top via check. Inbound SIP manipulations are performed in order of increasing precedence: SIP interface, realm, and session agent.

The fact that the top via check happens right before the SBC carries out pre-validation header manipulations means that you cannot use this capability to repairs the first via header if it is indeed invalid. If pre-validation header manipulation were to take place at another time during processing, it would not be possible to use it for SIP session agents. The system learns of matching session agents after top via checking completes.

For logistical reasons, this capability does not extend to SIP responses. Inbound manipulation for responses cannot be performed any sooner that it does by default, a time already preceding any header validation.

To enable SIP header pre-processing:

Access the sip-config configuration element.

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

options—Set the inmanip-before-validate parameter.
```
ORACLE(sip-config)# options +inmanip-before-validate
```
This value allows the SBC to perform pre-validation header manipulation in order of increasing precedence: SIP interface, realm, and session agent.
Save and activate the configuration.

Back Reference Syntax

You can use back reference syntax in the new-value parameter for header and element rules. Denoted by the use of $1, $2, $3, etc. (where the number refers to the regular expression's stored value), you can reference the header and header rule's stored value without having to use the header rule's name. It instead refers to the stored value of this rule.

For example, when these settings are in place:

header-rule=changeHeader
action=manipulate
match-value=(.+)([^;])

you can set the new-value as sip:$2 instead of sip:$changeHeader.$2.

You can use the back reference syntax when:

The header-rule action parameter is set to manipulate or find-replace-all
The element-rule action parameter is set to replace or find-replace-all

Using back reference syntax simplifies your development work because you do not need to create a store rule and then manipulate rule; the manipulate rule itself performs the store action if the comparison-type parameter is set to pattern-rule.

Dialog Matching

The out-of-dialog setting is useful for To/From NATing rules.

Service providers can use HMR to support legacy RFC 2543 devices and some non-compliant RFC 3261 devices. The header-rule msg-type setting called out-of-dialog has been added, which applies the rule (and any of its sub-rules) only to out-of-dialog requests. If the rule was applied as an outbound sip-manipulation to the first request, then it will apply the rule against all subsequent requests going in the same direction. The primary purpose of this new configuration setting is to support changing the To/From URI's in mid-dialog requests without breaking dialog matching for some over-strict SIP devices.

About Dialog-Matching Header Manipulations

The goal of this feature is to maintain proper dialog-matching through manipulation of dialog-specific information using HMR. Two fundamental challenges arise when looking at the issue of correctly parameters manipulating dialog-matching:

Inbound HMR
Outbound HMR

The new setting out-of-dialog (for the msg-type parameter) addresses these challenges by offering an intelligent more of dialog matching of messages for inbound and outbound HMR requests. This is a msg-type parameter, meaning that it becomes matching criteria for operations performed against a message. If you also specify methods (such as REGISTER) as matching criteria, then the rule is further limited to the designated method.

For both inbound and outbound manipulations, using the out-of-dialog setting means the message must be a request without a to-tag in order to perform the manipulation.

Inbound HMR Challenge

Because inbound manipulations take place before the message reaches the core of Oracle Communications Session Border Controller (SBC) SIP processing, the SIP proxy takes the manipulated header as directly received from the client. This can cause problems for requests leaving the SBC for the UAC because the dialog does not match the initial request sent.

The unmodified header must be cached because for any subsequent request (For example, a BYE originating from the terminator. See the following diagram.) the SBC might need to restore the original value, enabling the UAC to identify the message correctly as being part of the same dialog. For out-of-dialog requests (when the To, From, or Call-ID headers are modified) the original header is stored in the dialog when the msg-type out-of-dialog is used.

The SBC performs the restoration of original headers outside of SIP manipulations. There are no manipulation rules to configure for restore the header to their original context. The SBC recognizes that the headers are modified, and restores them to their original state prior to sending the message out. Restoration takes place prior to outbound manipulations so that any outbound manipulation can those headers after they are restored.

This didagram shows a BYE message originating from the UAS

Outbound HMR Challenge

When you use the out-of-dialog setting for an outbound manipulation, the Oracle Communications Session Border Controller executes this specific SIP header rule only if the same SIP header rule was executed against the initial dialog-creating request.

For example, if the INVITE’s To header was not manipulated, it would not be correct to manipulate the To header in the BYE request. To do so would render the UAC unable to properly match the dialog. And this also means that the outbound manipulation should be carried out against a To, From, or Call-ID header in the BYE request if it was manipulated in the INVITE.

This diagram shows a call flow where out-of-dialog is appropriate.

Dialog-matching Header Manipulation Configuration

You using the out-of-dialog setting in the msg-type parameter, part of the SIP header rules configuration.

To enable dialog-matching header manipulation:

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)#

msg-type—Set this parameter to out-of-dialog to enable dialog-matching header manipulation.
Type done to save your work.

Built-In HMRs

In the course of HMR use, certain SIP manipulations have become commonly used. Oracle created a library of built-in SIP manipulations that you use exactly like the HMRs you create yourself. You apply the built-in HMRs as arguments to the in-manipulationid and out-manipulationid parameters for session agents, realms, and SIP interfaces. You can also apply them in HMR sets as a nested manipulation.

Built-in rules start with the prefix ACME_, so Oracle recommends you name your own rules in a different manner to avoid conflict.

You can view a list of built-in manipulations using the following ACLI command:

show built-in-sip-manipulation

ACME_NAT_TO_FROM_IP

When performed outbound, this rule changes:

The To-URI hostname to the logical $TARGET_IP and port to $TARGET_PORT
The From-URI to the logical $LOCAL_IP and port to be $LOCAL_PORT

Note:

This built-in HMR only runs when the URI-host is an IP address, not when it's a domain name.

When applied in an inbound manner, the remote and local ports are reveresed.

Built-In Variables

To improve performance and reduce development complexity, the SBC contains built-in variables for common components of the SIP message. These reserved variables operate exactly like customer-defined variables. The recommended syntax is:

$<variable>.$0

For example:

$PAI_USER.$0

When you omit the $0, the resulting value is TRUE or FALSE, which can be useful to determine if there was no username in the PAI header or that no PAI header exists.

The values for the variables are obtained when they are resolved. For example, when the To-URI has been changed by a previous rule, the current rule gets the changed value (as would apply to $ORIGINAL). When the header or value does not exist in the SIP message, either an empty string is returned or, for Boolean uses, the value FALSE is returned.

The following table lists and describes the built-in variables.

Variable	Description
$ORIGINAL	Original value of element
$LOCAL_IP	IP address of the SIP interface on which the message was received for inbound manipulation or sent on for outbound manipulation.
$LOCAL_PORT	Port number of the SIP interface on which the message was received for inbound manipulation or sent on for outbound manipulation.
$REMOTE_IP	IP address the message was received from for inbound manipulation or sent to for outbound manipulation.
$REMOTE_PORT	Port number the message was received from for inbound manipulation or sent to for outbound manipulation.
$REMOTE_VIA_HOST	Host from the top Via header of the message.
$TRUNK_GROUP	Legacy reserved variable that can resolve to <TRUE/FALSE>.
$TRUNK_GROUP_CONTEXT	Legacy reserved variable that can resolve to <TRUE/FALSE>.
$REPLY_IP	IP address where the SIP message came from
$REPLY_PORT	Port number where the SIP message came from
$TARGET_IP	IP address where the SIP message is sent to
$TARGET_PORT	Port number where the SIP message is sent to
$MANIP_STRING	The manipulation string
$MANIP_PATTERN	Use a regex pattern from the most specific matching session agent, realm, or SIP interface. Only this variable can be used in the match-value field. You cannot combine it with additional characters. This variable can be used in any rule you use a pattern-rule match value, including store action rules. You can also reference the stored values from those referenced in later rules. For example, you can create an allow list based on trunk From header uri-user parameter. Each session agent passes a different string on which to perform the allow list operation. Because the MANIP_PATTERN is dynamically decided at run-time every time the HMR executes for each message, it is possible no manipulation pattern will be found. In this scenario, it will use the default `\,+`. This default works most like `.+`. It is also possible a sub-group might be referenced that was not in the pattern chosen, in this scenario the variable resolves to empty/FALSE.
$CRLF	Search for carriage returns in new lines. Because you can search for these value and replace them, you also must be able to add them back in when necessary. Resolves to `\r\n` and is commonly used in MIME manipulation. If you are creating a new body, there might be a need for many CRLFs in the new-value parameter.
$TO_USER	URI username from To header without any user parameters.
$TO_PHONE	URI user of the To header as a phone number without any visual separators and with the leading + if it is present.
$TO_HOST	URI host portion from the To header.
$TO_PORT	URI port number from the To header. This is set to 5060 if it is not actually in the message.
$FROM_USER	URI username from the From header without any user parameters
$FROM_PHONE	URI user of the From header as a phone number without any visual separators and with the leading + if it is present
$FROM_HOST	URI host portion from the From header.
$FROM_PORT	URI port number from the From header. This is set to 5060 if it is not actually in the message.
$CONTACT_USER	URI username from the first instance of the Contact header without any user parameters.
$CONTACT_PHONE	URI user of the first instance of the Contact header as a phone number without any visual separators and with the leading + if it is present.
$CONTACT_HOST	URI host portion from the first instance of the Contact header
$CONTACT_PORT	URI port number from the first instance of the Contact header. This is set to 5060 if it is not actually in the message.
$RURI_USER	URI username from the Request-URI header without any user parameters.
$RURI_PHONE	URI user of the Request-URI header as a phone number without any visual separators and with the leading + if it is present.
$RURI_HOST	URI host portion from the Request-URI header.
$RURI_PORT	URI port number from the Request-URI header. This is set to 5060 if it is not actually in the message.
$PAI_USER	URI username from the first instance of the P-Asserted-Identity header without any user parameters.
$PAI_PHONE	URI user of the first instance of the P-Asserted-Identity header as a phone number without any visual separators and with the leading + if it is present.
$PAI_HOST	URI host portion from the first instance of the P-Asserted-Identity header.
$PAI_PORT	URI port number from the first instance of the P-Asserted-Identity header. This is set to 5060 if it is not actually in the message.
$PPI_USER	URI username from the first instance of the P-Preferred-Identity header without any user parameters.
$PPI_PHONE	URI user of the first instance of the P-Preferred-Identity header as a phone number without any visual separators and with the leading + if it is present.
$PPI_HOST	URI host portion from the first instance of the P-Preferred-Identity header.
$PPI_PORT	URI port number from the first instance of the P-Preferred-Identity header. This is set to 5060 if it is not actually in the message.
$PCPID_USER	URI username from the P-Called-Party-ID header without any user parameters.
$PCPID_PHONE	URI user of theP-Called-Party-ID header as a phone number without any visual separators and with the leading + if it is present.
$PCPID_HOST	URI host portion from theP-Called-Party-ID header.
$PCPID_PORT	URI port number from the P-Called-Party-ID header. This is set to 5060 if it is not actually in the message.
$CALL_ID	Resolves to the Call-ID of the current SIP message; is a commonly stored rule.
$TIMESTAMP_UTC	Gets the current time from the SBC's system clock in RFC 3339 format: YYYY-MM-DDTHH:MM:SS.PPPZ The PPP is partial seconds and the time is based on UTC. For example: 2012-01-01 T22:00:09.123Z
$T_GROUP	Trunk group
$T_CONTEXT	Trunk group context
$M_STRING	A boolean that is true if the manipulation-string exists, false if not. The variable $M_STRING.$0 contains the manipulation-string.

The $TARGET_IP and $REMOTE_IP Variables

The $TARGET_IP variable is always the next hop IP address for a SIP request. This variable is set only for requests.

The $REMOTE_IP variable changes depending on the state of the message. For outbound manipulations, the $REMOTE_IP variable is the destination IP address or next hop IP address; that is, the $REMOTE_IP and $TARGET_IP are the same for outbound manipulations. For inbound manipulations of a SIP request, the $REMOTE_IP variable is the reply IP address; that is, the $REMOTE_IP and $REPLY_IP are the same. For all other inbound manipulations, the $REMOTE_IP is set using the From header.

Built-In SIP Manipulation Configuration

When you want to enable this feature for a realm, session agent, or SIP interface, you configure the in-manipulationid or out-manipulationid parameters with the rule.

The sample here shows this feature being applied to a session agent, but the realm and SIP interface configurations also have the same parameter you use to set up the feature.

To use built-in SIP manipulations:

Access the session-agent configuration element.

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

out-manipulationid—Enter name of the built-in rule you want to use.

Note:
All built-in rules start with ACME_.
Save your work.

Unique Regex Patterns Per Peer and Trunk

The built-in variable $MANIP_PATTERN reduces the complexity of writing HMRs for multiple peers and trunks.

Similar to the reserved variable $MANIP_STRING, the variable $MANIP_PATTERN uses a regex pattern from the most-specific matching session-agent, realm, or sip-interface. Within these configuration objects, the "manipulation-pattern" attribute allows you to set a unique regex pattern. Only one regex pattern can be specified in the configuration attribute, and only the :variable $MANIP_PATTERN can appear in the match-value field (for example; the "$MANIP_PATTERN" cannot be combined with additional characters in the match-value).

This feature enables service providers to configure one or a few common global HMRs, while having a unique regex pattern for each SIP trunk or peer. It reduces the number of sip-manipulation sets that need to be provisioned, reducing provisioning work and system memory usage.

The $MANIP_PATTERN can be used in any rule you can use a pattern-rule match-value in, including store action rules. You can also reference the stored values from those referenced in later rules for example: using the $RuleName for the Boolean TRUE or FALSE, or $RuleName.$0 for the whole matching string). For example, you can create an allow list based on the trunk From header uri-user parameter. Each session-agent then passes a different string on which to perform the allow list operation. The following code block shows a configuration example:

sip-manipulation
    name                            sipTrunkallowlist
    ...
    header-rule
        name                        allowlistOnFrom
        header-name                 From
        action                      manipulate
        comparison-type             case-sensitive
        msg-type                    out-of-dialog
        methods                     INVITE
        match-value
        new-value
        element-rule
            name                    checkFromUriUser
            parameter-name
            type                    uri-user
            action                  store
            match-val-type          any
            comparison-type         pattern-rule
            match-value             $MANIP_PATTERN
            new-value
        element-rule
            name                    rejectIfNoMatch
            parameter-name
            type                    uri-user
            action                  reject
            match-val-type          any
            comparison-type         boolean
            match-value             !$allowlistOnFrom.$checkFromUriUser
            new-value               403:Forbidden

session-agent
    hostname                    172.16.50.101
    ip-address                  172.16.50.101
    port                        5060
    realm-id                    peer1-core
    ...
    manipulation-string
    manipulation-pattern        ^78132841([0-4][0-9])$
 
session-agent
    hostname                    172.16.50.102
    ip-address                  172.16.50.102
    port                        5060
    realm-id                    peer2-core
    ...
    manipulation-string
    manipulation-pattern        ^78132841([5-9][0-9])$

Rejecting SIP Requests

SIP requests can be rejected using HMRs.

To simplify rejecting SIP requests with HMRs, the SBC supports the reject action in any rule type. This rejects SIP requests if the conditions within the rule (match-value, msg-type, etc.) are true. When a SIP message is rejected, the SBC increments the counter called "Rejected Messages," which can be displayed in the ACLI with the show sip transport command. SIP responses cannot be rejected but the counter is still incremented.

A new MIB object in the ap-smgmt.mib for SNMP GET is available to obtain the counter value. The SBC can send an SNMP trap when the counter exceeds a configured threshold in a configured time window. The threshold is set by new “reject-message-threshold” and “reject-message-window” config attributes in session-router config.

When rejecting a matching SIP Request, a response-code and reason-phrase can be specified. In the rule configured with the "reject" action, enter the syntax status-code[:reason-phrase] in the new-value field. For example 401:Denied in the new-value of a reject action rule will cause the SD to reject the SIP Request with a 401 response and "Denied" as the reason-phrase.

sip-manipulation
    name                      rejectINV
    description
    header-rule
        name                  from508
        header-name           from
        action                manipulate
        comparison-type       case-sensitive
        msg-type              any
        methods               INVITE
        match-value
        new-value
        element-rule
            name              fromUser
            parameter-name
            type              uri-phone-number-only
            action            reject
            match-val-type    any
            comparison-type   case-sensitive
            match-value       5085551212
            new-value         401:Denied

Note:

When a SIP request matches a rule with a reject action, the rejection is immediate and later rules aren't executed.

Note:

The reject action should not respond with a 200 OK. Instead, use a response code in the 400, 500, or 600 range.

HMR Information in Logs

You can apply an action type called log to all manipulation rules. When you use this action type and a condition matching the manipulation rule arises, the SBC logs information about the current message to a separate log file. This log files will be located on the same core in which the SIP manipulation occurred. On the core where sipt runs, a logfile called matched.log will appear when this action type is executed.

The matched.log file contains a timestamp, received and sent SBC network interface, sent or received IP address:port information, and the peer IP address:port information. It also specifies the rule that triggered the log action in this syntax: rule-type[rule name]. The request URI, Contact header, To Header, and From header are also present.

----------------------------------------
Apr 17 14:17:54.526 On [0:0]192.168.1.84:5060 sent to 192.168.1.60:5060
element-rule[checkRURIPort]
INVITE sip:service@192.168.1.84:5060 SIP/2.0
From: sipp <sip:+2125551212@192.168.1.60:5060>;tag=3035SIPpTag001
To: sut <sip:service@192.168.1.84>
Contact: sip:sipp@192.168.1.60:5060