Click on Create Peering Group to create a new group.

In order to create a group, you must select a peering contract. You will most likely want to create one contract per peering group.

Click on Create Contract create a Contact, then select a Billing Profile.

Click Save on the Contacts form, and you will get redirected back to the form for creating the actual Peering Group. Put a name, priority and description there, for example:

The Priority option defines which Peering Group to favor (Priority 1 gives the highest precedence) if two peering groups have peering rules matching an outbound call. Peering Rules are described below.

Then click Save to create the group.

In the group created before, you need to add peering servers to route calls to and receive calls from. To do so, click on Details on the row of your new group in your peering group list.

To add your first Peering Server, click on the Create Peering Server button.

In this example, we will create a peering server with IP 2.3.4.5 and port 5060:

Click Save to create the peering server.

	The hostname field for a peering server is optional. Usually, the IP address of the peer is used as the domain part of the Request URI. Fill in this field if a peer requires a particular hostname instead of the IP address. The IP address must always be given though as the request will always be sent to the specified IP address, no matter what you put into the hostname field.

	If you want to add a peering server with an IPv6 address, enter the address without surrounding square brackets into the IP Address column, e.g. ::1.

You can force an additional hop (e.g. via an external SBC) towards the peering server by using the Via Route option. The available options you can select there are defined in /etc/ngcp-config/config.yml, where you can add an array of SIP URIs in kamailio→lb→external_sbc like this:

kamailio:
  lb:
    external_sbc:
      - sip:192.168.0.1:5060
      - sip:192.168.0.2:5060

Execute ngcpcfg apply added external sbc gateways, then edit your peering server and select the hop from the Via Route selection.

Once a peering server has been created, this server can already send calls to the system.

	To be able to send outbound calls towards the servers in the Peering Group, you also need to define Peering Rules. They specify which source and destination numbers are going to be terminated over this group. To create a rule, click the Create Peering Rule button.

Since the previously created peering group will be the only one in our example, we have to add a default rule to route all calls via this group. To do so, create a new peering rule with the following values:

Then click Save to add the rule to your group.

In contrast to the callee/caller pattern, the callee prefix has a regular alphanumeric string and can not contain any regular expression. TIP: If you set the caller or callee rules to refine what is routed via this peer, enter all phone numbers in full E.164 format, that is <cc><ac><sn>. TIP: The Caller Pattern field covers the whole URI including the subscriber domain, so you can only allow certain domains over this peer by putting for example @example\.com into this field.

5.5.2.1. Routing Order Selection

The selection of peering groups and peering servers for outgoing calls is done in the following way:

1. All peering groups that meet the following criteria configured in the outbound peering rule are added to the list of routes for a particular call:

   • Callee’s username matches callee prefix
   • Callee’s URI matches callee pattern
   • Caller’s URI matches caller pattern
2. When all matching peering groups are selected, they are ordered by callee prefix according to the longest match basis (sometimes referred to as the longest pattern match or maximum pattern length match). One or more peering group with longest callee prefix match will be given first positions on the list of routes.

3. Peering groups with the same callee prefix length are further ordered by Priority. Peering group(s) with the higher priorities will occupy higher positions.

   	Priority 1 gives the highest precedence to the corresponding peering group. Hence, a lower priority value will put the peering group higher in the list of routes (compared to other peering groups with the same callee prefix length).

   Priority can be selected from 1 (highest) to 9 (lowest).

4. All peering servers in the peering group with the highest priority (e.g. priority 1) are tried one-by-one starting from the highest server weight. Peering groups with lower priorities or with shorter callee prefix will be used only for fail-over.

   The weight of the peering servers in the selected peering group will influence the order in which the servers within the group will be tried for routing the outbound call. The weight of a server can be set in the range from 1 to 127.

	Opposite to the peering group priority, a peering server with a higher weight value has a higher precedence, but the server weight rather sets a probability than a strict order. E.g. although a peering server with weight 127 has the highest chance to be the first in the list of routes, another server with a lower weight (e.g. 100) sometimes will be selected first.

In order to find out this probability knowing the weights of peering servers, use the following script:

#!/usr/bin/php
<?php

   // This script can be used to find out actual probabilities
   // that correspond to a list of peering weights.

if ($argc < 2) {
  echo "Usage: lcr_weight_test.php <list of weights (integers 1-254)>\n";
  exit;
 }

$iters = 10000;

$rands = array();
for ($i = 1; $i <= $iters; $i++) {
  $elem = array();
  for ($j = 1; $j < $argc; $j++) {
    $elem["$j"] = $argv[$j] * (rand() >> 8);
  }
  $rands[] = $elem;
 }

$sorted = array();
foreach ($rands as $rand) {
  asort($rand);
  $sorted[] = $rand;
 }

$counts = array();
for ($j = 1; $j < $argc; $j++) {
  $counts["$j"] = 0;
 }

foreach ($sorted as $rand) {
  end($rand);
  $counts[key($rand)]++;
 }

for ($j = 1; $j < $argc; $j++) {
  echo "Peer with weight " . $argv[$j] . " has probability " . $counts["$j"]/$iters . "\n";
 }
?>

Let us say you have 2 peering servers, one with weight 1 and another with weight 2. At the end — running the script as below — you will have the following traffic distribution:

# lcr_weight_test.php 1 2

 Peer with weight 1 has probability 0.2522
 Peer with weight 2 has probability 0.7478

If a peering server replies with SIP codes 408, 500 or 503, or if a peering server doesn’t respond at all, the next peering server in the current peering group is tried as a fallback. All the servers within the group are tried one after another until the call succeeds. If no more servers are left in the current peering group, the next group which matches the outbound peering rules is used.

These rules are used to normalize user-provided numbers (e.g. passed in From Display Name or P-Preferred-Identity headers) into E.164 format. In our example, we’ll normalize the three different formats mentioned above into E.164 format.

To create the following rules, click on the Create Rewrite Rule for each of them and fill them with the values provided below.

Normalization for national and local calls is possible with special variables ${caller_cc} and ${caller_ac} that can be used in Replacement Pattern and are substituted by the country and area code accordingly during the call routing.

	These variables are only being filled in when a call originates from a subscriber (because only then the cc/ac information is known by the system), so you can not use them when a calls comes from a SIP peer (the variables will be just empty in this case).

	When routing a call, the rewrite processing is stopped after the first match of a rule, starting from top to bottom. If you have two rules (e.g. a generic one and a more specific one), where both of them would match some numbers, reorder them with the up/down arrows into the appropriate position.

These rules are used to rewrite the number the end user dials to place a call to a standard format for routing lookup. In our example, we again allow the three different formats mentioned above and again normalize them to E.164, so we put in the same rules as for the caller.

Our provided rules will only match if the caller dials a numeric number. If he dials an alphanumeric SIP URI, none of our rules will match and no rewriting will be done. You can however define rules for that as well. For example, you could allow your end users to dial support and rewrite that to your support hotline using the match pattern ^support$ and the replace pattern 43800999000 or whatever your support hotline number is.

These rules are used to rewrite the calling party number for a call to an end user. For example, if you want the device of your end user to show 0<ac><sn> if a national number calls this user, and 00<cc><ac><sn> if an international number calls, put the following rules there.

	Note that both of the rules would match a number starting with 43, so reorder the national rule to be above the international one (if it’s not already the case).

These rules are used to rewrite the called party number immediately before sending out the call on the network. This gives you an extra flexibility by controlling the way request appears on a wire, when your SBC or other device expects the called party number to have a particular tech-prefix. It can be used on calls to end users too if you want to do some processing in intermediate SIP device, e.g. apply legal intercept selectively to some subscribers.

There are 2 ways to handle calls from local subscribers to emergency numbers in NGCP:

5.6.5.1. Simple Emergency Number Handling Overview

The overview of emergency call processing is as follows:

Figure 10. Simple Emergency Call Handling

Configuring Emergency Numbers is also done via Rewrite Rules.

Once you have finished to define your Rewrite Rule Sets, you need to assign them. For sets to be used for subscribers, you can assign them to their corresponding domain, which then acts as default set for all subscribers. To do so, go to Settings→Domains and click Preferences on the domain you want the set to assign to. Click on Edit and select the Rewrite Rule Set created before.

You can do the same in the Preferences of your subscribers to override the rule on a subscriber basis. That way, you can finely control down to an individual user the dial-plan to be used. Go to Settings→Subscribers, click the Details button on the subscriber you want to edit, the click the Preferences button.

For each peering server, you can use one of the Rewrite Rule Sets that was created previously as explained in Section 5.6, “Configuring Rewrite Rule Sets” (keep in mind that special variables ${caller_ac} and ${caller_cc} can not be used when the call comes from a peer). To do so, click on the name of the peering server, look for the preference called Rewrite Rule Sets.

If your peering servers don’t send numbers in E.164 format <cc><ac><sn>, you need to create Inbound Rewrite Rules for each peering server to normalize the numbers for caller and callee to this format, e.g. by stripping leading + or put them from national into E.164 format.

Likewise, if your peering servers don’t accept this format, you need to create Outbound Rewrite Rules for each of them, for example to append a + to the numbers.

The sip:provider CE provides a utility that helps with the verification of call routing among local subscribers and peers. It is called Call Routing Verification and employs rewrite rules and peer selection rules, in order to process calling and called numbers or SIP users and find the appropriate peer for the destination.

The Call Routing Verification utility performs only basic number processing and does not invoke the full number manipulation logic applied on real calls. The goal is to enable testing of rewrite rules, rather than validate the complete number processing.

You can access the utility following the path on Admin web interface: Tools → Call Routing Verification.

Expected input data

Examples