5.2. Defining Rules

The ABC SBC‘s behaviour is specified in form of rules, as explained in Section A-B-C rules. These rules consists of conditions and actions and are processed sequentially until a matching rule is found.

Each rule may have none, zero or multiple conditions. If no condition is specified, the rule always matches and all its actions are executed. If multiple conditions are associated with a rule, the rule matches only if all of the individual conditions match.

An example of such a rule is shown in the Figure Example Rule. It consists of two conditions that match if a call is intended for a telephone number beginning with 900 and the caller is not registered. If the condition applies, the call is rejected using the 403 SIP code.

_images/example_rule.png

Figure 1: Example Rule

Each individual rule condition consists of three parts: a condition type, an operator and a value. Subsequent subsections describe all these parts in details.

5.2.1. Condition Types

The type of a condition defines the left operand for the operation. The following table describes all available condition types and operators types that are applicable to the respective condition types. Operators == ,  != , RegExp , does not match RegExp , begins with , does not begin with  are supported unless specified otherwise.

Condition type Description
Source Call Agent Check the source call agent. Only operators == and != are supported.
Source Realm Check the source realm. Only operators == and != are supported.
Source IP Check IP address the incoming request was sent from.
Source port Check port number the incoming request was sent from.
Inbound interface Check local interface the incoming request was received on. Value has to be chosen from a list of configured signalling interfaces. Only operators == and != are supported.
Source-IP CC (GeoIP) Check country code against source IP’s geographic region
R-URI Check current request URI.
R-URI User Check user part of request URI
R-URI User Parameter Check parameter in username part of request URI. For example in the R-URI  ”sip:106;name=franta@domain.com”, the parameter “name” can be checked for value “franta”
R-URI Domain Check host part of request URI, can contain port number
R-URI URI Parameter Check parameter of request URI.
From Check From header field value.
From URI Check value of From URI.
From User Check user part of From URI.
From Domain Check host part of From header URI, can contain port number
To Check To header field value.
To URI Check value of To URI.
To User Check user part of To URI.
To Domain Check host part of To header URI, can contain port number.
Header Check value of given SIP header. This condition is a kind of “escape-code” for testing headers for which no other conditions exist. The following header-fields will not be processed using this condition: From, To, Call-ID, CSeq, RAck, RSeq, Route, Contact, Via, Max-Forwards, Record-Route, Content-Type, Content-Length
Codecs Check presence/absence of codecs within SDP. Right operand specifies codec name. Only operators Contain , Contain RegExp and Do not contain are supported.
Media Types

Check presence/absence of media type within SDP. Right operand specifies media type name (e.g., audio,video)

Only operators Contain , Contain RegExp and Do not contain are supported.

SRTP Types

Check presence/absence of SRTP type within SDP. Right operand specifies media type name (e.g., dtls,sdes, none)

Only operators Contain , and Do not contain are supported.

Call Variable Check call variable value using selected operator. The call variable has to be already defined by Set Call Variable action. Any condition referring to an undefined value returns FALSE as result.
Call Variable Existence Tests if a variable exists or is undefined. This is useful for example when table lookups are used to discriminate accurately betwen non-existing and empty values.
Method Check SIP request method. Value has to be chosen from a list of allowed methods. Only operators == and !=  are supported.
Register cache Check content of register cache. Operands From URI (AoR + Contact + IP/port), From URI (AoR + IP/port), Contact URI (Contact + IP/port), To URI(AoR), R-URI (Alias) are supported
NAT Check first Via address wether the sender is or is not behind NAT. This compares the SIP message source IP with the first Via address and works only if the UA directly communicates with the SBC.
Read Call Variables Trigger a predefined query in provisioned tables by a specified key value. The condition returns true if the lookup was succesful, false otherwise.
Last Action Result Returns true if the last action completed succesfuly, false otherwise. (analogical to shell $? variable)
Blacklist Checks if a call-agent is on a black-list (or not). A call-agent is blacklisted when it is not reachable to make sure that no futile attempts to send traffic to it are undertaken.
Date and Time Checks whether a Datetime, Date or Time value is before or after now plus an optional offset. The value may be in the form ‘2016-05-25 13:10:41’, ‘2016-05-25’ or ‘13:10:41’. The offset can be years, days, hours, minutes or seconds, e.g. ‘2y’, or ‘30d’, or ‘12h’, or ‘5m’, or ‘1800s’.
Parallel Call Count Tests if the number of parallel calls is below or above a threshold. The number refers to the specific place in rules execution flow from which the condition was evoked. It does not refer to a global number of calls.
Parallel Call Count (global key) Tests if the number of parallel calls for a global key is below or equal/above a threshold.

5.2.2. Condition Operators

Operators supported within general conditions:

Operator Description
== left operand equals given value
!= left operand does not equal given value
RegExp left operand matches given regular expression
does not match RegExp left operand does not match given regular expression
begins with left operand starts with given string
does not begin with left operand does not start with given string
Contain right operand is contained in
Contain RegExp sample described by right operand is contained in
Do not contain right operand is not contained in

It is important to know that if a mediation action (Section SIP Mediation) changes content of SIP message, the condition will refer to the value after modification. E.g., if you apply the rule action “SetFrom(sip:new@from.com)”, the “From URI” operator will return sip:new@from.com!

Some conditions types take special operators and/or values. Particularly the “Register Cache” condition tests if a registration can be found in SBC’s cache. The condition uses a specific operator that determines which URIs are used for the test.

Supported operators for “Register Cache” are:

Operator Description
From URI (AoR + Contact + IP/port) the user with given From URI and Contact is registered from given IP:port
From URI (AoR + IP/port) the user with given From URI is registered with any Contact from given IP:port
Contact URI (Contact + IP/port) a user with given Contact is registered from given IP:port
To URI (AoR) the user with given To URI is registered
R-URI (Alias) the user with given request-URI is registered

The value for the “Register cache” condition allows to refine the test. It can be one of the following:

Register Cache Type Description
Is Registered true if registered using built-in registrar or cache
Is Not Registered true if not registered at all
Is Registered Locally true if registered using built-in registrar using the action “Save REGISTER contact”
Is Not Registered Locally true if not registered using built-in registrar
Is Registered Remotely true if URI cached using “Enable REGISTER caching”
Is Not Registered Remotely true if URI not cached

Supported operators for “Date and Time” are:

Operator Description
is after now plus The left operand is checked for being after the current time plus an offset
is before now plus The left operand is checked for whether it is before now plus an offset
is after now minus The left operand is checked whether it is after the current time minus an offset
is before now minus The left operand is checked for whether it is before the current time minus an offset

Note that the offset is optional, and it is always added or subtracted to the current time before the comparision.

5.2.3. Condition Values and Regular Expressions

Values in a condition may be of several kinds. They are interpreted in the following descending order.

  • |SBC| Escape Codes. These are characters prefixed by backslash (\) that are supposed to be interpreted literally. These are normally used only for special characters. For example, \\ stands for backslash and \$ stands for the dollar character.
  • |SBC| Replacements. These are variables that refer to different parts of SIP messages or internal variables. They are refered to by $ character followed by variable name and replaced with value of the variable. The variables that can be used are listed in Section Using Replacements in Rules.
  • regular expressions. Regular expressions are expected if one of the regular-expression matching operators is used. ABC SBC uses the “extended POSIX regular expression” syntax. That means, among others, that a section enclosed in parenthessis can be refered to from backreferencing expressions in actions’ parameters (see Section Using Regular Expression Backreferences in Rules), the special characters * (star: zero to any), + (plus: one to any), ? (question mark: none or one), and {a,b} (curly brackets: from a to b) specify the number of occurences, . (dot) stands for wildcard, ^ (caret) stands for beginning of a string, $ (dollar) stands for end of a string, | (pipe) stands for alternation and square brackets are used for character sets (^ as leading character means negation).
  • literals. This is the simplest case: a value is used for condition “as is” without further interpration. For example, in condition “R-URI User == foo”, the word foo is matched against the value of userpart of request URI.

Note that this interpretation order determines the condition result. If a regular-expression includes the “end-of-string” character, $, it must be preceded by backslash. Otherwise it will be interpreted in the previous step as an attempt to use a replacement. For example, the “empty string” regular expression must be denoted as “^\$”. Another more tricky example is “telephone numbers consisting of a star and two four-digit number blocks”. To make sure that a regular expression matches the whole userpart of a URI and not just a part of it, it must begin with “^” and end with “$”. Because star has a special meaning in regular expression language, it must be preceded with a backslash. And because the backslash may have special meaning in the ABC SBC GUI, it must appear twice. The resulting expression looks like this

^\\*([0-9]{4,4})([0-9]{4,4})\$

Also note that an expression in the right operand can contain replacements, but can not contain backreferences as described in Section Using Regular Expression Backreferences in Rules. These are only available as action parameters.

5.2.4. Actions

Actions define how a request shall be treated. There are many kinds of, described in the following sections of this gudie as well as in the Section Reference of Actions.

The key functionality available through the actions covers the following aspects of VoIP processing:

Action Group Purpose
SIP Mediation Manipulation of identity and URIs, header fields, and response codes. See Section SIP Mediation.
SDP Mediation Manipulation of codec and early media negotiation. See Section SDP Mediation.
Management and Monitoring Logging traffic and reporting SNMP statistics. See Section Diagnostics Dashboard and Using SNMP for Measurements and Monitoring.
Traffic Shaping Putting quota on SIP and RTP traffic and reporting violations. See Section Traffic Limiting and Shaping.
Media Processing Handling RTP traffic: RTP anchoring, RTP/SRTP conversion, RTP inactivity detection, audio recording and transcoding. See Section Media Handling.
SIP dropping Eliminating non-compliant traffic, silently or with a SIP response. See Section Manual SIP Traffic Blocking.
Scripting Processing of internal variables that are used to link multiple actions together using intermediate results stored in variables. See Section Binding Rules together with Call Variables.
Register Processing REGISTER caching and uncaching, registar, throttling. See Section Registration Caching and Handling.
External Interaction Queries to external servers by REST or ENUM or internal pre-provisioned database. See section Advanced Use Cases with Provisioned Data.
NAT Handling Fixing SIP to facilitate NAT traversal in a safer way than by the SIP specification. See Section NAT Traversal.