How To Guide

Generic Header Manipulation

&
Regular Expressions
For the Ingate SIParators® and Firewalls using software release 4.10.x or later.
Updated to show features available from release 5.0.4

28/05/2018

Revision History:
Revision Date Author Comments
1 2010-11-03 Scott Beer
2 2010-11-16 SB and KES First Release
3 2012-05-23 Scott Beer 4.10 updates
4 2012-05-23 KES Front page only
5 2015-07-10 RN Major rewrite and 5.0.4 updates
6 2015-09-24 KES Renamed to reflect RegExp also
7 2016-01-19 PD Minor content updates
8 2016-02-23 PD / AG Add $([syntax])
9 2016-11-21 PD Minor updates
10 2016-12-19 PD Errata bug catch, minor fixes
11 2017-04-16 PD / AG Add 6.0.x GHM variable
12 2017-10-26 PD Modifications to CVS/CHM
13 2018-05-28 PD New regexps, some rewrites

Page 1 of 35


Table of Contents
Errata ............................................................................................................................................ 4
1 Introduction ........................................................................................................................... 5
1.1 Example of Generic Header Manipulation .......................................................................................... 5
2 General about Generic Header Manipulation (GHM) .............................................................. 6
2.1 Where to configure GHM .................................................................................................................... 6
2.2 Incoming messages ............................................................................................................................. 9
2.3 Outgoing messages ........................................................................................................................... 10
3 Regular Expressions .............................................................................................................. 12
3.1 Industry-standard regular expressions notation ............................................................................... 12
3.2 Routing of calls using the Dial Plan and the SIP trunk Page .............................................................. 13
3.3 Examples of Basic Regular Expressions ............................................................................................. 17
3.4 183 to 180 conversion ....................................................................................................................... 18
3.5 Do not REGISTER to trunk server(s) ................................................................................................... 18
3.6 Do not automatically monitor trunk server(s) with SIP OPTIONS ..................................................... 18
3.7 B2bua with media via the main dial plan .......................................................................................... 18
3.8 Explicitly stating transport ................................................................................................................. 19
3.9 Specifying Escape Characters (dial string) for e.g. Telia SIP trunk ..................................................... 19
3.10 Additional information ...................................................................................................................... 19
4 Conditional Regular Expressions (CRE) .................................................................................. 20
4.1 Example CRE - Sweden Number Reduction ....................................................................................... 20
4.2 Example CRE - USA Number Reduction ............................................................................................. 20
4.3 Generic Number Reduction to + prefix for phone numbers 8-12 digits long .................................... 21
5 Variable Substitution ............................................................................................................ 22
5.1 Port and Password ............................................................................................................................. 23
5.2 Examples ........................................................................................................................................... 25
6 Generic Header Manipulation (GHM) ................................................................................... 26
6.1 Adding or Replacing a Header ........................................................................................................... 26
6.2 Removing a header ............................................................................................................................ 27
6.3 Generic Header Manipulation (GHM) for Responses ........................................................................ 27
6.4 Multiple Occurrences of Headers ...................................................................................................... 28
6.5 Variable substitution ......................................................................................................................... 28
7 Conditional Variable substitution (CVS) ................................................................................ 30
7.1 Conditional Header Manipulation (CHM) .......................................................................................... 30
7.2 URI Parameter Chaining .................................................................................................................... 33
8 Keyword / Grammar Summary – CVS, CHM and CRE ............................................................. 35
8.1 Tests .................................................................................................................................................. 35
8.2 Results ............................................................................................................................................... 35
8.3 RegExp ............................................................................................................................................... 35

File name: How_To_use_Generic_Header_Manipulation.pdf

How To Guide: Generic Header Manipulation & Regular Expressions Page 2 of

f 35


Terminology used in this document:

Abbreviation Term
GHM Generic Header Manipulation
CRE Conditional Regular Expressions
CVS Conditional Variable Substitution
CHM Conditional Header Manipulation
B2BUA Back to Back User Agent
ITSP Internet Telephony Service Provider

How To Guide: Generic Header Manipulation & Regular Expressions Page 3 of

f 35


Errata:

Note: In firmware versions <= 5.0.11 you cannot use $1?From=$(......$1...) – i.e. regexp capture
result groups (on the trunk page i.e. where $1 is before and after the “?”), and $REGMATCH
expressions which also contain their own $1 capture groups. The workaround is to use
$0?From=$(....$1…).

Expressions such as the following will fail to evaluate:

sip:$1@192.168.1.1?From=%3Csip%3a$(REGMATCH_^001([0-
9]{10})$_REGMOD_+1$1_REGELSE_^1([0-9]{10})$_REGMOD_+1$1_REGELSE_([0-
9]{10})$_REGMOD_+1$1_REGEND.from.user)%40$(from.host)$([from.uriparams]) %3E$(fro
m.params)
A workaround is thus:
sip:$0?From=%3Csip%3a$(REGMATCH_^001([0-9]{10})$_REGMOD_+1$1_REGELSE_^1([0-
9]{10})$_REGMOD_+1$1_REGELSE_([0-
9]{10})$_REGMOD_+1$1_REGEND.from.user)%40$(from.host)$([from.uriparams]) %3E$(fro
m.params)

$0 evaluates to the whole user portion of the RURI on the trunk page.

Or not to use a capture group on the trunk page e.g.

Incoming Trunk Match Forward to
(.*) $1

While instead use:

Incoming Trunk Match Forward to
.* $0

If a fix is necessary e.g. you must forward trunk captures to a host which differs from the PBX
configured on the trunk page, write to support@ingate.com for a patch for your current firmware
version <= 5.0.11, or upgrade your firmware > 5.0.11

How To Guide: Generic Header Manipulation & Regular Expressions Page 4 of

f 35


1 Introduction
This document describes how to use Generic Header Manipulation (GHM) in an Ingate
SIParator/Firewall. With the GHM feature it is possible to Add, Change or Remove any SIP Header
of incoming or outgoing SIP messages, both Requests and Responses.
The purpose of this feature is to enhance the interoperability between different vendor equipment, as
many IP-PBX, Service Providers, and overall SIP devices require different usage of various SIP
Headers. Different vendors interpret the SIP standard in a non-conformant way and by using GHM
can SIP protocol variances be resolved.
Rules are configured in the Dial Plan and SIP Trunk Page GUIs. The rules are configured in the same
fields as regular expressions are written. With regular expressions, it is possible to match substrings
and variables from SIP messages. When forwarding SIP messages, they can be rewritten according to
your wishes. By variable substitutions it is also possible to take information from one header and put
it in another header.
Note: Text written in a Monospace Font signifies regular expression code i.e. GHM, CHM,
CRE, CVS or processing result.
Note: Result samples are not intended to be protocol-accurate or compliant; they are intended for
demonstration only and reduced for simplicity.

1.1 Example of Generic Header Manipulation

For example, when a Service Provider requires the use of a P-Asserted-Identity Header and the IP-
PBX is unable to provide this SIP Header, the Ingate can add in a P-Asserted-Identity Header. As
seen here:
INVITE sip:6135551212@209.216.177.59:5060 SIP/2.0
Via: SIP/2.0/UDP 209.249.3.100:5060;branch=z9hG4bK9624349
To: sip:6135551212@209.249.3.56:5060
From: <sip:5035551111@209.249.3.100>;tag=3462103187-665679
Supported: timer, 100rel
Call-ID: 2165939-3462103187-665672@NXT02.broadvox.net
CSeq: 1 INVITE
Allow: INVITE, BYE, OPTIONS, CANCEL, ACK, REGISTER, PRACK, UPDATE
Max-Forwards: 69
Session-Expires: 3600;refresher=uac
Contact: sip:5035551111@209.249.3.100:5060
Content-Type: application/sdp
Content-Length: 249
The additional header will be added into the SIP message when it is forwarded through the Ingate
unit.
INVITE sip:6135551212@209.216.177.59:5060 SIP/2.0
Via: SIP/2.0/UDP 209.249.3.100:5060;branch=z9hG4bK9624349
To: sip:6135551212@209.249.3.56:5060
From: <sip:5035551111@209.249.3.100>;tag=3462103187-665679
Supported: timer, 100rel
Call-ID: 2165939-3462103187-665672@NXT02.broadvox.net
CSeq: 1 INVITE
Allow: INVITE, BYE, OPTIONS, CANCEL, ACK, REGISTER, PRACK, UPDATE
Max-Forwards: 69
Session-Expires: 3600;refresher=uac
Contact: sip:5035551111@209.249.3.100:5060
P-Asserted-Identity:sip:5035551111@64.156.174.74:5060
Content-Type: application/sdp
Content-Length: 249

How To Guide: Generic Header Manipulation & Regular Expressions Page 5 of

f 35


2 Generic Header Manipulation (GHM) – Why do we need GHM?

The GHM feature allows arbitrary manipulation of SIP headers when the SIP messages are
transmitted through the Ingate Firewall/SIParator. It is possible to Add, Change or Remove any SIP
Header of incoming or outgoing SIP messages, both Requests and Responses. In addition, the GHM
feature can use regular expressions to modify existing SIP headers, add SIP headers, and to match
SIP headers to store variable information.

The following list summarizes the supported GHM actions for a SIP header:
• Add a header to the message, if the header doesn’t exist
• Replace header content
• Pass a header unchanged
• Remove a header
• Replace an instance of a header
All listed actions can be done conditionally – i.e. check for a matching condition, and then act.
Header manipulation for requests are performed after routing of calls, while responses are modified
prior to routing.

2.1 Where to configure GHM

Regular expressions for configuring matches from SIP message are configured in the below listed
locations within the Ingate Firewall/SIParator (marked with blue in the figures below).
Rules for regular expression substitution and header manipulation of SIP messages are configured in
the Forward To type of fields in the below listed locations within the Ingate Firewall/SIParator
(marked with red in the figures below).

Regular Expression match Header manipulation/Regular Expression

Substitution
SIP Traffic > Dial Plan SIP Traffic > Dial Plan
Matching From Header – Reg Expr Forward To – Reg Expr
Matching Request-URI – Reg Expr
SIP Traffic > Routing
User Routing – Forward To
Static Registrations – Forward To
SIP Trunks > Trunk n page SIP Trunks > Trunk n page
Main Trunk Line – Incoming Trunk Match Main Trunk Line – Username and Forward

PBX Lines – From PBX Number/User and PBX Lines – Username and Forward To PBX
Incoming Trunk Match Account
SIP Lines – From SIP Number/User and SIP Lines – Username and Forward To SIP
Incoming Trunk Match Account
SIP Traffic – Dial Plan

The purpose of the Matching From Header is to provide source SIP URI matching, as well as source
Transport and Network Address. In the Regular Expression, you create criteria for the From Header

How To Guide: Generic Header Manipulation & Regular Expressions Page 6 of

f 35


SIP URI of the SIP messages. This is used when matching requests in the Dial Plan. For a request to
match, all criteria must be fulfilled.

The purpose of the Matching Request URI is to match on incoming Request URI Header of the SIP
messages being sent to the Ingate. Typically, the “domain” portion of the URI is the Ingate IP
Address or FQDN. In the Regular Expression, you create criteria for the Request-URI of the SIP
messages. This is used when matching requests in the Dial Plan. For a request to match, all criteria
must be fulfilled.
Port and Transport can be used but it only matches if there's both a port and a transport parameter
contained in the SIP URI

The purpose of the Forward To attribute of the Dial Plan is to define where to send the SIP traffic. A
specific destination SIP URI address is defined to forward the call to. Here you may enter Regular
Expressions for the Dial Plan, used to define where and how the firewall should forward the request
using the Dial Plan. Here you may also enter rules for GHM and variable substitution.
SIP Traffic – Routing

With Static Registrations you can specify that calls to a certain user address should also be redirected
to another address, or that calls to a non-person user name (like support@company.com) should be
redirected to one or more other addresses. Even if a call should be forwarded, the SIParator will try to
put it through to the original addressee.
The User Routing table makes it possible to allow advanced routing options to be enabled per user.
You may enter aliases that are used to match incoming request to a specific user. Additionally you

How To Guide: Generic Header Manipulation & Regular Expressions Page 7 of

f 35


may define that the request should be forwarded to other users, and also set up connections to voice
mail.
In respective Forward to field you may use Variable substitution and GHM, but not regular
expressions.
SIP Trunk – Trunk 1-n

From PBX/SIP Number/User - Can contain a number/name or regular expression. For outgoing
calls, this field is matched to the calling user's user name in the From SIP URI (often a number but
can also be a name). If there is a match, this line is selected for usage for the outgoing call.
User Name - The SIP user name to use in the From SIP URI for outgoing calls and registrations.
This is usually the telephone number of the ITSP SIP account and usually the number displayed as
caller ID on the PSTN. In this field you can use the result of a sub-expression from a match in a
regular expression defined in the "From Number/User" field on the same row.

How To Guide: Generic Header Manipulation & Regular Expressions Page 8 of

f 35


2.2 Incoming messages

The SIP Trunk page is designed to connect IP-PBXs and other SIP endpoints (phones) to an ITSP's
(Internet Telephony Service Provider's) SIP Trunking service using a B2BUA (Back-To-Back User
Agent) with one interface to the ITSP and the other to the IP-PBX and SIP phones.
For incoming SIP messages the rules for header manipulation of SIP massages are configured in the
GUI for the SIP Trunk Page, in the columns of Incoming Trunk Match and Forward to for PBX
Lines, SIP Lines, and for Main Trunk Line.
For every incoming SIP message the rows in Incoming Trunk Match, for PBX Lines and SIP

ITSP

LAN WAN

SIP trunk page

Incoming Trunk Match Forward to
Main trunk line

PBX lines

SIP lines

Lines, are gone through row for row until match. In case of no match the values from Main Trunk
Line are used.

When there is a match in Incoming Trunk Match field, the call will be forwarded according to the
values in respective Forward to field at the same row. For PBX Lines, this is the number an
incoming call will be forwarded to on the PBX. For SIP Lines, this is the SIP address (complete SIP
URI or a SIP user name/number on this unit's SIP Server) an incoming call will be forwarded to.
Regular expressions can be used in the Incoming Trunk Match field to catch information from the
R-URI to be used in the Forward to field, where also variable substitution and GHM can be made.

How To Guide: Generic Header Manipulation & Regular Expressions Page 9 of

f 35


An example of a regular expression is:

Incoming Trunk Match Forward to

\+1306(7707[0- 0$1
9]{2})
\+1306(7707[0- 0$1;user=phone
9]{2})
This will result in an incoming call to +1306770713, forwards to the PBX number 0770713. Here
you may also add URI parameters such as ";user=phone" at the end of the domain of a complete
URI.

2.3 Outgoing messages

Outgoing calls are processed through the Dial Plan. The Dial Plan table is searched line by line from
the top for a match from the PBX of the dialed number where after it is forwarded to the SIP Trunk
page.
At the SIP Trunk Page, the caller’s number (the user part of the From header) will - row by row, from

ITSP

LAN WAN

Dial Plan
From header Request URI Forward to

SIP trunk page

From PBX Number/User User Name/Idenity
Main trunk line

PBX lines

SIP lines

top to bottom - be checked against the numbers or regular expressions entered in the column From

How To Guide: Generic Header Manipulation & Regular Expressions Page 10

of 35


PBX/SIP Number/User. A match will cause the trunk account under User Name to be used for the
outgoing call.

The results of subexpressions from a match in the column From PBX/SIP Number/User can be used in
the columns Display Name, User Name and Identity.

To understand how GHM works it is first necessary to understand how regular expressions are used,
see next chapter.

How To Guide: Generic Header Manipulation & Regular Expressions Page 11

of 35


3 Regular Expressions
Within the SIP Protocol (RFC 3261), a SIP URI identifies a communications resource. Like all URIs,
SIP URIs may be placed in web pages, email messages, or printed literature. They contain sufficient
information to initiate and maintain a communication session with the resource. In its simplest form a
SIP URI looks like sip:user@host, where the "user" is the identifier of a particular client resource
at the host being addressed. The term "host" in this context frequently refers to a domain, a
network location.
When using Regular Expressions to define a SIP URI, these expressions allow for the customization
and flexibility to define SIP URIs as variables. Regular expressions can increase the capabilities of
the Ingate Dial Plan and SIP trunk pages as it further increases the definitions of the SIP URIs used to
route calls. The Regular Expression can be used to define both the user and host portion of the SIP
URI.

3.1 Industry-standard regular expressions notation

Regular Expression flavor used in Ingate SIParator/Firewall is “POSIX Extended Regular
Expressions (ERE)”.
Note: Character matches are case sensitive.
Operator Description
[] A bracket expression. Matches any single character that is contained within the brackets.
For example:
[abc] Matches any single character in the set a, b, or c.
[a-z] Matches any single character in the range a-z but not A-Z
[1-8] Matches any single character in the range 1 to 8.
[369] Matches any single character in the set 3, or 6, or 9.
[^ ] Matches any single character that is not contained within the brackets. For example:
[^abc] Matches any single character not in the set a, b, or c.
. Matches any single character.
, Matches the minimum specified characters or more.
[0-9] Matches any decimal digit.
[^0-9] Matches any non-digit.
\s Matches any whitespace character.
\S Matches any non-whitespace character.
\w Matches any word (alphanumeric) character.
\W Matches any non-word (alphanumeric) character.
(abc) Defines a marked sub-expression. For example: (abc) Matches the sequence abc and
stores it as a variable which may be used in later expressions. Also used for grouping.
$1 The $ symbol is used to recall expressions that have been stored within ( )-variables
which are numbered according to the capture hierarchy. $1 refers to the first variable
stored, and $2 refers to the second variable stored, etc.
a|b Matches a or b
+ Matches the preceding expression one or more times.
? Makes preceding expression optional; if the preceding is inside () brackets, e.g. (345)?
then that 345 is optional.
* Matches the null string or any number of repetitions of the preceding expression.
{m} Matches exactly m repetitions of the one-character expression.
{m,n} Matches between m and n repetitions of the preceding expression, inclusive.
{m,} Matches m or more repetitions of the preceding expression.

How To Guide: Generic Header Manipulation & Regular Expressions Page 12

of 35


^ Matches the starting position within the string.

$ Matches the ending position of the string.

3.1.1 Examples
(.*) Stores any amount of characters in $1
sip:(.*)@(.*) Stores user in $1 and host in $2 if applied to sip:user@host

Sub-expressions are numbered in the order of their starting parenthesis and referred to as $number. In
the expression sip:(.*)@(.*) which matches any Request-URl like sip:user@ingate.com, there
are two referable sub-expressions: user, which is referred to as $1, and ingate.com, which is
referred to as $2.
Sub-expression can also be nested, as in the expression (sip:(.*))@ingate.com, which matches
any Request-URI like sip:user@ingate.com, there are two referable sub-expressions:
sip:user, which is referred to as $1, and user, which is referred to as $2.

3.1.2 Escape sequence for special characters:

Meta characters are characters with a special meaning in Regular Expressions. There are 12
characters with special meanings: “\”, “^”, “$”, “.”, “|”, “?”, “*”,“+”, “(”, “)”, “[”, “{”. If you want to
use any of these characters as a literal in a Regular Expression, you need to escape them with a
backslash. For example “+”-sign will be \+ and +46701234567 will be \+46701234567.

3.2 Routing of calls using the Dial Plan and the SIP trunk Page
The dial plan and the SIP Trunk pages are used to instruct the Ingate SIP Proxy or B2BUA about
how to route calls. Who to accept calls from, match on where calls are going to, and where to send
calls. Adding regular expressions into the dial plan and the SIP trunk page allows you to specify a
range of numbers, range of domains, or other set of specific digits.
Regular expressions are a flexible way of delivering patterns that match a unique set of criteria. For
example, if you specify the regular expression [0-9]{7,} Ingate Firewall/SIParator recognizes any
digits from zero to nine, repeated seven or more times, in other words, a telephone number.

3.2.1 Regular Expressions in the Matching From Header

The purpose of the Matching From Header is to provide source SIP URI matching, that is matching
the FROM: field or the origin of a call.

How To Guide: Generic Header Manipulation & Regular Expressions Page 13

of 35


SIP URI Example Description Equivalent Regular Expression

7-digit number @ Any Domain sip:[0-9]{7}@.*
7-digit number @ IP Address sip:[0-9]{7}@12.34.56.78
7-digit number @ Domain sip:[0-9]{7}@sip_domain.com
7-digit number @ (anything hereafter doesn’t matter) sip:[0-9]{7}@(.*)
North American long-distance number @ sip:1[2-9][0-9]{9}@
North American Toll-free number: 1+800+7 digits sip:18(00 | 66 |77 |88)[0-9]{7}@
@
Local 7-digit number, beginning with optional 9 @ sip:9?[0-9]{7}@
4-digit number (as an extension) starting with 5 @ sip:5[0-9]{3}@
4-digit number not starting with 36 @ sip:(?36)[0-9]{4}@
Any Username @ Any Domain sip:.*@.*
Any Username @ IP Address sip:.*@12.34.56.78
Any Username @ Domain sip:.*@sip_domain.com
UK 7-digit numbers within the London area codes sip:020[78][0-9]{7}@
0207 and 0208@
UK 7-digit number with 0845 Lo-call prefix @ sip:0845[0-9]{7}@
UK 6 to 7-digit number with 0845 Lo-call prefix @ sip:0845[0-9]{6,7}@
UK 6-digit number with 0845 Lo-call prefix @ sip:0845[0-9]{6}@
UK 7-digit number with 0870 National prefix @ sip:0870[0-9]{7}@
UK 6 to 7-digit number with 0870 National prefix @ sip:0870[0-9]{6,7}@
UK 6-digit number with 0870 National prefix @ sip:0870[0-9]{6}@
UK 7-digit number with 0845 Lo-call or 0870 sip:08[74][05][0-9]{7}@
National prefix @ sip:(0870|0845)[0-9]{7}@
Note: the first will also match 0875 or 0840, the
second won’t
UK Any 9 to 10-digit numbers prefixed with sip:00?44[0-9]{9,10}@
optional OO and then mandatory 44
UK 7-digit Liverpool 151 numbers prefixed with O sip:0151[0-9]{7}@

3.2.2 Regular Expressions in the Matching Request URI

The purpose of the Matching Request-URl is to match a Request URI Header of the SIP messages
being sent through the Ingate and determine where it wants to go.
Typically the "domain" portion of the URI is the Ingate IP Address or FQDN. In the Regular
Expression, you create criteria for the Request-URl of the SIP messages. This is used to match
requests in the Dial Plan. For a request to match, all criteria must be fulfilled. Port and Transport can
be used but will only match if there are both port and transport parameters contained in incoming the
SIP URI.

How To Guide: Generic Header Manipulation & Regular Expressions Page 14

of 35


SIP URI Example Description Equivalent Regular Expression

7-digit number @ Any Domain sip:([0-9]{7})@.*
7-digit number @ IP Address sip:([0-9]{7})@12.34.56.78
7-digit number @ Domain sip:([0-9]{7})@sip_domain.com
7-digit number @ (anything hereafter doesn’t sip:([0-9]{7})@(.*)
matter)
Emergency numbers 112 or 999 @ sip:112|999@
Warning: not all SIP providers have access to emergency
service numbers.
North American long-distance number @ sip:1[2-9][0-9]{9}@
North American Toll-free number: 1+800+7 sip:18(00|66|77|88)[0-9]{7}@
digits @
Local 7-digit number, beginning with optional 9 sip:9?[0-9]{7}@
@
4-digit number (as an extension) starting with 5 sip:5[0-9]{3}@
@
4-digit number not starting with 36 @ sip:(?36)[0-9]{4}@
Remove Prefix "1613" on any Username @ sip:1613(.*)@(.*)
Anything
$1 is (.*) i.e. 1613 is matched but not stored. If
the number doesn't begin "1613", there will be
no match.
Remove Prefix "1613" on 11-digit number@ sip:1613([0-9]{7})@(.*)
Anything
and pass only 7-digits
$1 is ([0-9]{7}) $2 is (.*)
Remove optional Prefix "+" on any Username @ sip:\+?(.*)@
Note: some characters need to have an escape
sequence, among them the "+" character.
Any Username @ Any Domain sip:(.*)@.*
Any Username @ IP Address sip:(.*)@12.34.56.78
Any Username @ Domain
sip:(.*)@sip_domain.com
Any Username @ Any Domain with Port sip:(.*)@.*:5060
Any Username @ IP Address with Port sip:(.*)@12.34.56.78:5060
Any Username @ Domain with Port
sip:(.*)@sip_domain.com:5060
Any Username @ Any Domain with Port and sip:(.*)@.*:5060;transport=UDP
Transport sip:(.*)@12.34.56.78:5060;transport=UDP
Any Username @ IP Address with Port and sip:(.*)@sip_domain.com:5060;transport=UDP
Transport
Any Username @ Domain with Port and
Transport
UK 7-digit numbers within the London area codes 0207 sip:020[78][0-9]{7}@
and 0208@
UK 7-digit number with 0845 Lo-call prefix @ sip:0845[0-9]{7}@
UK 6 to 7-digit number with 0845 Lo-call prefix sip:0845[0-9]{6,7}@
@
sip:0845[0-9]{6}@
UK 6-digit number with 0845 Lo-call prefix @

How To Guide: Generic Header Manipulation & Regular Expressions Page 15

of 35


UK 7-digit number with 0870 National prefix @ sip:0870[0-9]{7}@

UK 6 to 7-digit number with 0870 National sip:0870[0-9]{6,7}@
prefix @
sip:0870[0-9]{6}@
UK 6-digit number with 0870 National prefix @
UK 7-digit number with 0845 Lo-call or 0870 sip:08[74][05][0-9]{7}@
National prefix @ sip:(0870|0845)[0-9]{7}@
Note: the first can also match 0875 or 0840, the
second won’t
UK Any 9 to 10-digit numbers prefixed with sip:00?44[0-9]{9,10}@
optional OO and then mandatory 44
UK 7-digit Liverpool 151 numbers prefixed with sip:0151[0-9]{7}@
O
Optional 353 prefix with or without optional 00 sip:(((00)?353)?0?[0-9]{1,2})?([0-9]{7})@.*
start, then optional 0 with optional 1-2 digit area
code, then mandatory 7-digit number @ any
domain.
Note: The following URI’s will match:
sip:0035312345678@abc.com
sip:35312345678@asdf.com
sip:12345678@asdf.com
sip:2345678@abc.com
sip:012345678@domain.com
sip:0212345678@wherever
Note: that in all of the above expressions, there is no match if the RURI isn't pre-pended with “sip:”,
i.e. requests beginning with “tel:” will not match. Also, while sip: is matched, it isn't stored in any of
the above examples.

3.2.3 Regular Expressions in the Forward To

The Forward To attribute of the Dial Plan defines where and how to send SIP traffic, A specific
destination SIP URI address is defined to forward the call to.
Here you may enter Regular Expressions for the Dial Plan, used to define where and how the firewall
should forward the request using the Dial Plan. A Regular Expression refers to RegExp sub-
expressions on the corresponding row in the Matching Request-URl table. Sub-expressions are
numbered in the order of their starting parenthesis and referred to as $number.
You may define lines in the Dial Plan that lack a Forward to definition. This is useful if you for
example are forwarding by ENUM.

How To Guide: Generic Header Manipulation & Regular Expressions Page 16

of 35


SIP URI Example Description Equivalent Regular Expression

Fixed number: 911 @ IP Address sip:911@12.34.56.78
Fixed number: 911 @ Domain sip:911@sip_domain.com
Fixed 7-digit number @ IP Address sip:9630933@12.34.56.78
North American long-distance number @ sip:16139630933@sip_domain.com
Domain
North American Toll-free number: 1+800+7 sip:18668090002@sip_domain.com
digits @ Domain
Use Stored Variable @ IP Address sip:$1@12.34.56.78
Use Stored Variable @ Domain sip:$1@sip_domain.com
Use Stored Variable @ Domain with Port and sip:$1@sip_domain.com:5060;transport=UDP
Transport
Use To Header in Request URI @ Domain sip:$(to.user)@sip_domain.com
Use To Header in Request URI and To Host in sip:$(to.user)@$(to.host);maddr=12.34.56.78
Domain and send to specified address
Add +1 in front of To Header in Request URI @ sip:+1$(to.user)@sip_domain.com
Domain
Note: The table includes examples of variable substitution, e.g. $(to.user), see chapter 5
Variable Substitution for explanation.

3.3 Examples of Basic Regular Expressions

Here are some basic examples of some standard Regular Expressions to be used in the Forward To
columns either of the Dial Plan or the SIP Trunk page (without the use of the Generic Header
Manipulation). The examples assume that there is a match done resulting in that $1 contains the user
part of the Request-URl.

Using Proxy Adding Port parameter

sip:$1@192.168.1.1 sip:$1@192.168.1.1:5060
sip:$1@example.com sip:$1@example.com:5060
Adding B2BUA Adding Transport parameter
sip:$1@192.168.1.1;b2bu sip:$1@192.168.1.1;transport=UDP
a
sip:$1@example.com;b2bu sip:$1@example.com;transport=UDP
a
Adding Prefix Adding From Header parameter
sip:+$1@192.168.1.1 sip:$1@192.168.1.1;from="sip:$(from.user)@1.2.3.4"

sip:+$1@example.com sip:$1@example.com;from="sip:$(from.user)@1.2.3.4"

Adding Any Combination (This is an example of adding Transport, Port, B2BUA and From
Header)
sip:$1@192.168.1.1:5060;transport=TCP;b2bua;from="sip:$(from.user)@1.2.3.4"
sip:$1@example.com:5060;transport=TCP;b2bua;from="sip:$(from.user)@1.2.3.4"
Note: the Adding From Header parameter includes an example of Variable Substitution. See
chapter 5 Variable Substitution for clarification.

How To Guide: Generic Header Manipulation & Regular Expressions Page 17

of 35


Note: the From Header is the only header that can be added in this way i.e. using the ;uriparams
format. All headers can be added through GHM, including the From header. See chapter 6 Generic
Header Manipulation (GHM).

3.4 183 to 180 conversion

If you want to convert a 183 Session Progress from the ITSP to a 180 Ringing towards the PBX
add ;cnv183 to the Domain Name or IP Address in the Service Provider Domain field at the SIP
Trunk page.
Service Provider Domain:
10.20.30.40;cnv183

3.5 Do not REGISTER to trunk server(s)

Add ;no-reg to the Domain Name or IP Address in the Service Provider Domain field at the SIP
Trunk page. Requires firmware >= 6.0.3.
Service Provider Domain:
10.20.30.40;no-reg,10.20.30.41
This disables sending of REGISTER to a proxy when multiple proxies are entered in the Service Provider
Domain.

3.6 Do not automatically monitor trunk server(s) with SIP OPTIONS

Add ;no-mon to the Domain Name or IP Address in the Service Provider Domain field at the SIP
Trunk page. Requires firmware >= 6.0.3. In firmware >= 6.0.3, SIP Trunk servers are automatically
monitored
Service Provider Domain:
sip.itsp.com,sip2.itsp.com;no-mon
This disables sending of SIP OPTIONS to a proxy when multiple proxies are entered in the Service Provider
Domain.

3.7 B2bua with media via the main dial plan

In order to relay media i.e. to anchor media at the SBC when e.g. releasing or diverting calls back to
the operator – this option is synonymous with the “Relay media” trunk page option: on the main dial
plan, add ;b2buawm. A bug in the 5.0.x firmware series prevented this expression from working
properly and was fixed in the 6.0.2 firmware. Note, you must have a regexp ($) for the parameter to
work. This regexp is used on the main Dial Plan, Forward To rows:
Forward To …or this… Reg Expr:
$1@10.20.30.40;b2buawm

How To Guide: Generic Header Manipulation & Regular Expressions Page 18

of 35


3.8 Explicitly stating transport

SIP RFC 3261 specifically states that two URIs are not synonymous if a port or implied parameter is
absent in one but present in a second while all other parameters are equal. For implied parameters,
such as transport, their presence – or absence – can be important. A UAC must specify its transport
when registering to a proxy, if it is not UDP:
Reg Expr:
john@10.20.30.40;transport=tcp

Note that RFC3261 deprecates the use of transport=tls although its use on an Ingate is still possible
for compatibility. If an ITSP Contact: header contains the transport parameter “transport=tcp” in
one response, but removes it in another response – implying “transport=udp” – the transport will be
deemed to have changed on the ITSP side, and the Ingate will contact the new destination. If the
ITSP cannot handle this transport change (where two separate daemons listen for traffic via the two
different transports which may be unaware of each other), this is an error that the ITSP must correct.

3.9 Specifying Escape Characters (dial string) for e.g. Telia SIP trunk
Reg Expr:
;escape-chars=*#

3.10 Additional information

Here are a few resources we recommend to read more about to build and test regular expressions
before they go live:
• http://www.regular-expressions.info/
• http://gskinner.com/RegExr/ or https://regexr.com/
• http://renschler.net/RegexBuilder/
• echo (Test expression) | grep -E (regexp)

How To Guide: Generic Header Manipulation & Regular Expressions Page 19

of 35


4 Conditional Regular Expressions (CRE)

The variable substitution functionality has been enhanced in Ingate, with software version 5.0.4 or
later, to allow applying regular expressions and replace on the result of variable substitutions. For
example:

...$(REGMATCH_123_REGMOD_456_REGELSE_(.*)_REGMOD_789_REGEND.from.user)...
first takes the user portion of the From: header, and then performs the regular match/replace which
must be enclosed by the tags “REGMATCH_” and “_REGEND” as above;
• the user portion of the From: header is compared with 123. If the user portion contains 123, then the
result is modified to 456.
• else, the user portion of the From: header is compared with (.*) which greedily matches everything,
so the result of the above expression would be 789.
This was a simplified example just to show the basic logic. In practice this can be much more
complex. Note: the examples here are to be embedded in a GHM like:
$0?From=$(REGMATCH_123_... and must contain %40 (an @ symbol). See later examples

4.1 Example CRE - Sweden Number Reduction

The following expression will supply number reduction based on the From: header of a telephone
number (user portion) in Sweden:
• If the number starts with (^) a + followed by only digits until its end ($), leave the + and digits as is
• If the number starts with (^) 00 followed by only digits until its end ($), replace 00 with + and leave
the digits as they are
• if the number starts with (^) 0 followed by only digits until its end ($), add +46 followed by the digits
after the initial 0
• else, supply the number unmodified
The following is just one long line:
...$(REGMATCH_^\+([0-9]+)$_REGMOD_+$1_REGELSE_^00([0-9]+)$_REGMOD_+$1_REGELSE_^0([0-
9]+)$_REGMOD_+46$1_REGELSE_(.*)_REGMOD_$1_REGEND.from.user)...

Note: The result from the match from each “REGMATCH_” tag respective “REGELSE_” tag is
valid only for a replacement in the respectively immediately following “REGMOD_” tag.

4.2 Example CRE - USA Number Reduction

The following expression will supply number reduction based on the From: header of a telephone
number in USA:
• If the number already starts with a + followed by only digits, leave the + and digits as they are
• If the number starts with 001 followed by only digits, replace the 001 with +1 and leave the digits as
they are
• if the number starts with 1 followed by only digits, add +1 followed by the digits after the initial 1
...$(REGMATCH_^001([0-9]{10})$_REGMOD_+1$1_REGELSE_^1([0-
9]{10})$_REGMOD_+1$1_REGELSE_([0-9]{10})$_REGMOD_+1$1_REGEND.from.user)...

How To Guide: Generic Header Manipulation & Regular Expressions Page 20

of 35


4.3 Generic Number Reduction to + prefix for phone numbers 8-12 digits long
Rule

Order Look for the Prefix… …and change it to

1st 00 +
2nd 0 + (national) e.g. +31
3rd + + (no change)
4th (anything) +

Regexp

Order Match (and capture) Modify

1st ^00([0-9]{8,12})$ +$1
2nd ^0([0-9]{8,12})$ +31$1
3rd ^+([0-9]{8,12})$ +$1
4th ^(.*)$ +$1

Expression

Match Modify
REGMATCH_ ^00([0-9]{8,12})$ _REGMOD_ +$1 _REGELSE_
^0([0-9]{8,12})$ _REGMOD_ +31$1 _REGELSE_
^+([0-9]{8,12})$ _REGMOD_ +$1 _REGELSE_
^(.*)$ _REGMOD_ +$1 _REGEND

Expression which operates on user portion of From header

$(REGMATCH_^00([0-9]{8,12})$_REGMOD_+$1_REGELSE_^0([0-
9]{8,12})$_REGMOD_+31$1_REGELSE_^+(.*)$_REGMOD_+$1_
REGELSE_^(.*)$_REGMOD_+$1_REGEND.from.user)

Encoded expression producing a valid From header, operating on user portion of From header

?From=%3csip%3a$(REGMATCH_^00([0-9]{8,12})$_REGMOD_+$1_REGELSE_^0([0-
9]{8,12})$_REGMOD_+31$1_REGELSE_^+(.*)$_REGMOD_+$1_
REGELSE_^(.*)$_REGMOD_+$1_REGEND.from.user)%40$(from.host)$([from.uriparams])%3e$
(from.params)

Note: In firmware versions <= 5.0.11 you cannot use $1?From=$(......$1...) – i.e. capture groups on
the trunk page (i.e. where $1 is before and after the “?”), and $REGMATCH expressions which also
contain $1. The workaround is to use $0?From=$(....$1…). See Errata.

How To Guide: Generic Header Manipulation & Regular Expressions Page 21

of 35


5 Variable Substitution
The Ingate firmware has a range of variables to access all headers and URIs.
Where a SIP URI could be:
dname <sip:user:password@host:port;uriparams>;params

Below is a list of the variables used to access URI and header portions for use in substitution:

Variable Explanation
cfg.user The user part of the Local registrar account matched (if any) by a
request
cfg.host The host part of the Local registrar account matched (if any) by a
request
ruri.user User portion of Request-URI
ruri.host Host portion of Request-URI
ruri.uriparams URI parameters of Request-URI
header_name.user User of header "header_name" (e.g. to.user)
header_name.userinfo The whole user portion, containing password, up to the @ symbol.
header_name.password Password of header "header_name" (e.g. to.password)
2
header_name.cpassword As password; but prepended with colon (“:password”) 2. Will only
expand if header_name .userinfo contains a password.
header_name.userinfo User, Password and Parameters of user portion e.g. “joe:123”, or
“joe;tgrp=1…”. In effect, everything between sip(s): and @
header_name.userinfoat As above, but includes the final @ symbol – eases creation of valid
2
URI. E.g. ?foo=$([from.userinfoat])example.com
will only expand to "userinfo@" if the header_name contains userinfo.
header_name.host Host portion of header "header_name" (e.g. contact.host)
header_name.port Port portion of header "header_name" (e.g. contact.port)
2
header_name.cport As port, but prepended with a colon “:”.
E.g. ?foo=example.com$([from.cport]) Note: Only expands if
header_name contains a port param.
header_name.dname Display name of header "header_name" (e.g. from.dname)
header_name.uqdname Unquoted display name of header "header_name" (e.g. from.uqdname)
header_name.params Header parameters of header "header_name" (e.g. contact.params)
header_name.uriparams URI parameters of header "header_name" (e.g. contact.uriparams)
header_name.telnum Tel-URI telephone number of header "header_name" (e.g.
from.telnum)
header_name.uri Complete URI of header "header_name" (e.g. contact.uri)
hdr.header_name The complete header value of header "header_name"
hdr.header_name[2] The complete header value of 2nd occurrence of header
“header_name”
rawhdr.header_name The complete header value of header "header_name" (not escaped)
ip.interface The IP address of physical network interface "interface", (e.g. ip.eth1)
header_name.dnameu Display name and complete URI of header "header_name" (e.g.
ri1 from.dnameuri)
1 2
(Available from SW version 5.0.4) (Available from SW > 6.0.0)
Where a SIP URI is:
dname <sip:user:password@host;uriparams>;params
And may be formed by:

How To Guide: Generic Header Manipulation & Regular Expressions Page 22

of 35


$(x.dname) <sip:$(x.user):$(x.password)@$(x.host)$(x.uriparams)>$(x.params)
Or may be formed by:
$([x.dname]) <sip:$([x.user]):$([x.password])@$([x.host])$([x.uriparams])>$([x.params])
which may be formed by the encoded string:
$([x.dname])%20%3Csip:$([x.user]):$([x.password])%40$([x.host])$([x.uriparams])%3E$([x.params])

All variables are invoked by using the $(variable) syntax. The same is achieved by using
$([variable]) – the difference being that, if the content of $([variable]) is empty, then
the result is not inserted. If $(variable) syntax is empty, the literal string $(variable) is inserted.
The $([variable]) syntax is available from firmware >= 4.10.1.
Note: To use any variables, a regular expression match must have been done, together with a regular
expression substitution. E.g. $1?header=…
If you just want to rewrite the From header, use the Forward To Reg Expr field and append a
";from=" parameter. The from parameter value may contain references to Reg Expr sub-strings. It
may reference both sub-strings in the Matching From Header, and the Matching Request-URI Reg
Expr fields. Sub-strings of the From header are referenced as $fx (where x is an integer, 0 or
greater). And Request-URI sub-strings are referenced as $rx.

5.1 Port and Password

Parameters password and port are always prepended by a semicolon. If you write an expression
…$(from.user)%40(from.host)%3a(from.port)… where the from header contained no port
parameter, your string evaluates to 123@192.168.1.1: which is an invalid URI, since there is no
port value after the colon. If it is unknown in advance whether port or password would be found in a
URI of an incoming SIP message, the following CHMs (which require firmware >= 5.0.4) can work
around whether or not to insert a semicolon dependent upon the respective parameters’ existence:
$(CONDIF.from.port)$(CONDYES.PLAIN.%3A)$(CONDYES.from.port)
or
$(CONDIF.from.password)$(CONDYES.PLAIN.%3A)$(CONDYES.from.password)

Convenience variables for the above are provided in Ingate firmware >= v6.0:
header_name.cport yields e.g. :5060
header_name.cpassword yields e.g. :p@$$word

Regarding indices/indexes [?]

- index [0] is same as no index [], and becomes index 1, and gets the first instance of that header (the
one at the top)
- index [1] is the first instance of that header (the one at the top)
- the last index [-1] gets the last instance of that header (at the bottom)
- index [-2] gets the second last instance of that header (the second from the bottom) and so on.
e.g.
Via: SIP/2.0/UDP via[1].host:via[1].port;via[1].uriparams
Via: SIP/2.0/UDP via[2].host:via[2].port;via[2].uriparams
Via: SIP/2.0/UDP via[-1].host:via[-1].port;via[-1].uriparams
is the same as
Via: SIP/2.0/UDP via.host:via.port;via.uriparams
Via: SIP/2.0/UDP via[2].host:via[2].port;via[2].uriparams
Via: SIP/2.0/UDP via[-1].host:via[-1].port;via[-1].uriparams
is the same as
Via: SIP/2.0/UDP via[-3].host:via[-3].port;via[-3].uriparams
Via: SIP/2.0/UDP via[-2].host:via[-2].port;via[-2].uriparams

How To Guide: Generic Header Manipulation & Regular Expressions Page 23

of 35


Via: SIP/2.0/UDP via[-1].host:via[-1].port;via[-1].uriparams

Example INVITE where URIs and headers are written as variables

INVITE sip:ruri.user@ruri.host:ruri.port;ruri.uriparams SIP/2.0
Via: SIP/2.0/UDP via[1].host:via[1].port;via[1].uriparams
Via: SIP/2.0/UDP via[2].host:via[2].port;via[2].uriparams
Via: SIP/2.0/UDP via[-1].host:via[-1].port;via[-1].uriparams
To: "to.uqdname" <sip:to.user@to.host>
From: from.dname <sip:from.user@from.host>;from.params
Call-ID: call-id.user@call-id.host
P-Asserted-Identity: sip:P-Asserted-Identity.user@P-Asserted-Identity.host
P-Preferred-Identity: <sip:P-Preferred-Identity.user@P-Preferred-Identity.host>
Contact: <sip:Contact.user@Contact.host>
Record-Route: <sip:Record-Route[1].user@Record-Route[1].host;record-route.uriparams>
Record-Route: <sip:Record-Route[-1].user@Record-Route[-1].host;record-route.uriparams>
Session-Expires: hdr.session-expires
User-Agent: hdr.user-agent
Supported: hdr.supported
Allow: hdr.allow
Max-Forwards: hdr.max-forwards
CSeq: 1 INVITE
Content-Type: application/sdp
Content-Length: ...
...

Example equivalences - From

From: from.dname <sip:from.user@from.host>;from.params
is the same as
From: "from.uqdname" <sip:from.user@from.host>;from.params
is the same as
From: from.uri
is the same as
From: hdr.from

How To Guide: Generic Header Manipulation & Regular Expressions Page 24

of 35


5.2 Examples

Adding From Header

sip:$1@192.168.1.1;from="sip:$(from.user)@1.2.3.4"
sip:$1@example.com;from="sip:$(from.user)@1.2.3.4"
from="sip:$(from.user)@example.com"
Replaces the From domain with "example.com".
from="sip:$f1@example.com"
Replaces the From domain with "example.com" when matching on From Header Reg Expr
"(.*)@.*".
The examples assume that there is a match done resulting in that $1 contains the user part of the
Request- URI.
Note: the From Header is the only header that can be added or changed as a ;tag i.e. using
the ;uriparams format without using a GHM. All headers can be added through GHM, including
the From header. See chapter 6 Generic Header Manipulation (GHM).

How To Guide: Generic Header Manipulation & Regular Expressions Page 25

of 35


6 Generic Header Manipulation (GHM)

The rules for header manipulation of SIP messages are configured in the GUI for Dial Plan and SIP
Trunk Page in the same fields as regular expressions are entered. The rules in the "Forward to" fields
are applied when there is a match in the corresponding matching fields.
The Generic Header Manipulation uses grammar of the header field components in a SIP URI as
described in SIP RFC 3261.
The general form of a SIP URI, is:
sip:user:password@host:port;uri-parameters?headers
SIP headers are written in a GHM as an encoded URL. That is, they consist of name and value pair of
the form Header_Name=Header_Value. The first header is written after a ? and any additional
headers are separated by the symbol &.
Within the Header_Value, characters disallowed according to RFC 3261 must be escaped with
a %HEX notation where HEX is a 2-digit hexadecimal number representing the escaped character
(i.e. URL-Encoded String).
For example the SIP header:
Diversion=<sip:7202839130@192.168.1.1>
is written as:
Diversion=%3csip%3a7202839130%40192.168.1.1%3e
The table below lists characters often used, and their corresponding URL encoding:

Character HEX Value

@ %40
: %3a
; %3b
, %2c
= %3d
< %3c
> %3e
Spaces +
For GHM, the headers are added at the end of the Regular Expression URI, after “?” which denotes
the start of the GHM. Then the Header Name is identified, then a “=” is used to indicate the Header
Value, then the Header Value is provided as a URL-Encoded String. "&" is used as a separator for
subsequent headers. A header can be removed by assigning the reserved value, “__remove” (two
underscores).
“<” and “>” are required in the Header Value under some conditions. Refer to RFC 3261 section
20.10,
Example:

R-URI Header Name Header Value (URL-Encoded String)

sip:$1@192.168.1.1?Diversion=%3csip%3a7202839130%40192.168.1.1%3e

“?” is the Start separator “%HEX” is for escaped

characters

6.1 Adding or Replacing a Header

For GHM, if a specified header field is already present in the incoming SIP request, the header is
replaced, if a specified header field is NOT present in the incoming SIP request, the header field is
added.

How To Guide: Generic Header Manipulation & Regular Expressions Page 26

of 35


6.1.1 Adding and Replacing Header Examples

P-Asserted Identity
sip:$1@192.168.1.1?P-Asserted-Identity=%3csip%3a7202839130%40192.168.1.1%3e
sip:$1@example.com?P-Asserted_Identity=%3csip%3a7202839130%40192.168.1.1%3e
Diversion
sip:$1@192.168.1.1?Diversion=%3csip%3a7202839130%40192.168.1.1%3e
sip:$1@example.com?Diversion=%3csip%3a7202839130%40192.168.1.1%3e
Privacy
sip:$1@192.168.1.1?Diversion=<url-encoded_string>
sip:$1@example.com?Diversion=<url-encoded_string>
Multiple
sip:$1@192.168.1.1?P-Asserted-Identity=<url-encoded>&Diversion=<url-encoded>
sip:$1@example.com?P-Asserted-Identity=<url-encoded>&Diversion=<url-encoded>
Used in combination with regular expression
sip:$1@192.168.1.1;b2bua;from="Anonymous@10.182.0.178"
?P-Asserted-Identity=<url-encoded_string>&Privacy=id
Note: Replace <url-encoded_string> with the new header value.

6.2 Removing a header

This is done by starting with the GHM separator “?”, then the Header Name to be removed, followed
by “=”, then the reserved value __remove. (two underscores, then "remove")

6.2.1 Examples of Header removal

Removing Privacy Header

sip:$1@192.168.1.1?Privacy=__remove
sip:$1@example.com?Privacy=__remove
sip:$(ruri.user)@$(ruri.host)?Privacy=__remove

6.3 Generic Header Manipulation (GHM) for Responses

GHM for responses works similarly to header manipulation for requests except that header names
used for response manipulation need to be prefixed with an exclamation mark “!”. This means that
GHM will be performed on response messages, i.e. 180 Ringing, 200 OK, ACK (as opposed to
INVITE).
Example to solve Avaya display problem using PAI:
Add P-Asserted Identity Header
sip:$1@192.168.1.1?!P-Asserted-Identity=$(to.dnameuri)
sip:$1@example.com?!P-Asserted-Identity=$(to.dnameuri)
This adds P-Asserted-Identity to the response with the display name and URI from the To-
header.

How To Guide: Generic Header Manipulation & Regular Expressions Page 27

of 35


6.4 Multiple Occurrences of Headers

Header fields are indexed using angle brackets [x] so that one can refer to the n:th occurrence of a
certain header.
If a specified header field is present in the incoming SIP request, the header is replaced. Conversely if
a specified header field is absent from the incoming SIP request, the header field is NOT added.
Replacement operations will only be performed if the header index exists in the message, no headers
will be otherwise added. Use [*] as index to refer to all header fields with same name. Use [-1] as
index to refer to the last indexed field of a header.
If a variable is unknown or does not exist in an incoming message, the specified header will be left
untouched.

6.4.1 Breakout Example

The following is just one long line:
sip:$0@example.com?User-Agent=$(hdr.user-agent)
&Contact=sip%3afoo%40$(ip.eth4)%3buser%3dphone
&Organization=mycompany&Privacy=__remove
&Diversion[1]=sip%3a$(diversion[1].user)%401.1.1.1
Explanation of each Reg Expr component:
sip:$1@example.com
This is the Request URI, $1 is to use the first variable captured from the match, e.g. from Matching
Request URI field in the SIP Traffic – Dial Plan page.
?User-Agent=$(hdr.user-agent)
User-Agent header is supplied with the value taken from the incoming User-Agent header, where it
exists. The User-Agent header is effectively unchanged (the Ingate itself only rewrites User-Agent
header in B2BUA mode).
&Contact=sip%3afoo%40$(ip.eth4)%3buser%3dphone
The Contact Header is replaced with the IP address of eth e.g. Contact: sip:foo@1.2.3.4;user=phone
&Organization=mycompany
The header Organization is added as Organization: mycompany
&Privacy=__remove
The Privacy header is removed.
&Diversion[1]=sip%3a$(diversion[1].user)%401.1.1.1
Where a Diversion header exists, the host portion is replaced with 1.1.1.1.

6.5 Variable substitution

Variable substitution can be used for GHM as for Regular Expressions. The pre-defined variables can
be used in GHM expressions. These variables provide specific values from other headers into the
result. See chapter 5 Variable Substitution for a list of the variables that can be used.

6.5.1 Variable substitution Examples

How To Guide: Generic Header Manipulation & Regular Expressions Page 28

of 35


Modify Contact header with eth3 IP address

sip:$0@example.com?Contact=sip%3afoo%40$(ip.eth3)%3buser%3dphone
Add special character + to the From header
sip:$0@192.168.1.2?from=%3Csip%3a%2B$(from.user)%40172.16.0.1%3E

Reduce the From header prefix to USA +1, pass any other URI parameters
sip:$0?From=%3Csip%3a$(REGMATCH_^001([0-9]{10})$_REGMOD_+1$1_REGELSE_^1([0-
9]{10})$_REGMOD_+1$1_REGELSE_([0-
9]{10})$_REGMOD_+1$1_REGEND.from.user)%40$(from.host)$(CONDIF.from.uriparams)$
(CONDYES.from.uriparams)%3E$(from.params)
Reduce the From header prefix to USA +1, pass any other URI parameters (alternative)
sip:$0?From=%3Csip%3a$(REGMATCH_^001([0-9]{10})$_REGMOD_+1$1_REGELSE_^1([0-
9]{10})$_REGMOD_+1$1_REGELSE_([0-
9]{10})$_REGMOD_+1$1_REGEND.from.user)%40$(from.host)$([from.uriparams]) %3E$(
from.params)
Strip the Display name portion out of the From header
sip:$1@192.168.1.1?From=$(from.uri)

How To Guide: Generic Header Manipulation & Regular Expressions Page 29

of 35


7 Conditional Variable substitution (CVS)

From Ingate SW version 5.0.4 the variable substitution functionality has been enhanced to allow for
conditional variable substitution. It looks like this:

Conditional Variable substitution

$(CONDIF.diversion.user)$(CONDYES.diversion.user)$(CONDNO.from.us
er)
$(CONDIF…) evaluates a condition. $(CONDYES…)and $(CONDNO…) output a result based on
the evaluation of that condition.
Example from above: When there is a user portion of a Diversion: header present in the SIP
message (e.g. from the PBX), then the above expression supplies the $(diversion.user)header
portion, otherwise it supplies the $(from.user). Note: This CVS evaluates to produce a result,
which must be placed in a header. See below.

7.1 Conditional Header Manipulation (CHM)

The purpose of the PLAIN context is to conditionally include URL-encoded plain-text content e.g.:

?from=$(CONDIF.diversion.user)$(CONDYES.PLAIN.%3csip%3a12345678%40company.com%3
e)$(CONDNO.PLAIN.%3csip%3aABCDEFGH%40company.com%3e)
When there is a user portion of a Diversion: header, then the From: header produced will be
<sip:12345678@company.com>, otherwise it will be <sip:ABCDEFGH@company.com>
Resulting in either:
(CONDYES) ...
Diversion: joe@domain
From: <sip:12345678@company.com>
or
(CONDNO) ...
Diversion: empty or non-existent URI
From: <sip:ABCDEFGH@company.com>

Example. Assuming the above CHM, the following SIP INVITE:

INVITE sip:zyx@ingate.com SIP/2.0
Session-Expires: 14400
Via: SIP/2.0/UDP 192.0.2.2:5060;branch=z9hG4bK4cc7285324505f2f5baad12ef7e98054
To: <sip:zyx@ingate.com>
From: <sip:alpha@ingate.com>;tag=2267be7a
Call-ID: 21@sipgt-2d
CSeq: 3 INVITE
Contact: <sip:E4F0pr9vEUD3axDnp@192.0.2.2>
Supported: timer, replaces, path, histinfo
Allow: ACK, CANCEL, INVITE, BYE, NOTIFY, INFO, OPTIONS, PRACK, REFER, UPDATE
Max-Forwards: 15
Content-Type: application/sdp
Content-Length: ...
Will evaluate to NO because no Diversion header exists in the INVITE, thus producing:
%3csip%3aABCDEFGH%40company.com%3e
The expression effectively becomes:
?from=%3csip%3aABCDEFGH%40company.com%3e
This will result in a modified INVITE once the GHM completes:
INVITE sip:zyx@ingate.com SIP/2.0
Session-Expires: 14400
Via: SIP/2.0/UDP 192.0.2.2:5060;branch=z9hG4bK4cc7285324505f2f5baad12ef7e98054
To: <sip:zyx@ingate.com>
From: <sip:ABCDEFGH@company.com>
Call-ID: 21@sipgt-2d
CSeq: 3 INVITE

How To Guide: Generic Header Manipulation & Regular Expressions Page 30

of 35


Contact: <sip:E4F0pr9vEUD3axDnp@192.0.2.2>
Supported: timer, replaces, path, histinfo
Allow: ACK, CANCEL, INVITE, BYE, NOTIFY, INFO, OPTIONS, PRACK, REFER, UPDATE
Max-Forwards: 15
Content-Type: application/sdp
Content-Length: ...

The following SIP INVITE:

INVITE sip:zyx@ingate.com SIP/2.0
Session-Expires: 14400
Divresion: hello@123
Via: SIP/2.0/UDP 192.0.2.2:5060;branch=z9hG4bK4cc7285324505f2f5baad12ef7e98054
To: <sip:zyx@ingate.com>
From: <sip:alpha@ingate.com>;tag=2267be7a
Call-ID: 21@sipgt-2d
CSeq: 3 INVITE
Contact: <sip:E4F0pr9vEUD3axDnp@192.0.2.2>
Supported: timer, replaces, path, histinfo
Allow: ACK, CANCEL, INVITE, BYE, NOTIFY, INFO, OPTIONS, PRACK, REFER, UPDATE
Max-Forwards: 15
Content-Type: application/sdp
Content-Length: ...

Will also evaluate to NO (because no Diversion header exists - a ‘Divresion’ header exists, however),
thus producing:
%3csip%3aABCDEFGH%40company.com%3e
The expression again becomes:
?from=%3csip%3aABCDEFGH%40company.com%3e

The following SIP INVITE:

INVITE sip:zyx@ingate.com SIP/2.0
Diversion: gohereinstead@betacorp.xyz;reason=no-answer
Session-Expires: 14400
Via: SIP/2.0/UDP 192.0.2.2:5060;branch=z9hG4bK4cc7285324505f2f5baad12ef7e98054
To: <sip:zyx@ingate.com>
From: <sip:alpha@ingate.com>;tag=2267be7a
Call-ID: 21@sipgt-2d
CSeq: 3 INVITE
Contact: <sip:E4F0pr9vEUD3axDnp@192.0.2.2>
Supported: timer, replaces, path, histinfo
Allow: ACK, CANCEL, INVITE, BYE, NOTIFY, INFO, OPTIONS, PRACK, REFER, UPDATE
Max-Forwards: 15
Content-Type: application/sdp
Content-Length: ...

Will evaluate to YES (because a Diversion header exists, and contains:

gohereinstead@betacorp.xyz;reason=no-answer), thus producing:
%3csip%3a12345678%40company.com%3e
The expression becomes:
?from=%3csip%3a12345678%40company.com%3e
This will result in a modified INVITE once the GHM completes:
INVITE sip:zyx@ingate.com SIP/2.0
Diversion: gohereinstead@betacorp.xyz;reason=no-answer
Session-Expires: 14400
Via: SIP/2.0/UDP 192.0.2.2:5060;branch=z9hG4bK4cc7285324505f2f5baad12ef7e98054
To: <sip:zyx@ingate.com>
From: <sip:12345678@company.com>;tag=55566567be7a
Call-ID: 21@sipgt-2d
CSeq: 3 INVITE
Contact: <sip:E4F0pr9vEUD3axDnp@192.0.2.2>
Supported: timer, replaces, path, histinfo
Allow: ACK, CANCEL, INVITE, BYE, NOTIFY, INFO, OPTIONS, PRACK, REFER, UPDATE
Max-Forwards: 15
Content-Type: application/sdp
Content-Length: ...

A note about parameters: we have not included any parameters in our expression. The b2bua will add
its own special ;tag parameter separately to the new From header. Any ;tag parameter you copy
from the source through the use of a $(from.params) expression will be updated separately by the

How To Guide: Generic Header Manipulation & Regular Expressions Page 31

of 35


b2bua, but other parameters will remain unchanged. If you want to include any parameters found
after <sip:…> in your result, add $(from.params) to your expression:

?from=$(CONDIF.diversion.user)$(CONDYES.PLAIN.%3csip%3a12345678%40company.com%3e)
$(CONDNO.PLAIN.%3csip%3aABCDEFGH%40company.com%3e)$(from.params)

7.1.1 More Examples

?from=$(CONDIF.diversion.user)$(CONDYES.PLAIN.%3csip%3a)$(CONDYES.REGMATCH_^\+([0-9]+)
$_REGMOD_+$1_REGELSE_^00([0-9]+)$_REGMOD_+$1_REGELSE_^0([0-9]+)
$_REGMOD_+46$1_REGELSE_(.*)_REGMOD_$1_REGEND.from.user)$(CONDYES.PLAIN.%40company.com%3e
)$(CONDNO.PLAIN.%3csip%3aABCDEFGH%40company.com%3e)
This does the following:
1. Where the message from the PBX contains a Diversion: header, then the username portion in the
From: header (appended with “company.com”) replaces the From: header of the message sent out,
after applying the Sweden number Reduction example.
2. Where the message from the PBX does not contain a Diversion: header, no header manipulation is
performed.

Resulting in either:
(CONDYES) ...
Diversion: mike@domain
From: <sip:+46812345678@company.com>
or an unmodified from header:
(CONDNO) ...
From: <sip:0812345678@company.com>

7.1.2 More Complex Example - History-Info

Where forwarding information is transported via a History-Info: header, then the following should
used:

?from=$(CONDIF.history-info[-1].user)$(CONDYES.PLAIN.%3csip%3a)
$(CONDYES.REGMATCH_^\+([0-9]+)$_REGMOD_+$1_REGELSE_^00([0-9]+)$_REGMOD_+
$1_REGELSE_^0([0-9]+)$_REGMOD_+46$1_REGELSE_(.*)_REGMOD_$1_REGEND.from.user)
$(CONDYES.PLAIN.%40company.com%3e)
Note: that history-info[-1] refers to the last history-info header present in the SIP message from the
PBX.
Resulting in either:
(CONDYES) ...
History-Info: qwerty
From: <sip:+46812345678@company.com>
or an unmodified from header:
(CONDNO) ...
From: <sip:0812345678@company.com>

How To Guide: Generic Header Manipulation & Regular Expressions Page 32

of 35


7.1.3 More Complex Example – Conditional From Header, based on To callee

A company has an old PRI. Outbound calls are now made over the new SIP trunk. On standard calls,
they want to send the main number from the PRI out over the SIP trunks. They need to send the real
caller ID of the SIP trunks on 911 calls, however.
The old PRI number is 555-101-2001.
Their new SIP trunk number is 555-777-8888.
So, if the call is to 911 i.e.
the user portion of the To header is 911,
the resulting From number is 5557778888,
if the call is not to 911 (i.e. to anything other than 911),
the resulting From number is 5551012001.
A suitable expression would be:

?from=$(CONDIF.REGMATCH_^911$_REGEND.to.user)$(CONDYES.PLAIN.%3csip%3a5557778888%40192.0
.2.2%3e)$(CONDNO.PLAIN.%3csip%3a5551012001%40192.0.2.2%3e)
Resulting in either (911 is being called):
(CONDYES) ...
From: <sip:5556668888@192.0.2.2>
Or (911 is not being called):
(CONDNO) ...
From: <sip:5551012001@192.0.2.2>

7.2 URI Parameter Chaining

You can also manipulate multiple headers this way, by chaining the header manipulations in the
usual way with the “&” character. The example below is like the previous History-Info example
above, plus it sets the field P-Preferred-Identity:

?from=$(CONDIF.diversion.user)$(CONDYES.PLAIN.%3csip%3a)
$(CONDYES.REGMATCH_^\+([0-9]+)$_REGMOD_+$1_REGELSE_^00([0-9]+)$_REGMOD_+
$1_REGELSE_^0([0-9]+)$_REGMOD_+46$1_REGELSE_(.*)_REGMOD_$1_REGEND.from.user)
$(CONDYES.PLAIN.%40company.com%3e)&P-Preferred-
Identity=%3csip%3aanother_id%40shop.com%3e
Resulting in either:
(CONDYES) ...
Diversion: mike@domain
From: <sip:+46812345678@company.com>
P-Preferred-Identity: <sip:another_id@shop.com>
or an unmodified from header:
(CONDNO) ...
From: <sip:0812345678@company.com>
P-Preferred-Identity: <sip:another_id@shop.com>

How To Guide: Generic Header Manipulation & Regular Expressions Page 33

of 35


Note: If you want to add a header (which did not already exist in the message) only under certain
circumstances e.g.: Replace a possibly existing Referred-By: header with a Diversion: header

?Diversion=$(CONDIF.Referred-By.user)$(CONDNO.ABORT)$(CONDYES.PLAIN.%3csip%3a)
$(CONDYES.Referred-By.user)$(CONDYES.PLAIN.%40)$(CONDYES.ReferredBy.host)
$(CONDYES.PLAIN.%3e)&Referred-By=__remove
If no Referred-By header is present then without the $(CONDNO.ABORT) the following string for
header manipulation would remain:
?Diversion=
&Referred-By=__remove
which would result in an empty diversion header in the resulting message. But with the
$(CONDNO.ABORT), the resulting header manipulation string becomes
?Diversion=$(ABORT)&Referred-By=__remove
and since header manipulations with unresolved variables will be skipped, no empty diversion header
will be added. In effect becoming just:
?Referred-By=__remove

7.2.1 Illegal Chaining

The following example of chaining is illegal, and will not work:

?from=$(CONDIF.diversion.user)
$(CONDYES.PLAIN.%3csip%3a&P-Preferred-Identity=%3csip%3aanother_id%40shop.com%3e)

For the above example to compile, it must be corrected – note the closing parenthesis:

?from=$(CONDIF.diversion.user)
$(CONDYES.PLAIN.%3csip%3a)&P-Preferred-Identity=%3csip%3aanother_id%40shop.com%3e

Summary: Parameter chaining only works outside of the regular expression $() context, and cannot
be chained conditionally.

How To Guide: Generic Header Manipulation & Regular Expressions Page 34

of 35


8 Keyword / Grammar Summary – CVS, CHM and CRE

8.1 Tests
$(
[ CONDIF(.REGMATCH…) |
CONDIFNOT |
CONDANDIF |
CONDANDIFNOT |
CONDORIF |
CONDORIFNOT ].Header.Portion
)

8.2 Results
$(
CONDYES
.PLAIN.Text |
.Header.Portion |
.ABORT
| CONDNO
.PLAIN.Text |
.Header.Portion |
.ABORT
)

8.3 RegExp
$(
REGMATCH_
_REGMOD_
_REGELSE_
_REGMOD_
…
_REGEND.Header.Portion
)
Note: Keywords and expressions are evaluated from left to right, i.e. forwards in their construction.

How To Guide: Generic Header Manipulation & Regular Expressions Page 35

of 35