1. Header Manipulation Rules Resource Guide
  2. Header Manipulation Rules
  3. HMR Fundamentals

HMR Fundamentals

HMR is a tool language based on rulesets, header rules, and element rules.

  • Rulesets contain one or more header rules, as well as optional element rules that operate on specified header elements. They are applied to inbound or outbound traffic for a session agent, realm, or SIP interface.
  • Header rules operate on specific headers. They can contain element rules, each of which specify the actions to perform for a given element of this header.
  • Element rules perform operations on the elements of a header. Header elements include all subparts of a header, excluding the header name; for example, header value, header parameter, and URI parameter.

The OCSBC cannot dynamically perform validation as you enter rules. Use the ACLI verify-config command to confirm that the HMR configuration does not contain invalid or circular references.

  • An invalid reference is a reference that points to a non-existing rule.
  • A circular reference is a reference that creates an endless loop of manipulation actions.

Audience

This document is intended for those users who already understand the Oracle Communications Session Border Controller and the SIP protocol. In addition, Oracle recommends you become as HMR-savvy as possible by attending Oracle training courses prior to launching any HMR in production. You should be aware of all issues that might result from misinformed or misapplied HMRs.

When to Use HMR

HMR is a flexible, powerful tool. As such, Oracle recommend using it with utmost care. HMR should only be implemented in production networks once the HMRs and their applications have been rigorously tested in a lab environment. You want to ensure your HMRs work as you intend them before using them for your production network.

Oracle's Customer Support Team can assist you in developing HMRs for your network. Our customer support team can ensure that your HMR are constructed, configured, and applied properly, thereby guaranteeing your HMR achieves the result you want.

Managing HMR Impact on Performance

The following suggestions help manage HMR effect on performance.

  • Use the pre-constructed manipulations and variable tags. They consume less processing and decrease the effect on performance.
  • Include constructs and constrain the HMR to specific methods and messages. For example, you can limit effected methods or the length of a string match.
  • Construct the HMR to only work on the traffic that matches your criteria, letting the remaining traffic pass untouched. (Unless you want to manipulate all traffic.)
  • Take advantage of the test tools available on OCSBC to evaluate your HMRs.
  • Administer the HMRs by using HMR export and import and reorder tools also available.
  • Use logfiles to resolve issues.

Applying HMRs to Traffic

You can apply HMR rules to inbound or outbound traffic for session agents, realms, and SIP interfaces. The order of precedence is:

  1. session agent
  2. realm
  3. SIP interface

A SIP manipulation applied to a session agent overrides the other two, and a SIP manipulation for a realm overrides one for a SIP interface.

Outbound HMR

Outbound HMR rules are applied just before the SIP message is sent out by the OCSBC, after SIP-NAT processing. Any changes made by the HMR affects the message. Those changes are not overridden by the OCSBC, which means the OCSBC does not prevent the rules from breaking the protocol.

The rules are performed in a stateless manner. They do not store values across messages and they do not remember what they did in previous messages.

Note:

You can work around the stateless behavior by having an inbound HMR copy the information needed to a private header, which then goes through the OCSBC. The outbound rule can then look for the header and act upon the information.

Inbound HMR

Inbound HMR rules are applied before most processing done by the OCSBC, but after some SIP parser processing is performed. The message's source is determined to decide which session agent, realm, or SIP interface it belongs to.

By default, the header rules are applied after the message is parsed; this verifies the message is well-formed and follows the specifications. This is necessary to securely perform any subsequent message processing, including HMR. An exception to this rule can be created by setting the inmanip-before-validate option. See "SIP Header Pre-Processing HMR" for more details.

Because inbound rules are applied before the message is completely processed by the OCSBC, you can use them to make the OCSBC perform specific actions outside of ordinary processing. For example, you can change the request-URI, add a Route header, or add a trunk group URI to make the OCSBC route the request on a different path.

Inbound rules are stateless. However, if the OCSBC is in B2BUA mode (its most common mode) it stores and remembers certain header values for later use in the dialog. If HMR changes them on inbound, the OCSBC later believes them to be the actual received values. There are a few exceptions to this with the following headers:

  • To and From can be changed by HMR and are used when the message gets forwarded out another interface.

    But if they were for a new request message, the OCSBC remembers the original ones when it sends back 1xx-6xx responses. The previous hop that sent the new request inspects the responses and needs them to be identical based on SIP protocol rules. However, requests sent by the OCSBC back to the originator for the call, from the called to the caller, will not be automatically undone by the OCSBC as the responses were.

  • Call-ID values are stored before HMR is applied and cannot be changed by HMR on inbound.

If a SIP INVITE is received for a new call, inbound HMR can change the To or From headers so that the next hop device gets the changed headers and the OCSBC stores them. But the 100 Trying, 180 Ringing, and 200 OK responses, for example, will use the original To and From values and not the HMR modified ones. If the called party later sends a Bye or re-Invite, back to the caller, the OCSBC will then use the HMR modified values it stored, which may or may not be correct.

Order of Header Rule Application

The OCSBC applies SIP header rules in the order you have entered them. This guards against the OCSBC removing data that might be used in the other header rules.

This ordering also provides you with ways to strategically use manipulations. For example, you might want to use two rules if you want to store the values of a regular expression. The first rule would store the value of a matched regular expression, and the second could delete the matched value.

In addition to taking note of the order in which header rules are configured, you must also configure a given header rule prior to referencing it. For example, you must create Rule1 with the action store for the Contact header before you can create Rule2 which uses the stored value from the Contact header.

HMR Store Actions and Boolean Results

Although HMR rulesets are stateless (they do not store values across messages nor remember what they did in previous messages), they can store strings for use within the same ruleset. Some header rules and element rules can store values that later header rules or element rules can use. Once the set of header rules and element rules in a SIP manipulation are performed, and the SIP manipulation is complete for the message, the stored values are forgotten.

Routing Decisions

Before routing the message, the OCSBC parses the ingress SIP message, ensuring the validity of the message's structure. After this parsing, the OCSBC applies the inbound header manipulation. You can use the inbound HMRs to modify the OCSBC's routing behavior if you want to increase the flexibility of the routing options.

An outbound HMR is the last processing the OCSBC performs on traffic before passing it back to the interface hardware. Knowing where this processing fits in helps you to know what state the traffic will be in before being processed by the outbound HMR. Outbound traffic is not subject to the screening functions performed by the hardware on inbound traffic.

Static and Dynamic HMR

You can manipulate the headers in SIP messages both statically and dynamically. You can edit response headers or the Request-URI in a request, and change the status code or reason phrase in SIP responses.

Static HMR

Static HMR lets you set up rules that remove and/or replace designated portions of specified SIP headers. The OCSBC can:

  • Search headers for dynamic content or patterns with the header value. It can search, for example, for all User parts of a URI that begin with 617 and end with 5555 (e.g., 617...5555).
  • Manipulate any part of a patterns match with any part of a SIP header. For example, 617 123 5555 can become 617 231 5555 or 508 123 0000, or any combination of those.

Dynamic HMR

SIP HMR lets you set up dynamic header manipulation rules that give the OCSBC complete control over alterations to the header value. Using regular expressions provides a high degree of flexibility for header manipulation. For example, you can search a specific URI when you do not know the value of the parameter, but want to use the matched parameter value as the header value. It also lets you preserve matched sections of a pattern, and change what you want to change.

Sample HMR

The following shows a complete HMR that manipulates To and From headers, changes the URI-host element, and hides IP topology. It is applied as outgoing for a realm. The HMR includes a built-in HMR variable $REMOTE_IP. 

sip-manipulation
    name                                    NAT_IP
    description
    split-headers
    join-headers
    header-rule
        name                                    To
        header-name                             To
        action                                  manipulate
        comparison-type                         case-sensitive
        msg-type                                request
        methods
        match-value
        new-value
        element-rule
            name                                    To
            parameter-name
            type                                    uri-host
            action                                  none
            match-val-type                          ip
            comparison-type                         case-sensitive
            match-value
            new-value                               $REMOTE_IP
    header-rule
        name                                    From
        header-name                             From
        action                                  manipulate
        comparison-type                         case-sensitive
        msg-type                                request
        methods
        match-value
        new-value
        element-rule
            name                                    From
            parameter-name
            type                                    uri-host
            action                                  none
            match-val-type                          ip
            comparison-type                         case-sensitive
            match-value
            new-value                               $LOCAL_IP