Oracle SBC HMR Notes

HMR Rule Notes

#

HMR rules are are stateless rule-sets that can edit any header, SDP in a sip message. You can only have one rule-set for inbound or outbound messages but any number of header rules or element rules in a rule-set.
More information can be found on the Oracle website Header Manipulation Rules Guide - for Service Provider and Enterprise

Guide Lines

#

• Define Storage rules first.
• Rules should be implemented at the element rule level and not the header-rule level.
• use multiple element rules to modify a header. Do not use multiple header rules.
• For better performance it is best to use built in variables. Avoid lengthy matches unless necessary. Constrain your SIP method and message type.

Terms

#

• Regex: short for regular expression
• Header-rules: used for the entire header.
• Element rule: used for specific parts of a header. It is a sub-element of header-rules. This option is needed to store sub-elements of a header.

Header Breakdown

#

The following outlines the sections of a header. It is useful to keep this info in mind for identifying the sections of a header. Using the following from header as an example. The parameter breakdown would be as follows.

From: "Test Phone Display" <sip:4085151111@10.10.9.132:5060>;tag=ECC78E56-382

• uri-header = From: "Test Phone Display" <sip:4085151111@10.10.9.132:5060>;tag=ECC78E56-382
• uri-header-name = From
• header-value = "Test Phone Display" <sip:4085151111@10.10.9.132:5060>;tag=ECC78E56-382
• uri-display = Test Phone Display
• uri-user = 4085151111
• uri-host = 10.10.9.132
• uri-port = 5060
• header-param-name = tag
• header-param = tag=ECC78E56-382
• plus more.

Order of Operations

#

• Hardware Level processing (DDoS, ACL’s, Policers, Decryption, etc.).
• Software Level Processing (Dos, Authorization, Allowed Methods, etc.).
• Inbound Rules.
  • HMR.
  • Number Translation.
• Call Routing.
• Lookup Table for Media.
• Outbound Rules
  • Outbound HMR.
  • QoS.
  • Number Translation.
• Hardware Level processing: transmit to port / VLAN.

HMR Structure

#

header-rules

#

Edit the entire header depending on the following settings.

• header-name: the header you wish to act on. via, request-uri, from, to, etc.
  • Case-insensitive.
  • Must match a actual header in the SIP message.
  • To match a status code(e.g. 404) you can use @status-line.
  • To manipulate the SDP body you can use content-type.
• action: what action you will take on the header. add, delete, manipulate (requires element-rule), store (may need an element-rule if you want to store part of a header).
  • find-replace-all: matching on a specific value.
  • reject: rejects requests but not responses.
  • log: creates an entry in matched.log every time it executes.
• comparison-type: How you should match you header / element. Options are case-sensitive, case-insensitive, pattern-rule, boolean, refer-case-sensitive(does not work with action store), refer-case-insensitive(does not work with action store)
• methods: What SIP methods you want the rule to apply to. e.g. INVITE, REGISTER. If this option is left blank it will apply to all methods
• match-value: used with comparison-type, the actions will only be preformed if the match-value matches the value in the message.
• new-value:
  • + will append.
  • +^ will prepend.
  • - will truncate.
  • -^ will truncate from the front.

element-rule

#

Edit specific parts of a header, only runs if the header-rule condition matches. sub-element of a header are header-value, uri-display, uri-user, uri-host, uri-port, header-param-name, header-param.

• you can have multiple rules, each rule should operate on one part of the header. e.g. one rule for each of the following header-value, uri-display, uri-user, uri-host, uri-port, header-param-name, header-param
• parameter-name: using the below example it would be either branch or tag if type is set to header-param.
  • "Test Phone Display" <sip:4085151111@10.10.9.132:5060>;branch=dvfs09fdas909fdsfdsf;tag=ECC78E56-382
• type: This would be one of the following types. example data included.
  • header-value = "Test Phone Display" <sip:4085151111@10.10.9.132:5060>;branch=dvfs09fdas909fdsfdsf;tag=ECC78E56-382
  • uri-display = Test Phone Display
  • uri-user = 4085151111
  • uri-host = 10.10.9.132
  • uri-port = 5060
  • header-param = branch=dvfs09fdas909fdsfdsf;tag=ECC78E56-382
  • plus more.
• action: what action you will take. add, delete, manipulate, store.

Built-In Variables

#

These variables are all caps and can include a _ they will begin with a $. A couple common variables are as follows.

For a complete list you can refer to this guide HMR Components

Boolean Results

#

Boolean values are used in a similar manor to their stored regex match. if the match-value pattern matches a result then the Boolean is True. this result can be used later in other header-rules or elements-rules. a ! can be used to match on the opposite of the match value for negation match.

Duplicate Headers

#

With the below example you write a head rule to look ar all headers or a subset.

Diversion: <sip:fsifhjdfFDSF494+3mnrfew@10.0.0.10:5060;lrltransport=udp>
Diversion: <sip:fsifhjdfFDSF494+3mnrfew@10.0.0.10:5060;lrltransport=udp>

Subgroups

#

used to replace portions of a regex pattern. the syntax is formed by adding [[:n:]] to the end of the regex pattern. n is the group to replace.

• sip:user()@host[[:1:]] would match the empty () in user()
• sip:user()@(host)[[:2:]] would match the host in (host)

MIME Manipulations

#

MIME are considered an attachment to the SIP Header Message. MIME manipulations use the same header / element structure. they may use more system resources. actions like find-replace-all should only be used if there are no other options. the following escaped characters can be used. the entire SDP message is also a single string so any rule will execute against the entire SDP body.

When matching an SDP body use of .* or .+will only match a single line of a SDP body because . exempts carriage return. To match multiple lines you can use \,* or \,+

Examples

#

Blacklisting a Call

#

You can use the following configuration in a element rule to reject a call.

header-rule
  name               from_1313555
  header-name        from
  action             reject
  comparision-type   pattern-rule
  msg-type           request
  methods            INVITE
  match-value        ^1313555
  new-value          403:Blacklisted

Convert a SIP Response

#

header-rule
  name               404to200
  header-name        @status-line
  action             manipulate
  comparision-type   case-sensitive
  msg-type           reply
  methods            OPTIONS
  element-rule
     name            updateStatus
     type            status-code
     action          replace
     match-val-type  any
     match-value     404
     new-value       200
   element-rule
     name            updateReason
     type            reason-phrase
     action          replace
     match-val-type  any
     match-value     Not Found
     new-value       "Ping OK"

Find Replace All on SDP

#

sip-manipulation
  name                   removePtime
  desciription           Remoes the ptime attribute
  header-rule            
    name                 ConentTypeManip
    header-name          Content-Type
    action               mainpulate
    comparision-type     case-sensitive
    msg-type             request
    methods              INVITE
    element-rule         
       name              removePTime
       parameter-name    application/SDP
       type              mime
       action            find-replace-all
       match-val-type    any
	   comparision-type  patteren-rule
       match-value       a=ptime: [0-9]{1,2}{\n|\r\n}
       new-value

Testing Sip Manipulations

#

test-sip-manipulation

#

This can be done from the CLI if you make changes to a sip-manipulation while testing you may need to do refresh-manipulations for changes to reflect in the tool.

test-sip-manipulation
sip-manipulation <name of sip-manipulation>
load-sip-message

<an example SIP message>

debugging enabled
execute

test-pattern-rule

#

test-pattern-rule allows you to check your matching logic and confirm the group that the SBC will return. This can be done from the CLI.

• expression <you expression>
• string <sting>
• show

example

expression ".*(;branch=(.+)).*"
string "Test Phone Display" <sip:4085151111@10.10.9.132:5060>;branch=dvfs09fdas909fdsfdsf;tag=ECC78E56-382"

show
Pattern Rule:
        Expression : .*(;branch=(.+)).*
        String     : Display" <sip:4085151111@10.10.9.132:5060>;branch=dvfs09fdas909fdsfdsf;tag=ECC78E56-382
        Matched    : TRUE
        Matches:
$0 Display" <sip:4085151111@10.10.9.132:5060>;branch=dvfs09fdas909fdsfdsf;tag=ECC78E56-382
$1 ;branch=dvfs09fdas909fdsfdsf;tag=ECC78E56-382
$2 dvfs09fdas909fdsfdsf;tag=ECC78E56-382