6. Administrative Configuration

6.1. Creating a Customer
6.2. Creating a Subscriber
6.3. Domain Preferences
6.4. Subscriber Preferences
6.5. Creating Peerings
6.5.1. Creating Peering Groups
6.5.2. Creating Peering Servers
6.5.3. Authenticating and Registering against Peering Servers
6.5.3.1. Proxy-Authentication for outbound calls
6.5.3.2. Registering at a Peering Server
6.6. Configuring Rewrite Rule Sets
6.6.1. Inbound Rewrite Rules for Caller
6.6.2. Inbound Rewrite Rules for Callee
6.6.3. Outbound Rewrite Rules for Caller
6.6.4. Outbound Rewrite Rules for Callee
6.6.5. Emergency Number Handling
6.6.6. Assigning Rewrite Rule Sets to Domains and Subscribers
6.6.7. Creating Dialplans for Peering Servers

To be able to configure your first test clients, you will need a Customer, a SIP domain and some subscribers in this domain. Throughout this steps, let’s assume you’re running the NGCP on the IP address 1.2.3.4, and you want this IP to be used as SIP domain. This means that your subscribers will have an URI like user1@1.2.3.4.

[Tip]

You can of course set up a DNS name for your IP address (e.g. letting sip.yourdomain.com point to 1.2.3.4) and use this DNS name throughout the next steps, but we’ll keep it simple and stick directly with the IP as a SIP domain for now.

[Warning]

Once you started adding subscribers to a SIP domain, and later decide to change the domain, e.g. from 1.2.3.4 to sip.yourdomain.com, you’ll need to recreate all your subscribers in this new domain. It’s currently not possible to easily change the domain part of a subscriber.

Go to the Administrative Web Panel (Admin Panel) running on https://<ce-ip>:1443/ and follow the steps below. The default user on the system is administrator with the password administrator, if you haven’t changed it already in Section 5.3, “Start Securing Your Server”.

6.1. Creating a Customer

A Customer is a special type of contract on the system acting as billing container for SIP subscribers. You can create as many SIP subscribers within a Customer as you want.

To create a Customer, got to SettingsCustomers.

Dashboard Customer

Click on Create Customer.

Create Customer

Each Customer needs a Contact. We can either reuse the default one, but for a clean setup, we create a new Contact for each Customer to be able to identify the Customer. Click on Create Contact to create a new Contact.

Create Contact

We assign the Contact to the default Reseller. You can create a new one if you want, but for a simple setup the default Reseller is sufficient. Select the Reseller and enter the contact details (at least an Email is required), then press Save.

Save Contact

You will be redirected back to the Contract form. The newly created Contact is selected by default now, so you only have to select a Billing Profile. Again you can create a new one on the fly, but we will go with the default profile for now. Select it and press Save.

You will now see your first Customer in the list. Hover over the customer and click Details to view the details.

Select Customer Details

6.2. Creating a Subscriber

In your Customer details view, click on the Subscribers row, then click the Create Subscriber.

Create Subscriber

As you can see, we don’t have any SIP Domains yet, so click on Create Domain to create one.

Go To Domain

Select the Reseller (make sure to use the same reseller where your Customer is created in) and enter your domain name, then press Save.

Create Domain

Your Domain will be preselected now, so fill out the rest of the form:

  • Web Username: This is the user part of the username the subscriber may use to log into her Customer Self Care Interface. The user part will be automatically suffixed by the SIP domain you choose for the SIP URI. Usually the web username is identical to the SIP URI, but you may choose a different naming schema.
[Caution]

The web username needs to be unique. The system will return a fault if you try to use the same web username twice.

  • Web Password: This is the password for the subscriber to log into her Customer Self Care Interface. It must be at least 6 characters long.
  • E164 Number: This is the telephone number mapped to the subscriber, separated into Country Code (CC), Area Code (AC) and Subscriber Number (SN). For the first tests, you can set a made-up number here and change it later when you get number blocks assigned by your PSTN interconnect partner. So in our example, we’ll use 43 as CC, 99 as AC and 1001 as SN to form the phantasy number +43 99 1001.
[Tip]

This number can actually be used to place calls between local subscribers, even if you don’t have any PSTN interconnection. This comes in handy if you use phones instead of soft-clients for your tests. The format in which this number can be dialled so the subscriber is reached is defined in Section 6.6, “Configuring Rewrite Rule Sets”.

[Important]

NGCP allows single subscriber to have multiple E.164 numbers to be used as aliases for receiving incoming calls. Also NGCP supports "implicit" extensions, e.g. if a subscriber has number 012345, but somebody calls 012345100, then it first tries to send the call to number 012345100 (even though the user is registered as myusername), and only after 404 it falls back to the user-part for which the user is registered.

  • SIP Username: The user part of the SIP URI for your subscriber.
  • SIP Domain: The domain part of the SIP URI for your subscriber.
  • SIP Password: The password of your subscriber to authenticate on the SIP proxy. It must be at least 6 characters long.
  • Status: You can lock a subscriber here, but for creating one, you will most certainly want to use active.
  • External ID: You can provision an arbitrary string here (e.g. an ID of a 3rd party provisioning/billing system).
  • Administrative: If you have multiple subscribers in one account and set this option for one of them, this subscriber can administrate other subscribers via the Customer Self Care Interface.

Create Subscriber

Repeat the creation of Customers and Subscribers for all your test accounts. You should have at least 3 subscribers to test all the functionality of the NGCP.

[Tip]

At this point, you’re able to register your subscribers to the NGCP and place calls between these subscribers.

You should now revise the Domain and Subscriber Preferences.

6.3. Domain Preferences

The Domain Preferences are the default settings for Subscriber Preferences, so you should set proper values there if you don’t want to configure each subscriber separately. You can later override these settings in the Subscriber Preferences if particular subscribers need special settings.

To configure your Domain Preferences, go to SettingsDomains and click on the Preferences button of the domain you want to configure.

Create Subscriber

The most important settings are in the group Number Manipulations, where you can configure where from a SIP message to take numbers from for incoming messages, where in the SIP messages to put which numbers for outgoing SIP messages, and how these numbers are normalized to E164 format and vice versa.

To assign a Rewrite Rule Set to a Domain, create a set first as described in Section 6.6, “Configuring Rewrite Rule Sets”, then assign it to the domain by editing the rewrite_rule_set preference.

Configure Rewrite Rule Set

Select the Rewrite Rule Set and press Save.

Assign Rewrite Rule Set

Then, select the field you want the User Provided Number to be taken from for inbound INVITE messages. Usually the From-Username should be fine, but you can also take it from the Display-Name of the From-Header, and other options are available as well.

6.4. Subscriber Preferences

You can override the Domain Preferences on a subscriber basis as well. Also, there are Subscriber Preferences which don’t have a default value in the Domain Preferences.

To configure your Subscriber, go to SettingsSubscribers and click Details on the row of your subscriber. There, click on the Preferences button on top.

You want to look into the Number Manipulations and Access Restrictions options in particular, which control what is used as user-provided and network-provided calling numbers.

  • For outgoing calls, you may define multiple numbers or patterns to control what a subscriber is allowed to send as user-provided calling numbers using the allowed_clis preference.
  • If allowed_clis does not match the number sent by the subscriber, then the number configured in cli (the network-provided number) preference will be used as user-provided calling number also.
  • You can override any user-provided number coming from the subscriber using the user_cli preference.

6.5. Creating Peerings

If you want to terminate calls at or allow calls from 3rd party systems (e.g. PSTN gateways, SIP trunks), you need to create SIP peerings for that. To do so, go to SettingsPeerings. There you can add peering groups, and for each peering group add peering servers and rules controlling which calls are routed over these groups. Every peering group needs a peering contract for correct interconnection billing.

6.5.1. Creating Peering Groups

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.

Select Peering Contract

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

Create Peering Contract

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:

  • Peering Contract: select the id of the contract created before
  • Name: test group
  • Priority: 1
  • Description: peering to a test carrier

Create New Peering Group

The Priority option defines which Peering Group to favor if two peering groups have peering rules matching an outbound call. Peering Rules are described below.

Then click Save to create the group.

6.5.2. Creating Peering Servers

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.

Create Peering Server

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

  • Name: test-gw-1
  • IP Address: 2.3.4.5
  • Hostname: leave empty
  • Port: 5060
  • Protocol: UDP
  • Weight: 1

Save Peering Server

Click Save to create the peering server.

[Tip]

The hostname field for a peering server is optional. Usually, the IP address of the peer is used as domain part in the Request URI. Some peers may require you to set a particular hostname instead of the IP address there, which can be done by filling in this field. The IP address must always be given though, and the request will always be sent to the IP address, no matter what you put into the hostname field.

[Tip]

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.

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

[Important]

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.

Create Peering Rule

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:

  • Callee Prefix: leave empty
  • Callee Pattern: leave empty
  • Caller Pattern: leave empty
  • Description: Default Rule

Save Peering Rule

Then click Save to add the rule to your group.

[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.

Fully Configured Peering Group

[Important]

The selection of peering servers for outbound calls is done in the following order: 1. whether caller or callee pattern matched. 2. length of the callee prefix. 3. priority of the peering group. 4. weight of the peering servers in the selected peering group. After one or more peering group(s) is matched for an outbound call, all servers in this group are tried, according to their weight (lower weight has more precedence). 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 used as a fallback, one after the other until the call succeeds. If no more servers are left in the current peering group, the next group which matches the peering rules is going to be used.

6.5.3. Authenticating and Registering against Peering Servers

6.5.3.1. Proxy-Authentication for outbound calls

If a peering server requires the SPCE to authenticate for outbound calls (by sending a 407 as response to an INVITE), then you have to configure the authentication details in the Preferences view of your peer host.

Peer Preferences

To configure this setting, open the Remote Authentication tab and edit the following three preferences:

  • peer_auth_user: <username for peer auth>
  • peer_auth_pass: <password for peer auth>
  • peer_auth_realm: <domain for peer auth>

Set Authentication Credentials For Peer

[Important]

If you do NOT authenticate against a peer host, then the caller CLI is put into the From and P-Asserted-Identity headers, e.g. "+4312345" <sip:+4312345@your-domain.com>. If you DO authenticate, then the From header is "+4312345" <sip:your_peer_auth_user@your_peer_auth_realm> (the CLI is in the Display field, the peer_auth_user in the From username and the peer_auth_realm in the From domain), and the P-Asserted-Identity header is as usual like <sip:+4312345@your-domain.com>. So for presenting the correct CLI in CLIP no screening scenarios, your peering provider needs to extract the correct user either from the From Display-Name or from the P-Asserted-Identity URI-User.

[Tip]

You will notice that these three preferences are also shown in the Subscriber Preferences for each subscriber. There you can override the authentication details for all peer host if needed, e.g. if every user authenticates with his own separate credentials at your peering provider.

6.5.3.2. Registering at a Peering Server

Unfortunately, the credentials configured above are not yet automatically used to register the SPCE at your peer hosts. There is however an easy manual way to do so, until this is addressed.

Configure your peering servers with the corresponding credentials in /etc/ngcp-config/templates/etc/sems/etc/reg_agent.conf.tt2, then execute ngcpcfg apply.

[Important]

Be aware that this will force SEMS to restart, which will drop all calls.

6.6. Configuring Rewrite Rule Sets

[Important]

On the NGCP, every phone number is treated in E.164 format <country code><area code><subscriber number>. Rewrite Rule Sets is a flexible tool to translate the caller and callee numbers to the proper format before the routing lookup and after the routing lookup separately. The created Rewrite Rule Sets can be assigned to the domains, subscribers and peers as a preference.

You would normally begin with creating a Rewrite Rule Set for your SIP domains. This is used to control what an end user can dial for outbound calls, and what is displayed as the calling party on inbound calls. The subscribers within a domain inherit Rewrite Rule Sets of that domain, unless this is overridden by a subscriber Rewrite Rule Set preference.

To create a new Rewrite Rule Set, go to SettingsRewrite Rule Sets. There you can create a Set identified by a name. This name is later shown in your peer-, domain- and user-preferences where you can select the rule set you want to use.

Create New Rewrite Rule Set

Click Create Rewrite Rule Set and fill in the form accordingly.

Save New Rewrite Rule Set

Press the Save button to create the set.

To view the Rewrite Rules within a set, hover over the row and click the Rules button.

View Rewrite Rules

The rules are ordered by Caller and Callee as well as direction Inbound and Outbound.

[Tip]

In Europe, the following formats are widely accepted: +<cc><ac><sn>, 00<cc><ac><sn> and 0<ac><sn>. Also, some countries allow the areacode-internal calls where only subscriber number is dialed to reach another number in the same area. Within this section, we will use these formats to show how to use rewrite rules to normalize and denormalize number formats.

6.6.1. Inbound Rewrite Rules for Caller

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.

Strip leading 00 or +

  • Match Pattern: ^(00|\+)([1-9][0-9]+)$
  • Replacement Pattern: \2
  • Description: International to E.164
  • Direction: Inbound
  • Field: Caller

Replace 0 by caller’s country code:

  • Match Pattern: ^0([1-9][0-9]+)$
  • Replacement Pattern: ${caller_cc}\1
  • Description: National to E.164
  • Direction: Inbound
  • Field: Caller

Normalize local calls:

  • Match Pattern: ^([1-9][0-9]+)$
  • Replacement Pattern: ${caller_cc}${caller_ac}\1
  • Description: Local to E.164
  • Direction: Inbound
  • Field: Caller

Save New Rewrite Rule

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.

[Important]

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).

[Tip]

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.

Reorder Rules

6.6.2. Inbound Rewrite Rules for Callee

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.

Strip leading 00 or +

  • Match Pattern: ^(00|\+)([1-9][0-9]+)$
  • Replacement Pattern: \2
  • Description: International to E.164
  • Direction: Inbound
  • Field: Callee

Replace 0 by caller’s country code:

  • Match Pattern: ^0([1-9][0-9]+)$
  • Replacement Pattern: ${caller_cc}\1
  • Description: National to E.164
  • Direction: Inbound
  • Field: Callee

Normalize areacode-internal calls:

  • Match Pattern: ^([1-9][0-9]+)$
  • Replacement Pattern: ${caller_cc}${caller_ac}\1
  • Description: Local to E.164
  • Direction: Inbound
  • Field: Callee
[Tip]

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.

6.6.3. Outbound Rewrite Rules for Caller

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.

Replace Austrian country code 43 by 0

  • Match Pattern: ^43([1-9][0-9]+)$
  • Replacement Pattern: 0\1
  • Description: E.164 to Austria National
  • Direction: Outbound
  • Field: Caller

Prefix 00 for international caller

  • Match Pattern: ^([1-9][0-9]+)$
  • Replacement Pattern: 00\1
  • Description: E.164 to International
  • Direction: Outbound
  • Field: Caller
[Tip]

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).

6.6.4. Outbound Rewrite Rules for Callee

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.

Prefix sipsp# for all calls

  • Match Pattern: ^([0-9]+)$
  • Replacement Pattern: sipsp#\1
  • Description: Intercept this call
  • Direction: Outbound
  • Field: Callee

6.6.5. Emergency Number Handling

Configuring Emergency Numbers is also done via Rewrite Rules.

For Emergency Calls from a subscriber to the platform, you need to define an Inbound Rewrite Rule For Callee, which adds a prefix emergency_ to the number (and can rewrite the number completely as well at the same time). If the proxy detects a call to a SIP URI starting with emergency_, it will enter a special routing logic bypassing various checks which might make a normal call fail (e.g. due to locked or blocked numbers, insufficient credits or exceeding the max. amount of parallel calls).

Tag an Emergency Call

  • Match Pattern: ^(911|112)$
  • Replacement Pattern: emergency_\1
  • Description: Tag Emergency Numbers
  • Direction: Inbound
  • Field: Callee

To route an Emergency Call to a Peer, you can select a specific peering group by adding a peering rule with a callee prefix set to emergency_ to a peering group.

In order to normalize the emergency number to a valid format accepted by the peer, you need to assign an Outbound Rewrite Rule For Callee, which strips off the emergency_ prefix. You can also use the variables ${caller_emergency_cli}, ${caller_emergency_prefix} and ${caller_emergency_suffix} as well as ${caller_ac} and ${caller_cc}, which are all configurable per subscriber to rewrite the number into a valid format.

Normalize Emergency Call for Peer

  • Match Pattern: ^emergency_(.+)$
  • Replacement Pattern: ${caller_emergency_prefix}${caller_ac}\1
  • Description: Normalize Emergency Numbers
  • Direction: Outbound
  • Field: Caller

6.6.6. Assigning Rewrite Rule Sets to Domains and Subscribers

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 SettingsDomains and click Preferences on the domain you want the set to assign to. Click on Edit and select the Rewrite Rule Set created before.

Assign Rewrite Rule Set To Domain

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 SettingsSubscribers, click the Details button on the subscriber you want to edit, the click the Preferences button.

6.6.7. Creating Dialplans for Peering Servers

For each peering server, you can use one of the Rewrite Rule Sets that was created previously as explained in Section 6.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.