7. Advanced Subscriber Configuration

7.1. Access Control for SIP Calls
7.1.1. Block Lists
7.1.1.1. Block Modes
7.1.1.2. Block Lists
7.1.1.3. Block Anonymous Numbers
7.1.2. NCOS Levels
7.1.2.1. Creating NCOS Levels
7.1.2.2. Creating Rules per NCOS Level
7.1.2.3. Assigning NCOS Levels to Subscribers/Domains
7.1.2.4. Assigning NCOS Level for Forwarded Calls to Subscribers/Domains
7.1.3. IP Address Restriction
7.2. Call Forwarding and Call Hunting
7.2.1. Setting a simple Call Forward
7.2.2. Advanced Call Hunting
7.2.2.1. Configuring Destination Sets
7.2.2.2. Configuring Time Sets
7.3. Limiting Subscriber Preferences via Subscriber Profiles
7.3.1. Subscriber Profile Sets
7.4. Voicemail System
7.4.1. Accessing the IVR Menu
7.4.1.1. Mapping numbers and codes to IVR access
7.4.1.2. External IVR access
7.4.2. IVR Menu Structure
7.5. Configuring Subscriber IVR Language
7.6. Sound Sets
7.6.1. Configuring Early Reject Sound Sets
7.7. Conference System
7.7.1. Configuring Call Forward to Conference
7.7.2. Configuring Conference Sound Sets
7.7.3. Entering the Conference with a PIN

The sip:provider CE provides a large amount of subscriber features in order to offer compelling VoIP services to end customers, and also to cover as many deployment scenarios as possible. In this chapter, we will go over the features and describe their behavior and their use cases.

7.1. Access Control for SIP Calls

There are two different methods to provide fine-grained call admission control to both subscribers and admins. One is Block Lists, where you can define which numbers or patterns can be called from a subscriber to outbound direction and which numbers or patterns are allowed to call a subscriber in inbound direction. The other is NCOS Levels, where the admin predefines rules for outbound calls, which are grouped in certain levels. The user can then just choose the level, or the admin can restrict a user to a certain level. Also sip:provider CE offers some options to restrict the IP addresses that subscriber is allowed to use the service from. The following chapters will discuss these features in detail.

7.1.1. Block Lists

Block Lists provide a way to control which users/numbers are able to call or to be called, based on a subscriber level, and can be found in the Call Blockings section of the subscriber preferences.

Subscriber Block Lists

Block Lists are separated into Administrative Block Lists (adm_block_*) and Subscriber Block Lists (block_*). They both have the same behavior, but Administrative Block Lists take higher precedence. Administrative Block Lists are only accessible by the system administrator and can thus be used to override any Subscriber Block Lists, e.g. to block certain destinations. The following break-down of the various block features apply to both types of lists.

7.1.1.1. Block Modes

Block lists can either be whitelists or blacklists and are controlled by the User Preferences block_in_mode, block_outmode__ and their administrative counterparts.

  • The blacklist mode (option is not checked tells the system to allow anything except the entries in the list. This mode is used if you want to just block certain numbers and allow all the rest.
  • The whitelist mode indicates to reject anything except the entries in the list. This is used if you want to enforce a strict policy and allow only selected destinations or sources.

You can change a list mode from one to the other at any time.

7.1.1.2. Block Lists

The list contents are controlled by the User Preferences block_in_list, block_out_list and their administrative counterparts. Click on the Edit button in the Preferences view to define the list entries.

In block list entries, you can provide shell patterns like * and []. The behavior of the list is controlled by the block_xxx_mode feature (so they are either allowed or rejected). In our example above we have block_out_mode set to blacklist, so all calls to US numbers and to the Austrian number +431234567 are going to be rejected.

Outgoing Block List

Click the Close icon once you’re done editing your list.

7.1.1.3. Block Anonymous Numbers

For incoming call, the User Preference block_in_clir and adm_block_in_clir controls whether or not to reject incoming calls with number supression (either "[Aa]nonymous" in the display- or user-part of the From-URI or a header Privacy: id is set). This flag is independent from the Block Mode.

7.1.2. NCOS Levels

NCOS Levels provide predefined lists of allowed or denied destinations for outbound calls of local subscribers. Compared to Block Lists, they are much easier to manage, because they are defined on a global scope, and the individual levels can then be assigned to each subscriber. Again there is the distinction for user- and administrative-levels.

NCOS levels can either be whitelists or blacklists.

  • The blacklist mode indicates to allow everything except the entries in this level. This mode is used if you want to just block certain destinations and allow all the rest.
  • The whitelist mode indicates to reject anything except the entries in this level. This is used if you want to enforce a strict policy and allow only selected destinations.
7.1.2.1. Creating NCOS Levels

To create an NCOS Level, go to SettingsNCOS Levels and press the Create NCOS Level button.

NCOS Levels

Select a reseller, enter a name, select the mode and add a description, then click the Save button.

Create NCOS Levels

7.1.2.2. Creating Rules per NCOS Level

To define the rules within the newly created NCOS Level, click on the Patterns button of the level.

Enter NCOS Pattern View

In the Number Patterns view you can create multiple patterns to define your level, one after the other. Click on the Create Pattern Entry Button on top and fill out the form.

Create NCOS Pattern

In this example, we block (since the mode of the level is blacklist) all numbers starting with 439. Click the Save button to save the entry in the level.

The option include local area code in list for a blacklist means that calls within the area code of the subscribers are denied, and for whitelist that they are allowed, respectively. For example if a subscriber has country-code 43 and area-code 1, then selecting this checkbox would result in an implicit entry ^431.

7.1.2.3. Assigning NCOS Levels to Subscribers/Domains

Once you’ve defined your NCOS Levels, you can assign them to local subscribers. To do so, navigate to SettingsSubscribers, search for the subscriber you want to edit, press the Details button and go to the Preferences View. There, press the Edit button on either the ncos or admncos setting in the Call Blockings__ section.

Assign NCOS Level

You can assign the NCOS level to all subscribers within a particular domain. To do so, navigate to SettingsDomains, select the domain you want to edit and click Preferences. There, press the Edit button on either ncos or admin_ncos in the Call Blockings section.

Note: if both domain and subscriber have same NCOS preference set (either ncos or adm_ncos, or both) the subscriber’s preference is used. This is done so that you can override the domain-global setting on the subscriber level.

7.1.2.4. Assigning NCOS Level for Forwarded Calls to Subscribers/Domains

In some countries there are regulatory requirements that prohibit subscribers from forwarding their numbers to special numbers like emergency, police etc. While the sip:provider CE does not deny provisioning Call Forward to these numbers, the administrator can prevent the incoming calls from being actually forwarded to numbers defined in the NCOS list: just select the appropriate NCOS level in the domain’s or subscriber’s preference adm_cf_ncos. This NCOS will apply only to the Call Forward from the subscribers and not to the normal outgoing calls from them.

7.1.3. IP Address Restriction

The sip:provider CE provides subscriber preference allowed_ips to restrict the IP addresses that subscriber is allowed to use the service from. If the REGISTER or INVITE request comes from an IP address that is not in the allowed list, the sip:provider CE will reject it with a 403 message. Also a voice message can be played when the call attempt is rejected (if configured).

By default, allowed_ips is an empty list which means that subscriber is not restricted. If you want to configure a restriction, navigate to SettingsSubscribers, search for the subscriber you want to edit, press Details and then Preferences and press Edit for the allowed_ips preference in the Access Restrictions section.

Edit Subscriber Allowed IP Addresses

Press the Edit button to the right of empty drop-down list.

You can enter multiple allowed IP addresses or IP address ranges one after another. Click the Add button to save each entry in the list. Click the Delete button if you want to remove some entry.

7.2. Call Forwarding and Call Hunting

The sip:provider CE provides the capabilities for normal call forwarding (deflecting a call for a local subscriber to another party immediately or based on events like the called party being busy or doesn’t answer the phone for a certain number of seconds) and serial call hunting (sequentially executing a group of deflection targets until one of them succeeds). Targets can be stacked, which means if a target is also a local subscriber, it can have another call forward or hunt group which is executed accordingly.

Call Forwards and Call Hunting Groups can either be executed unconditionally or based on a Time Set Definition, so you can define deflections based on time period definitions (e.g. Monday to Friday 8am to 4pm etc).

7.2.1. Setting a simple Call Forward

Go to your Subscriber Preferences and click Edit on the Call Forward Type you want to set (e.g. Call Forward Unconditional).

Create Simple Call Forward

If you select URI/Number in the Destination field, you also have to set a URI/Number. The timeout defines for how long this destination should be tried to ring.

7.2.2. Advanced Call Hunting

If you want multiple destinations to be executed one after the other, you need to change into the Advanced View when editing your call forward. There, you can select multiple Destination Set/Time Set pairs to be executed.

A Destination Set is a list of destinations to be executed one after another.

A Time Set is a time definition when to execute this Destination Set.

7.2.2.1. Configuring Destination Sets

Click on Manage Destination Sets to see a list of available sets. The quickset_cfu has been implicitly created during our creation of a simple call forward. You can edit it to add more destinations, or you can create a new destination set.

Create CF Destination Set

When you close the Destination Set Overview, you can now assign your new set in addition or instead of the quickset_cfu set.

Assign CF Destination Sets

Press Save to store your settings.

7.2.2.2. Configuring Time Sets

Click on Manage Time Sets in the advanced call-forward menu to see a list of available time sets. By default there are none, so you have to create one.

Create CF Time Set

You need to provide a Name, and a list of Periods where this set is active. If you only set the top setting of a date field (like the Year setting in our example above), then it’s valid for just this setting (like the full year of 2013 in our case). If you provide the bottom setting as well, it defines a period (like our Month setting, which means from beginning of April to end of September).

[Important]

the period is a through definition, so it covers the full range. If you define an Hour definition 8-16, then this means from 08:00 to 16:59:59 (unless you filter the Minutes down to something else).

If you close the Time Sets management, you can assign your new time set to the call forwards you’re configuring.

7.3. Limiting Subscriber Preferences via Subscriber Profiles

The preferences a subscriber can provision by himself via the CSC can be limited via profiles within profile sets assigned to subscribers.

7.3.1. Subscriber Profile Sets

Profile sets define containers for profiles. The idea is to define profile sets with different profiles by the administrator (or the reseller, if he is permitted to do so). Then, a subscriber with administrative privileges can re-assign profiles within his profile sets for the subscribers of his customer account.

Profile Sets can be defined in SettingsSubscriber Profiles. To create a new Profile Set, click Create Subscriber Profile Set.

Create Subscriber Profile Set

You need to provide a reseller, name and description.

To create Profiles within a Profile Set, hover over the Profile Set and click the Profiles button.

Profiles within a Profile Set can be created by clicking the Create Subscriber Profile button.

Create Subscriber Profile

Checking the Default Profile option causes this profile to get assigned automatically to all subscribers, who have the profile set assigned. Other options define the user preferences which should be made available to the subscriber.

7.4. Voicemail System

7.4.1. Accessing the IVR Menu

For a subscriber to manage his voicebox via IVR, there are two ways to access the voicebox. One is to call the URI voicebox@yourdomain from the subscriber itself, allowing password-less access to the IVR, as the authentication is already done on SIP level. The second is to call the URI voiceboxpass@yourdomain from any subscriber, causing the system to prompt for a mailbox and a PIN.

7.4.1.1. Mapping numbers and codes to IVR access

Since access might need to be provided from external networks like PSTN/Mobile, and since certain SIP phones don’t support calling alphanumeric numbers to dial voicebox, you can map any arbitrary number to the voicebox URIs using rewrite rules.

To do so, you can provision a match pattern like ^(00|\+)12345$ with a replace pattern voicebox or voiceboxpass to map a number to either password-less or password-based IVR access.

7.4.1.2. External IVR access

When reaching voiceboxpass, the subscriber is prompted for her mailbox number and a password. All numbers assigned to a subscriber are valid input (primary number and any alias number). By default, the required format is in E.164, so the subscriber needs to enter the full number including country code, for example 4912345 if she got assigned a German number.

You can globally configure a rewrite rule in config.yml using asterisk.voicemail.normalize_match and asterisk.voicemail.normalize_replace, allowing you to customize the format a subscriber can enter, e.g. having ^0([1-9][0-9]+)$ as match part and 49$1 as replace part to accept German national format.

7.4.2. IVR Menu Structure

The following list shows you how the voicebox menu is structured.

  • 1 Read voicemail messages

    • 3 Advanced options

      • 3 To Hear messages Envelope
      • * Return to the main menu
    • 4 Play previous message
    • 5 Repeat current message
    • 6 Play next message
    • 7 Delete current message
    • 9 Save message in a folder

      • 0 Save in new Messages
      • 1 Save in old Messages
      • 2 Save in Work Messages
      • 3 Save in Family Messages
      • 4 Save in Friends Messages
      • # Return to the main menu
  • 2 Change folders

    • 0 Switch to new Messages
    • 1 Switch to old Messages
    • 2 Switch to Work Messages
    • 3 Switch to Family Messages
    • 4 Switch to Friends Messages
    • # Get Back
  • 3 Advanced Options

    • * To return to the main menu
  • 0 Mailbox options

    • 1 Record your unavailable message

      • 1 accept it
      • 2 Listen to it
      • 3 Rerecord it
    • 2 Record your busy message

      • 1 accept it
      • 2 Listen to it
      • 3 Rerecord it
    • 3 Record your name

      • 1 accept it
      • 2 Listen to it
      • 3 Rerecord it
    • 4 Record your temporary greetings

      • 1 accept it
      • 2 Listen to it
      • 3 Rerecord it
    • 5 Change your password
    • * To return to the main menu
  • * Help
  • # Exit

7.5. Configuring Subscriber IVR Language

The language for the Voicemail system IVR or Vertical Service Codes (VSC) IVRs may be set using the subscriber or domain preference language.

Set Subscriber IVR Language

The sip:provider CE provides the pre-installed prompts for the Voicemail in the English, Spanish, French and Italian languages and the pre-installed prompts for the Vertical Service Codes IVRs in English only.

The other IVRs such as the Conference system and the error announcements use the Sound Sets configured in NGCP Panel and uploaded by the administrator in his language of choice.

7.6. Sound Sets

The sip:provider CE provides the administrator with ability to upload the voice prompts such as conference prompts or call error announcements on the Sound Sets page. There is a preference sound_set on Domain and Subscriber levels to link subscribers to the sound set that they should hear (as usual the subscriber preference overrides the domain one). Sound Sets can be defined in SettingsSound Sets. To create a new Sound Set, click Create Sound Set. Then click the Files button.

Create a Sound Set

[Note]

You may use 8 or 16 bit mono WAV audio files for all of the voice prompts.

7.6.1. Configuring Early Reject Sound Sets

The call error announcements are grouped under Early Rejects section. Unfold the section and click Upload next to the sound handles (Names) that you want to use. Choose a WAV file from your file system, and click the Loopplay setting if you want to play the file in a loop instead of just once. Click Save to upload the file.

Early Reject Sounds

The call error announcements are played to the user in early media hence the name "Early Reject". If you don’t provide the sound files for any handles they will not be used and the sip:provider CE will fallback to sending the error response code back to the user.

Table 2. Early Reject Sound Sets

HandleDescriptionMessage played

block_in

This is what the calling party hears when a call is made from a number that is blocked by the incoming block list (adm_block_in_list, block_in_list subscriber preferences)

Your call is blocked by the number you are trying to reach.

block_out

This is what the calling party hears when a call is made to a number that is blocked by the outgoing block list (adm_block_out_list, block_out_list subscriber preferences)

Your call to the number you are trying to reach is blocked.

block_ncos

This is what the calling party hears when a call is made to a number that is blocked by the NCOS level assigned to the subscriber or domain (the NCOS level chosen in ncos and adm_ncos preferences)

Your call to the number you are trying to reach is not permitted.

block_override_pin_wrong

Announcement played to calling party if it used wrong PIN code to override the outgoing user block list or the NCOS level for this call (the PIN set by block_out_override_pin and adm_block_out_override_pin preferences)

The PIN code you have entered is not correct.

locked_in

Announcement played on incoming call to a subscriber that is locked for incoming calls

The number you are trying to reach is currently not permitted to receive calls.

locked_out

Announcement played on outgoing call to subscriber that is locked for outgoing calls

You are currently not allowed to place outbound calls.

max_calls_in

Announcement played on incoming call to a subscriber who has exceeded the concurrent_max limit by sum of incoming and outgoing calls or whose customer has exceeded the concurrent_max_per_account limit by sum of incoming and outgoing calls

The number you are trying to reach is currently busy. Please try again later.

max_calls_out

Announcement played on outgoing call to a subscriber who has exceeded the concurrent_max (total limit) or concurrent_max_out (limit on number of outbound calls) or whose customer has exceeded the concurrent_max_per_account or concurrent_max_out_per_account limit

All outgoing lines are currently in use. Please try again later.

max_calls_peer

Announcement played on calls from the peering if that peer has reached the maximum number of concurrent calls (configured by admin in concurrent_max preference of peering server)

The network you are trying to reach is currently busy. Please try again later.

unauth_caller_ip

This is what the calling party hears when it tries to make a call from unauthorized IP address or network (allowed_ips, man_allowed_ips preferences)

You are not allowed to place calls from your current network location.

relaying_denied

Announcement played on inbound call from trusted IP (e.g. external PBX) with non-local Request-URI domain

The network you are trying to reach is not available.

invalid_speeddial

This is what the calling party hears when it calls an empty speed-dial slot

The speed dial slot you are trying to use is not available.

cf_loop

Announcement played when the called subscriber has the call forwarding configured to itself

The number you are trying to reach is forwarded to an invalid destination.

callee_offline

Announcement played on incoming call to the subscriber which is currently not registered

The number you are trying to reach is currently not available. Please try again later.

callee_busy

Announcement played on incoming call to the subscriber which is currently busy (486 response from the UAS)

The number you are trying to reach is currently busy. Please try again later.

callee_unknown

Announcement that is played on call to unknown or invalid number (not associated with any of our subscribers/hunt groups)

The number you are trying to reach is not in use.

callee_tmp_unavailable

Announcement played on incoming call to the subscriber which is currently unavailable (408, other 4xx or no response code or 30x with malformed contact)

The number you are trying to reach is currently not available. Please try again later.

peering_unavailable

Announcement played in case of outgoing off-net call when there is no peering rule matching this destination and/or source

The network you are trying to reach is not available.

voicebox_unavailable

Announcement played on call to voicebox if the voicemail server is not configured (system operation is impaired)

The voicemail of the number you are trying to reach is currently not available. Please try again later.

emergency_unsupported

Announcement played when emergency destination is dialed but the emergency calls are administratively prohibited for this user or domain (reject_emergency preference is enabled)

You are not allowed to place emergency calls from this line. Please use a different phone.

no_credit

Announcement played when prepaid account has insufficient balance to make a call to this destination


 

7.7. Conference System

The sip:provider CE provides the simple pin-protected conferencing service built using the SEMS DSM scripting language. Hence it is open for all kinds of modifications and extensions.

Template files for the sems conference scripts stored in /etc/ngcp-config/templates/etc/ngcp-sems/:

  • IVR script: /etc/ngcp-config/templates/etc/ngcp-sems/dsm/confpin.dsm.tt2
  • Config: /etc/ngcp-config/templates/etc/ngcp-sems/dsm/confpin.conf.tt2

7.7.1. Configuring Call Forward to Conference

Go to your Subscriber Preferences and click Edit on the Call Forward Type you want to set (e.g. Call Forward Unconditional).

Configure Call Forward to Conference

You should select Conference option in the Destination field and leave the URI/Number empty. The timeout defines for how long this destination should be tried to ring.

7.7.2. Configuring Conference Sound Sets

Sound Sets can be defined in SettingsSound Sets. To create a new Sound Set, click Create Sound Set. Then click the Files button.

Conference Sounds

Upload the following files:

Table 3. Conference Sound Sets

HandleMessage played

conference_greeting

Welcome to the conferencing service. Please enter your PIN, followed by the pound key.

conference_pin_wrong

You have entered an invalid PIN number. Please try again.

conference_joined

You will be placed into the conference.

conference_join

A person has joined the conference.

conference_leave

A person has left the conference.

goodbye

Goodbye.


[Note]

You may use 8 or 16 bit mono WAV audio files.

Then set the preference sound_set on the Domain or Subscriber level in order to assign the Sound Set you have just created to the subscriber (as usual the subscriber preference overrides the domain one).

7.7.3. Entering the Conference with a PIN

It is mandatory to configure the PIN code for entrance to the conference on the same subscriber which has the Call Forwarding active. Responsible for this is the conference_pin preference in the Internals section of subscriber preferences.

Set Subscriber IVR Language

When calling the conference IVR you are requested to enter this PIN. Upon the successful entry of the PIN the caller hears the announcement that he is going to be placed into a conference and at the same time this is announced to all participants in the conference.