FRAFOS ABC SBC ConfigurationGuide

Release 1.8.5 VM

FRAFOS GmbH

April 16, 2013

Contents

1 ABC SBC Virtual Machine (VM) installation and Web GUI access ii1.1 ABC SBC Virtual Machine (VM) version . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . ii1.2 Virtual Machine (VM) installation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . ii1.3 WEB GUI access . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . iii1.4 VM customization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . iii1.5 VM update . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . iv

2 ABC SBC Network modeling iv2.1 Realms and call agents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . iv2.2 A / B / C rules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . iv

3 Routing (B) rules processing v3.1 Routing rules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . v3.2 Routing rules processing algorithm . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . vi

4 Inbound (A) and Outbound (C) rules processing vi4.1 Conditions and actions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . vi4.2 Rule flags . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . vi4.3 Rules processing algorithm . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . vii

5 A / B/ C Rules configuration vii5.1 Conditions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . vii5.2 Actions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . viii5.3 Replacements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . ix5.4 Regexp backreferences . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . x5.5 Call rules examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . x

Regexp backreferences . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xCall variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xReplacements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . x

6 Applying configuration x

7 CDRs management xiv7.1 CDRs location . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xiv7.2 CDR format . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xiv7.3 Access to CDRs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xv

8 Appendix xv8.1 Value Replacements Reference . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xv

This manual, the ABC SBC Configuration Guide, describes configuration of FRAFOS ABC SBC using Web GUI.

The document is valid for FRAFOS ABC SBC version 1.8.5 VM.

Note: The call length of the ABC SBC demo virtual machine (VM) is limited to 90 sec.

1 ABC SBC Virtual Machine (VM) installation and Web GUI access

1.1 ABC SBC Virtual Machine (VM) version

For demo purposes FRAFOS ABC SBC is delivered as a virtual machine that can be imported into virtualizationsoftware – VMware Player or other VMware products (VMware Workstation, WMware ESX,. . . ), VirtualBox orother virtualization platforms that support OVA or VMX formats.

FRAFOS ABC SBC VM can be downloaded from FRAFOS web site.

The Virtual Machine is available in two formats:

• ‘FRAFOS ABC SBC VM v1.8.5‘_ – VMware format (vmdk)

• ‘FRAFOS ABC SBC VM v1.8.5-OVF‘_ – open virtualization format – can be imported into VirtualBoxor VMware Player

The Virtual Machine includes:

• Debian 6.0.6 64bit OS

• VMware-tools extensions

• FRAFOS ABC SBC application v1.8.5

1.2 Virtual Machine (VM) installation

The VM is provided as a compressed file archive. Extract VM files to the specific location from the archive usingfollowing command:

% tar zfx FRAFOS_ABC_SBC_VM_v1.8.5.tar.gz ./

Then import the virtual machine into your virtualization software (e.g. for VMware player, using File -> OpenVirtual Machine and locate extracted files).

The VM is preconfigured and installed with the following settings:

hardware:

• CPU: one processor

• memory: 365 MB RAM

• hard disk: 4 GB (SCSI)

• network adapters: bridged

networking:

• Interface 1: eth0

– static IP: 192.168.1.100

– netmask: 255.255.255.0

– gateway: 192.168.1.1

– DNS server: 192.168.1.1

• Interface 2: eth1

– static IP: 10.1.1.100

– netmask: 255.255.255.0

software:

• user login:

– username: root

– password: frafos

• Web GUI access:

– URL: https://192.168.1.100

– username: root

– password: frafos

1.3 WEB GUI access

The Frafos ABC SBC appliance is configured using a Web GUI. Point your web browser to the management IPaddress using “https” scheme, e.g.

• https://192.168.1.100

The Frafos ABC SBC login screen should appear. Use the same credentials as for the system login:

• user: root

• password: frafos

1.4 VM customization

After logging in to the Web GUI, you can change network settings according to the actual network configurationusing “Networking” tab. Then press “Apply Configuration” button.

Alternatively you can modify following network configuration files using e.g. “nano” or “vim” editor:

• /etc/network/interfaces – for IP address, netmask and gateway setting

• /etc/resolv.conf – for DNS servers setting

Note: In VirtualBox under Linux, if mode is set to “bridged”, the network interface needs to be connected (cableplugged in) in order to have network actually working.

Once the configuration is done, reboot the system to apply the changes:

% reboot

Then update the ABC SBC application settings using the following command:

% dpkg-reconfigure frafos-sbc-cfg

The configuration process will ask you for the management interface. Use the preconfigured VM interface -“eth0”. It will update all the ABC SBC configuration files according to the current network settings.

To verify that all necessary applications are running, use the command:

% monit summary

The following processes should be running:

| root@abcsbc:~# monit summary| The Monit daemon 5.1.1 uptime: 14m|| System ’localhost’ running| Process ’sems’ running| Process ’ser’ running| Process ’redis’ running| Process ’syslog-ng’ running| Process ’mysql’ running| Process ’ssh’ running| Process ’collectd’ running

1.5 VM update

Note: It is highly recommended to update the FRAFOS ABC SBC application to the latest version. This is doneusing standard Debian package management.

First, update the package cache:

% apt-get update

and then upgrade the packages:

% apt-get upgrade

Reconfigure the ABC SBC application after the upgrade:

% dpkg-reconfigure frafos-sbc-cfg

2 ABC SBC Network modeling

2.1 Realms and call agents

The FRAFOS ABC SBC world is modeled as consisting of SIP call agents (UAs, gateways, PBXs, etc) groupedinto an abstract notion of a realm, which typically represents a peering partner. Call agents (CA) can be specifiedusing:

• IP address and port or

• IP network and mask or

• Domain name and port.

For incoming calls to the ABC SBC, the source call agent is determined by the remote IP address from which theINVITE request has been sent. For incoming calls via UDP, the remote port number is also taken into account.Please note that only call agents identified by IP address or IP address range can be determined as source callagents. The source realm is the realm that the source call agent is part of. For outgoing calls, destination realmand call agent are determined according to the configured routing rules.

2.2 A / B / C rules

In the ABC SBC three types of rules are defined:

• inbound (A) rules – used to process calls to the SBC;

• routing (B) rules – used to make routing decision;

• outbound (C) rules – used to process calls from the SBC.

Both call agents and realms have inbound (A) and outbound (C) rules configured for them in the ABC SBC WebGUI. When SIP traffic comes from a source call agent associated with a realm, it is first subject to processing bytheir inbound (A) rules, afterwards the destination is determined using routing (B) rules, and finally outbound (C)rules are applied for the destination realm and call agent.

The ABC SBC handles calls according to the following schema:

Figure 1: Call handling algorithm

3 Routing (B) rules processing

3.1 Routing rules

A routing rule consists of zero, one or many conditions, destination realm, call agent associated with the realmand routing method. Conditions consist of a value to match, and an operator. The operator may be

• equality (==)

• inequality (!=)

• regular expression (RegExp)

Three routing methods are available:

• Set next hop – route calls to the specified address

• Set outbound proxy – add the specified address to a route header and route calls accordingly

• Route via Request URI – route calls to the host address of the Request URI.

If a call agent identified by IP address or domain name is selected, the outbound proxy address or next hop addressis not mandatory. If it is not specified in the routing action, it defaults to the address of the selected call agent.

If a call agent identified by IP range is selected, the Route via R-URI routing method is not available, and anoutbound proxy address or next hop address must be specified in the routing rule.

The “Update R-URI host” flag indicates whether the host part of the Request URI of the outgoing INVITE requestshould be set to the address of the next hop or outbound proxy. Please note that the host value will be updatedafter applying both A and C call rules.

The “active” flag indicates whether the rule should be used during processing or not – inactive routing rules willbe ignored.

A Rule is applied when all its conditions are satisfied. In case a rule does not contain any conditions, the ruleis always applied. Applying the rule means setting destination realm and call agent for the call along with therouting method.

3.2 Routing rules processing algorithm

All active rules are traversed and evaluated sequentially. In case that all conditions of a rule are satisfied, thedestination call agent and routing method are successfully determined. In case that conditions of a rule are notsatisfied, processing continues with the next rule. If no matching routing rule can be found, then the call is refusedwith a 404 Not Found error code. The Figure below depicts the routing rules processing algorithm:

Figure 2: Routing rules processing algorithm

4 Inbound (A) and Outbound (C) rules processing

4.1 Conditions and actions

A Rule can contain zero, one or many conditions and one or many actions. Conditions consist of a value to match,and an operator. The operator may be

• equality (==)

• inequality (!=)

• regular expression (RegExp)

• containing (Contain)

• containing regular expression (Contain RegExp)

• not containing (Do not contain)

Actions can have one or more parameters depending on its type.

A Rule is applied if all its conditions are satisfied (‘AND’ combination). In case a rule does not contain anyconditions, the rule is always applied. Applying the rule means applying of all its actions in the order in whichthey are defined.

4.2 Rule flags

Rules have a priority represented by the order in the list and will be processed in that order. The rule flag “active”indicates whether the rule should be used during processing or not, i.e. inactive rules will be ignored. The

“continue” flag indicates whether processing of rules should continue after the rule was successfully applied ornot.

4.3 Rules processing algorithm

Active rules are traversed and evaluated sequentially. In case that all conditions of a rule are satisfied, afterapplying the rule processing continues with the next rule or stops depending on the “continue” flag. In case thatconditions of a rule are not satisfied and none of the processed rules was applied yet, processing continues withthe next rule regardless of the “continue” flag. In case that conditions of a rule are not satisfied and at least onerule was already applied – processing stops. The rules processing algorithm can be represented with the followingschema:

Figure 3: Rules processing algorithm

5 A / B/ C Rules configuration

5.1 Conditions

The type of a condition defines the left operand for the operation. Please note that an expression in the rightoperand can contain replacements (see 6.3), but can not contain backreferences (see 6.4).

Condition type Left operandCall Variable value of a call variable that has to be already defined by Set Call Variable actionCodecs names of codecs listed in sdpDestination Interface local interface the incoming INVITE was received onFrom the whole From headerFrom Domain host part of From header URI, can contain port numberFrom URI From header URIFrom User user part of From header URIHeader value of a header with the specified nameMedia Types names of media types listed in sdpMethod method of the SIP requestR-URI the whole Request URIR-URI Domain Request URI host part, can contain port numberR-URI URI Parameter Request URI parameter with the specified nameR-URI User Request URI user partR-URI User Parameter Request URI user parameter with the specified nameSource Call Agent source call agent determined for the callSource IP IP address the incoming INVITE request was sent fromSource Port port number the incoming INVITE request was sent fromSource Realm source realm determined for the callTo the whole To headerTo Domain host part of To header URI, can contain port numberTo URI To header URITo User user part of To header URI

5.2 Actions

Action Name Description NotesAdd Header Add a header with the specified name and

valueAppend to RURI user Append suffix to RURI user 1Enable REGISTER pass-through handling

Pass REGISTER messages through SBC

Enable RTP anchoring Enable RTP relay via SBCEnable SIP Session Timers(SST) callee leg

Enable session timer for callee (B) leg

Enable SIP Session Timers(SST) caller leg

Enable session timer for caller (A) leg

Limit parallel calls Set limit for number of parallel callsLimit CAPS Set limit for call attempts per secondLimit Bandwidth (kbps) Set limit for RTP trafficPrefix RURI user Add prefix to RURI user 1Refuse call with reason andcode

Refuse incoming call

Remove Header Exclude a header with the specified nameSet Call Variable Define a variable with the specified name

and valueSet codec blacklist Exclude codec from listSet codec whitelist Allow codecSet From Set From header 2Set From display name Set From display name 2Set From host Set From host(:port) 2Set From user Set From user 2Set header blacklist Exclude header

Continued on next page

Table 1 – continued from previous pageAction Name Description Notes

Set header whitelist Allow headerSet RURI Set RURI 2Set RURI host Set RURI host(:port) 2Set RURI parameter Add or replace RURI parameter 2Set RURI user Set RURI user 2Set RURI user parameter Add or replace RURI user parameter 2Set To Set To header 2Set To display name Set To display name 2Set To host Set To host(:port) 2Set To user Set To user 2Strip RURI user Strip the specified number first characters

from RURI user1

Translate reply code Translate code and reason of received replyfor the specified reply code

Use TCP transport Send outgoing call via TCP

Note:

1. The result is accumulated if the action is applied several times in the same rule or in different rules.

2. Overwrites the previous modifications if the action has been applied several times in the same rule or indifferent rules.

Once defined, a call variable can be used in a Call Variable condition by its name and can be referred in any actionusing $V(gui.varname) replacement, where varname is the variable name.

Blacklists and whitelists are applied to the final appearance of the INVITE request after applying both A and Crules. They are applied one by one in the order in which they are defined in the rules.

The Add header action will add the header with the specified value even if the header is present in a Set headerblacklist actions.

Limit actions in inbound (A) rules define inbound limits (applied to incoming calls to the ABC-SBC), and limitactions defined in outbound (C) rules define outbound limits (applied to outgoing calls from the ABC-SBC).

Example: To limit the number of parallel calls from the ABC SBC to a realm, add a Limit parallel calls actionto the realm’s outbound rules. To limit the number of parallel calls from a realm to the ABC SBC, add a Limitparallel calls action to the realm’s inbound rules.

The rules processing will be stopped immediately if a Refuse action is applied.

5.3 Replacements

Any parameter of any rule action can contain replacements – a special string, a dollar (“$”) sign followed byan identifier. Each instance of a replacement is replaced by its value. Replacement values are initialized to thecorresponding parts of the incoming INVITE request and then modified by actions.

For example, $aU is a replacement for the User part of the P-Asserted-Identity header; $th is a replacement forthe host part of the To header. The action Set R-URI with the parameter set to sip:$aU@$th combines mentionedparts of P-Asserted-Identity and To headers of the incoming INVITE request and puts them into Request URI ofthe outgoing INVITE request.

All supported replacements are listed below in Value Replacement Reference.

5.4 Regexp backreferences

Rule conditions allow to validate a value against regular expression (RegExp). If you need to use a matchedsubstring, you can retrieve it using backreferences.

You can create backreferences by placing some parts of a regular expression inside round brackets. Backreferensescontain the parts of the string matched by the parts of the regular expression inside the brackets. For example,regexp Set(Value) matches either Set or SetValue strings. In the first case, the first backreference will be empty,because it did not match anything. In the second case, the first backreference will contain Value.

Once defined in a rule condition, regexp backreferences can be referred in actions of the same rule using$B(cond_number,backref_number) replacement, where:

• cond_number – number of condition in the rule and

• backref_number – number of backreference inside the regular expression.

Both conditions and backreferences are indexed from 1, so $B(1.1) is the first backreference of the first regularexpression condition.

5.5 Call rules examples

Regexp backreferences

In this example (Figure 4) we save the scheme of the Request URI of the incoming INVITE request in a callvariable called scheme and enforce the “sip” scheme for the R-URI of the outgoing INVITE request. Here thesecond condition defines two backreferences: The first one will contain the scheme of the R-URI, the second one– address of R-URI.

Call variables

In this example (Figure 5) we refuse the call when the Request URI is a “tel” URI. First we check value of schemecall variable (which was defined in the previous example). If it has the value “tel”, we define the call variablerefuse and refuse the call. We also put the value of the call variable scheme into the Reason header using areplacement pattern.

Replacements

In this example (Figure 6) we set up outgoing INVITE request as follows: set Request URI of the outgoingINVITE request to the user part of the P-Asserted-Identity header combined with the host part of the To headerof the incoming INVITE request; set host part of the To header to the value of the P-NextHop-IP header of theincoming INVITE request (the user part will not be changed); convert the user part and the host part of the Fromheader into lower case.

6 Applying configuration

When you click Apply or Save button to save some modifications the message “Warning: SBC configurationchanged, activate to use” appears on the screen. Click activate link if you want to apply the changes immediatelyand start processing calls with the new rules.

However it is recommended to finish all needed configuration changes and then apply the whole configuration atonce.

The configuration could also be activated by clicking the “Activate SBC configuration” link at the bottom of theOverview page.

Figure 4: Regexp backreferences example

Figure 5: Call variables example

Figure 6: Replacements example

7 CDRs management

The FRAFOS ABC SBC generates call data records (CDRs) for every call processed by the SBC.

7.1 CDRs location

CDRs are generated by the ABC SBC into the specific directory:

/var/log/frafos/cdr/

CDRs are generated on Source Realm basis, so every CDR is filtered to a specific file with the name “cdr-_source_realm_.log”. All CDRs also go to one combined file called “cdr.log”.

CDR output files are rotated once a day at midnight and exported to the directory:

/var/log/frafos/cdr/export

the exported files are renamed to include the date – e.g. “cdr.log-20120701”.

7.2 CDR format

In the 1.8.2 VM version, the CDRs have a fixed format and include all the necessary call details. CDRs containthe following items in the given order:

• srcrlm.name - Source Realm

• srcca.name - Source Call Agent

• dstrlm.name - Destination Realm

• dstca.name - Destination Call Agent

• caller_id_user - From user part

• caller_id_host - From host part

• caller_id_name - From display name

• callee_id_user - To user part

• callee_id_host - To host part

• callee_id_name - To display name

• ltag - Local tag (ID for call)

• start_tm - Timestamp when the call is initiated (format - 2012-05-04 02:22:01)

• connect_tm - Timestamp when the call is connected

• end_tm - End Timestamp of the call

• duration - Duration from start to end (sec.ms)

• setup_duration - Duration from start to connect/end (sec.ms)

• bill_duration - Duration from connect to end (sec.ms)

• sip_req_uri - SIP R-URI

• sip_from_uri - SIP From URI

• sip_to_uri – SIP To URI

CDR example:

pstnprovider.com,gw1,mobile.com,uas,"alice","test.com","","bob","192.168.1.4","","6D47CCAA-4FF10747000824C5-80299700","2012-07-02 04:28:23","2012-07-02 04:28:28","2012-07-02 04:28:33","10.139","4.895","5.244","bob@192.168.1.4:6000","alice@test.com","bob@192.168.1.4"

7.3 Access to CDRs

CDRs can be accessed remotely using SFTP protocol. There is a default user configured with privileges to theparticular location.

• username: cdr

• password: cdrfrafos

Using SFTP you can log in from your local machine to the FRAFOS ABC SBC and download the CDRs outputfile:

% sftp cdr@_abcsbc_IP_address% sftp> get cdr* ./

8 Appendix

8.1 Value Replacements Reference

Please note that when a replacement is used, special characters should be escaped as follows:

• \ → \\

• $ → \$

Table 2: Value Replacements Reference

Replacement group Replacements Description$r $r R-URI

$ru R-URI URI$rU R-URI User$rd R-URI Domain (host:port)$rh R-URI Host$rp R-URI Port$rP R-URI Parameters

$f $f From header$fu From URI$fU From User$fd From Domain (host:port)$fh From Host$fp From Port$fn From Display name$fP From Parameters$ft From Tag$fH From Headers

$t $t To header$tu To URI$tU To User$td To Domain (host:port)$th To Host$tp To Port

Continued on next page

Table 2 – continued from previous pageReplacement group Replacements Description

$tn To Display name$tP To Parameters$tt To Tag$tH To Headers

$a $a P-Asserted-Identity header$au P-Asserted-Identity URI$aU P-Asserted-Identity User$ad P-Asserted-Identity Domain (host:port)$ah P-Asserted-Identity Host$ap P-Asserted-Identity Port$aP P-Asserted-Identity Parameters$at P-Asserted-Identity Tag$aH P-Asserted-Identity Headers

$p $p P-Preferred-Identity header$pu P-Preferred-Identity URI$pU P-Preferred-Identity User$pd P-Preferred-Identity Domain (host:port)$ph P-Preferred-Identity Host$pp P-Preferred-Identity Port$pP P-Preferred-Identity Parameters$pt P-Preferred-Identity Tag$pH P-Preferred-Identity Headers

$c $ci Call-ID$H $H(headername) value of header headername (Note: not all headers

are available here)$HU(headername) header headername (as URI) User$Hd(headername) header headername (as URI) domain (host:port)

$V $V(gui.varname) value of call variable varname$B $B(cnum,rnum) value of backreference with rnum number from

the condition with cnum number$_ $_u(value) value to uppercase

$_l(value) value to lowercase$_s(value) length of value$_5(value) MD5 of value$_r(value) random number 0..value, e.g. $_r(5) gives 0, 1, 2,

3 or 4