Extra Modules

Cloud PBX

The Sipwise C5 comes with a commercial Cloud PBX module to provide B2B features for small and medium sized enterprises. The following chapters describe the configuration of the PBX features.

PBX Device Provisioning

How it works

A device gets provisioned with the following steps:

  • Your customer creates a PBX device for a supported model and inputs a device’s MAC address.

  • Sipwise C5 sends the provided MAC address to the device vendor (e.g. api.eds.al-enterprise.com, rps.yealink.com or sraps.snom.com).

  • When the corresponding device is connected to the network, the device fetches the provisioning URL from the vendor site.

  • The device downloads its specific configuration and the firmware from Sipwise C5.

  • The phone updates the firmware and automatically sets the SIP proxy server, username and password and other SIP parameters received from Sipwise C5.

PBX device provisioning requires appropriate device models, firmwares, configurations and profiles to be added to the system.

A device model defines a specific hardware device, like the vendor, the model name, the number of keys and their capabilities. For example, a Cisco SPA504G has 4 keys, which can be used for private lines, shared lines (SLA) and busy lamp field (BLF). If you have an additional attendant console, you get 32 more buttons, which can only do BLF. The list of supported devices can be found in List of available pre-configured devices.

A device firmware is used to update a potentially outdated factory firmware on a device. The default firmwares included in Sipwise C5 were tested with the provided device configurations and hence guarantee that all the supported features work as expected. That is why we recommend using the default firmwares and device configurations provided by Sipwise.

To make device provisioning easy-to-use for end-users, they do not have to care about firmwares or configurations mentioned above. Instead, you provide a device profile for every supported device model and associate such a device profile with a specific device configuration and firmware. When a customer employee with administrative rights provisions PBX devices for the company, they select the corresponding device profiles and specifies MAC addresses if necessary. Sipwise C5 will take care of the rest.

Sipwise C5 is supplied with a set of supported device models, their firmwares, configurations and profile. You can enable them and your customers will be able to use PBX device provisioning immediately.

To perform basic configuration and upload the set for a specific vendor, device model(s) or for all supported devices, execute the steps described in the following section.

Initial device provisioning configuration

Execute the following initial steps before your customers can easily and securely provision their PBX devices:

  1. Set the certificates and the keys for your HTTPs FQDN

  2. Upload the required device models/firmwares/configurations/profiles

Set the certificates and the key for your web domain

You can create new ones or use the existing certificate and the key for your web FQDN.

  • Put the required files into the /etc/ngcp-config/shared-files/ssl folder.

  • Specify the paths to the files and the FQDN in the following config.yml parameters:

    • server_certfile

    • server_keyfile

    • Specify the FQDN in autoprov.server.host

    • Optionally, enable autoprov.server.nginx_debug

The final configuration should look similar to this one:

autoprov:
  hardphone:
    skip_vendor_redirect: no
    skip_vendor_ssl_verify: []
    skip_vendor_ssl_verify_hostname: []
  server:
    bootstrap_port: '1445'
    cisco_port: '1447'
    client_ca_certfile: /etc/ngcp-config/shared-files/ssl/client-auth-ca.crt
    host: portal.yourdomain.com
    nginx_debug: yes
    port: '1444'
    server_ca_certfile: /etc/ngcp-config/shared-files/ssl/my_server.crt
    server_certfile: /etc/ngcp-config/shared-files/ssl/certificate.pem
    server_certfile_cisco: /etc/ngcp-config/shared-files/ssl/certificate_cisco.pem
    server_keyfile: /etc/ngcp-config/shared-files/ssl/private_key.pem
    server_keyfile_cisco: /etc/ngcp-config/shared-files/ssl/private_key_cisco.pem
    ssl_enabled: yes
    ssl_mac_check: no
  softphone:
    config_lockdown: '0'
    webauth: '0'

  • Apply and push the changes

ngcpcfg apply 'PBX device provisioning configuration'
ngcpcfg push all

Upload the required device items

To upload device models/firmwares/configurations/profiles for devices with ZTP support, you need to obtain credentials from the corresponding vendor or its local distributor in advance. These credentials are required to send information about your devices and their provisioning URLs to the corresponding ZTP/RPS systems.

The script ngcp-insert-pbx-devices will insert the specified items into the database. For example, to upload items for all supported Yealink devices for the default reseller, execute the script with the following parameters on your management node (standby on PRO; web01a/db01a on CARRIER):

ngcp-insert-pbx-devices --api-user youruser --api-pass yourpassword --yealink-user user --yealink-password password
Execute ngcp-insert-pbx-devices --help to find other useful parameters, e.g. --device-models, --resellers and others.

Preparing PBX Rewrite Rules

In a PBX environment, the dial-plans usually looks different than for normal SIP subscribers. PBX subscribers should be able to directly dial internal extensions (e.g. 100) instead of the full number to reach another PBX subscriber in the same PBX segment. Therefore, we need to define specific Rewrite Rules to make this work.

The PBX dial plans are different from country to country. In the Central European area, you can directly dial an extension (e.g. 100), and if you want to dial an international number like 0049 1 23456, you have to dial a break-out digit first (e.g. 0), so the number to be dialed is 0 0049 1 23456. Other countries are used to other break-out codes (e.g. 9), which then results in 9 0049 1 23456. If you dial a national number like 01 23456, then the number to actually be dialled is 9 01 23456.

Since all numbers must be normalized to E.164 format via inbound rewrite rules, the rules need to be set up accordingly.

As with normal SIP accounts, you can use variables like ${caller_cc} and ${caller_ac}. For PBX subscribers, there is an additional variable ${caller_cloud_pbx_base_cli}, which is the primary number of the administrative subscriber for a PBX customer. When you create this pilot subscriber, you can specify the primary number and a list of alias numbers. If the customer creates his own extensions by himself, he only has to provide the extension number, which will be appended to the primary number of the pilot subscriber, and which in turn forms the primary number of the extension subscriber. So if the pilot subscriber’s primary number is 49 1 23456, and he creates a new extension subscriber with extension 100, the primary number of the extension will be 49 1 23456100. If another extension of this customer dials 100, you can prefix that with ${caller_cloud_pbx_base_cli}, so the 100 gets normalized to 49 1 23456100 and the correct extension subscriber can be matched. You will learn more about number assignment for PBX subscribers in the following sections, when the creation of them is shown.

Let’s assume that the break-out code for the example customers created below is 0, so we have to create a Rewrite Rule Set with the following rules.

Inbound Rewrite Rules for Caller

PBX devices usually send their SIP URI (e.g. myuser@mydomain.org) as initiating CLI, so nothing special is to be done here. If you have PBX devices which only send their extension number (e.g. 100) as CLI, you need to prefix that with the ${caller_cloud_pbx_base_cli} variable, like this:

  • Match Pattern: ^([1-9][0-9]+)$

  • Replacement Pattern: ${caller_cloud_pbx_base_cli}\1

  • Description: extension to e164

  • Direction: Inbound

  • Field: Caller

Inbound Rewrite Rule for Caller
Figure 1. Inbound Rewrite Rule for Caller

Inbound Rewrite Rules for Callee

These rules are the most important ones, as they define which number formats the PBX subscribers can dial. For the break-out code of 0, the following rules are necessary e.g. for German dialplans to allow pbx internal extension dialing, local area calls without area codes, national calls with area code, and international calls with country codes.

PBX internal extension dialin

  • Match Pattern: ^([1-9][0-9]+)$

  • Replacement Pattern: ${caller_cloud_pbx_base_cli}\1

  • Description: extension to e164

  • Direction: Inbound

  • Field: Callee

Local dialing without area code (use break-out code 0)

  • Match Pattern: ^0([1-9][0-9]+)$

  • Replacement Pattern: ${caller_cc}${caller_ac}\1

  • Description: local to e164

  • Direction: Inbound

  • Field: Callee

National dialing (use break-out code 0 and prefix area code by 0)

  • Match Pattern: ^00([1-9][0-9]+)$

  • Replacement Pattern: ${caller_cc}\1

  • Description: national to e164

  • Direction: Inbound

  • Field: Callee

International dialing (use break-out code 0 and prefix country code by 00)

  • Match Pattern: ^000([1-9][0-9]+)$

  • Replacement Pattern: \1

  • Description: international to e164

  • Direction: Inbound

  • Field: Callee

Inbound Rewrite Rule for Callee
Figure 2. Inbound Rewrite Rule for Callee

Outbound Rewrite Rules for Caller

When a call goes to a PBX subscriber, it needs to be normalized in a way that it’s call-back-able, which means that it needs to have the break-out code prefixed. We create a rule to show the calling number in international format including the break-out code. For PBX-internal calls, the most common setting is to show the short extension of the caller and caller name that is provisioned to a PBX subscriber (in order to do that set domain preferences outbound_from_display and outbound_from_user accordingly, so you don’t have to worry about that in rewrite rules).

Adding a break-out code (use break-out code 0 and prefix country code by 00)

  • Match Pattern: ^([1-9][0-9]+)$

  • Replacement Pattern: 000\1

  • Description: e164 to full international

  • Direction: Outbound

  • Field: Caller

Outbound Rewrite Rule for Caller
Figure 3. Outbound Rewrite Rule for Caller

Create a new Rewrite Rule Set for each dial plan you’d like to support. You can later assign it to customer domains and even to subscribers, if a specific subscriber of a PBX customer would like to have his own dial plan.

Creating Customers and Pilot Subscribers

As with a normal SIP Account, you have to create a Customer contract per customer, and one Subscriber, which the customer can use to log into the web interface and manage his PBX environment.

Creating a PBX Customer

Go to Settings→Customers and click Create Customer. We need a Contact for the customer, so press Create Contact.

Create PBX Customer Part 1
Figure 4. Create PBX Customer Part 1

Fill in the desired fields (you need to provide at least the Email Address) and press Save.

Create PBX Customer Contact
Figure 5. Create PBX Customer Contact

The new Contact will be automatically selected now. Also select a Billing Profile you want to use for this customer. If you don’t have one defined yet, press Create Billing Profile, otherwise select the one you want to use.

Create PBX Customer Part 2
Figure 6. Create PBX Customer Part 2

Next, you need to select the Product for the PBX customer. Since it’s going to be a PBX customer, select the product Cloud PBX Account.

Since PBX customers are supposed to manage their subscribers by themselves, they are able to create them via the web interface. To set an upper limit of subscribers a customer can create, define the value in the Max Subscribers field.

As you will see later, both PBX subscribers and PBX groups are normal subscribers, so the value defined here limits the overall amount of subscribers and groups. A customer can create an unlimited amount of subscribers if you leave this field empty.

Press Save to create the customer.

Create PBX Customer Part 3
Figure 7. Create PBX Customer Part 3

Creating a PBX Pilot Subscriber

Once the customer is created, you need to create at least one Subscriber for the customer, so he can log into the web interface and manage the rest by himself.

Click the Details button on the newly created customer to enter the detailed view.

Go to Customer Details
Figure 8. Go to Customer Details

To create the subscriber, open the Subscribers row and click Create Subscriber.

Go to Create Subscriber
Figure 9. Go to Create Subscriber

For your pilot subscriber, you need a SIP domain, a pilot number (the main number of the customer PBX), the web credentials for the customer to log into the web interfaces, and the SIP credentials to authenticate via a SIP device.

In a PBX environment, customers can create their own subscribers. As a consequence, each PBX customer should have its own SIP domain, in order to not collide with subscribers created by other customers. This is important because two customers are highly likely to create a subscriber (or group, which is also only a subscriber) called office. If they are in the same SIP domain, they’d both have the SIP URI office@pbx.example.org, which is not allowed, and the an end customer will probably not understand why office@pbx.example.org is already taken, because he (for obvious reasons, as it belongs to a different customer) will not see this subscriber in his subscribers list.
To handle one domain per customer, you should create a wild-card entry into your DNS server like \*.pbx.example.org, which points to the IP address of pbx.example.org, so you can define SIP domains like customer1.pbx.example.org or customer2.pbx.example.org without having to create a new DNS entry for each of them. For proper secure access to the web interface and to the SIP and XMPP services, you should also obtain a SSL wild-card certificate for *.pbx.example.org to avoid certification warnings on customers' web browsers and SIP/XMPP clients.

So to create a new domain for the customer, click Create Domain.

Go to Create Customer Domain
Figure 10. Go to Create Customer Domain

Specify the domain you want to create, and select the PBX Rewrite Rule Set which you created in Preparing PBX Rewrite Rules, then click Save.

Create Customer Domain
Figure 11. Create Customer Domain

Finish the subscriber creation by providing an E.164 number, which is going to be the base number for all other subscribers within this customer, the web username and password for the pilot subscriber to log into the web interface, and the sip username and password for a SIP device to connect to the PBX.

The parameters are as follows:

  • Domain: The domain in which to create the pilot subscriber. Each customer should get his own domain as described above to not collide with SIP usernames between customers.

  • E.164 Number: The primary number of the PBX. Calls to this number are routed to the pilot subscriber, and each subsequent subscriber created for this customer will use this number as its base number, suffixed by an individual extension. You can later assign alias numbers also for DID support.

  • Display Name: This field is used on phones to identify subscribers by their real names instead of their number or extension. On outbound calls, the display name is signalled in the Display-Field of the From header, and it’s used as a name in the XMPP contact lists.

  • Web Username: The username for the subscriber to log into the customer self-care web interface. This is optional, if you don’t want a subscriber to have access to the web interface.

  • Web Password: The password for the subscriber to log into the customer self-care web interface.

  • SIP Username: The username for the subscriber to authenticate on the SIP and XMPP service. It is automatically used for devices, which are auto-provisioned via the Device Management, or can be used manually by subscribers to sign into the SIP and XMPP service with any arbitrary clients.

  • SIP Password: The password for the subscriber to authenticate on the SIP and XMPP service.

Create Pilot Subscriber Part 1
Figure 12. Create Pilot Subscriber Part 1
Create Pilot Subscriber Part 2
Figure 13. Create Pilot Subscriber Part 2

Once the subscriber is created, he can log into the customer self-care interface at https://<your-ip>/ and manage his PBX, like creating other users and groups, assigning Devices to subscribers and configure the Auto Attendant and more.

As an administrator, you can also do this for the customer, and we will walk through the typical steps as an administrator to configure the different features.

Go to the Customer Details of the PBX customer you want to configure, e.g. by navigating to Settings→Customers and clicking the Details button of the customer you want to configure.

Creating Regular PBX Subscribers

Since we already created a pilot subscriber, more settings now appear on the Customer Details view. The sections we are interested in for now are the Subscribers and PBX Groups sections.

Subscribers and PBX Groups
Figure 14. Subscribers and PBX Groups

To create another subscriber for the customer PBX, open the Subscribers row and click Create Subscriber.

Create a Subscriber Extension
Figure 15. Create a Subscriber Extension

When creating another subscriber in the PBX after having the pilot subscriber, some fields are different now, because the Domain and E.164 Number are already pre-defined at the pilot subscriber level.

What you need to define for a new subscriber is the Group the subscriber is supposed to be in. We don’t have a group yet, so create one by clicking Create Group.

A PBX Group has four settings:

  • Name: The name of the group. This is used to identify a group when assigning it to subscribers on one hand, and also subscribers are pushed as server side contact lists to XMPP clients, where they are logically placed into their corresponding groups.

  • Extension: The extension of the group, which is appended to the primary number of the pilot subscriber, so you can actually call the group from the outside. If our pilot subscriber number is 43 1 9999 and the extension is 100, you can reach the group from the outside by dialing 43 1 9999 100. Since PBX Groups are actually normal subscribers in the system, you can assign Alias Numbers to it for DID later, e.g. 43 1 9998.

  • Hunting Policy: If you call a group, then all members in this group are ringing based on the policy you choose. Serial Ringing causes each of the subscribers to be tried one after another, until one of them picks up or all subscribers are tried. Parallel Ringing causes all subscribers in the group to be tried in parallel. Note that a subscriber can have a call-forward configured to some external number (e.g. his mobile phone), which will work as well.

  • Hunting Timeout: This value defines for how long to ring each member of a group.

From mr11.0.1, Serial Hunting Timeout becomes Hunting Timeout and defines the ringing timeout of each member whatever is the group policy.

We will only fill in the Name and Extension for now, as the hunting policy can be changed later if needed. Click Save to create the group.

Create a PBX Group
Figure 16. Create a PBX Group

Once the group is created and selected, fill out the rest of the form as needed. Instead of the E.164 Number, you can now only choose the Extension, which is appended to the primary number of the pilot subscriber and is then used as primary number for this particular subscribers. Again, if your pilot number is 43 1 9999 and you choose extension 101 here, the number of this subscriber is going to be 43 1 9999 101. Also, you can again later assign more alias numbers (e.g. 43 1 9997) to this subscriber for DID.

The rest of the fields is as usual, with Display Name defining the real name of the user, Web Username and Web Password allowing the subscriber to log into the customer self-care interface, and the SIP Username and SIP Password to allow signing into the SIP and XMPP services.

Finish PBX Subscriber Creation Part 1
Figure 17. Finish PBX Subscriber Creation Part 1

Click Save to create the subscriber.

Finish PBX Subscriber Creation Part 2
Figure 18. Finish PBX Subscriber Creation Part 2

Repeat the steps to create all the subscribers and groups as needed. An example of a small company configuration in terms of subscribers and groups might look like this:

Example of Subscribers List
Figure 19. Example of Subscribers List
The subscribers can be reached via 3 different ways. First, you can call them by their SIP URIs (e.g. by dialing frank.fowler@customer1.pbx.example.org) from both inside and outside the PBX. Second, you can dial by the full number (e.g. 43 1 9999 201; depending on your rewrite rules, you might need to add a leading \+ or 00 or leave out the country code when dialing from the outside, and adding a 0 as break-out digit when dialing from the inside) from both inside and outside the PBX. Third, you can dial the extension (e.g. 201) from inside the PBX. If the subscriber also has an alias number assigned, you can dial that number also, according to your dial-plan in the rewrite rules.

Device/Aliases (how to register a phone on an alias)

Subscribers belonging to CloudPBX customers can create a special type of alias numbers called Device/Alias. Device/Alias differs in two important things compared to standard aliases:

  • A device can register directly on a Device/Alias number. To do that configure the Device/Alias number on the authentication username of the device instead of using the sip username defined during the creation of the subscriber. The password to use is instead still the same.

  • Devices registered directly on the alias number can make calls as devices registered using the subscribers’ sip username. Incoming calls, instead, behave differently:

    • Incoming calls directed to the SIP Uri, to the full number, to the extension or to 'standard aliases' will let ring ONLY devices registered using the subscriber’s sip username.

    • Incoming calls directed to Device/Aliases will let ring ONLY devices registered on that particular Device/Alias.

How to create a Device/Alias

To create a Device/Alias proceed as for the creation of a standard alias but flag the Is Device ID option shown just under the Alias Number definition.

Device/Alias Creation
Figure 20. Device/Alias Creation

To easily distinguish which is the type of alias associated to a subscriber, Device/Alias are reported with a handset logo just beside the number in the subscriber’s master data.

Show Device/Alias Master Data
Figure 21. Show Device/Alias Master Data
Internal calls to Device/Aliases won’t work in combination with Extended matching inbound routing user preference.

lookup_all_registrations preference

The lookup_all_registrations subscriber’s preference allows to modify the incoming call behaviour described above. In particular, if the preference is flagged the behaviour is modified as following:

  • Incoming calls directed to the SIP Uri, to the full number, to the extension or to 'standard aliases' will let ring BOTH devices registered using the subscriber’s sip username and devices registered on all the Device/Aliases.

  • Incoming calls directed to Device/Aliases will continuous let ring ONLY devices registered on that particular Device/Alias.

Assigning Subscribers to a Device

You can register any SIP phone with the system using a SIP subscriber credentials. However, the platform supports PBX Device Provisioning of certain vendors and models, as described in PBX Device Provisioning.

To configure a physical device, expand the PBX Devices section in the Customer Details page and click Create Device.

Set up three general parameters for the new device, which are:

  • Device Profile: The actual device profile you want to use. This has been pre-configured in the Device Management by the administrator or reseller, and the customer can choose from the list of profiles (which is a combination of an actual device plus its corresponding configuration).

  • MAC Address/Identifier: The MAC address of the phone to be added. The information can usually either be found on the back of the phone, or in the phone menu itself.

  • Station Name: Since you can (depending on the actual device) configure more lines on a phone, you can give it a station name, like Reception or the name of the owner of the device.

In addition to that information, you can configure the lines (subscribers) you want to use on which key, and the mode of operation (e.g. if it’s a normal private phone line, or if you want to monitor another subscriber using BLF, or if you want it to act as shared line using SLA).

For example, a Cisco SPA504G has 4 keys you can use for private and shared lines as well as BLF on the phone itself, and in our example we have an Attendant Console attached to it as well, so you have 32 more keys for BLF.

The settings per key are as follows:

  • Subscriber: The subscriber to use (for private/shared lines) or to monitor (for BLF).

  • Line/Key: The key where to configure this subscriber to.

  • Line/Key Type: The mode of operation for this key, with the following options (depending on which options are enabled in the Device Model configuration for this device:

    • Private Line: Use the subscriber as a regular SIP phone line. This means that the phone will register the subscriber, and you can place and receive phone calls with/for this subscriber.

    • Shared Line: The subscriber is also registered on the system and you can place and receive calls. If another phone has the same subscriber also configured as shared line, both phones will ring on incoming calls, and you can pick the call up on either of them. You cannot place a call with this subscriber though if the line is already in use by another subscriber. However, you can "steal" a running call by pressing the key where the shared line is configured to barge into a running call. The other party (the other phone where the shared line is configured too) will then be removed from the call (but can steal the call back the same way).

    • BLF Key: The Busy Lamp Field monitors the call state of another subscriber and provides three different functionalities, depending on the actual state:

      • Speed Dial: If the monitored subscriber is on-hook, the user can press the button and directly call the monitored subscriber.

      • Call Pickup: If the monitored subscriber is ringing, the user can press the button to pick up the call on his own phone.

      • State Indication: It the monitored subscriber is on the phone, the key is indicating that the monitored subscriber is currently busy.

    • Speeddial Key: The key allows to call a predefined number.

    • Forward Key: The key allows to redirect and incoming call to a predefined number.

    • Transfer Key: The key allows to blind transfer and active call to a predefined number.

In our example, we will configure a private line on the first key, and the BLF for another subscriber on the second key.

Configuring a PBX Device
Figure 22. Configuring a PBX Device

Once the PBX device is saved, you will see it in the list of PBX Devices.

Initial provisioning of a PBX Device

Depending on a manufacturer and the model, there are two ways of provisioning a device:

  • (legacy) putting the provisioning URL directly into the device via a web browser (this option is used e.g. for Cisco devices);

  • (recommended) using the device’s Zero Touch Provisioning (ZTP) feature. For Yealink it is called Redirection and Provisioning Service (RPS). Also available are Snom redirection and provisioning service (SRAPS) and Easy Deployment Server (EDS) from ALE.

Direct device provisioning

Since a stock device obtained from an arbitrary distributor doesn’t know anything about your system, it can’t fetch its configuration from there. For that to work, you need to push the URL of where the phone can get the configuration to the phone once.

In order to do so, click the Sync Device button on the device you want to configure for the very first time.

Go to Sync Device
Figure 23. Go to Sync Device
As you will see in the next step, you need the actual IP address of the phone to push the provisioning URL onto it. That implies that you need access to the phone to get the IP, and that your browser is in the same network as the phone in order to be able to connect to it, in case the phone is behind NAT.

Enter the IP Address of the phone (on Cisco SPAs, press Settings 9, where Settings is the paper sheet symbol, and note down the Current IP setting), then click Push Provisioning URL.

Sync Device
Figure 24. Sync Device

You will be redirected directly to the phone, and the Provisioning URL is automatically set. If everything goes right, you will see a confirmation page from the phone that it’s going to reboot.

Device Sync Confirmation from Phone
Figure 25. Device Sync Confirmation from Phone

You can close the browser window/tab and proceed to sync the next subscriber.

You only have to do this step once per phone to tell it the actual provisioning URL, where it can fetch the configuration from. From there, it will regularly sync with the server automatically to check for configuration changes and apply them automatically.

Provisioning a device using ZTP/RPS/SRAPS/EDS

All ALE, Polycom, Panasonic, Snom, Grandstream and Yealink phones supported by Sipwise C5 can be provisioned using ZTP/RPS/SRAPS/EDS service without physically accessing the devices. You only need to input MAC addresses of corresponding devices and associate them with subscribers. Sipwise C5 will then immediately supply this information to the remote system of the corresponding device vendor. When a subscriber unpacks the phone and connects it to the Internet for the first time, the phone will contact the manufacturer’s service and get its provisioning URL to Sipwise C5. Then, the phone downloads all required items from Sipwise C5 and automatically configures itself. Immediately after that, the subscriber can make the first call.

To prepare a PBX device for zero-touch provisioning, follow these steps:

  • Go to the PBX Devices section of the corresponding customer and click Create PBX Device.

  • Specify the device and its SIP lines parameters:

    • Select the required device model

    • Input the device MAC address

    • Specify the name of this line for your convenience

    • Select a subscriber from the list for the corresponding SIP line. Some devices support multiple lines and you can provision all of them at once.

    • Select the line type: private, shared, BLF, speeddial, forwardor transfer.

Create a PBX device
Figure 26. Create a PBX device

  • Click Save. You will see the device in the list of customer’s PBX devices.

Created a PBX device
Figure 27. Created a new PBX device
If you have already provisioned a specific device on another platform or for another reseller, then you might need to delete that MAC address manually from the ZTP/RPS service (it is device vendor specific).

When the PBX device provisions itself, it will become registered with your SIP proxy server. From then, it will be listed in the subscriber’s Registered Devices page.

Registered devices
Figure 28. Registered devices

If you need to troubleshoot the provisioning process, the following logs would help you:

  • /var/log/ngcp/nginx (e.g. SSL errors are collected here: autoprov_bootstrap_error.log and autoprov_error.log)

  • /var/log/ngcp/panel-debug.log (general provisioning logs)

In case you would like to edit a device model, firmware, configuration or profile, refer to Adjusting the PBX Devices Configuration

Configuring Sound Sets for the Customer PBX

In the Customer Details view, there is a row Sound Sets, where the customer can define his own sound sets for Auto Attendant, Music on Hold and the Office Hours Announcement.

To create a new sound set, open the Sound Sets row and click Create Sound Set.

If you do this as administrator or reseller, the Reseller and/or Customer is pre-selected, so keep it as is. If you do this as customer, you don’t see any Reseller or Customer fields.

So the important settings are:

  • Name: The name of the sound set as it will appear in the Subscriber Preferences, where you can assign the sound set to a subscriber.

  • Description: A more detailed description of the sound set.

  • Expose to customer: It doesn’t have any influence on the Contract Sound Sets.

  • Default for Subscribers: If this setting is enabled, then the sound set is automatically assigned to all already existing subscribers which do NOT have a sound set assigned yet, and also for all newly created subscribers.

  • Parent: Select if this sound set has to inherit the announcements from another sound set. This allows to upload in the new sound set only the annoucements that are different from the parent, saving disk spece.

Fill in the settings and click Save.

Create Customer Sound Set
Figure 29. Create Customer Sound Set

To upload files to your Sound Set, click the Files button for the Sound Set.

Uploading a Music-on-Hold File

Open the music_on_hold row and click Upload on the music_on_hold entry. 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 only once. Click Save to upload the file.

Upload MoH Sound File
Figure 30. Upload MoH Sound File

Auto-Attendant Function

The Auto-Attendant is a built-in IVR feature that is available to Cloud PBX subscribers. It provides an automatic voice menu that enables the caller to select from a number of destinations, which could be other PBX subscribers or groups.

Another typical use case for the Auto-Attendant function is when the customer would like to have an "office assistant" that automatically takes incoming calls and routes them to the desired extension (i.e. to a subscriber).

The Auto-Attendant offers 2 ways of selecting the final call destination:

  • option selection: selecting one of the pre-configured destinations by pressing a single digit (0-9)

  • extension dialing: entering an arbitrary PBX extension number directly

Enabling the Auto-Attendant

The Auto-Attendant feature can be activated for any subscriber in the Customer PBX individually. There are three steps involved:

  1. You have to prepare a Sound Set to have Auto-Attendant sound files.

  2. You have to configure the destinations for the various options you provide (e.g. pressing 1 should go to the marketing subscriber, 2 to development and 3 to some external number).

  3. You have to set a Call Forward to the Auto-Attendant.

To do so, go to Customer Details and in the Subscribers section, click the Preferences button of the subscriber, where the Auto-Attendant should be set.

Preparing the Sound Set

Create a Sound Set and upload the Sound Files for it as described below. Afterwards in the Subscriber Preferences view, set the Contract_Sound_Set preference to the Sound Set to be used. To do so, click Edit on the Contract_Sound_Set preference and assign the set to be used.

Uploading Auto-Attendant Sound Files

When configuring a Call Forward to the Auto-Attendant, it will play the following files:

  • aa_welcome: This is the welcome message (the greeting) which is played when someone calls the Auto-Attendant.

  • each available pair of aa_X_for/aa_X_option: Each menu item in the Auto-Attendant consists of two parts. The for part, which plays something like Press One for, and the option part, which play something like Marketing. The Auto-Attendant only plays those menu options where both the for part and the option part is present, so if you only have 3 destinations you’d like to offer, and you want them to be on keys 1, 2 and 3, you have to upload files for aa_1_for, aa_1_option, aa_2_for, aa_2_option and aa_3_for and aa_3_option.

The sound files only define the general structure of what is being played to the caller. The actual destinations behind your options are configured separately in Configuring the Auto-Attendant Slots.

An example configuration could look like this:

Upload Auto-Attendant Options Sound Files
Figure 31. Upload Auto-Attendant Options Sound Files

In order to activate the extension dialing function within the Auto-Attendant, you have to upload the following prompt files:

  • aa_star_for, aa_star_option: the announcement "Press star for connecting to an extension" (or similar message, depending on customer’s needs)

  • aa_enter_extension: will instruct the caller to enter the phone number of the extension he wants to connect to

  • aa_invalid_extension: will be played when the phone number entered does not match any of the customer’s extensions

Upload Auto-Attendant Extension Dialing Sound Files
Figure 32. Upload Auto-Attendant Extension Dialing Sound Files

In order to enable the Auto-Attendant to play a prompt when the caller hasn’t selected any menu item within the timeout period, you have to upload a file to the "aa_timeout" prompt in the "pbx" section of the Sound Set.

Upload Auto-Attendant Timeout Sound File
Figure 33. Upload Auto-Attendant Timeout Sound File

Auto-Attendant Flowchart with Voice Prompts

The illustration below shows the sequence of voice prompts played when Auto-Attendant feature is activated and a caller listens the IVR menu.

Flowchart of Auto-Attendant
Figure 34. Flowchart of Auto-Attendant

Configuring the Auto-Attendant Slots

In the Auto-Attendant Slots section, click the Edit Slots button to configure the destination options. There are up to 10 available slots to configure, from keys 0 to 9.

Be aware that only configured slots will be prompted in the Auto-Attendant menu.

Click Add another Slot to add a destination option, select the Key the destination should be assigned to, and enter a Destination. The destination can be a subscriber username (e.g. marketing), a full SIP URI (e.g. sip:michelle.miller@customer1.pbx.example.org or any external SIP URI) or a number or extension (e.g. 491234567 or 101).

Repeat the step for every option you want to add, then press Save.

Define the Auto-Attendant Slots
Figure 35. Define the Auto-Attendant Slots
You have a possibility to define the 'default' slot for cases when a caller doesn’t pick out anything. Other than that, you can additionally set a sound file for this action.

Activating the Auto-Attendant

Once the Sound Set and the Slots are configured, activate the Auto-Attendant by setting a Call Forward to Auto-Attendant.

To do so, open the Call Forwards section in the Subscriber Preferences view and press Edit on the Call Forward type (e.g. Call Forward Unconditional if you want to redirect callers unconditionally to the Auto-Attendant).

Select Auto-Attendant and click Save to activate the Auto-Attendant.

Set a Call Forward to Auto-Attendant
Figure 36. Set a Call Forward to Auto-Attendant
As with any other Call Forward, you can define more complex forwarding rules in the Advanced View to only forward the call to the Auto-Attendant during specific time periods, or as a fallback if no one picks up the office number.

Handling input errors in the Auto-Attendant

If the caller enters an invalid menu item (0-9), i.e. a choice that hasn’t got a valid destination or is not configured at all, the Auto-Attendant application will repeat the available choices again. The same happens when the caller enters an invalid extension number after selecting "star". After trying to select the wrong destination 3 times, the Auto-Attendant will terminate the call.

If the caller doesn’t select any menu item for a pre-configured timeout, the Auto-Attendant will repeat the menu items again. When the caller doesn’t select any menu item for 3 times, the Auto-Attendant will do the following:

  • terminate the call immediately if the "aa_timeout" prompt is not defined in the Sound Set

  • play the "aa_timeout" prompt before terminating the call, if that prompt is defined in the Sound Set, and then terminate the call

Cloud PBX Groups with Busy Members

A huntgroup (HG) or a PBX Group is a Cloud PBX feature that distributes the calls between members of the group according to the configured hunt policy and timeout. The PBX group belongs to a customer and one Cloud PBX subscriber can be a member of one or more of the huntgroups of the customer. Call Waiting is a CPE (phone) feature that allows you to take another call while you’re already on the phone.

Multiple incoming calls to the huntgroup may result in multiple calls delivered to the same subscriber if the Call Waiting feature is enabled on his phone, regardless whether the huntgroup members are busy at this time. Hence, busy subscribers may get a second incoming call. It may be an expected behavior (since one subscriber may have multiple devices and/or clients that all ring in parallel) or not, depending on the setup.

Therefore, Sipwise C5 Cloud PBX module offers busy huntgroup member mode feature to check the busy status of individual huntgroup members before routing a call to them. This will leave subscribers on active phone calls undisturbed by calls to huntgroup.

From 10.4, busy hunt group member mode is the new name for what used to be previously named Ignore Busy Hunt Group Members. Not only the name is changed, but the configuration is also moved from the main configuration file: /etc/ngcp-config/config.yml to the domain preferences or to the subscriber preferences as described below. This evolution offers more flexibility in the configuration allowing to change the behavior on subscriber basis instead of system wide. The 10.4 upgrade procedure automatically migrates the config.yml setting to all your domains preferences.

The configuration of the busy huntgroup member mode feature is done via the busy_hg_member_mode parameter available at domain or subscriber preferences:

busy hunt group member mode domain
Figure 37. Busy huntgroup member mode configuration for domain
busy hunt group member mode subscriber
Figure 38. Busy huntgroup member mode configuration for subscriber

The busy_hg_member_mode preference may take the following values:

  • ring (default value): A hunt group member is alerted of all incoming calls to his groups, regardless of his busy state.

  • skip_totaluser: A hunt group member is not alerted of incoming calls to his groups because he is busy for the following reasons (call distribution continues with other available huntgroup members):

    • he is involved in one or more incoming or outgoing calls in alerting or active phase

    • an incoming call intended for him has been forwarded to another destination an this call is in alerting or active phase.

  • skip_activeuser: A hunt group member is not alerted of incoming calls to his groups because he is involved in one or more incoming or outgoing calls in alerting or active phase but NOT busy for the calls that have been forwarded (call distribution continues with other available huntgroup members).

  • use domain default (subscriber prefs. only): use the setting of the domain preference busy_hg_member_mode.

This feature does not present an extended server-side Call Waiting functionality. It concerns only the huntgroups' behavior. Hence subscriber would still be able to receive multiple calls when called directly (not via huntgroup) with Call Waiting enabled on his phone.

As an example, if the busy_hg_member_mode preference is set to skip_totaluser, a huntgroup call will not be distributed to a subscriber in the following situations:

Use Case 1

Subscriber receives an incoming call. A second call is made to the HG. The subscriber should NOT receive this call via HG extension.

Use Case 2

Subscriber makes an outgoing call. A second call is made to the HG. The subscriber should NOT receive this call via HG extension.

Use Case 3

Subscriber with a call forward enable (CFU, CFB, CFNA, CFT) receives a call to his extension (not extension of HG) which is then forwarded. A second call is made to the HG. The subscriber should NOT receive the call via HG extension.

In order to prevent the forwarded calls from keeping the subscriber as "busy" for the purpose of this feature the platform administrator should set the domain or the subscriber preference busy_hg_member_mode to the value skip_activeuser:

While User Cases 1 an 2 will behave in the same way as described above, the change of behavior happens in Use Case 3:

Use Case 3

Subscriber with a call forward enabled (CFU, CFB, CFNA, CFT) receives a call to his extension (not extension of HG) which is then forwarded. A second call is made to the HG. The subscriber should receive the call as normal.

Configuring Call Queues

The Sipwise C5 platform offers call queueing feature for Cloud PBX subscribers. For any subscriber within the PBX, the Sipwise C5 system administrator or the subscriber themselves may activate the Call Queue.

If call queue activation has been done and the subscriber receives more than 1 call at a time, then the second and all further callers will be queued until the subscriber finishes their call with the first caller and is available.

Activating the Call Queue

The call queue configuration is available at the path: Subscribers → press the three dots → Preferences → Cloud PBX.

Following configuration parameters may be set for call queueing:

  • cloud_pbx_callqueue : shows the status of call queueing (enabled / disabled); by default it is disabled

  • max_queue_length : the length of call queue, i.e. the maximum number of callers in a queue; the default is 5

  • queue_wrap_up_time : the delay in seconds between the ending of the previous call and the connection of the next queued caller with the subscriber; the default is 10

Subscribers Preferences
Figure 39. Subscribers Preferences
Call Queue Preferences
Figure 40. Call Queue Preferences

Call Queue Voice Prompts

Queued callers first hear a greeting message then information about their position in the queue and finally a waiting music / signal.

Table 1. Call Queue Voice Prompts
Prompt handle Prompt content

queue_greeting

All lines are busy at the moment, you are being queued.

queue_prefix

You are currently number…​

queue_suffix

… in the queue, please hold the line.

queue_full

All lines are busy at the moment, please try again later.

queue_waiting_music

<waiting music>

Call Queue Flowchart with Voice Prompts

The following illustration shows which voice prompts are played to the caller when the call gets into a queue.

Flowchart of Call Queue
Figure 41. Flowchart of Call Queue

Device Auto-Provisioning Security

Server Certificate Authentication

Cisco SPA phones can connect to the provisioning interface of the PBX via HTTP and HTTPS. When performing secure provisioning over HTTPS, the phones validate the server certificate to check if its a legitimate Cisco provisioning server. To pass this check, the provisioning interface must provide a certificate signed by Cisco for that exact purpose.

The following steps describe how to obtain such a certificate.

First, a new SSL key needs to be generated:

$ openssl genrsa -out provisioning.key 2048
Generating RSA private key, 2048 bit long modulus
...+++
...............................................................+++
e is 65537 (0x10001)

Next, a certificate signing request needs to be generated as follows. Provide your company details.

The Common Name (e.g. server FQDN or YOUR name) field is crucial here. Provide an FQDN which the phones will later use via DNS to connect to the provisioning interface, for example pbx.example.org. Cisco does NOT support wild-card certificates.
Leave the password empty when asked for it (press Enter without entering anything). 
$ openssl req -new -key provisioning.key -out provisioning.csr
You are about to be asked to enter information that will be incorporated
into your certificate request.
What you are about to enter is what is called a Distinguished Name or a DN.
There are quite a few fields but you can leave some blank
For some fields there will be a default value,
If you enter '.', the field will be left blank.

Country Name (2 letter code) [AU]:AT
State or Province Name (full name) [Some-State]:Vienna
Locality Name (eg, city) []:Vienna
Organization Name (eg, company) [Internet Widgits Pty Ltd]:Sipwise GmbH
Organizational Unit Name (eg, section) []:Operations
Common Name (e.g. server FQDN or YOUR name) []:pbx.example.org
Email Address []:office@sipwise.com

Please enter the following 'extra' attributes
to be sent with your certificate request
A challenge password []:
An optional company name []:

Finally, compress the provisioning.csr file via ZIP and send it to our Cisco sales representative. If in doubt, you can try to send it directly to ciscosb-certadmin@cisco.com asking them to sign it.

Please submit only the CSR file. Do NOT submit the key file, as it contains your private key.
Ask for both the signed certificate AND a combinedca.crt which is needed to perform client authentication via SSL. Otherwise you cannot restrict access to Cisco SPAs only.

You will receive a signed CRT file, which Sipwise can use to configure the PBX provisioning interface.

Client Certificate Authentication

If a client connects via HTTPS, the server also checks for the client certificate in order to validate that the device requesting the configuration is indeed a legitimate Cisco phone, and not a fraudulent user with a browser trying to fetch user credentials.

Cisco Client Root Certificate can be obtained from Download Client Certificates website.

Device Bootstrap and Resync Workflows

The IP phones supported by the PBX need to initially be configured to fetch their configuration from the system. Since the phones have no initial information about the system and its provisioning URL, they need to be boot-strapped. Furthermore, changes for a specific device might have to be pushed to the device immediately instead of waiting for it to re-fetch the configuration automatically.

The following sections describe the work-flows how this is accomplished without having the customer directly accessing the phone.

ALE Device Bootstrap

Initial Bootstrapping

ALE provides a zero-touch provisioning mechanism in their firmware, which causes the factory-reset phones to connect to the ALE website to check if a custom provisioning URL is configured for the MAC address of the phone. If an association between the MAC and a provisioning URL is found, the web service redirects the phone to the provisioning URL, where the phone connects to in order to obtain the configuration file.

Initially bootstrap an ALE phone
Figure 42. Initially bootstrap an ALE phone

The CloudPBX module ensures that when an end customer creates an ALE device, the MAC address is automatically provisioned on the ALE web service via an API call, so the customer’s phone can use the correct provisioning URL to connect to the auto-provisioning server of the CloudPBX.

As a result, no customer interaction is required to bootstrap ALE phones, other than just creating the phone with the proper MAC on the CloudPBX web interface.

Updating ALE Firmware

For Myriad Devices:

NGCP provides version 2.13.01.000.1899 by default, but also offers versions 2.12.04.1729 and 2.11.01.1604. If another firmware version is needed, these can be downloaded at https://www.aledevice.com/site/download and manually uploaded to NGCP

If firmware older than 2.11.01.1604 is used, direct upgrades to the latest firmware can no longer be guaranteed. To prevent this, upgrade phones manually to version 2.11.01.1604 or newer
If firmware older than 2.13.01.000.1899 is used, position of accounts set in NGCP will no longer align with the phone display. To prevent this, upgrade phones to version 2.13.01.000.1899 or newer

For Halo Devices: NGCP provides version 2.12.05.000.1194 for devices H3G and H6 and version 2.10.00.0001078 for device H2P. If another firmware version is needed, these can be downloaded at https://www.aledevice.com/site/download and manually uploaded to NGCP

For Cloud Edition series devices: NGCP provides version 1.53.37.4117 for all Cloud Edition devices. If another firmware version is needed, these can be downloaded at https://www.aledevice.com/site/download and manually uploaded to NGCP

Factory Reset

For already provisioned phones, the end customer might need to perform a factory reset.

On Myriad, H3G and H6 phones, holding down the conference button for 10 seconds will give you the option to reset the device.

On H2P phone, holding down the "OK" button for 8 seconds will give you the option to reset the device

On Cloud Edition phones, following steps need to be done.

  • Start up the phone

  • When the boot up screen shows up, during step 1 press keys 1, 3, 7, and 9 at the same time

  • Input 46*46*253 and the phone should reset

The default keypad password is 0000. The WEB username for factory-reset phones is admin with password 123456.

See more details here: ALE FAQ.

Bootstrap URL

The default ALE bootstrap URI is: http://<ngcp.fqdn>:1445/device/autoprov/bootstrap/{mac} You can find the URI above on EDS WEB interface for newly provisionied ALE devices. The variable "{mac}" will expand to the device MAC address automatically on ALE device before connecting to NGCP. You can change the default "Bootstrap URI" on page "Edit Device Model". See more details in PBX bootstrap, firmwares and security.

We strongly recommended using a secure bootstrap config: https://<ngcp.fqdn>:1444/device/autoprov/config/{mac}

Cisco SPA Device Bootstrap

Initial Bootstrapping

Initially bootstrap a PBX device
Figure 43. Initially bootstrap a PBX device

Subsequent Device Resyncs

If one of the subscribers configured on a PBX device is registered via SIP, the system can trigger a re-sync of the phone directly via SIP without having the customer enter the IP of the phone again. This is accomplished by sending a special NOTIFY message to the subscriber:

NOTIFY sip:subscriber@domain SIP/2.0
To: <sip:subscriber@domain>
From: <sip:subscriber@domain>;tag=some-random-tag
Call-ID: some-random-call-id
CSeq: 1 NOTIFY
Subscription-State: active
Event: check-sync
Content-Length: 0

In order to prevent unauthorized re-syncs, the IP phone challenges the request with its own SIP credentials, so the NOTIFY is sent twice, once without authentication, and the second time with the subscriber’s own SIP credentials.

Resync a registered PBX device
Figure 44. Resync a registered PBX device

Panasonic Device Bootstrap

Initial Bootstrapping

to connect to a Panasonic web service at https://provisioning.e-connecting.net to check if a custom provisioning URL is configured for the MAC address of the phone. If an association between the MAC and a provisioning URL is found, the web service redirects the phone to the provisioning URL, where the phone connects to in order to obtain the configuration file. Panasonic provides a zero-touch provisioning mechanism in their firmware, which causes the factory-reset phones to connect to the Panasonic website to check if a custom provisioning URL is configured for the MAC address of the phone. If an association between the MAC and a provisioning URL is found, the web service redirects the phone to the provisioning URL, where the phone connects to in order to obtain the configuration file.

Initially bootstrap a Panasonic phone
Figure 45. Initially bootstrap a Panasonic phone

The CloudPBX module ensures that when an end customer creates a Panasonic device, the MAC address is automatically provisioned on the Panasonic web service via an API call, so the customer’s phone can use the correct provisioning URL to connect to the auto-provisioning server of the CloudPBX.

As a result, no customer interaction is required to bootstrap Panasonic phones, other than just creating the phone with the proper MAC on the CloudPBX web interface.

Factory Reset

For already provisioned phones, the end customer might need to perform a factory reset:

  • Press Settings or Setup

  • Enter #136

  • Select Factory Setting and press Enter

  • Select Yes and press Enter

  • Select Yes and press Enter

The default username for factory-reset phones is admin with password adminpass.

Subsequent Device Resyncs

The same procedure as with Cisco SPA phones applies, once a subscriber configured on the phone is registered.

SNOM Device Bootstrap

Initial Bootstrapping

SNOM provides a zero-touch provisioning mechanism in their firmware, which causes the factory-reset phones to connect to the SNOM website to check if a custom provisioning URL is configured for the MAC address of the phone. If an association between the MAC and a provisioning URL is found, the web service redirects the phone to the provisioning URL, where the phone connects to in order to obtain the configuration file.

Initially bootstrap a SNOM phone
Figure 46. Initially bootstrap a SNOM phone

The CloudPBX module ensures that when an end customer creates a SNOM device, the MAC address is automatically provisioned on the SNOM web service via an API call, so the customer’s phone can use the correct provisioning URL to connect to the auto-provisioning server of the CloudPBX.

As a result, no customer interaction is required to bootstrap SNOM phones, other than just creating the phone with the proper MAC on the CloudPBX web interface.

Linking SNOM Handsets with SNOM M900 Base Station

To add a handset to a base station and to assign a subscriber to the handset, open preferences of a subscriber and add the IPUI of the handset into the settings field 'gpp0' (the gpp number can be changed in device config if necessary).

IPUIs have to start with 0x (e.g. if IPUI is 123456789, set gpp0 equal to 0x123456789)
If a new IPUI is added, a base station config reload is necessary. It happens periodically on automated bases or base station reboot.

Updating SNOM Firmware

For D-Series Phones: It is recommended to use the SNOM Update Center URL to update the firmware of phones and base stations. SNOM firmware files are signed and the phones check the signatures of the files during provisioning. This makes sure only a proper SNOM firmware can be installed on the phones via HTTP. HTTPS transport might be unreliable on newly started devices due to wrong date/time. The firmware can be downloaded from NGCP as well. In the Device Configuration XML config, there is a commented line pointing to NGCP.

<firmware>[% config.bootstrap ? firmware.booturl : firmware.baseurl %]/[% config.mac #%]/from/0/latest/</firmware>

For M-Series Base Stations: M-Series base stations require the user to define the version and branch of the firmware to update to. By default, this version is set to V510B01. If a different firmware version is needed, it has to be manually changed in the Device Configuration XML config.

<fp_fwu_sw_version>510</fp_fwu_sw_version>­

<fp_fwu_branch_version>1</fp_fwu_branch_version>

Base stations with firmware below version V500B1 cannot directly upgrade to the newest firmware. Please double check vendor upgrade recommendations and limitations on the SNOM website.

For Handsets to use with M-Series Base Stations: Handsets require you to add the version, branch and type of device you want to update separately like this:

­<pp_fwu_sw_version type="M65">510</pp_fwu_sw_version>­

<pp_fwu_branch_version type="M65">1</pp_fwu_branch_version>

If a new handset is added to a base station, a reboot is required to apply the update settings
Handsets require the included charger to complete the firmware upgrade.

Additionally, handsets also require you to add the IPUI of the handset you want to update. This step can be done via NGCP. Go to the subscriber settings, search for setting gpp, use an unused gpp preference and add the IPUI in here. It is possible to use any general purpose field from subscriber preferences (gpp1, gpp2, …​) until it matches PBX Device Configuration for XML attribute "<subscr_dect_ipui>".

IPUIs have to start with 0x, for example 0x123456789

Acquiring the IP of SNOM Base Stations

To get the IP address of the base stations close to you, use a SNOM Handset, go to the applications menu and type *47*. All base stations should show up in a list view with their IP Address.

Adding Vertical Service Code Wrappers into D-Series Templates

The Vertical Service Code (VSC) Interface offers a list of codes which can be masked by using specific “wrappers” tags within SNOM D-Series devices. Some examples for Reminder, Call Forward Unconditional and Speed Dial features are provided as follows:

<functionKeys e="2">
<fkey idx="3" context="1" lp="on" default_text="Reminder" icon_type="kIconTypeFkeyClock" perm="">url http://192.168.91.254/sipwise/vcs_mb.xml#sub=*[@id="vcs_55"]&amp;var:sc_vcs_55_on=*55&amp;var:sc_vcs_55_default=0830</fkey>
<fkey idx="4" context="1" lp="on" default_text="CFU" icon_type="kIconTypeFkeyTransfer" perm="">url http://192.168.91.254/sipwise/vcs_mb.xml#sub=*[@id="vcs_72"]&amp;var:sc_vcs_72_on=*72&amp;var:sc_vcs_72_off=#72</fkey>
<fkey idx="5" context="1" lp="on" default_text="SpeedDial" icon_type="kIconTypeFkeySpeedDial" perm="">url http://192.168.91.254/sipwise/vcs_mb.xml#sub=*[@id="vcs_50"]&amp;var:sc_vcs_50_on=*50&amp;var:sc_vcs_50_default_slot=1</fkey>
</functionKeys>

[* TAGS default *]

On the example above, the XML file 'vcs_mb.xml' needs to be placed on an external HTTP Server, or needs to be provisioned into the phone.

Please, contact SNOM for further assistance, or check SNOM Service Hub (Keyword: VCS Sipwise) if needed.

Factory Reset

For already provisioned phones, the end customer might need to perform a factory reset:

  • Press **## (the phone starts to reboot)

  • Hold # during boot

  • Press 1 to choose the option Settings reset

The default keypad password is 0000. The WEB username for factory-reset phones is admin with password admin.

See more details on SNOM Wiki.

Bootstrap URL

The default SNOM bootstrap URI is: http://<ngcp.fqdn>:1445/device/autoprov/bootstrap/{mac} You can find the URI above on SRAPS WEB interface for newly provisioned SNOM device. The variable "{mac}" will expand to device MAC address automatically on SNOM device before connecting to NGCP. You can change the default "Bootstrap URI" on page "Edit Device Model". See more details in PBX bootstrap, firmwares and security.

We strongly recommended using a secure bootstrap config: https://<ngcp.fqdn>:1444/device/autoprov/config/{mac}

The bootstrap config should point to the proper firmware:

http://<ngcp.fqdn>:1445/device/autoprov/firmware/{mac}/from/{firmware_version}/next

The variable '{firmware_version}' is available for SNOM firmware version 1.10.47+.

For earlier SNOM firmwares it is recommended to build a custom firmware upgrade vector using:

http://<ngcp.fqdn>:1445/device/autoprov/firmware/{mac}/from/0/latest
OR
http://<ngcp.fqdn>:1445/device/autoprov/firmware/{mac}/from/0/next/<tag>

See more details in PBX bootstrap, firmwares and security.

Yealink Device Bootstrap

Initial Bootstrapping

Yealink provides a zero-touch provisioning mechanism in their firmware, which causes the factory-reset phones to connect to the Yealink web service to check if a custom provisioning URL is configured for the MAC address of the phone. If an association between the MAC and a provisioning URL is found, the web service redirects the phone to the provisioning URL, where the phone connects to in order to obtain the configuration file.

If both Cisco SPA and Yealink phones are used, an issue with the Cisco-signed server certificate configured on the provisioning port (1444 by default) of the CloudPBX provisioning server arises. Yealink phones by default only connect to trusted server certificates, and the Cisco CA certificate used to sign the server certificate is not trusted by Yealink. Therefore, a two-step approach is used to disable the trusted check via a plain insecure http port (1445 by default) first, where only device-generic config options are served. No user credentials are provided in this case, because no SSL client authentication can be performed. The generic configuration disables the trusted check, and at the same time changes the provisioning URL to the secure port, where the Yealink phone is now able to connect to.

Initially bootstrap a Yealink phone
Figure 47. Initially bootstrap a Yealink phone

The CloudPBX module ensures that when an end customer creates a Yealink device, the MAC address is automatically provisioned on the Yealink web service via an API call, so the customer’s phone can use the correct insecure bootstrap provisioning URL to connect to the auto-provisioning server of the CloudPBX for the generic configuration, which in turn provides the information on where to connect to for the secure, full configuration.

As a result, no customer interaction is required to bootstrap Yealink phones, other than just creating the phone with the proper MAC on the CloudPBX web interface.

Factory Enable Yealink Auto-Provisioning

Older Yealink firmware does not automatically connect to the Yealink auto-provisioning server on initial boot, so it needs to be enabled manually by the end customer.

Subsequent Device Resyncs

The same procedure as with Cisco SPA phones applies, once a subscriber configured on the phone is registered.

Audiocodes Mediant Device Bootstrap and Configuration

Initial Bootstrapping

An Audiocodes device provides a zero-touch provisioning mechanism in its firmware which causes a factory-reset device to connect to the URL built into the firmware. This URL points to Sipwise C5 provisioning server (in case of Sipwise C5 Carrier: web01 node) listening on TCP port 1444 for HTTPS sessions.

The prerequisites for the device provisioning are that the device has a routable IP address and can reach the IP address of Sipwise C5 provisioning interface.

The Audiocodes device should request the firmware file or CLI configuration file from Sipwise C5 platform. The firmware versions and CLI config versions are decoupled from each other; Sipwise C5 can not enforce specific version of the firmware on the device. Instead, it should be requested by the device itself. In other words, provisioning is a 'pull' and not a 'push' process.

Sipwise C5 expects the provisioning request from the Audiocodes device after SSL handshake and serves the requested file to the device if the device provides valid MAC address as the part of the URL. The MAC address is used to identify the device to Sipwise C5 platform. The firmware and CLI config files are provided at the following URLs:

  • the base URL to download firmwares: https://<NGCP_IP>:1444/device/autoprov/firmware/001122334455/from/0/latest

  • the base URL to download CLI config: https://<NGCP_IP>:1444/device/autoprov/config/001122334455

where 001122334455 should be replaced with the actual device’s MAC address and <NGCP_IP> with IP address of Sipwise C5 provisioning interface.

Initially bootstrap a Mediant gateway
Figure 48. Initially bootstrap a Mediant gateway

Device management basics

The list of device models, firmware and configurations are global to a reseller and are available to the end customer. This data is initially provided by the Sipwise as bulk upload of all supported phone models. The firmware and settings are stored in the database on the DB node pair(s). The Sipwise C5 leverages the Cloud PBX module with its template system to generate the configurations and firmware files from the database on the fly. Please refer to the following chapters in Sipwise C5 handbook for the current information on how to perform device management:

Parameterizing the Device Configuration Template

The device-specific parameters are filled in by the system individually when a physical device fetches its configuration file. Parameters from Sipwise C5 panel:

  • username: Subscriber Details → Master Data → SIP Username

  • password: Subscriber Details → Master Data → SIP Password

  • domain: Subscriber Details → Master Data → Domain

  • extension: Subscriber Details → Master Data → Extension

  • area code: Subscriber Preferences → Number Manipulations → ac

  • country code: Subscriber Preferences → Number Manipulations → cc

The produced CLI config file has the following structure:

  1. SIP account credentials:

    "sip-definition account 0"

    • user-name [username]

    • password [password]

    • host-name [domain]

    • register reg

    • contact-user "[country code][area code][extension]"

  2. IP Groups:

    "voip-network ip-group 1" and "voip-network ip-group 2"

    • sip-group-name [domain]

  3. Proxy and registration settings:

    "sip-definition proxy-and-registration"

    • set gw-name [domain]

  4. Manipulations:

    • manipulation-name "from trunk domain":

      "sbc manipulations message-manipulations 3"

      • action-value "[% line.domain %]"

    • manipulation-name "clip no screening":

      "sbc manipulations message-manipulations 8"

      • action-value "\'<sip:+[country code][area code][extension]@' + param.ipg.dst.host + \'>'"

Specific CLI parameters are:

  • [IPPBX_Hostname]

  • [IPPBX_server_IP]

which are used at the following configuration parameters:

  • Proxy settings:

    "voip-network proxy-ip 1"

    • proxy-address [IPPBX_Hostname]

  • Manipulations:

    "sbc manipulations message-manipulations 1"

    • action-value [IPPBX_Hostname]

PBX bootstrap, firmwares and security

In theory, it is enough to provide the device with one config file which contains all parameters inside (including SIP credentials and a link to the new firmware). However, the connection from device to the server has to be secure due to the sensitive data inside the config file. A SSL tunnel must be used and the server must authenticate the phone using the client SSL certificate.

Due to real-world logistic constraints, the received device may potentially have an outdated firmware, which could render it classified as an "insecure client" when connecting to the recently updated SSL server. Instances of this scenario include mismatches in TLS versions, SSL cipher suites, and elliptic curves, among other factors.

The only option to connect such a device to the server is to use more modern firmware and the only way to receive it is to download it from server. Some vendors provide initial/constant firmware upgrade as a part of their zero-touch provisioning platforms while it is not always possible to use it.

The NGCP platform also provides bootstrap functionality for such old devices/firmwares using 'bootstrap' concept. Please note the difference:

  • config: https://<ngcp.server>:1444/device/autoprov/config/<mac>

  • bootstrap: http://<ngcp.server>:1445/device/autoprov/bootstrap/<mac>

The first SSL-based link provides a valid device config with all details, while the second/insecure link only provides a minimal config to update the firmware. Modern firmwares are usually SHA256 signed and can be securely re-distributed using insecure channels.

By default, the bootstrap URI is http://...:1445/device/autoprov/bootstrap/<mac> and can be changed on page "Edit Device Model" (field 'Bootstrap URI').

The bootstrap URI contains vendor specific variables, e.g. lower cased "{mac}" for SNOM and upper cased {MAC} for Panasonic. Please check the list of supported variables on the device vendor Website. Keep in mind, some variables might not be supported by very old firmware.

NGCP provides three access points by default: "config" (port 1444), "bootstrap" (port 1445) and "cisco" (port 1447). The last one is necessary due to the specific SSL setup for Cisco devices, see Server Certificate Authentication. Using "bootstrap"/"cisco" entrance is not mandatory and only necessary to bootstrap devices with very old firmware.

NGCP provides a flexible way to build a chain of bootstraps/configs to achieve the desired upgrade path. Every config/bootstrap contains the link on the next config/bootstrap. A Device can (and often should) upgrade several firmware versions to achieve the latest firmware version. Some vendors do not support upgrading from old, ancient firmware to the latest firmware directly. The specific upgrade path should be built.

NGCP supports various URIs to fetch any firmware using version and/or tag. For example, you can request some specific firmware version using:

https://<ngcp.fqdn>:1444/device/autoprov/firmware/<mac>/version/{firmware_version}
https://<ngcp.fqdn>:1447/device/autoprov/firmware/<mac>/version/{firmware_version}
http://<ngcp.fqdn>:1445/device/autoprov/firmware/<mac>/version/{firmware_version}

All methods are available for any "config/bootstrap/cisco" entrances. Also firmware can be requested using "Firmware tag" (NGCP searches versions first and repeats the search using the tag if nothing found by the version):

https://<ngcp.fqdn>:1444/device/autoprov/firmware/<mac>/version/{firmware_tag}
https://<ngcp.fqdn>:1447/device/autoprov/firmware/<mac>/version/{firmware_tag}
http://<ngcp.fqdn>:1445/device/autoprov/firmware/<mac>/version/{firmware_tag}

It is also possible to request the "latest" and the "next" firmware from your current possition

https://<ngcp.fqdn>:1444/device/autoprov/firmware/<mac>/from/<firmware_version>/latest
https://<ngcp.fqdn>:1444/device/autoprov/firmware/<mac>/from/<firmware_version>/next
https://<ngcp.fqdn>:1444/device/autoprov/firmware/<mac>/from/<firmware_version>/latest/<tag>
https://<ngcp.fqdn>:1444/device/autoprov/firmware/<mac>/from/<firmware_version>/next/<tag>

For example, NGCP has 7 firmwares configured for SNOM D715 with MAC 0004138aa403. For simplicity, let’s call those firmware versions: 1, 2, 3, 4, 5, 6, 7. The firmwares '4' and '6' have the same tag 'mytag'. The latest firmware is firmware with id '7' and it has no tag set.

The endpoint 'latest' gives access to firmware '6' only (if 'mytag' is used):

> curl http://myserver.com:1445/device/autoprov/firmware/0004138aa403/from/0/latest
firmware 7

> curl http://myserver.com:1445/device/autoprov/firmware/0004138aa403/from/0/latest/mytag
firmware 6

The enpoint 'next' allows to address the complete chain of firmwares using tags:

> curl http://myserver.com:1445/device/autoprov/firmware/0004138aa403/from/0/next
firmware 1  # the next firmware after version '0' is firmware '1'

> curl http://myserver.com:1445/device/autoprov/firmware/0004138aa403/from/0/next/mytag
firmware 4  # the next firmware after version '0' with tag 'mytag' is firmware '4'

> curl http://myserver.com:1445/device/autoprov/firmware/0004138aa403/from/2/next/mytag
firmware 4  # the same as above, the firmware after version '2' with tag 'mytag' is firmware '4'

> curl http://myserver.com:1445/device/autoprov/firmware/0004138aa403/from/4/next/mytag
firmware 6  # the next firmware after version '4' with tag 'mytag' is firmware '6'

Device Provisioning and Deployment Workflows

This chapter provides information and hints for preparing and performing the deployment of certain VoIP devices at customer sites, that have a customer-facing interface which also needs customisation.

Audiocodes Mediant Device Provisioning Workflow

Audiocodes ISDN gateways and eSBCs are devices used to connect legacy (ISDN) PBX and IP-PBX to Sipwise C5 platform and maintain their operations within the Operator’s network. The Sipwise C5 offers a SipConnect 2.0 compliant signaling and media interface to connect SIP trunks to the platform. In addition to this interface, the Sipwise C5 provides an auto-provisioning mechanism to configure SIP endpoints like IP phones, media gateways and eSBCs.

Provisioning URL

An Audiocodes device needs to obtain the provisioning URL of the Sipwise C5 in one way or another, to request its device configuration and subsequently download specific firmware, obtain SIP credentials to connect to the network facing side, and configure the customer facing side for customer devices to connect either via ISDN or SIP. Typical ways of obtaining the provisioning URL for a SIP endpoint are:

  • using DHCP option-66 (in a pre-staging environment or directly at the customer premise) where vendor-specific Redirect Servers are configured in the default configuration or firmware

  • getting pre-configured per deployment from the SIP endpoint vendor

  • getting pre-configured per deployment by a 3rd party distributor

The assumption is that Audiocodes devices are supplied with a firmware (and all required SSL certificates) being pre-configured and the provisioning URL pointing to an Operator URL Sipwise C5 is serving, before handing the devices over to field service engineers doing the truck rolls.

Field Configuration

The Sipwise C5 provides a SipConnect 1.1 compliant interface on the network side for the Audiocodes devices. This interface defines the numbering formats of the calling and called party, the SIP header mechanisms to provide CLI restriction, the RTP codecs, etc.

On the customer facing side, however, those variables might be different from deployment to deployment:

  • An IP-PBX might choose to only send its extension as calling party number, or might choose to send the full number in national format.

  • It might choose to use the SIP From-header mechanisms to suppress displaying of the CLI, oruse the SIP Privacy header.

  • The same uncertainty exists to some extent for a legacy PBX connecting via ISDN to the Audiocodes device.

The assumption here is that a field service engineer is NOT supposed to change the Audiocodes configuration in order to make the customer interface work, as this will lead to big issues in maintaining those local changes, especially if a replacement of the device is necessary. Instead, the Audiocodes configuration must ensure that all different kinds of variants in terms of SIP headers, codecs and number formats are translated correctly to the network side and vice versa. If it turns out that there are scenarios in the field which are not handled correctly, temporary local changes might be performed to finish a truck roll, but those changes MUST be communicated to the platform operator, and the server-side configuration templates must be adapted to handle those scenarios gracefully as well.

For deployments with ISDN interfaces on the customer facing side of the Audiocodes, different Device Profiles with specific Device Configurations per Device Model must exist to handle certain scenarios, specifically whether the ISDN interface is operating in Point-to-Point or Point-to-Multipoint mode. Configuration options like which side is providing the clock-rate are to be defined up-front, and the PBX must be reconfigured to adhere to the configuration.

Network Configuration

On the network facing side, both the ISDN and eSBC style deployments have to be designed to obtain an IP address via DHCP. The definition of the IP address ranges is up to the Operator. It may or may not be NAT-ed, but it is advised to use a private IP range directly routed in the back-bone to avoid NAT.

On the customer facing side, networking is only relevant for the eSBC deployment. In order to make the IP-PBX configuration as stream-lined as possible, a pre-defined network should be established on the customer interface of the Audiocodes device.

The proposal is to define a network 192.168.255.0/24 with the Audiocodes device using the IP 192.168.255.2 (leaving the 192.168.255.1 to a possible gateway). The IP-PBX could obtain its IP address via DHCP from a DHCP server running on the Audiocodes device (e.g. serving IP addresses in the range of 192.168.255.100-254), or could have it configured manually (e.g. in the range of 192.168.255.3-99). Since the Audiocodes device IP on the customer side is always fixed at 192.168.255.2, the IP-PBX for each customer can be configured the same way, pointing the SIP proxy/registrar or outbound proxy always to this IP.

The customer facing side is outside the Sipwise demarcation line, that is why the network configuration mentioned above only serves as proposal and any feedback is highly welcome. However, it must be communicated how the customer facing network is going to be configured, because the Sipwise C5 needs to incorporate this configuration into the Audiocodes configuration templates.

Audiocodes Mediant Device Deployment Workflow

Pre-Configuration on Sipwise C5 platform

  1. Before connecting a customer to a SIP trunk, it must be clear which Audiocodes Device Model is going to be used (depending on if, which and how many ISDN ports are necessary) and which Device Profile for the Device Model is required (eSBC mode, ISDN P-to-P or P-to-MP mode). Based on that, the correct physical device must be picked.

  2. Next, the customer has to be created on the Sipwise C5. This step requires the creation of the customer, and the creation of a subscriber within this customer. For the subscriber, the proper E.164 numbers or number blocks must be assigned, and the correct subscriber preferences must be set for the network interface to adhere to the SipConnect 2.0 interface. This step is automated by a script provided by Sipwise until the provisioning work-flow is fully integrated with Operator’s OSS/BSS systems. Required parameters are:

    • an external customer id to relate the customer entity on Sipwise C5 with a customer identifier in Operator’s IT systems

    • a billing profile name

    • a subscriber username and password, the domain the subscriber is configured for

    • the numbers or number blocks assigned to the subscriber, and the network provided number of the subscriber

    • optional information is geographic location information and IP network information to properly map emergency calls

  3. Finally, the association between the MAC address of the Audiocodes device and the SIP subscriber to be used on the SIP trunk must be established. This step is also automated by a script provided by Sipwise. Required parameters are:

    • the subscriber id

    • the Device Profile to be used

    • and the MAC address of the Audiocodes device

Installation

Once the above requirements are fulfilled and the customer is created on Sipwise C5, the Audiocodes device can be installed at the customer premise.

When the Audiocodes device boots, it requests the configuration file from Sipwise C5 by issuing a GET request via HTTPS.

For authentication and authorization purposes, Sipwise C5 requests an SSL client certificate from the device and will check whether it’s signed by a Certificate Authority (CA) known to Sipwise C5. Therefore, Audiocodes must provide the CA certificate used to sign the devices' client certificates to Sipwise to allow for this process. Also, Sipwise C5 will provide an SSL server certificate to the device. The device must validate this certificate in order to prevent man-in-the-middle attacks. Options here are to have:

  • Sipwise provides a self-signed certificate to Audiocodes for Audiocodes or a 3rd party distribution partner to configure it as trusted CA in the pre-staging process

  • the Operator provide a certificate signed by a CA which is already in the trust store of the Audiocodes devices.

Once the secured HTTPS connection is established, Sipwise C5 will provide a CLI style configuration file, with its content depending on the pre-configured Device Profile and subscriber association to the device’s MAC address.

The configuration includes the firmware version of the latest available firmware configured for the Device Model, and a URL defining from where to obtain it. The configuration details on how the Audiocodes devices manage the scheduling of firmware updates are to be provided by Audiocodes or its partners, since this is out of scope for Sipwise. Ideally, firmware updates should only be performed if the device is idle (no calls running), and within a specific time-frame (e.g. between 1 a.m. and 5 a.m. once a certain firmware version is reached, including some random variation to prevent all devices to download a new firmware version at the same time).

Device Replacement

If a customer requires the replacement of a device, e.g. due to hardware issues or due to changing the number or type of ISDN interfaces, a new association of the new device MAC, its Device Profile and the subscriber must be established.

In order to make the change as seamless as possible for the customer, a new device is created for the customer with the new MAC, a proper Device Profile, but the same subscriber as used on the old device. Once the new device boots at the customer premise, it will obtain its configuration and will register with the same subscriber as the old device (in case it is still operational). For inbound calls to the customer, this will cause parallel ringing to take place, and it is up to the customer or the field engineer when to re-configure or re-cable the PBX to connect to one or the other device.

Once the old device is decommissioned, the old MAC association can be deleted on Sipwise C5.

Adjusting the PBX Devices Configuration

Usually, everything required for PBX devices autoprovisioning is uploaded automatically as described in PBX Device Provisioning. In case you would like to introduce changes into a PBX device configuration, create a custom PBX device profile or even upload a newer firmware, this section will help you.

The Device Management is used by admins and resellers to define the list of device models, firmware and configurations available for end customer usage. These settings are pre-configured for the default reseller up-front by the Sipwise and have to be set up for every reseller separately, so a reseller can choose the devices he’d like to serve and potentially tweak the configuration for them. List of available pre-configured devices.

End customers choose from a list of Device Profiles, which are defined by a specific Device Model, a list of Device Firmwares and a Device Configuration. The following sections describe the setup of these components.

To do so, go to Settings→Device Management.

Device Management
Figure 49. Device Management

Setting up Device Models

A Device Model defines a specific hardware device, like the vendor, model name, the number of keys and their capabilities. For example a Cisco SPA504G has 4 keys, which can be used for private lines, shared lines (SLA) and busy lamp field (BLF). If you have an additional attendant console, you get 32 more buttons, which can only do BLF.

In this example, we will create a Cisco SPA504G with an additional Attendant Console.

Create Device Model
Figure 50. Create Device Model

Expand the Device Models row and click Create Device Model.

First, you have to select the reseller this device model belongs to, and define the vendor and model name.

Create Device Model - Main
Figure 51. Create Device Model - Main

In the Line/Key Range section, you can define the first set of keys, which we will label Phone Keys. The name is important, because it is referenced in the configuration file template, which is described in the following sections. The SPA504G internal phone keys support private lines (where the customer can assign a normal subscriber, which is used to place and receive standard phone calls), shared lines (where the customer can assign a subscriber which is shared across multiple people) and busy lamp field (where the customer can assign other subscribers to be monitored when they get a call, and which also acts as speed dial button to the subscriber assigned for BLF), so we enable all 3 of them.

Create Device Model - Lines
Figure 52. Create Device Model - Lines

In order to also configure the attendant console, press the Add another Line/Key Range button to specify the attendant console keys.

Again provide a name for this range, which will be Attendant Console 1 to match our configuration defined later. There are 32 buttons on the attendant console, so set the number accordingly. Those 32 buttons only support BLF, so make sure to uncheck the private and shared line options, and only check the Supports Busy Lamp Field option.

Create Device Model - Add a Line
Figure 53. Create Device Model - Add a Line

The last two settings to configure are the Front Image and MAC Address Image fields. Upload a picture of the phone here in the first field, which is shown to the customer for them to recognize easily how the phone looks like. The MAC image is used to tell the customer where he can read the MAC address from. This could be a picture of the back of the phone with the label where the MAC is printed, or an instruction image how to get the MAC from the phone menu.

The rest of the fields are left at their default values, which are set to work with Cisco SPAs. Their meaning is as follows:

  • Bootstrap Sync URI: If a stock phone is plugged in for the first time, it needs to be provisioned somehow to let it know where to fetch its configuration file from. Since the stock phone does not know about your server, you have to define an HTTP URI here, where the customer is connected with his web browser to set the according field.

  • Bootstrap Sync HTTP Method: This setting defines whether an HTTP GET or POST is sent to the Sync URI.

  • Bootstrap Sync Params: This setting defines the parameters appended to the Sync URI in case of a GET, or posted in the request body in case of POST, when the customer presses the Sync button later on.

Finally press Save to create the new device model.

Create Device Model - Bootstrap
Figure 54. Create Device Model - Bootstrap

Uploading Device Firmwares

A device model can optionally have one or more device firmware versions. Some devices like the Cisco SPA series do not support direct firmware updates from an arbitrary to the latest one, but need to go over specific firmware steps. In the device configuration discussed next, you can return the next supported firmware version, if the phone passes the current version in the firmware URL.

Since a stock phone purchased from any shop can have an arbitrary firmware version, we need to upload all firmwares needed to get from any old one to the latest one. In case of the Cisco SPA3x/SPA5x series, that would be the following versions, if the phone starts off with version 7.4.x:

  • spa50x-30x-7-5-1a.bin

  • spa50x-30x-7-5-2b.bin

  • spa50x-30x-7-5-5.bin

So to get an SPA504G with a firmware version 7.4.x to the latest version 7.5.5, we need to upload each firmware file as follows.

Open the Device Firmware row in the Device Management section and press Upload Device Firmware.

Device Firmware
Figure 55. Device Firmware

Select the device model we are going to upload the firmware for, then specify the firmware version and choose the firmware file, then press Save.

Upload Device Firmware
Figure 56. Upload Device Firmware

Repeat this step for every firmware in the list above (and any new firmware you want to support when it’s available).

Creating Device Configurations

Each customer device needs a configuration file, which defines the URL to perform firmware updates, and most importantly, which defines the subscribers and features configured on each of the lines and keys. Since these settings are different for each physical phone at all the customers, the Cloud PBX module provides a template system to specify the configurations. That way, template variables can be used in the generic configuration, which are filled in by the system individually when a physical device fetches its configuration file.

To upload a configuration template, open the Device Configuration row and press Create Device Configuration.

Device Configuration
Figure 57. Device Configuration

Select the device model and specify a version number for this configuration (it is only for your reference to keep track of different versions). For Cisco SPA phones, keep the Content Type field to text/xml, since the configuration content will be served to the phone as XML file.

For devices other than the Cisco SPA, you might set text/plain if the configuration file is plain text, or application/octet-stream if the configuration is compiled into some binary form.

Finally paste the configuration template into the Content area and press Save.

Upload Device Configuration
Figure 58. Upload Device Configuration

The templates for certified device models are provided by Sipwise, but you can also write your own. The following variables can be used in the template:

  • config.url: The URL to the config file, including the device identifier (e.g. http://sip.example.org:1444/device/autoprov/config/001122334455).

  • config.baseurl: The URL to the config file, without the device identifier (e.g. http://sip.example.org:1444/device/autoprov/config/).

  • config.mac: The device MAC address.

  • config.filename: The requested config filename (e.g. 001122334455-firmware.xml in case the URL is http://sip.example.org:1444/device/autoprov/config/001122334455-firmware.xml).

  • firmware.maxversion: The latest firmware version available on the system for the specific device.

  • firmware.baseurl: The base URL to download firmwares (e.g. http://sip.example.org:1444/device/autoprov/firmware). To fetch the next newer firmware for a Cisco SPA, you can use the template line [% firmware.baseurl %]/$MA/from/$SWVER/next.

  • phone.model: The device model. It is useful for the cases of a shared/common template for several devices within the same vendor.

  • phone.vendor: The device vendor name. It is available for the general PBX template’s flexibility.

  • phone.stationname: The name of the station (physical device) the customer specifies for this phone. Can be used to show on the display of the phone.

  • phone.lineranges: An array of lines/keys as specified for the device model. Each entry in the array has the following keys:

    • name: The name of the line/key range as specified in the Device Model section (e.g. Phone Keys).

    • num_lines: The number of lines/keys in the line range (e.g. 4 in our Phone Keys example, or 32 in our Attendant Console 1 example).

    • lines: An array of lines (e.g. subscriber definitions) for this line range. Each entry in the array has the following keys:

      • keynum: The index of the key in the line range, starting from 0 (e.g. keynum will be 3 for the 4th key of our Phone Keys range).

      • rangenum: The index of the line range, starting from 0. The order of line ranges is as you have specified them (e.g. Phone Keys was specified first, so it gets rangenum 0, Auto Attendant 1 gets rangenum 1).

      • type: The type of the line/key, one of private, shared, blf, speeddial, forward or transfer.

      • username: The SIP username of the line.

      • domain: The SIP domain of the line.

      • password: The SIP password of the line.

      • displayname: The SIP Display Name of the line.

In the configuration template, you can adjust embedded variable references for the existing variables. Please also check the bootstrap section: PBX bootstrap, firmwares and security. If you need other specific variables, please request their development from Sipwise.

In order to change the provisioning base IP and port (default 1444), you have to access /etc/ngcp-config/config.yml and change the value host and port under the autoprov.server section.

Creating Device Profiles

When the customer configures his own device, he does not select a Device Model directly, but a Device Profile. A device profile specifies which model is going to be used with which configuration version. This allows the operator to create new configuration files and assign them to a profile, while still keeping older configuration files for reference or roll-back scenarios. It also makes it possible to test new firmwares by creating a test device model with the new firmware and a specific configuration, without impacting any existing customer devices.

To create a Device Profile for our phone, open the Device Profiles row in the Device Management section and press Create Device Profile.

Device Profile
Figure 59. Device Profile

Select the device configuration (which implicitly identifies a device model) and specify a Profile Name. This name is what the customer sees when they are selecting a device they want to provision, so pick a descriptive name which unambiguously identifies a device. Press Save to create the profile.

Create Device Profile
Figure 60. Create Device Profile

Repeat the steps as needed for every device you want to make available to customers.

List of available pre-configured devices

Vendor Model Available from release Deprecated from release

ALE

8008

mr7.0.1.1

-

ALE

8018

mr7.0.1.1

-

ALE

8028

mr7.0.1.1

-

ALE

8058

mr7.0.1.1

-

ALE

8068

mr7.0.1.1

-

ALE

8078

mr7.0.1.1

-

ALE

AOM10

mr7.0.1.1

-

ALE

AOM40

mr7.0.1.1

-

ALE

AOMEL

mr7.0.1.1

-

ALE

M3

mr10.2.1.1

-

ALE

M5

mr10.2.1.1

-

ALE

M7

mr10.2.1.1

-

ALE

H3P

mr10.2.1.1

-

ALE

H6

mr10.2.1.1

-

Audiocodes

Mediant800

mr4.1.1.1

mr10.5.1.1

Cisco

ATA112

mr3.4.1.1

mr10.5.1.1

Cisco

ATA122

mr3.4.1.1

mr10.5.1.1

Cisco

SPA232D

mr3.4.1.1

mr10.5.1.1

Cisco

SPA301

mr3.4.1.1

mr10.5.1.1

Cisco

SPA303

mr3.4.1.1

mr10.5.1.1

Cisco

SPA501G

mr3.4.1.1

mr10.5.1.1

Cisco

SPA502G

mr3.4.1.1

mr10.5.1.1

Cisco

SPA512G

mr3.4.1.1

mr10.5.1.1

Cisco

SPA504G

mr3.4.1.1

mr10.5.1.1

Cisco

SPA504G + SPA500S

mr3.7.1.4

mr10.5.1.1

Cisco

SPA504G + two SPA500S

mr3.7.1.4

mr10.5.1.1

Cisco

SPA514G

mr3.4.1.1

mr10.5.1.1

Cisco

SPA508G

mr3.4.1.1

mr10.5.1.1

Cisco

SPA509G

mr3.4.1.1

mr10.5.1.1

Cisco

SPA525G

mr3.4.1.1

mr10.5.1.1

Grandstream

HT814

mr5.1.1.1

-

Grandstream

GXW-4008

mr5.1.1.1

-

Grandstream

GXW-4216

mr5.1.1.1

-

Innovaphone

IP2X2X

mr3.8.3.3

mr10.5.1.1

Innovaphone

IP230-X

mr3.8.3.3

mr10.5.1.1

Innovaphone

IP232

mr3.8.3.3

mr10.5.1.1

Innovaphone

IP222

mr3.8.3.3

mr10.5.1.1

Innovaphone

IP240

mr3.8.3.3

mr10.5.1.1

Innovaphone

IP22

mr3.8.3.3

mr10.5.1.1

Innovaphone

IP111

mr3.8.3.3

mr10.5.1.1

Panasonic

KX-UT113

mr3.7.1.1

mr10.5.1.1

Panasonic

KX-UT123

mr3.7.1.1

mr10.5.1.1

Panasonic

KX-UT133

mr3.7.1.1

mr10.5.1.1

Panasonic

KX-UT136

mr3.7.1.1

mr10.5.1.1

Panasonic

KX-UT248

mr3.7.1.1

mr10.5.1.1

Panasonic

KX-TGP600

mr5.1.1.1

mr10.5.1.1

Panasonic

KX-HDV330

mr5.1.1.1

mr10.5.1.1

Panasonic

KX-HDV230

mr5.1.1.1

mr10.5.1.1

Panasonic

KX-HDV130

mr5.1.1.1

mr10.5.1.1

Polycom

VVX300

mr5.4.1.1

mr10.5.1.1

Polycom

VVX400

mr5.4.1.1

mr10.5.1.1

Polycom

VVX500

mr5.4.1.1

mr10.5.1.1

SNOM

D715

mr9.1.1.1

-

SNOM

D717

mr9.1.1.1

-

SNOM

D735

mr9.1.1.1

-

SNOM

D785

mr9.1.1.1

-

SNOM

D862

mr11.5.1.1

-

SNOM

D865

mr11.5.1.1

-

SNOM

M900

mr9.1.1.1

-

SNOM

M65

mr9.1.1.1

-

SNOM

M70

mr9.1.1.1

-

SNOM

M80

mr9.1.1.1

-

SNOM

M85

mr9.1.1.1

-

SNOM

M90

mr9.1.1.1

-

SNOM

A190 (no uaCSTA)

mr9.1.1.1

-

Yealink

CP860

mr5.2.1.1

mr11.5.1.1

Yealink

SIP-T19P

mr3.7.1.1

mr10.5.1.1

Yealink

SIP-T20P

mr3.7.1.1

mr10.5.1.1

Yealink

SIP-T21P

mr3.7.1.1

mr10.5.1.1

Yealink

SIP-T22P

mr3.7.1.1

mr10.5.1.1

Yealink

SIP-T23P

mr3.7.1.1

mr11.5.1.1

Yealink

SIP-T23G

mr3.7.1.1

mr11.5.1.1

Yealink

SIP-T26P

mr3.7.1.1

mr10.5.1.1

Yealink

SIP-T28P

mr3.7.1.1

mr10.5.1.1

Yealink

SIP-T28P + EXP39

mr3.8.1.1

mr10.5.1.1

Yealink

SIP-T28P + two EXP39

mr3.8.1.1

mr10.5.1.1

Yealink

SIP-T32G

mr3.7.1.1

mr10.5.1.1

Yealink

SIP-T38G

mr3.7.1.1

mr10.5.1.1

Yealink

SIP-T41P

mr3.7.1.1

mr10.5.1.1

Yealink

SIP-T42G

mr3.7.1.1

mr10.5.1.1

Yealink

SIP-T46G

mr3.7.1.1

mr10.5.1.1

Yealink

SIP-T48G

mr3.7.1.1

mr10.5.1.1

Yealink

SIP-T53

mr8.5.1.1

-

Yealink

SIP-T54W

mr8.5.1.1

-

Yealink

SIP-T57W

mr8.5.1.1

-

Yealink

W52P

mr3.7.1.6

mr11.5.1.1
Deprecated phones are phones for which the device manufacturer has stopped hardware and software support entirely. These are still available for autoprovisioning, but will no longer be supported and potentially removed in a future version of NGCP

Alcatel-Lucent Enterprise (ALE) Devices

Model IPv6 TLS SRTP Auto provisioning Private Line Shared Line Busy Lamp Speed Dial Forward Key Transfer Key Extension Boards

8008

Y

Y

Y

redirect

1-2

0

1-6

N

N

N

N

8018

Y

Y

Y

redirect

1-2

0

1-6

N

N

N

N

8028

Y

Y

Y

redirect

1-2

0

1-6

N

N

N

N

8058

Y

Y

Y

redirect

1-4

1

1-10

N

N

N

Y

8068

Y

Y

Y

redirect

1-4

1

1-10

N

N

N

Y

8078

Y

Y

Y

redirect

1-4

1

1-10

N

N

N

Y

AOM10

N

N

N

device

1

0

1

Y

N

N

Y

AOM40

N

N

N

device

1

0

1

Y

N

N

Y

AOMEL

N

N

N

device

1

0

1

Y

N

N

Y

M3

Y

Y

Y

redirect

1-8

0

1-20

Y

Y

Y

N

M5

Y

Y

Y

redirect

1-8

0

1-28

Y

Y

Y

N

M7

Y

Y

Y

redirect

1-8

0

1-28

Y

Y

Y

N

H2P

Y

Y

Y

redirect

1-2

0

0

Y

Y

Y

N

H3G

Y

Y

Y

redirect

1-3

0

1-8

Y

Y

Y

N

H6

Y

Y

Y

redirect

1-4

0

1-12

Y

Y

Y

N

Audiocodes Devices

Model IPv6 TLS SRTP Auto provisioning Private Line Shared Line Busy Lamp Speed Dial Forward Key Transfer Key Mediant800

Cisco Devices

IP Phones

Model IPv6 TLS SRTP Auto provisioning Private Line Shared Line Busy Lamp Speed Dial Forward Key Transfer Key Extension Boards

SPA301

N

Y

Y

http

1

1

0

N

N

N

N

SPA303

N

Y

Y

http

1-3

1-3

1-2

N

N

N

N

SPA501G

N

Y

Y

http

1-8

1-8

1-7

N

N

N

N

SPA502G

N

Y

Y

http

1

1

0

N

N

N

N

SPA512G

N

N

Y

http

1

1

0

N

N

N

N

SPA504G

N

Y

Y

http

1-4

1-4

1-3

N

N

N

2

SPA514G

N

N

Y

http

1-4

1-4

1-3

N

N

N

N

SPA508G

N

Y

Y

http

1-8

1-8

1-7

N

N

N

N

SPA509G

N

Y

Y

http

1-12

1-12

1-11

N

N

N

N

SPA525G

N

Y

N

http

1-5

1-5

1-4

N

N

N

N

Analog Adapters

Model IPv6 TLS SRTP Auto provisioning Private Line Shared Line Busy Lamp Speed Dial Forward Key Transfer Key

SPA232D

N

Y

Y

http

1-6

0

0

N

N

N

ATA112

Y

Y

Y

http

1-2

0

0

N

N

N

ATA122

Y

Y

Y

http

1-2

0

0

N

N

N

Extension Boards

Model Ports Buttons Busy Lamp Speed Dial Forward Key Transfer Key Supported phones

SPA500S

2

32

1-32

N

N

N

SPA500

Grandstream Devices

Analog Adapters

Model IPv6 TLS SRTP Auto provisioning Private Line Shared Line Busy Lamp Speed Dial Forward Key Transfer Key

HT814

N

Y

Y

redirect

4

N

N

N

N

N

GXW-4008

N

Y

Y

redirect

8

N

N

N

N

N

GXW-4216

N

Y

Y

redirect

16

N

N

N

N

N

Innovaphone Devices

IP Phones

Model IPv6 TLS SRTP Auto provisioning Private Line Shared Line Busy Lamp Speed Dial Forward Key Transfer Key Extension Boards

IP232

N

Y

Y

dhcp

1

0

1-16

N

N

N

2

IP222

N

Y

Y

dhcp

1

0

1-16

N

N

N

2

IP240

N

N

N

dhcp

1

0

1-15

N

N

N

2

IP111

N

Y

Y

dhcp

1

0

1-16

N

N

N

0

Analog Adapters

Model IPv6 TLS SRTP Auto provisioning Private Line Shared Line Busy Lamp Speed Dial Forward Key Transfer Key

IP22

N

Y

Y

dhcp

1

0

0

N

N

N

Extension Boards

Model Ports Buttons Busy Lamp Speed Dial Forward Key Transfer Key Supported phones

IP2X2X

2

64

1-32

N

N

N

IP2x2

IP230-X

2

30

1-30

N

N

N

IP230

Panasonic Devices

IP Phones

Model IPv6 TLS SRTP Auto provisioning Private Line Shared Line Busy Lamp Speed Dial Forward Key Transfer Key Extension Boards

KX-UT113

N

N

N

redirect

1-2

1-2

0

N

N

N

N

KX-UT123

N

N

N

redirect

1-2

1-2

0

N

N

N

N

KX-UT133

N

N

N

redirect

1-4

1-4

1-23

N

N

N

N

KX-UT136

N

N

N

redirect

1-4

1-4

1-23

N

N

N

N

KX-UT248

N

N

Y

redirect

1-6

1-6

1-23

N

N

N

N

KX-TGP600

Y

Y

Y

redirect

1-8

N

N

N

N

N

N

KX-HDV330

Y

Y

Y

redirect

1-12

Y

Y

N

N

N

N

KX-HDV230

Y

Y

Y

redirect

1-6

Y

Y

N

N

N

N

KX-HDV130

Y

Y

Y

redirect

1-2

Y

Y

N

N

N

N

Polycom Devices

IP Phones

Model IPv6 TLS SRTP Auto provisioning Private Line Shared Line Busy Lamp Speed Dial Forward Key Transfer Key Extension Boards

VVX300

N

N

Y

redirect

1-6

1-6

Y

N

N

N

N

VVX400

N

N

Y

redirect

1-12

1-12

Y

N

N

N

N

VVX500

N

N

Y

redirect

1-12

1-12

Y

N

N

N

N

SNOM Devices

IP Phones

Model IPv6 TLS SRTP Auto provisioning Private Line Shared Line Busy Lamp Speed Dial Forward Key Transfer Key Extension Boards

D715

Y

Y

Y

redirect

1-4

N

Y

Y

Y

Y

Y

D717

Y

Y

Y

redirect

1-6

N

Y

Y

Y

Y

Y

D735

Y

Y

Y

redirect

1-12

N

Y

Y

Y

Y

Y

D785

Y

Y

Y

redirect

1-12

N

Y

Y

Y

Y

Y

D862

Y

Y

Y

redirect

1-12

N

Y

Y

Y

Y

Y

D865

Y

Y

Y

redirect

1-8

N

Y

Y

Y

Y

Y

Base Stations

Model IPv6 TLS SRTP Auto provisioning Private Line Shared Line Busy Lamp Speed Dial Forward Key Transfer Key Extension Boards

M900

Y

Y

Y

redirect

1-4

N

N

N

N

N

N

Handsets and Headsets

Model IPv6 TLS SRTP Auto provisioning Private Line Shared Line Busy Lamp Speed Dial Forward Key Transfer Key Extension Boards

M65

Y

Y

Y

redirect

1

N

N

N

N

N

N

M70

Y

Y

Y

redirect

1

N

N

N

N

N

N

M80

Y

Y

Y

redirect

1

N

N

N

N

N

N

M85

Y

Y

Y

redirect

1

N

N

N

N

N

N

M90

Y

Y

Y

redirect

1

N

N

N

N

N

N

A190

Y

Y

Y

redirect

1

N

N

N

N

N

N

Yealink Devices

IP Phones

Model IPv6 TLS SRTP Auto provisioning Private Line Shared Line Busy Lamp Speed Dial Forward Key Transfer Key Extension Boards

CP860

Y

Y

Y

redirect

1

N

N

N

N

N

N

SIP-T19P

Y

Y

Y

redirect

1

1

0

N

N

N

N

SIP-T20P

Y

Y

Y

redirect

1

1

0

N

N

N

N

SIP-T21P

Y

Y

Y

redirect

1-2

1-2

1

Y

Y

Y

N

SIP-T22P

Y

Y

Y

redirect

1-3

1-3

1-2

Y

Y

Y

N

SIP-T23P

Y

Y

Y

redirect

1-3

1-3

1-2

Y

Y

Y

N

SIP-T23G

Y

Y

Y

redirect

1-3

1-3

1-2

Y

Y

Y

N

SIP-T26P

Y

Y

Y

redirect

1-3

1-3

1-12

Y

Y

Y

N

SIP-T28P

Y

Y

Y

redirect

1-6

1-6

1-15

Y

Y

Y

2

SIP-T32G

Y

Y

Y

redirect

1-3

1-3

1-2

Y

Y

Y

N

SIP-T38G

Y

Y

Y

redirect

1-6

1-6

1-15

Y

Y

Y

N

SIP-T41P

Y

Y

Y

redirect

1-3

1-3

1-14

Y

Y

Y

N

SIP-T42G

Y

Y

Y

redirect

1-3

1-3

1-14

Y

Y

Y

N

SIP-T46G

Y

Y

Y

redirect

1-6

1-6

1-26

Y

Y

Y

N

SIP-T48G

Y

Y

Y

redirect

1-6

1-6

1-28

Y

Y

Y

N

W52P

N

Y

Y

redirect

1-5

1-5

0

N

N

N

N

Phone features

Cisco phones

SPA301

1) Soft keys

Not available.

2) Hard keys

  • vm

  • hold/unhold

3) Line keys

Not available.

4) VSC

  • directed pickup

  • park/unpark

SPA303

1) Soft keys

Idle:

redial

lcr

dir

dnd >

< cfwd

unpark

Idle with missed calls:

lcr

miss

Call:

hold

endCall

conf

xfer >

< bxfer

park

Call on hold:

resume

endCall

newCall

redial >

< dir

cfwd

dnd

Ringing:

answer

ignore

2) Hard keys

  • vm

  • hold/unhold

3) Line keys

  • BLF monitoring

  • directed pickup

4) VSC

  • directed pickup

SPA501G

1) Soft keys

Idle:

redial

lcr

dir

dnd >

< cfwd

unpark

Idle with missed calls:

lcr

miss

Call:

hold/resume

endCall

conf

xfer >

< bxfer

park

Call on hold:

resume

endCall

newCall

redial >

< dir

cfwd

dnd

Ringing:

answer

reject

2) Hard keys

  • vm

  • hold/unhold

3) Line keys

  • BLF monitoring

  • directed pickup

4) VSC

  • directed pickup

SPA502G

1) Soft keys

Idle:

redial

lcr

dir

dnd >

< cfwd

unpark

Idle with missed calls:

lcr

miss

Call:

hold/resume

endCall

conf

xfer >

< bxfer

park

Call on hold:

resume

endCall

newCall

redial >

< dir

cfwd

dnd

Ringing:

answer

reject

2) Hard keys

  • vm

  • hold/unhold

3) Line keys

Not available.

4) VSC

  • directed pickup

SPA504G

1) Soft keys

Idle:

redial

lcr

dir

dnd >

< cfwd

unpark

Idle with missed calls:

lcr

miss

Call:

hold/resume

endCall

conf

xfer >

< bxfer

park

Call on hold:

resume

endCall

newCall

redial >

< dir

cfwd

dnd

Ringing:

answer

reject

2) Hard keys

  • vm

  • hold/unhold

3) Line keys

  • BLF monitoring

  • directed pickup

4) VSC

  • directed pickup

SPA512G

1) Soft keys

Idle:

redial

lcr

dir

dnd >

< cfwd

unpark

Idle with missed calls:

lcr

miss

Call:

hold/resume

endCall

conf

xfer >

< bxfer

park

Call on hold:

resume

endCall

newCall

redial >

< dir

cfwd

dnd

Ringing:

answer

reject

2) Hard keys

  • vm

  • hold/unhold

3) Line keys

Not available.

4) VSC

  • directed pickup

SPA514G

1) Soft keys

Idle:

redial

lcr

dir

dnd >

< cfwd

unpark

Idle with missed calls:

lcr

miss

Call:

hold/resume

endCall

conf

xfer >

< bxfer

park

Call on hold:

resume

endCall

newCall

redial >

< dir

cfwd

dnd

Ringing:

answer

reject

2) Hard keys

  • vm

  • hold/unhold

3) Line keys

  • BLF monitoring

  • directed pickup

4) VSC

  • directed pickup

SPA509G

1) Soft keys

Idle:

redial

lcr

dir

dnd >

< cfwd

unpark

Idle with missed calls:

lcr

miss

Call:

hold/resume

endCall

conf

xfer >

< bxfer

park

Call on hold:

resume

endCall

newCall

redial >

< dir

cfwd

dnd

Ringing:

answer

reject

2) Hard keys

  • vm

  • hold/unhold

3) Line keys

  • BLF monitoring

  • directed pickup

4) VSC

  • directed pickup

SPA508G

1) Soft keys

Idle:

redial

lcr

dir

dnd >

< cfwd

unpark

Idle with missed calls:

lcr

miss

Call:

hold/resume

endCall

conf

xfer >

< bxfer

park

Call on hold:

resume

endCall

newCall

redial >

< dir

cfwd

dnd

Ringing:

answer

reject

2) Hard keys

  • vm

  • hold/unhold

3) Line keys

  • BLF monitoring

  • directed pickup

4) VSC

  • directed pickup

SPA525G

1) Soft keys

Idle:

Redial

call Rtn

Directory

DND >

< Forward

Unpark

Idle with missed calls:

Call Rtn

Miss

Call:

Hold

End Call

Conf

Transfer >

BlindXfer

Park

Call on hold:

Resume

EndCall

EewCall

Redial >

< Directory

Forward

DND

Ringing:

Answer

Ignore

2) Hard keys

  • vm

  • hold/unhold

3) Line keys

  • BLF monitoring

  • directed pickup

4) VSC

  • directed pickup

Yealink phones

T19P

1) Soft keys

Idle:

History

DND

Menu

Idle with missed calls:

Exit

View

Call:

Tran

Hold

Conf

Cancel

Call on hold:

Tran

Resume

NewCall

Cancel

Ringing:

Answer

FWD

Silence

Reject

2) Hard keys

  • vm

  • redial

  • transfer

3) Line keys

Not available.

4) VSC

  • transfer park

  • directed pick up

  • park/unpark

T20P

1) Soft keys

Idle:

History

DND

Menu

Idle with missed calls:

Exit

View

Call:

Tran

Hold

Conf

Cancel

Call on hold:

Tran

Resume

NewCall

Cancel

Ringing:

Answer

FWD

Silence

Reject

2) Hard keys

  • vm

  • redial

  • transfer

3) Line keys

  • BLF monitoring

  • directed pickup

  • speed dial

  • forward

  • transfer

4) VSC

  • transfer park

  • park/unpark

T21P

1) Soft keys

Idle:

History

DND

Menu

Idle with missed calls:

Exit

View

Call:

Tran

Hold

Conf

Cancel

Call on hold:

Tran

Resume

NewCall

Cancel

Ringing:

Answer

FWD

Silence

Reject

2) Hard keys

  • vm

  • redial

  • transfer

3) Line keys

  • BLF monitoring

  • directed pickup

  • speed dial

  • forward

  • transfer

4) VSC

  • transfer park

  • park/unpark

T22P

1) Soft keys

Idle:

History

DND

Menu

Idle with missed calls:

Exit

View

Call:

Tran

Hold

Conf

Cancel

Call on hold:

Tran

Resume

NewCall

Cancel

Ringing:

Answer

FWD

Silence

Reject

2) Hard keys

  • vm

  • redial

  • transfer

3) Line keys

  • BLF monitoring

  • directed pickup

  • speed dial

  • forward

  • transfer

4) VSC

  • park/unpark

  • transfer park

T23P

1) Soft keys

Idle:

History

DND

Menu

Idle with missed calls:

Exit

View

Call:

Tran

Hold

Conf

Cancel

Call on hold:

Tran

Resume

NewCall

Cancel

Ringing:

Answer

FWD

Silence

Reject

2) Hard keys

  • vm

  • redial

  • transfer

3) Line keys

  • BLF monitoring

  • directed pickup

  • speed dial

  • forward

  • transfer

4) VSC

  • park/unpark

  • transfer park

T23G

1) Soft keys

Idle:

History

Dir

DND

Menu

Idle with missed calls:

Exit

View

Call:

Tran

Hold

Conf

EndCall

Call on hold:

Tran

Resume

NewCall

EndCall

Ringing:

Answer

FWD

Reject

2) Hard keys

  • vm

  • redial

  • transfer

3) Line keys

  • BLF monitoring

  • directed pickup

  • speed dial

  • forward

  • transfer

4) VSC

  • unpark

  • transfer park

T26P

1) Soft keys

Idle:

History

DND

Menu

Idle with missed calls:

Exit

View

Call:

Tran

Hold

Conf

Cancel

Call on hold:

Tran

Resume

NewCall

Cancel

Ringing:

Answer

FWD

Silence

Reject

2) Hard keys

  • vm

  • redial

  • transfer

3) Line keys

  • BLF monitoring

  • directed pickup

  • speed dial

  • forward

  • transfer

4) VSC

  • unpark

  • transfer park

T28P

1) Soft keys

Idle:

History

DND

Menu

Idle with missed calls:

Exit

View

Call:

Tran

Hold

Conf

Cancel

Call on hold:

Tran

Resume

NewCall

Cancel

Ringing:

Answer

FWD

Silence

Reject

2) Hard keys

  • vm

  • redial

  • transfer

3) Line keys

  • BLF monitoring

  • directed pickup

  • speed dial

  • forward

  • transfer

4) VSC

  • park/unpark

  • transfer park

T32G

1) Soft keys

Idle:

History

DND

Menu

Idle with missed calls:

Exit

View

Call:

Tran

Hold

Conf

Cancel

Call on hold:

Tran

Resume

NewCall

Cancel

Ringing:

Answer

FWD

Silence

Reject

2) Hard keys

  • vm

  • redial

  • transfer

3) Line keys

  • BLF monitoring

  • directed pickup

  • speed dial

  • forward

  • transfer

4) VSC

  • unpark

  • transfer park

T38G

1) Soft keys

Idle:

History

DND

Menu

Idle with missed calls:

Exit

View

Call:

Tran

Hold

Conf

Cancel

Call on hold:

Tran

Resume

NewCall

Cancel

Ringing:

Answer

FWD

Silence

Reject

2) Hard keys

  • vm

  • redial

  • transfer

3) Line keys

  • BLF monitoring

  • directed pickup

  • speed dial

  • forward

  • transfer

4) VSC

  • unpark

  • transfer park

T41P

1) Soft keys

Idle:

History

DND

Menu

Idle with missed calls:

Exit

View

Call:

Tran

Hold

Conf

Cancel

Call on hold:

Tran

Resume

NewCall

Cancel

Ringing:

Answer

FWD

Silence

Reject

2) Hard keys

  • vm

  • redial

  • transfer

3) Line keys

  • BLF monitoring

  • directed pickup

  • speed dial

  • forward

  • transfer

4) VSC

  • park/unpark

  • transfer park

T42G

1) Soft keys

Idle:

History

DND

Menu

Idle with missed calls:

Exit

View

Call:

Tran

Hold

Conf

Cancel

Call on hold:

Tran

Resume

NewCall

Cancel

Ringing:

Answer

FWD

Silence

Reject

2) Hard keys

  • vm

  • redial

  • transfer

3) Line keys

  • BLF monitoring

  • directed pickup

  • speed dial

  • forward

  • transfer

4) VSC

  • park/unpark

  • transfer park

T46G

1) Soft keys

Idle:

History

DND

Menu

Idle with missed calls:

Exit

View

Call:

Tran

Hold

Conf

Cancel

Call on hold:

Tran

Resume

NewCall

Cancel

Ringing:

Answer

FWD

Silence

Reject

2) Hard keys

  • vm

  • redial

  • transfer

3) Line keys

  • BLF monitoring

  • directed pickup

  • speed dial

  • forward

  • transfer

4) VSC

  • park/unpark

  • transfer park

T48G

1) Soft keys

Idle:

History

DND

Menu

Idle with missed calls:

Exit

View

Call:

Tran

Hold

Conf

Cancel

Call on hold:

Tran

Resume

NewCall

Cancel

Ringing:

Answer

FWD

Silence

Reject

2) Hard keys

  • vm

  • redial

  • transfer

3) Line keys

  • BLF monitoring

  • directed pickup

  • speed dial

  • forward

  • transfer

4) VSC

  • park/unpark

  • transfer park

W52P

1) Soft keys

Idle:

History

Line

Idle with missed calls:

Exit

View

Call:

Ext. Call

Options

Call on hold:

Resume

Line

Ringing:

Accept

2) Hard keys

  • vm

  • redirect

3) VSC

  • park/unpark

  • transfer park

Panasonic phones

KX-UT113

1) Soft keys

Idle:

Settings

Call Log

Phone book

Call:

Blind

Phone book

Call on hold:

Call Log

Phone book

Ringing:

Answer

Reject

2) Hard keys

  • vm

  • forward/dnd

  • hold/unhold

  • redial

  • recall

  • transfer

  • conf

3) Line keys

Not available.

4) VSC

  • park/unpark

  • transfer park

KX-UT123

1) Soft keys

Idle:

Settings

Call Log

Phone book

Call:

Blind

Phone book

Call on hold:

Call Log

Phone book

Ringing:

Answer

Reject

2) Hard keys

  • vm

  • forward/dnd

  • hold/unhold

  • redial

  • recall

  • transfer

  • conf

3) Line keys

Not available.

4) VSC

  • park/unpark

  • transfer park

KX-UT133

1) Soft keys

Idle:

Settings

Call Log

Phone book

Call:

Blind

Phone book

Call on hold:

Call Log

Phone book

Ringing:

Answer

Reject

2) Hard keys

  • vm

  • forward/dnd

  • hold/unhold

  • redial

  • recall

  • transfer

  • conf

3) Line keys

  • BLF monitoring

  • directed pickup

4) VSC

  • unpark

  • transfer park

KX-UT136

1) Soft keys

Idle:

Settings

Call Log

Phone book

Call:

Blind

Phone book

Call on hold:

Call Log

Phone book

Ringing:

Answer

Reject

2) Hard keys

  • vm

  • forward/dnd

  • hold/unhold

  • redial

  • recall

  • transfer

  • conf

3) Line keys

  • BLF monitoring

  • directed pickup

4) VSC

  • park/unpark

  • transfer park

KX-UT248

1) Soft keys

Idle:

Settings

Call Log

Phone book

Call:

Blind

Phone book

Call on hold:

Call Log

Phone book

Ringing:

Answer

Reject

2) Hard keys

  • vm

  • forward/dnd

  • hold/unhold

  • redial

  • recall

  • transfer

  • conf

3) Line keys

  • BLF monitoring

  • directed pickup

4) VSC

  • park/unpark

  • transfer park

Innovaphone

IP222

1) Soft keys

Idle:

Setup

All Calls

Home

Calls

My favorites

Phonebook

Call:

Hold

Transfer

Park

Cancel

Call on hold:

Resume

Transfer

Park

Cancel

Ringing:

Answer

Transfer

Silence

Reject

2) Hard keys

  • hold

  • redial

3) Line keys

  • BLF monitoring

4) VSC

  • unpark

  • transfer park

IP232

1) Soft keys

Idle:

Setup

All Calls

Home

Calls

My favorites

Phonebook

Call:

Hold

Transfer

Park

Cancel

Call on hold:

Resume

Transfer

Park

Cancel

Ringing:

Answer

Transfer

Silence

Reject

2) Hard keys

  • hold

  • redial

3) Line keys

  • BLF monitoring

4) VSC

  • unpark

  • transfer park

IP111

1) Soft keys

Idle:

Setup

All Calls

Home

Calls

My favorites

Phonebook

Call:

Hold

Transfer

Park

Cancel

Call on hold:

Resume

Transfer

Park

Cancel

Ringing:

Answer

Transfer

Silence

Reject

2) Hard keys

  • hold

  • redial

3) Line keys

  • BLF monitoring

4) VSC

  • unpark

  • transfer park

IP240

1) Soft keys

Not available.

2) Hard keys

  • hold

  • redial

  • conference

  • dnd

  • forward

3) Line keys

  • BLF monitoring

4) VSC

  • transfer park

  • unpark

Shared line appearance

In PBX environment, shared line appearance is supported for PBX subscribers. In comparison to the private line, subscriber registering for the shared line will, immediately after the successful registration, subscribe for Call-Info event. This subscribe is challenged for authentication and if the credentials are provided, subscriber is notified that the subscription is active. In the respective NOTIFY message, this is reflected in Subscription-State header set to active. NOTIFY also contains information about the status of the shared line in Call-Info header. If the appearance is not used, Call-Info header will describe the state as idle. In the NOTIFY message, this is reflected as “appearance-index=*;appearance-state=idle”.

If there is incoming call to the subscriber, the appearance index is created after the call is accepted and state will be set to active. Call-Info header will contain “appearance-index=1; appearance-state=active”. After the call is finished and appearance is not used elsewhere, appearance index is removed and state is set to idle. In the case of outgoing call, subscription to line-seize event is required to be able to dial. Before dialing can be started, SUBSCRIBE to line-seize is sent. Consequently, subscriber receives NOTIFY for line-seize with active subscription state. Call-info subscription is updated accordingly, appearance is created and its state is set to seized. As soon as the call starts ringing, Call-Info status is updated to progressing and line-seize subscription is set to terminated with “reason=noresource” in Subscription-State header. When the call is accepted, Call-Info status is changed to active and set again to idle when call is finished. Also, the appearance index is removed.

Sipwise sip:phone App (SIP client)

Sipwise provides a commercial Unified Communication Client for full end-to-end integration of voice, video, chat and presence features. The application is called sip:phone and is a mobile app for iOS and Android.

The clients are fully brandable to the customer’s corporate identity. They are not part of the standard delivery and need to be licensed separately. This handbook discusses the mobile client in details.

Zero Config Launcher

Part of the mobile apps is a mechanism to sign up to the service via a 3rd party website, which is initiated on the login screen and rendered within the app. During the sign-up process, the 3rd party service is supposed to create a new account and subscriber in Sipwise C5 (e.g. automatically via the API) and provide the end user with the access credentials.

The mobile apps come with a zero config mechanism to simplify the end-customer log in using these credentials (especially ruling out the need to manually enter them). It makes it possible to deliver the access credentials via a side channel (e.g. Email, SMS) packed into a URL. The user only clicks the URL, and it automatically launches the app with the correct credentials. The following picture shows the overall workflow.

Provisioning Push Workflow
Figure 61. Provisioning Push Workflow

There are two components provided by a 3rd party system. One is the 3rd Party Sign-Up Form, and the other is the 3rd Party Launch Handler. The purpose of these components is to allow an end customer to open a link with the access credentials via the sip:phone app.

3rd Party Sign-Up Form

The 3rd Party Sign-Up Form is a website the app shows to the end user when they tap the sign-up link on the app Login Screen. There, the end customer usually provides their contact details like name, address, phone number and email address, etc. After validation, the website creates an account and a subscriber in Sipwise C5 via the API.

After successfully creating the account and the subscriber, this site needs to construct a specially crafted URL, which is sent back to the end customer via a side channel. Ideally, this channel would be an SMS if you want to verify the end customer’s mobile number, or an email if you want to check the email address.

The sip:phone app registers a URL schema handler for URLs starting with sipphone://. If you start such a link, the app performs a Base64 decoding of the string right after the sipphone:// prefix and then decrypts the resulting binary string via AES using the keys defined during the branding step. The resulting string is supposed to be

username=$user&server=$domain&password=$password&fsurl=$fsurl&fsttl=$fsttl&country=$country.

Therefore, the 3rd Party Sign-Up Form needs to construct this string using the credentials defined while creating the subscriber via Sipwise C5 API, then encrypt it via AES, and finally perform a Base64 encoding of the result.

The parameters of the string are as follows:

  • username: The SIP username for the login (e.g. testuser)

  • password: The SIP password for the login (e.g. testpass)

  • server: The server string containing either the IP address or a domain resolving via DNS SRV or A records to the load-balancer IP of the deployment (e.g. sip.example.org)

  • fsurl: The filesharing URL for the apps to upload data (e.g. https://sip.example.org:1446/rtc/fileshare/uploads)

  • fsttl: The number of seconds a shared file is valid by default (e.g. 1209600 for 14 days)

  • country: The ISO country code for the app to normalize phone numbers (e.g. de for Germany)

An example Perl code performs encoding of such a string. The AES key and initialization vector ($key and $iv) are the standard values of the sip:phone app and should work until you specify other values during the branding process.

#!/usr/bin/perl -w
use strict;
use Crypt::Rijndael;
use MIME::Base64;
use URI::Escape;

my $key = 'iBmTdavJ8joPW3HO';
my $iv = 'tww21lQe6cmywrp3';

my $plain = do { local $/; <> };
# pkcs#5 padding to 16 bytes blocksize
my $pad = 16 - (length $plain) % 16;
$plain .= pack('C', $pad) x $pad;

my $cipher = Crypt::Rijndael->new(
        $key,
        Crypt::Rijndael::MODE_CBC()
);
$cipher->set_iv($iv);
my $encrypted = $cipher->encrypt($plain);
# store b64-encoded string and print to STDOUT
my $b64 = encode_base64($encrypted, '');
print $b64, "\n";
# print to STDOUT using URL escaping also
print uri_escape($b64), "\n";

This snippet takes a string from STDIN, encrypts it via AES, encodes it via Base64 and sends the result to STDOUT. It also writes the second line with the same string, but this time, the URL is escaped. To test it, you would run it as follows on a shell, granted it’s stored at /path/to/encrypt.pl.

echo -n 'username=testuser&server=example.org&password=testpass&fsurl=https://example.org:1446/rtc/fileshare/uploads&fsttl=3600&country=at' \
  | /path/to/encrypt.pl

This command would result in the output strings like

CI8VN8toaE40w8E4OH2rAuFj3Qev9QdLI/Wv/VaBCVK2yNkBZjxE9eafXkkrQfmYdeu01PquS5P40zhUq8Mfjg==

and like

CI8VN8toaE40w8E4OH2rAuFj3Qev9QdLI%2FWv%2FVaBCVK2yNkBZjxE9eafXkkrQfmYdeu01PquS5P40zhUq8Mfjg%3D%3D

The sip:phone can use the former string to automatically fill in the login form of the Login Screen if started via a Link like

sipphone://CI8VN8toaE40w8E4OH2rAuFj3Qev9QdLI/Wv/VaBCVK2yNkBZjxE9eafXkkrQfmYdeu01PquS5P40zhUq8Mfjg==

Here is the same code in PHP.

#!/usr/bin/php
<?php
$key = "iBmTdavJ8joPW3HO";
$iv = "tww21lQe6cmywrp3";

$clear = fgets(STDIN);
$cipher = fnEncrypt($clear, $key, $iv);

echo $cipher, "\n";
echo urlencode($cipher), "\n";

function fnEncrypt($clear, $key, $iv) {
        $pad = 16 - strlen($clear) % 16;
        $clear .= str_repeat(pack('C', $pad), $pad);
        return rtrim(base64_encode(mcrypt_encrypt(
                MCRYPT_RIJNDAEL_128, $key, $clear,
                MCRYPT_MODE_CBC, $iv)), "\0");
}
?>

Similar to the Perl code, you can call it like this:

echo -n 'username=testuser&server=example.org&password=testpass&fsurl=https://example.org:1446/rtc/fileshare/uploads&fsttl=3600&country=at' \
  | /path/to/encrypt.php

However, a URL with the sipphone:// schema is not displayed as a link in an SMS or an Email client and thus can not be clicked by the end customer, so you need to make a detour via a regular http:// URL. To do so, you need a 3rd Party Launch Handler to trick the phone to open such a link.

Therefore, that the 3rd Party Sign-Up Form needs to return a link containing a URL pointing to the 3rd Party Launch Handler and pass the URL escaped string gathered above to the client via an SMS or an Email. Since it is the regular http:// link, it is clickable on the phone and can be launched from virtually any client (SMS, Email, etc.), which correctly renders an HTML link.

A possible SMS sent to the end customer (via the phone number entered in the sign-up from) could, therefore, look as follows (trying to stay below 140 chars).

http://example.org/p?c=CI8VN8toaE40w8E4OH2rAuFj3Qev9QdLI
%2FWv%2FVaBCVK2yNkBZjxE9eafXkkrQfmYdeu01PquS5P40zhUq8Mfjg%3D%3D to launch sipphone

An HTML Email could look like this:

Welcome to Example.org,
<a href="http://www.example.org/sipphone?c=CI8VN8toaE40w8E4OH2rAuFj3Qev9QdLI
%2FWv%2FVaBCVK2yNkBZjxE9eafXkkrQfmYdeu01PquS5P40zhUq8Mfjg%3D%3D">
click here
</a> to log in.

That way, you can do both: verify the contact details of the end customer, and send the end customer the login credentials in a secure manner.

3rd Party Launch Handler

The URL http://www.example.org/sipphone mentioned above can be any simple script, and its sole purpose is to send back a 301 Moved Permanently or 302 Moved Temporarily with a Location: sipphone://xxxxxxxxxxxx header to tell the phone to open this link via the sip:phone app. The xxxxxxxxxxxx is the plain (non-URL-escaped) string generated by the above script.

An example CGI script performing this task follows.

#!/usr/bin/perl -w
use strict;
use CGI;

my $q = CGI->new;
my $c = $q->param('c');
print CGI::redirect("sipphone://$c");

The script takes the URL parameter c from the URL http://www.example.org/sipphone?c=CI8VN8toaE40w8E4OH2rAuFj3Qev9QdLI%2FWv%2FVaBCVK2yNkBZjxE9eafXkkrQfmYdeu01PquS5P40zhUq8Mfjg%3D%3D crafted above and puts its content into a Location header using the sipphone:// schema, and finally sends a 301 Moved Permanently back to the phone.

The phone follows the redirect by opening the URL using the sip:phone app, which in turn decrypts the content and fills in the login form.

Future versions of Sipwise C5 will be shipped with this launch handler integrated into the system. Up until and including the version mr11.5.1, this script needs to be installed on any webserver manually.

Mobile Push Notification

The mobile push functionality provides the remote start of a mobile application on incoming calls via the Google FCM or the Apple APNS notification services. It enables you to offer your subscribers a modern and convenient service on mobile devices.

Although suspending an application on a phone and waking it up via the mobile push notification service extends battery life, the whole mobile push notification concept is the best effort framework provided by Apple and Google for iOS and Android respectively, and therefore does not guarantee 100% reliability.

Architecture

If the mobile push functionality is enabled and there are no devices registered for a subscriber, the call-flow looks as follows.

Mobile Push Workflow
Figure 62. Mobile Push Workflow

  1. The caller sends INVITE to the Proxy

  2. The callee is offline, the Proxy sends the PUSH request to the GCM/APNS service

  3. If configured, Proxy sends a 18x message to the caller to trigger remote ringing

  4. The GCM/APNS service delivers the PUSH request to the callee

  5. The callee accepts the PUSH request and confirms the mobile application start (unattended on Android), then the mobile application registers at the Proxy

  6. The newly received registration triggers in the Proxy a sending of an INVITE to the callee’s mobile device

  7. The callee accepts the call

  8. The response is sent back to the caller. Hence, the call setup is completed

In case of timeout (no registration notification within certain period of time), Proxy rejects the call request with an error.

Sipwise C5 allows to trigger mobile push notifications even if the callee has a device already registered, thus allowing to have a parallel forking to deskphone and mobile phone. In this case ff the mobile push functionality is enabled the call flow looks as follow.

Mobile Push Workflow
Figure 63. Parallel Mobile Push Workflow

  1. The caller sends INVITE to the Proxy

  2. The callee is online, the Proxy anyway sends the PUSH request to the GCM/APNS service

  3. If configured, Proxy sends a 18x message to the caller to trigger remote ringing

  4. At the same time Proxy sends the INVITE to the callee’s registered device (deskphone)

  5. The GCM/APNS service delivers the PUSH request to the callee

  6. The callee’s mobile device accepts the PUSH request and confirms the mobile application start (unattended on Android), then the mobile application registers at the Proxy

  7. The newly received registration triggers in the Proxy a sending of an INVITE to the callee’s mobile device

  8. The callee accepts the call using one of its devices

  9. The response is sent back to the caller. Hence, the call setup is completed

  10. Proxy sends a CANCEL message to the other ringing device

The Configuration Checklist

Follow this checklist to make sure you have completed all the steps. If steps are not completed in their entirety, the service may not work as expected.

Name Description Link

Obtain a trusted SSL certificate from a CA

Required for either application

Obtain the Trusted SSL Certificate

Create an Apple developer account and enable the push notification service

For iOS mobile application

Create an Apple Account and Enable the Push Notification Service

Obtain the Apple certificate for the app

For iOS mobile application

Obtain an Apple SSL Certificate and a Private Key

Obtain the API key for the app from Google

For Android mobile application

Obtain the API Key for the App from Google

Provide the required information to developers

It is required to make beta builds and publish the apps

Provide the Required Information to Developers

Adjust the configuration

Adjust the config.yml file and apply the changes (usually performed by Sipwise)

Adjust Sipwise C5 Configuration (Usually Performed by Sipwise)

Recheck your DNS Zone configuration

Check that the DNS Zone is correctly configured

Recheck Your DNS Zone Configuration

Add DNS SRV records

Create specific DNS SRV records for SIP and XMPP services

Add SRV Records to DNS

Check NTP configuration

Ensure that all your servers show exact time

Check NTP Configuration

Enable Apple/Google Mobile Push in the Admin Panel

It can be enabled for a domain or separate subscribers

Enable Apple/Google Mobile Push

Configure a mobile application

Check that subscribers can easily install and use your application

Perform Tests

Obtain the Trusted SSL Certificate

A trusted SSL certificate is required, and we suggest obtaining it before starting the configuration.

The mobile application uses respective iOS/Android libraries to establish a secure TLS connection with certain Sipwise C5 services, such as SIP/XMPP/pushd(https). A signed SSL certificate is required to guarantee the security of this connection.

Any Certificate Authority (CA) such as Verisign and others can provide you with the required trusted SSL certificate (a certificate and the key files) which you will use in the configuration below.

Create an Apple Account and Enable the Push Notification Service

Below is a brief instruction on how to create an Apple account and enable the Push Notification Service in it. You may need to perform additional steps depending on your project.

You may only create an Apple account (step 1 below) and enroll into the Apple Developer Program (step 2 below) and Sipwise developers will do the rest. Still, you can perform all the steps by yourself.

  1. Create an Apple developer account to get the Apple ID for your company. For this, go to https://developer.apple.com/account

  2. Enroll in the Apple Developer Program. It is required to configure push notifications as you will need a push notification certificate for your App ID, which requires the Apple Developer Program membership. Go to https://developer.apple.com/programs for more details.

  3. Register an App ID:

    • Sign into https://developer.apple.com/account.

      Register an App ID - Main
      Figure 64. Register an App ID - Main

    • Click Certificates, IDs & Profiles.

      Register an App ID - Certificates, IDs & Profiles
      Figure 65. Register an App ID - Certificates, IDs & Profiles

    • Under Identifiers, select App IDs.

      Register an App ID - App IDs
      Figure 66. Register an App ID - App IDs

    • Click the Add button (+) in the upper-right corner.

      Register an App ID - New
      Figure 67. Register an App ID - New

    • Enter a name for the App ID in the App ID Description block. This helps you identify the App ID later.

      Register an App ID - Details
      Figure 68. Register an App ID - Details

    • Select Explicit App ID and enter the app’s bundle ID in the Bundle ID field. Note that an explicit App ID exactly matches the bundle ID of an app you are building — for example, com.example.push. An explicit App ID can not contain an asterisk (*).

      Register an App ID - Services
      Figure 69. Register an App ID - Services

    • In the App Services section enable Push Notifications. Click Continue to submit the form

      Register an App ID - Confirmation
      Figure 70. Register an App ID - Confirmation

    • Click Submit to create the App ID.

Obtain an Apple SSL Certificate and a Private Key

  1. Create a CSR (Certificate Signing Request):

    • Sign into https://developer.apple.com/account/ios/certificate.

      Create CSR - Main
      Figure 71. Create CSR - Main

    • Click the Add button (+) in the upper-right corner.

      Create CSR - Add
      Figure 72. Create CSR - Add

    • Select Apple Push Notification service SSL (Sandbox & Production) as the certificate type and click Continue.

      Create CSR - Select App ID
      Figure 73. Create CSR - Select App ID

    • Select your App ID and click Continue.

      Create CSR - Confirm App ID
      Figure 74. Create CSR - Confirm App ID

    • Read the information about creating a CSR.

    • Follow the instructions to create a CSR using Keychain Access in MAC.

      If you do not have access to a Mac, you can still create a CSR in Linux or Windows using OpenSSL, for example.

  2. Get the Certificate and Private Key

    • When you have the CSR file return to the browser and click Continue.

      Create CSR - Generate Certificate
      Figure 75. Create CSR - Generate Certificate

    • Click Choose File…​ in your browser.

      Create CSR - Upload Certificate
      Figure 76. Create CSR - Upload Certificate

    • Select the CSR file you just created and saved and click Continue.

      Create CSR - Download Certificate
      Figure 77. Create CSR - Download Certificate

    • Click Download to download the certificate (give it the aps.cer name).

    • Open the downloaded certificate file (it should automatically be opened in Keychain Access, otherwise open it manually in Keychain Access).

    • Find the certificate you just opened/imported in Keychain Access.

    • Expand the certificate to show the Private Key.

    • Select only the Private Key portion of the certificate, right-click on it and select Export "Common Name"…​ from the menu.

    • Choose a location (e.g. Desktop) and filename to export the .p12 file to and click Save.

    • Optionally pick a password for the .p12 file to protect its private key contents and click OK. (You will then need to enter your log-in password to permit the export).

  3. Generate a PEM file from the p12 file:

    • Open up your terminal and run the following commands to create a PEM file from the p12 file (If you input a password for the p12 file, you will need to enter it here):

cd ~/Desktop
openssl x509 -in aps.cer -inform der -out PushChatCert.pem
openssl pkcs12 -in PushChatCert.p12 -out PushCertificate.pem -nodes –clcerts
openssl pkcs12 -nocerts -out PushChatKey.pem -in PushChatKey.p12

Obtain the API Key for the App from Google

You can use Google Firebase Cloud Messaging (FCM) to send push notifications to your subscribers with Android-based mobile devices. Google Cloud Messaging is a free service that acts as an intermediary between Sipwise C5 and devices of your subscribers. Google’s Cloud Connection Server (CCS), a part of GCP, manages the persistent connections with mobile devices to deliver your push notifications.

While communicating with CCS, Sipwise C5 identifies itself using an API key. To get it, follow the steps below.

  1. Create a new project in the Google APIs Console page. For this go to code.google.com/apis/console.

    Google API Manager
    Figure 78. Google API Manager

  2. Click Create a Project..

    New Project creation
    Figure 79. New Project creation

  3. Input the project name, agree with the Terms of Service and click Create.

    Google Cloud Messaging
    Figure 80. Google Cloud Messaging

  4. Click Google Cloud Messaging on the Overview page.

    Enabling Google Cloud Messaging
    Figure 81. Enabling Google Cloud Messaging

  5. Click Enable for the Google Cloud Messaging.

    Adding Credentials
    Figure 82. Adding Credentials

  6. Click Go to Credentials.

    The Add Credentials page
    Figure 83. The Add Credentials page

  7. Select Google Cloud Messaging and Web Server from the corresponding lists and click What credentials do I need?

    Create API key
    Figure 84. Create API key

  8. Adjust the API Key name and input the IP addresses of all your load balancers under Accept requests from these server IP addresses. Click Create API key.

    You may skip adding the IP addresses, otherwise list ALL your load balancers.
    API key created
    Figure 85. API key created

  9. Copy your API key and click Done. Save the API key for future use.

    Done
    Figure 86. Done

Provide the Required Information to Developers

Please, provide Sipwise developers with the following files and information so that they can make beta builds and submit the application to the App Store:

  • Access to your Apple developer account

  • The trusted SSL certificate and its private key

  • The Apple SSL certificate and its private key

For the Android application, provide the following:

  • Access to your Google developer account

  • Google application API key

Adjust Sipwise C5 Configuration (Usually Performed by Sipwise)

  1. Upload the Apple SSL certificate (PushChatCert.pem) and the private key (PushChatKey.pem) to /etc/ngcp-config/shared-files/ssl/

  2. Upload the trusted SSL certificate (CAsigned.crt) and the private key (CAsigned.key) to /etc/ngcp-config/shared-files/ssl/

  3. Specify the corresponding paths and names in the pushd section of the config.yml file:

    • apns: section (For iOS mobile application)

      • certificate: \'/etc/ngcp-config/shared-files/ssl/PushChatCert.pem'

      • enable: yes

      • key: \'/etc/ngcp-config/shared-files/ssl/PushChatKey.pem'

    • enable: yes

    • android: section (for Android mobile application)

      • enable: yes

      • key: \'google_server_api_key_here'

    • ssl: yes

    • sslcertfile: /etc/ngcp-config/shared-files/ssl/CAsigned.crt

    • sslcertkeyfile: /etc/ngcp-config/shared-files/ssl/CAsigned.key

    You can find an example of /etc/ngcp-config/config.yml configuration in the config.yml overview section.

  4. Apply your changes:

ngcpcfg apply 'enabled the backup feature.'
ngcpcfg push all

Recheck Your DNS Zone Configuration

Check that your NS and A DNS records are correctly configured.

Let us consider the following example: * the load-balancers have the lb01a.example.com and the lb01b.example.com names * the shared name is lb01.example.com and the shared IP address is 1.1.1.1 * the service name is voipservice.example.com

The following DNS records must be present:

Server Name

Record type

IP Address

lb01a.example.com

A

1.2.3.4

lb01b.example.com

A

5.6.7.8

lb01.example.com

A

1.1.1.1

voipservice.example.com

A

1.1.1.1

Add SRV Records to DNS

Add at least one record for each service: xmpp-server, xmpp-client, sips.

A regular SRV record has the following form:

_service._proto.name. TTL class SRV priority weight port target

  • service: the symbolic name of the service (xmpp-server, xmpp-client, sips).

  • proto: the transport protocol of the desired service (TCP).

  • name: the domain name (ending in a dot).

  • TTL: standard DNS time to live field.

  • class: the standard DNS class field (this is always IN).

  • priority: the priority of the target host (lower value means more preferred).

  • weight: a relative weight for records with the same priority (the higher the value, the more requests will be sent).

  • port: the TCP or UDP port of the service.

  • target: the canonical hostname of the machine providing the service (ending in a dot).

Here are examples of the SRV records:

_xmpp-server._tcp.voipservice.example.com. 18000 IN SRV 10 50 5269 voipservice.example.com.
_xmpp-client._tcp.voipservice.example.com. 18000 IN SRV 10 50 5222 voipservice.example.com.
_sips._tcp.voipservice.example.com. 18000 IN SRV 10 100 5061 voipservice.example.com.

You can always check whether the required SRV records are configured by executing the following commands:

dig SRV _xmpp-client._tcp.voipservice.example.net
dig SRV _xmpp-server._tcp.voipservice.example.net
dig SRV _sips._tcp.voipservice.example.net

Check NTP Configuration

We strongly suggest that the clocks of all the nodes within the platform are synchronized. To ensure this, check that the NTP service is correctly configured on all your Sipwise C5 servers and works reliably. Execute the following command for quick test of time synchronization:

timedatectl

If the current node synchronizes with an NTP server, this server will be marked by 'NTP service: active'.

Execute the following command to get the NTP service status:

timedatectl timesync-status

When using the optional 'ntpd' implementation instead of the default 'systemd-timesyncd', execute the following command to get the time synchronization status:

ntpq -p

If the current node synchronizes with an NTP server, this server will be marked by the star ('*') symbol.

Enable Apple/Google Mobile Push

It can be enabled for a domain or separate subscribers in the web administration panel or using API.

To enable the service:

  1. Go to Domain Preferences or Subscriber Preferences of the domain/subscriber you want to enable Apple/Google Mobile Push for.

  2. Go to the Internals group and enable the mobile_push_enable parameter selecting one of the following options:

    • Never send push: the mobile push feature is disabled.

    • Always send push: the mobile push will be triggered every time the subscriber receives a call in parallel with the already registered devices, if there are any.

    • Send push only if no device registered: the mobile push will be triggered only if the subscriber doesn’t have any registered device. In case there is one or more devices registered only those will receive the incoming call.

    • Always send push, skip registered devices: the mobile push will be triggered immediately disregarding the already registered devices. That means, already registered devices do not receive the incoming call.

    • Registered devices, then send push: the Sipwise C5 will call the already registered devices as first. In case of failure (devices reject the call) it will then trigger the mobile push.

    • Send push, then registered devices: the Sipwise C5 will trigger the mobile push as first. In case of failure (push service return an error or the mobile devices reject the call) it will then send the call to the already registered devices.

Domain Preferences
Figure 87. Domain Preferences
Mobile Push Preferences
Figure 88. Mobile Push Preferences
Mobile Push Options
Figure 89. Mobile Push Options

Perform Tests

Perform tests when the application is available:

  1. Download and install the application.

  2. Open the application and input your registration username in the username@domain.name format and password.

  3. Review the quality of application branding.

  4. Make test calls.

  5. Test the presence functionality.

  6. Test the chat and group chat.

  7. Test messaging.

  8. Test the sharing functionality (e.g. pictures, video and voice messages and maps).

  9. Check the application phone book integration with the phone’s one

Make sure that the subscribers can start using your services in the easiest possible way.

Lawful Interception

Introduction

The Sipwise C5, as a communications platform carrying voice, fax and messaging data has to provide means for lawful interception of the content of communication by third party entities. Those Law Enforcement Agencies (LEAs) have to be able to connect to Sipwise C5 platform in a standardized way — ETSI, 3GPP and other organisations define the interface (and data exchange) between telecommunication operators and LEAs.

High level overview of lawful interception is shown in the following figure:

LI: High Level Overview
Figure 90. LI: High Level Overview

Main interfaces of lawful interception according to ETSI standard:

LI: ETSI Interfaces
Figure 91. LI: ETSI Interfaces

Terms and Abbreviations

Content of Communication (CC)

Information exchanged between two or more users of a telecommunications service, excluding Intercept Related Information.

This includes information which may, as part of some telecommunications service, be stored by one user for subsequent retrieval by another.
CC Internal Interception Function (CC-IIF)

The CC-IIF shall cause the CC, specified by the CCTF, via the CCCI to be duplicated and passed to the MF.

Content of Communication Control Interface (CCCI)

Carries controls information from the CCTF to the CC-IIF.

CC Trigger Function (CCTF)

The purpose of the CCTF is to determine the location of the CC-IIF device associated to the target CC traffic, and to control the CC-IIF via the CCCI interface.

Content of Communication Trigger Interface (CCTI)

Carries trigger information from the IRI-IIF to the CCTF.

Handover Interface (HI)

Physical and logical interface across which the interception measures are requested from an operator, and the results of interception are delivered from an operator to an LEMF.

Intercept Related Information (IRI)

Collection of information or data associated with telecommunication services involving the target identity, specifically call or service associated information or data (e.g. call identifier, unsuccessful call attempts) and location information.

Intercept Related Information Internal Interception Function (IRI-IIF)

The purpose of the IRI-IIF is to generate IRI information associated with sessions, calls, connections and any other information involving interception targets identified by Law Enforcement Agency (LEA) sessions.

Internal Network Interface (INI)

Network’s internal interface between the Internal Intercepting Function and a mediation function.

Law Enforcement Agency (LEA)

Organization authorized, by a lawful authorization based on a national law, to request interception measures and to receive the results of telecommunications interceptions.

Law Enforcement Monitoring Facility (LEMF)

Law enforcement facility designated as the transmission destination for the results of interception relating to a particular interception subject.

Lawful Interception Administration Function (AF)

The AF ensures that an intercept request from a LEA for IRI or CC or both is provisioned for collection from the network, and subsequent delivery to the LEMF.

Lawful Interception Mediation Function (MF)

Mechanism which passes information between an access provider or network operator or service provider and a handover interface.

  1. Firstly it receives information related to active intercepts from the IRI-IIF(s) and CC-IIF(s) within the service provider network.

  2. Secondly correlates and formats that IRI and CC information in real time for delivery to the LEMF over the HI2 and HI3 handover Interfaces.

X1, X2 and X3 Interfaces

The 3GPP standard for Lawful Interception defines the handover interfaces with different names compared to the ETSI standard. The Xn interface corresponds to the INIn interface and is functionally identical to the INIn interface.

Architecture and Configuration of LI Service

The Sipwise C5 platform implements the functions defined by LI requirements in a way that it relies on a third party provider for the Lawful Interception Mediation Function (MF).

Regarding other LI functions that are defined by ETSI / 3GPP standards there are 2 possible implementations:

  1. The Sipwise C5 behaves as the Administration Function (AF) but the actual call data capturing is carried out by other SIP endpoints. In this case the Sipwise C5 forwards the calls to be intercepted to its SIP peers dedicated for LI service. Within the scope of SIP peer based solution there are still 2 modes of operation:

    • Call loopback to NGCP: the LI peer receives the call, extracts IRI and CC data and then routes the call back to NGCP. The Sipwise C5 handles the looped back call as if that was initiated from the Sipwise C5 and sets up the second call leg to the destination.

    • Call forwarded by peer directly to destination: in this case the Sipwise C5 will handle the call to LI peer as an ordinary second call leg to the destination.

  2. Sipwise Sipwise C5 itself provides the required LI functions: AF and call data capturing; IRI and CC of intercepted calls are forwarded to the third party MF from NGCP. Sipwise C5 can be configured in two modes:

    • Non-Distributed: The LI roles are hosted on the PROXY nodes. The REST API endpoint to LEA will be the usual MGMT nodes.

    • Distributed: The LI roles are hosted on geographically distributed LB+RTP nodes, for example one pair of LB+RTP nodes per country, each of which has different law enforcement authorities. The LB+RTP nodes will provide an ngcp-panel instance, which due to privacy laws is specially configured to store intercepts locally (the node will operate on its own set of data), and the external party (law enforcement, LI integration, etc.) interacts with the pertinent LB+RTP nodes via the REST API (or SOAP for older installations).

This handbook will discuss the second setup in detail in the following sections.

The below figure illustrates the logical connection of LI functions on the Sipwise C5.

LI with 3rd Party Provider
Figure 92. LI with 3rd Party Provider

Architecture Based on NGCP Voisniff Module

The implementation of LI services with captagent is no longer available and configurable on the Sipwise C5, Sipwise requires deploying a revised solution with its ngcp-voisniff software module. This newer implementation also relies on a 3rd party LI provider representing the LI Mediation Function (MF), where Sipwise currently cooperates with Group2000, Pine and Utimaco.

Sipwise C5 components providing LI functions:

  • ngcp-panel: this module is responsible for managing REST API for the whole NGCP in general

    • runs on: the active node with web role (sp on PRO; web01 on CARRIER) on a Sipwise C5 platform

    • LI functions: AF; INI1 / X1 interface towards the MF

  • kamailio-proxy: this module serves as a generic call control function on the NGCP

    • runs on: the active node typically with proxy role (sp on PRO; prx01 on CARRIER) on a Sipwise C5 platform

    • LI functions: CCTF and IRI-IIF; INI2 / X2 interface towards the MF

  • ngcp-voisniff: this module is a generic element for capturing SIP and RTP traffic on the NGCP

    • runs on: the active node typically with lb role (sp on PRO; lb01 on CARRIER) on a Sipwise C5 platform

    • LI functions: CC-IIF; INI3 / X3 interface towards the MF

The ngcp-voisniff module is installed by default but not activated on the Sipwise C5. It provides the possibility to get call statistics through the Admin web interface, and is not readily configured for LI services. Please contact Sipwise if you need to activate LI services on the platform.

Authentication and Confidentiality

It is required that the communication between the telecommunication operator’s network element (that is: Sipwise C5) and the MF be authenticated and confidential, since the intercepted session related data and content of communication must not be disclosed to any 3rd party. For this purpose NGCP’s LI service applies authentication and LI session data encryption based on public key cryptography mechanism (TLS).

Both the Sipwise C5 and the MF must authenticate themselves by certificates, for this reason the Sipwise C5 operator must ensure that valid certificates are deployed on the system. You must contact the 3rd party LI provider, so that they can provide the necessary client certificates that the Sipwise C5 will use to setup secured connection to the MF on X2 and X3 interfaces.

Similarly, the MF provider must contact the Sipwise C5 operator to offer him valid client certificates that the MF element will use to establish secured connection to the Sipwise C5 on X1 interface.

Configuration of LI Service

To enable LI services on the Sipwise C5 the platform administrator has to enable lawful interception through the main configuration file (config.yml).

For a distributed setup, the cluster_sets.type variable has to be set to 'distributed' (see cluster_sets.type for more information), and the lb nodes need to be assigned the li role. For a non-distributed setup, the proxy nodes need to be assigned the li role.

From the user and program point of view, the li role will only be visible in a node if the intercept.enable setting is set to 'yes'. When the cluster is set up in a distributed mode (that is cluster_sets.type is set to 'distributed'), the nodes will also have the li_dist virtual role visible (which is synthesized at run-time and cannot be specified in the node configuration), so that these can check for a single condition instead of multiple.

Here below is a sample configuration, which shows parameters of intercept and voisniff sections.

On a CARRIER it would look like:

intercept:
  enable: yes
  local: no
  peer:
    acc: no
    inbound_prefix: LI_
    outbound_prefix: intercept_
  type: voisniff

voisniff:
  admin_panel: no
  daemon:
    custom_bpf: ''
    filter:
      exclude:
      - active: '0'
        case_insensitive: '1'
        pattern: '\ncseq: *\d+ +(register|notify|options)'
      include: []
      sip_ports:
      - 5060
      - 5062
    interfaces:
      extra: []
      types:
      - sip_int
      - sip_ext
      - rtp_ext
    li_x1x2x3:
      call_id:
        del_patterns:
        - _pbx\-1(?:_[0-9]{1,10})?$
        - _b2b\-1(?:_[0-9]{1,10})?$
        - _xfer\-1(?:_[0-9]{1,10})?$
      captagent:
        cin_max: '3000'
        cin_min: '0'
        x2:
          threads: 20
      client_certificate: /etc/ngcp-config/shared-files/ssl/li/x23_client/x23_client_cert.pem
      enable: yes
      fix_checksums: no
      fragmented: no
      interface:
        excludes: []
      local_name: sipwise
      private_key: /etc/ngcp-config/shared-files/ssl/li/x23_client/x23_client_cert_priv_key.pem
      split_intercept: no
      x1:
        port: '18090'
      x23:
        protocol: sipwise
    mysql_dump:
      enable: no
      max_query_len: 67108864
      num_threads: '4'
    rtp_filter: yes
    start: yes
    threads_per_interface: '10'
  partitions:
    increment: '700000'
    keep: '10'

On a PRO it would look like:

intercept:
  enable: no
  local: no
  peer:
    acc: no
    inbound_prefix: LI_
    outbound_prefix: intercept_
  type: none

voisniff:
  admin_panel: yes
  daemon:
    custom_bpf: ''
    filter:
      exclude:
      - active: '0'
        case_insensitive: '1'
        pattern: '\ncseq: *\d+ +(register|notify|options)'
      include: []
      sip_ports:
      - 5060
      - 5062
    interfaces:
      extra: []
      types:
      - sip_int
      - sip_ext
      - rtp_ext
    li_x1x2x3:
      call_id:
        del_patterns:
        - _pbx\-1(?:_[0-9]{1,10})?$
        - _b2b\-1(?:_[0-9]{1,10})?$
        - _xfer\-1(?:_[0-9]{1,10})?$
      captagent:
        cin_max: '3000'
        cin_min: '0'
        x2:
          threads: 20
      client_certificate: ''
      enable: no
      fix_checksums: no
      fragmented: no
      interface:
        excludes: []
      local_name: sipwise
      split_intercept: no
      x1:
        port: '18090'
      x23:
        protocol: sipwise
    mysql_dump:
      enable: yes
      max_query_len: 67108864
      num_threads: '4'
    rtp_filter: yes
    start: yes
    threads_per_interface: '2'
  partitions:
    increment: '700000'
    keep: '10'

Configuration Parameters

intercept.enable

Set it to yes if you want to activate LI service. Default: no

intercept.local

On CARRIER systems, if set to yes, intercept data will be stored on the local system instead of the central database node.

intercept.peer.acc

Calls to be intercepted may be forwarded to LI peers. The LI peer may forward the call to the original destination, without looping the call back to the Sipwise C5. Set this parameter to yes if you want to enable billing for such calls. Default: no

intercept.peer.inbound_prefix

Calls to be intercepted may be forwarded to LI peers. This parameter specifies the prefix that is prepended to SIP usernames when the call is looped back to the Sipwise C5, in order to avoid sending the call again to any LI peer. Used by the Sipwise C5 internally. Default: LI_

intercept.peer.outbound_prefix

Calls to be intercepted may be forwarded to LI peers. This parameter specifies the prefix that is prepended to SIP usernames when the call is routed to an LI peer. It will be stripped off by rewrite rules of the peer, before sending the call effectively to the peer. Used by the Sipwise C5 internally. Default: intercept_

intercept.type

The LI service provider module; allowed values are:

  • none: LI service is not activated

  • peer: LI service is activated and call data capturing is performed by SIP peers

  • voisniff: LI service is activated and call data capturing is performed by the voisniff module

Default: none

voisniff.admin_panel
voisniff.daemon.mysql_dump.*
voisniff.partitions.*

These parameters are not used in LI configuration, but only for call statistics which can be retrieved through the Admin web interface.

voisniff.daemon.custom_bpf

Allows the operator to set a custom packet filter to be used when capturing packets on the network interfaces, overriding the default packet filter generated by the system based on other configuration settings (port ranges, etc). It is not normally necessary to set this. Default: empty

voisniff.daemon.filter.exclude

Additional filter to determine packets that need to be excluded from capturing. This configuration parameter is a list of items, each of them has 3 components:

  • active: Determines whether the filter is active or not. Allowed values are: 0 (false/inactive; this is the default) or 1 (true/active).

  • case_insensitive: Determines whether the pattern is case-insensitive (1; this is the default) or not (0).

  • pattern: A regular expression providing the matching pattern for packets that have to be filtered.

voisniff.daemon.filter.include

Additional filter to determine packets that need to be included in capturing. The parameter has the same syntax as voisniff.daemon.filter.exclude.

voisniff.daemon.filter.sip_ports

A list of ports that should be considered to carry SIP traffic. Intercepted packets that do not involve one of these ports will not be attempted to be parsed as SIP packets. This filter can be disabled by having this list empty. Default: 5060 and 5062

voisniff.daemon.interfaces.extra

This is a list of additional network interfaces (typically VLAN IDs) where ngcp-voisniff should listen for and capture packets. These interfaces are in addition to the list of interfaces generated by the system based on the interface types (see below).

VLAN interfaces have to be listed when they are used for intercepted calls. On the other hand virtual interfaces for additional IP addresses (e.g. eth0:1) do not have to be listed separately, because the base interface (e.g. eth0) will be used to capture packets.
voisniff.daemon.interfaces.types

A list of network interface types that should be activated for interception. All interfaces that match the given types will be activated. Default: sip_int, sip_ext, and rtp_ext

voisniff.daemon.li_x1x2x3.call_id.del_patterns

List of NGCP-internal Call-ID suffix patterns that should be ignored when determining the original SIP Call-ID of an intercepted call.

Please refrain from modifying these patterns unless explicitly directed to do so by a Sipwise engineer. Changing the patterns may result in falsely recognised Call-IDs and eventually missed SIP messages during an intercepted call.
voisniff.daemon.li_x1x2x3.captagent.cin_min
voisniff.daemon.li_x1x2x3.captagent.cin_max

When using the captagent-compatible protocol, this specifies the range of intercept ID numbers (CIN) to be generated. Default: 0 through 3000

voisniff.daemon.li_x1x2x3.captagent.x2.threads

When using the captagent-compatible protocol, this specifies the number of threads to be used for sending outgoing X2 (SIP) captures. Interception may stall if this number if set too low. Default: 20

voisniff.daemon.li_x1x2x3.client_certificate

The client certificate that Sipwise C5 uses to connect over TLS to a 3rd party LI provider. Relevant only when using the sipwise outbound protocol.

voisniff.daemon.li_x1x2x3.enable

Set it to yes to enable LI services via X1, X2 and X3 interfaces. Default: no

voisniff.daemon.li_x1x2x3.fix_checksums

When enabled (= yes), Sipwise C5 will calculate UDP header checksum for packets sent out on X2 and X3 interfaces. This is necessary when the checksum calculation is normally left to the network interface hardware and therefore the UDP header checksum is inherently incorrect on application level. Also the UDP checksum must be calculated by ngcp-voisniff on re-assembled packets, so enable this option if there are fragmented packets in intercepted call traffic. Default: disabled (= no)

voisniff.daemon.li_x1x2x3.fragmented

When disabled (= no), ngcp-voisniff defragments all packets and sends out only reassembled packets via X2 and X3 interfaces. If the option is enabled (= yes), ngcp-voisniff will instead send out the original fragments via X2 and X3. Default: no

voisniff.daemon.li_x1x2x3.instant_intercept

When disabled (= no), creating a new interception object does not affect already running calls. In other words, if a call that is already running matches the parameters by a newly created interception object, that call will not start to be intercepted, only new calls established afterwards will. Enabling this option changes this behaviour so that already running calls will also start to be intercepted at the moment when a new interception object is created. Doing so creates additional processing overhead within ngcp-voisniff. Default: no

voisniff.daemon.li_x1x2x3.interface.excludes

This is a list of interfaces that must be excluded from the interception procedures. The list contains regular expressions that describe the to-be-excluded interfaces, for example: - ^lo$ to exclude the loopback interface. Default: empty list

voisniff.daemon.li_x1x2x3.local_name

This parameter maps to the header.source field of the X2 protocol. It is an arbitrary string and can be used to identify the sending Sipwise C5 system. Default: sipwise

This is currently not used.
voisniff.daemon.li_x1x2x3.private_key

The private key that Sipwise C5 uses to connect over TLS to a 3rd party LI provider. Only necessary if the client certificate file does not include the private key.

voisniff.daemon.li_x1x2x3.split_intercept

When enabled (= yes), ngcp-voisniff uses the Split-LI algorithm to detect which calls have to be intercepted. This algorithm should be enabled only on CARRIER systems with a central core and local satellites architecture and ngcp-voisniff running on LB nodes. Default: no

voisniff.daemon.li_x1x2x3.x1.port

The port number on which ngcp-voisniff listens for incoming X1 messages. Default: 18090

Please refrain from modifying these patterns unless explicitly directed to do so by a Sipwise engineer.
voisniff.daemon.li_x1x2x3.x23.protocol

Specified the outbound protocol to speak when delivering X2 (SIP) or X3 (RTP) data. This can be either the sipwise protocol using TLS connections, or the captagent compatible protocol using HTTP and UDP. Default: sipwise

voisniff.daemon.mysql_dump.enable

Master switch for call statistics collection. Default: yes

voisniff.daemon.mysql_dump.max_query_len

Determines how much data should be gathered into a single statement for insertion into the database. This should not normally be changed. Default: 67108864

voisniff.daemon.mysql_dump.num_threads

The number of threads dedicated to inserting data into the database. Default: 4

voisniff.daemon.rtp_filter

Determined whether to intercept RTP packets or not. Enabling the filter (set to yes) suppresses interception of RTP packets. Disabling it (no) enabled interception of RTP packets. Default: yes

voisniff.daemon.start

Determines whether voisniff service must be started on the platform. Set it to yes if you would like to activate voisniff. Default: no (on CARRIER), yes (on PRO)

voisniff.daemon.threads_per_interface

This is a performance tuning option and controls how many threads per enabled sniffing interface should be launched. Example: if it is set to 10, and 3 interfaces are enabled for sniffing, a total of 30 threads will be launched. Default: 2

It is recommended not to increase too much this number unless there is a performance problem with voisniff service. Please keep in mind that a high number of threads might also decrease the overall system performance of the Sipwise C5.

X1, X2 and X3 Interface Specification

Short description of Xn interfaces:

  • The X1 interface is used by an LI provider to create, modify, delete and list interceptions on the Sipwise C5. It is designed as RESTful HTTP interface using JSON (with JSON-HAL in responses from the NGCP) as content type to provision interceptions.

  • The X2 interface is a TLV based interface with JSON payload with a simple request/response mechanism over a secure TLS connection, used to pass intercepted signaling data towards an LI provider.

  • The X3 interface is also a TLV based interface with a binary payload encapsulating the intercepted RTP data.

X1 Interface

The resource used to work with interceptions is always https://ngcp-ip:1443/api/interceptions/

Authentication

Authentication and authorization on the Sipwise C5 API is performed via HTTP Basic Auth or SSL Client certificates.

  • HTTP Basic Auth: With cURL use --user username:password option to specify your access credentials.

    curl ­-i -­X GET --­­user myuser:mypassword https://example.org:1443/api/interceptions/

    Additionally use the ­­--insecure option if you are testing against a self-signed server certificate.

  • SSL Client Authentication: You can generate and download client certificates for administrators and resellers via the Sipwise C5 web interface in the Administrators view.

    For the actual client authentication, you will need two files which you can download from the panel after creating the client certificates:

    1. The client certificate generated via the Sipwise C5 web interface. This is usually labelled NGCP-API-client-certificate-xxxxx.pem.

    2. The CA certificate used to sign the server certificate, in case it as been self-signed or the CA is not recognized by the client host environment.

    With cURL use ­­--cert /path/to/NGCP­API­client­certificate­xxxxx.pem to specify the client certificate, and ­­--cacert /path/to/ca­cert.pem to specify the CA certificate in case of a self-signed server certificate.

    curl ­-i -­X GET ­­--cert /path/to/NGCP­API­client­certificate­xxxxx.pem \
--­­cacert /path/to/ca­cert.pem https://example.org:1443/api/interceptions/

    Additionally use the --insecure option if you are testing against a self-signed server certificate.

API Description

Collection Actions

Allowed methods for the collection as in METHOD /api/interceptions/

  • OPTIONS

  • POST

  • GET

  • HEAD

Item Actions

Allowed methods for a collection item as in METHOD /api/interceptions/id

  • PATCH

  • OPTIONS

  • DELETE

  • PUT

  • GET

  • HEAD

Properties

  • liid (Number): The LI ID for this interception.

  • number (String): The number to intercept.

  • x2_host (String): The IP address of the X2 interface.

  • x2_password (null, String): The password for authenticating on the X2 interface.

  • x2_port (Number): The port of the X2 interface.

  • x2_user (null, String): The username for authenticating on the X2 interface.

  • x3_host (null, String): The IP address of the X3 interface.

  • x3_port (null, Number): The port of the X3 interface.

  • x3_required (null, Boolean): Whether to also intercept call content via X3 interface (false by default).

Query Parameters

  • liid: Filter for interceptions of a specific interception ID

  • number: Filter for interceptions of a specific number (in E.164 format)

  • order_by: Order collection by a specific attribute. Possible values are: id, reseller_id, liid, number, cc_required, delivery_host, delivery_port, delivery_user, delivery_pass, modify_timestamp, create_timestamp, deleted, uuid, sip_username, sip_domain, cc_delivery_host, cc_delivery_port

  • order_by_direction: Direction which the collection should be ordered by. Possible values are: asc (default), desc

API Examples

Get a specific interception

  • Request:

    curl -­i --­­insecure --­­user administrator:administrator -­X GET
https://localhost:1443/api/interceptions/528

  • Response:

    HTTP/1.1 200 OK
Server: nginx
Date: Tue, 01 Dec 2015 09:43:41 GMT
Content­Type: application/hal+json; profile="http://purl.org/sipwise/ngcp­api/";
  charset=utf­8
Content­Length: 634
Connection: keep­alive
Link: </api/interceptions/>; rel=collection
Link: <http://purl.org/sipwise/ngcp­api/>; rel=profile
Link: </api/interceptions/528>; rel="item self"
Set­Cookie: ngcp_panel_session=35b56d921c36c1fc6edb8fcd0a86dd9af61ec62a; path=/;
  expires=Tue, 01­Dec­ 2015 10:43:41 GMT; HttpOnly
Strict­Transport­Security: max­age=15768000
  {
    "_links" : {
      "collection" : {
        "href" : "/api/interceptions/"
      },
      "curies" : {
        "href" : "http://purl.org/sipwise/ngcp­api/#rel­{rel}",
        "name" : "ngcp",
        "templated" : true
      },
      "profile" : {
        "href" : "http://purl.org/sipwise/ngcp­api/"
      },
      "self" : {
        "href" : "/api/interceptions/528"
      }
    },
    "id" : 528,
    "liid" : 918273,
    "number" : "0014155550132",
    "x2_host" : "192.168.42.42",
    "x2_password" : null,
    "x2_port" : 3002,
    "x2_user" : null,
    "x3_host" : "192.168.42.42",
    "x3_port" : 3003,
    "x3_required" : true
  }

Get all interceptions for a number

  • Request:

    curl -­i --­­insecure ­--­user administrator:administrator -­X GET \
https://localhost:1443/api/interceptions/?number=0014155550132

  • Response:

    HTTP/1.1 200 OK
Server: nginx
Date: Tue, 01 Dec 2015 09:47:36 GMT
Content­Type: application/hal+json; profile="http://purl.org/sipwise/ngcp­api/";
  charset=utf­8
Content­Length: 1283
Connection: keep­alive
Set­Cookie: ngcp_panel_session=238550c5737058db619b183d925b5f9a61261cfe; path=/;
  expires=Tue, 01­ Dec­ 2015 10:47:36 GMT; HttpOnly
Strict­Transport­Security: max­age=15768000
{
   "_embedded" : {
      "ngcp:interceptions" : {
         "_links" : {
            "collection" : {
               "href" : "/api/interceptions/"
            },
            "curies" : {
               "href" : "http://purl.org/sipwise/ngcp­api/#rel­{rel}",
               "name" : "ngcp",
               "templated" : true
            },
            "profile" : {
               "href" : "http://purl.org/sipwise/ngcp­api/"
            },
            "self" : {
               "href" : "/api/interceptions/520"
            }
         },
         "id" : 520,
         "liid" : 1,
         "number" : "0014155550132",
         "x2_host" : "192.168.42.42",
         "x2_password" : null,
         "x2_port" : 3002,
         "x2_user" : null,
         "x3_host" : "192.168.42.42",
         "x3_port" : 3003,
         "x3_required" : true
      }
   },
   "_links" : {
      "curies" : {
         "href" : "http://purl.org/sipwise/ngcp­api/#rel­{rel}",
         "name" : "ngcp",
         "templated" : true
      },
      "ngcp:interceptions" : {
         "href" : "/api/interceptions/520"
      },
      "profile" : {
         "href" : "http://purl.org/sipwise/ngcp­api/"
      },
      "self" : {
         "href" : "/api/interceptions/?page=1&rows=10"
      }
   },
   "total_count" : 1
}

Get all interceptions for all numbers

  • Request:

    curl -­i --­­insecure --­­user administrator:administrator -­X GET \
https://localhost:1443/api/interceptions/

  • Response:

    HTTP/1.1 200 OK
Server: nginx
Date: Tue, 01 Dec 2015 09:43:18 GMT
Content­Type: application/hal+json; profile="http://purl.org/sipwise/ngcp­api/";
  charset=utf­8
Content­Length: 2364
Connection: keep­alive
Set­Cookie: ngcp_panel_session=68398eea5bdd3885ad0517e1f6d367ccc80111fa; path=/;
  expires=Tue, 01­ Dec­ 2015 10:43:18 GMT; HttpOnly
Strict­Transport­Security: max­age=15768000
{
   "_embedded" : {
      "ngcp:interceptions" : [
         {
            "_links" : {
               "collection" : {
                  "href" : "/api/interceptions/"
               },
               "curies" : {
                  "href" : "http://purl.org/sipwise/ngcp­api/#rel­{rel}",
                  "name" : "ngcp",
                  "templated" : true
               },
               "profile" : {
                  "href" : "http://purl.org/sipwise/ngcp­api/"
               },
               "self" : {
                  "href" : "/api/interceptions/520"
               }
            },
            "id" : 520,
            "liid" : 1,
            "number" : "0014155550132",
            "x2_host" : "192.168.42.42",
            "x2_password" : null,
            "x2_port" : 3002,
            "x2_user" : null,
            "x3_host" : "192.168.42.42",
            "x3_port" : 3003,
            "x3_required" : true
         },
         {
            "_links" : {
               "collection" : {
                  "href" : "/api/interceptions/"
               },
               "curies" : {
                  "href" : "http://purl.org/sipwise/ngcp­api/#rel­{rel}",
                  "name" : "ngcp",
                  "templated" : true
               },
               "profile" : {
                  "href" : "http://purl.org/sipwise/ngcp­api/"
               },
               "self" : {
                  "href" : "/api/interceptions/528"
               }
            },
            "id" : 528,
            "liid" : 918273,
            "number" : "0014155550132",
            "x2_host" : "192.168.42.42",
            "x2_password" : null,
            "x2_port" : 3002,            "x2_user" : null,
            "x3_host" : "192.168.42.42",
            "x3_port" : 3003,
            "x3_required" : true
         }
      ]
   },
   "_links" : {
      "curies" : {
         "href" : "http://purl.org/sipwise/ngcp­api/#rel­{rel}",
         "name" : "ngcp",
         "templated" : true
      },
      "ngcp:interceptions" : [
         {
            "href" : "/api/interceptions/520"
         },
         {
            "href" : "/api/interceptions/528"
         }
      ],
      "profile" : {
         "href" : "http://purl.org/sipwise/ngcp­api/"
      },
      "self" : {
         "href" : "/api/interceptions/?page=1&rows=10"
      }
   },
   "total_count" : 2
}

Get interception for specific LIID

  • Request:

    curl -­i --­­insecure --­­user administrator:administrator ­-X GET \
https://localhost:1443/api/interceptions/?liid=9876

  • Response:

    HTTP/1.1 200 OK
Server: nginx
Date: Tue, 01 Dec 2015 09:50:41 GMT
Content­Type: application/hal+json; profile="http://purl.org/sipwise/ngcp­api/";
  charset=utf­8
Content­Length: 1283
Connection: keep­alive
Set­Cookie: ngcp_panel_session=23960dde6bb90f0c5c84575890194c53cce120ce; path=/;
  expires=Tue, 01­ Dec­ 2015 10:50:40 GMT; HttpOnly
Strict­Transport­Security: max­age=15768000
{
   "_embedded" : {
      "ngcp:interceptions" : {
         "_links" : {
            "collection" : {
               "href" : "/api/interceptions/"
            },
            "curies" : {
               "href" : "http://purl.org/sipwise/ngcp­api/#rel­{rel}",
               "name" : "ngcp",
               "templated" : true
            },
            "profile" : {
               "href" : "http://purl.org/sipwise/ngcp­api/"
            },
            "self" : {
               "href" : "/api/interceptions/520"
            }
         },
         "id" : 520,
         "liid" : 1,
         "number" : "0014155550132",
         "x2_host" : "192.168.42.42",
         "x2_password" : null,
         "x2_port" : 3002,
         "x2_user" : null,
         "x3_host" : "192.168.42.42",
         "x3_port" : 3003,
         "x3_required" : true
      }
   },
   "_links" : {
      "curies" : {
         "href" : "http://purl.org/sipwise/ngcp­api/#rel­{rel}",
         "name" : "ngcp",
         "templated" : true
      },
      "ngcp:interceptions" : {
         "href" : "/api/interceptions/520"
      },
      "profile" : {
         "href" : "http://purl.org/sipwise/ngcp­api/"
      },
      "self" : {
         "href" : "/api/interceptions/?page=1&rows=10"
      }
   },
   "total_count" : 1
}

Create interception for a specific number

  • Request:

    curl -­i --­­insecure ­--­user administrator:administrator ­-X POST \
-­H "Content­Type: application/json" ­­--data \
'{"liid":123, "number":"31032222203", "x2_host":"127.0.0.1", "x2_port":12345,
  "x3_required":true, "x3_host":"127.0.0.2", "x3_port":23456}' \
https://localhost:1443/api/interceptions/

  • Response:

    HTTP/1.1 201 Created
Transfer­Encoding: chunked
Connection: close
Location: /api/interceptions/528
Set­Cookie: ngcp_panel_session=e7817079d121fae4d86448b10e1fa21d0201c526; path=/;
  expires=Tue, 01­ Dec­ 2015 10:43:18 GMT; HttpOnly
Strict­Transport­Security: max­age=15768000

    The path to the newly created interception is found in the Location header of the response.

Update specific interception

  • Request:

    curl -­i --­­insecure --­­user administrator:administrator ­-X PUT \
-­H "Content­Type: application/json" -­H 'Prefer: return=representation' --­­data \
'{"liid":918273, "number":"0014155550132", "x2_host":"192.168.42.42", "x2_port":5000,
  "x3_required":false}' \
https://localhost:1443/api/interceptions/123

  • Response:

    HTTP/1.1 200 OK
Content­Type: application/hal+json; profile="http://purl.org/sipwise/ngcp­api/";
  charset=utf­8
Content­Length: 621
Link: </api/interceptions/>; rel=collection
Link: <http://purl.org/sipwise/ngcp­api/>; rel=profile
Link: </api/interceptions/530>; rel=self
Preference­Applied: return=representation
Set­Cookie: ngcp_panel_session=0b56e4a197b0e9f6e22a998e85473a0184770740; path=/;
  expires=Tue, 01­ Dec­ 2015 10:56:17 GMT; HttpOnly
{
   "_links" : {
      "collection" : {
         "href" : "/api/interceptions/"
      },
      "curies" : {
         "href" : "http://purl.org/sipwise/ngcp­api/#rel­{rel}",
         "name" : "ngcp",
         "templated" : true
      },
      "profile" : {
         "href" : "http://purl.org/sipwise/ngcp­api/"
      },
      "self" : {
         "href" : "/api/interceptions/530"
      }
   },
   "id" : 530,
   "liid" : 918273,
   "number" : "0014155550132",
   "x2_host" : "192.168.42.42",
   "x2_password" : null,
   "x2_port" : 5000,
   "x2_user" : null,
   "x3_host" : null,
   "x3_port" : null,
   "x3_required" : false
}

    The Prefer: return=representation header forces the API to return the content, otherwise status 201 with no content is returned.

Update only certain items for a specific interception

  • Request:

    curl -­i --­­insecure --­­user administrator:administrator -­X PATCH \
-­H "Content­Type: application/json­patch+json" -­H 'Prefer: return=representation' \
­­--data '[{"op":"replace", "path":"/x2_host", "value":"192.168.42.42"},{"op":"replace",
  "path":"/x2_port", "value":4000}]' \
https://localhost:1443/api/interceptions/530

  • Response:

    HTTP/1.1 200 OK
Server: nginx
Date: Tue, 01 Dec 2015 10:06:06 GMT
Content­Type: application/hal+json; profile="http://purl.org/sipwise/ngcp­api/";
  charset=utf­8
Content­Length: 620
Connection: close
Link: </api/interceptions/>; rel=collection
Link: <http://purl.org/sipwise/ngcp­api/>; rel=profile
Link: </api/interceptions/530>; rel=self
Preference­Applied: return=representation
Set­Cookie: ngcp_panel_session=0693129d63d543a85f96d464ff9a8f807cfc4d18; path=/;
  expires=Tue, 01­ Dec­ 2015 11:06:06 GMT; HttpOnly
Strict­Transport­Security: max­age=15768000
{
   "_links" : {
      "collection" : {
         "href" : "/api/interceptions/"
      },
      "curies" : {
         "href" : "http://purl.org/sipwise/ngcp­api/#rel­{rel}",
         "name" : "ngcp",
         "templated" : true
      },
      "profile" : {
         "href" : "http://purl.org/sipwise/ngcp­api/"
      },
      "self" : {
         "href" : "/api/interceptions/530"
      }
   },
   "id" : 530,
   "liid" : 918273,
   "number" : "0014155550132",
   "x2_host" : "192.168.42.42",
   "x2_password" : null,
   "x2_port" : 4000,
   "x2_user" : null,
   "x3_host" : null,
   "x3_port" : null,
   "x3_required" : false
}

Delete specific interception

  • Request:

    curl -­i --­­insecure ­--­user administrator:administrator ­-X DELETE \
https://localhost:1443/api/interceptions/123

  • Response:

    HTTP/1.1 204 No Content
Server: nginx
Date: Tue, 01 Dec 2015 10:08:49 GMT
Connection: keep­alive
Set­Cookie: ngcp_panel_session=570c66b66732629766f86b8ed9bd0d64902ae73e; path=/;
  expires=Tue, 01­ Dec­ 2015 11:08:49 GMT; HttpOnly
X­Catalyst: 5.90042
Strict­Transport­Security: max­age=15768000

X2 Interface

The communication via the X2 interface consists of request-response pairs.

Request

The request is formatted as: X2/<body­length>/<body>

Body part has the following items:

Table 2. X2 Message Body Items
Element Type Length Description

/x2/header/source

String

arbitrary length

identifier of Sipwise node which captured the data

/x2/header/destination

String

arbitrary length

identifier of LI mediation system

/x2/header/type

String

arbitrary length

always "sip" (but later potentially "xmpp" and others too)

/x2/header/version

PosInteger

arbitrary length

always "1"

/x2/header/timestamp

String

27 chars

format: YYYY-MM-DDThh:mm:ss.ffffffZ; timestamp in UTC when the X2 package is sent to mediation

/x2/body/dialogid

PosInteger

arbitrary length

globally increasing counter for each new communication dialog (e.g. call)

/x2/body/messageid

PosInteger

arbitrary length

increasing counter for each new x2 message within a dialog, starting from 0

/x2/body/timestamp

String

27 chars

format: YYYY-MM-DDThh:mm:ss.ffffffZ; timestamp in UTC when the package has been captured on the wire

/x2/body/interceptions

one or more elements containing the following information, one element per intercepted target:

/x2/body/interceptions/liid

PosInteger

arbitrary length

interception id ("liid") as set via X1 interface

/x2/body/interceptions/direction

String

arbitrary length

either "totarget" or "fromtarget" from the soft-switch perspective (if target is the called party, it is "totarget", if target is the calling party, it is "fromtarget").

/x2/body/data

Base64 encoded

arbitrary

content of full IP frame and up on the OSI layer; packets fragmented on the wire are provided in fully assembled format

Example of full message:

X2/418/
{
  "header": {
    "source": "prx01a.example.com",
    "destination": "x2destination.example.com",
    "type": "sip",
    "version": 1,
    "timestamp": "2015­03­11T09:18:04.729803Z"
  },
  "body": {
    "dialogid": 4,
    "messageid": 0,
    "timestamp": "2015­03­11T09:18:04.729123Z",
    "interceptions": [
      { "liid": 174, "direction": "fromtarget" },
      { "liid": 175, "direction": "totarget" }
    ],
    "data": "<base64 encoded ip,udp/tcp,sip frame>"
  }
}

Response

  • Success: X2­-ACK/0/

  • Error: X2-­ERR/<length>/<error string>

Keep-Alive Mechanism

A regular keep-alive mechanism with a default value of 10s is used on the connection if it is re-used across multiple messages.

  • Request: X2/0/

  • Response: X2­-ACK/0/

X3 Interface

On the X3 interface TLV based packets are sent via secured (TLS) connection on a pre-established stream. X3 messages do not need to be acknowledged, except for keep-alive messages.

X3 Message Structure

Table 3. X3 Message Structure
Field Length

Header

arbitrary

CCCID

4 bytes

MessageId

4 bytes

Timestamp

8 bytes

Payload

arbitrary

Header Details

Table 4. X3: Header Details
Field Length Content

type

2 bytes

always "X3"

delimiter

1 byte

always "/"

length

arbitrary

ASCII string

delimiter

1 byte

always "/"

CCCID Details

dialogid (32 bit in network byte order, reset to 0 after 232­-1)

The dialogid is referencing the /x2/body/dialogid field in order to correlate an X3 packet to an X2 call.

MessageId Details

messageid (32 bit in network byte order, reset to 0 after 232-­1)

The messageid is a counter within a dialog sequencing the X3 packets sent from the NGCP. This counter is not correlated in any way with X2, rather than starting at 0 with the first RTP packet captured within a dialog.

Timestamp Details

  • seconds (32 bit in network byte order)

  • fraction (32 bit in network byte order)

The timestamp represents the Unix epoch starting from 1970-01-01.

Payload Details

Table 5. X3: Payload Details
Field Length

original ip header

20 bytes for v4, 40 bytes for v6

original udp header

8 bytes

original rtp header

variable, 12­-72 bytes

original rtp payload

arbitrary

Keep-Alive Mechanism

A regular keep-alive mechanism with a default value of 10s is used on the connection if it is re-used across multiple messages.

  • Request: X3/0/

  • Response: X3-­ACK/0/

3PCC functionality (TPCC), CSTA sessions and Websocket component

Abbreviations / definitions used in this chapter

  • 3PCC - Third Party Call Control, which is a concept for managing calls from the separate network element (for e.g. through ngcp-websocket using CSTA). In a scope of this chapter, 3PCC is the .so module connected via the SEMS component and it implements the third party call control in the Sipwise C5.

Sometimes 3PCC can be also written as TPCC.

  • 1PCC - First Party Call Control, which is a usual/manual way of originating/managing calls. In other words, when Alice calls Bob manually using SIP hard- / softphone (she can put Bob on hold and then terminate the session if needed).

  • CSTA - Computer Supported Telecommunication Application(s). Is a protocol for voice service invocations using XML-based messages, which works via the WebSocket protocol (that implements a role of a transport mechanism for the CSTA messages). It is implemented by the ngcp-websocket component, which interacts with the Kamailio-Proxy for a purpose of calls monitoring and with the SEMS for calls control (3PCC).

Standard ECMA-269 - "Services for Computer Supported Telecommunications Applications (CSTA) Phase III" : https://www.ecma-international.org/publications-and-standards/standards/ecma-269/ Standard ECMA-323 - "XML protocol for Computer Supported Telecommunications Applications (CSTA) Phase III" : https://www.ecma-international.org/publications-and-standards/standards/ecma-323/ Standard ECMA-TR/82 - "Scenarios for Computer Supported Telecommunications Applications (CSTA) Phase III" : https://www.ecma-international.org/publications-and-standards/technical-reports/ecma-tr-82/

  • FIFO - fifo socket (first in / first out), in other words program’s in-queue / out-queue. In a scope of this chapter this is related to the SEMS, which has a dedicated FIFO implemented in the 3PCC (TPCC) module.

  • SEMS - this is a sems-b2b component, through which the 3PCC (TPCC) module is connected to whole architecture/stack.

  • ngcp-websocket - this is the websocket component and is used to interconnect the sems-b2b and the kamailio-proxy with the CSTA environment. The main purpose is to send/receive commands to the dedicated redis channels, which can trigger some job/action to be implemented either on sems-b2b/kamailio-proxy side or in the CSTA environment (for e.g. change of SIP call status).

  • protobuf - protocol buffers is Google’s language- / platform-neutral,extensible mechanism for serializing structured data – think XML, but smaller, faster, and simpler.

https://en.wikipedia.org/wiki/Protocol_Buffers

  • WebSocket protocol - is a transport mechanism used for the CSTA messages.

WebSocket protocol is compatible with RFC6455: https://tools.ietf.org/html/rfc6455

Introduction

This chapter covers CSTA call flows of the 3PCC model and various extended telephony services based on that. It shows how the relations between different components involved into CSTA processing, make it possible to establish SIP-based sessions/dialogs. It includes different possible call scenarios, which can be done using CSTA/3PCC and how to use API in order to trigger them.

The CSTA model is implemented based on the ECMA-269 Phase III and ECMA TR/82 standards. It uses XML format with ECMA-323 XSD to carry required metadata over the WebSocket protocol.

In practice you can use your own web-based application or any other kind of application capable of sending IP-packets, to realize the following stack:

  • web client (web GUI for user)

  • CSTA via the WebSocket protocol

  • ngcp-websocket component

  • 3PCC (TPCC) module of the SEMS-b2b component

A good example of such integration is the Rainbow developed by Alcatel Lucent Enterprise, which is used as a superstructure in a combination with the Sipwise C5 to give users all capabilities of the CSTA.

CSTA and WebSocket protocol

CSTA session is being established using WebSocket protocol. Which makes it possible to control sessions via the ngcp-websocket component of the Sipwise C5. As already mentioned before, the WebSocket protocol is compatible with RFC6455.

Devices that are visible or controllable via CSTA are known as CSTA Devices.

CSTA Devices can be either physical devices (such as SIP hardphone) or logical devices (such as groups of devices, pilot numbers). CSTA Devices have attributes that allow CSTA to monitor and manipulate them.

The most important CSTA requests/event types used in the setup with the Sipwise C5:

  • MakeCall - originate a call with a remote side

  • HoldCall - put a remote side on hold

  • ConsultationCall - initiate a consultation call with a third side

  • ClearConnection - finalize a connection/terminate a session

  • MonitorStart - start monitoring of device

  • RequestSystemStatus - establish a connection with the CSTA system (ngcp-websocket)

  • OriginatedEvent - indicates to the caller, that an invitation has been sent to the remote device (however not answered yet)

  • ServiceInitiatedEvent - indicates to the caller, that an invitation has been sent to the originating device (however not answered yet)

  • DeliveredEvent - indicates that remote device has started to ring (180/183)

  • EstablishedEvent - indicates that remote device has answered a call (200OK)

  • HoldEvent - indicates that the session has been successfully put on hold

  • ConnectionClearedEvent - indicates a call clearing/termination phase (due to whatever reason)

  • FailedEvent - indicates that a previously requested event has not been delivered as intended (for e.g. on an invitation we’ve gotten 486 from a remote device)

Some of the most important attributes used in the setup with the Sipwise C5:

  • monitorCrossRefID - this is a monitor cross reference identifier parameter, which associates the event with the established monitor

  • initiatedConnection - this parameter specifies the connection, at which a service was initiated

  • originatedConnection - this parameter specifies the connection, at which a call was originated

  • callID - an identifier which is used to represent a valid call

  • deviceID - an identifier which is used to represent a device in the domain

  • callingDevice - this parameter in the Call Control events represents the calling device associated with the call

  • calledDevice - this parameter specifies an originally called device. In case of prompting, this parameter specifies the device that will be called after the prompt is answered

  • initiatingDevice - this parameter specifies the initiating device

  • answeringDevice - this parameter specifies the device that has been connected to the call

  • deviceIdentifier - this parameter keeps the SIP URI of callingDevice/calledDevice/initiatingDevice/alertingDevice/answeringDevice

  • localConnectionInfo - this parameter specifies the local connection state of device associated with the 'monitorCrossRefID'

  • cause - this parameter specifies the reason for the event (for e.g.: 'newCall', 'makeCall' etc.)

  • connection - this parameter specifies the connection that is alerting (ringing)

  • establishedConnection - this parameter specifies the connection that has been established

  • alertingDevice - this parameter specifies the device that is alerting (ringing)

  • lastRedirectionDevice - this parameter specifies a previously known redirection from device (in most cases will be used with the 'notRequired' value)

A list of important details:

  • Subprotocol (Sec-WebSocket-Protocol header) must have the value: ‘csta’

  • WebSocket frames should be of the ‘text’ type

  • Packets fragmentation has to be not applied on CSTA packets

  • WebSocket clients can send WebSocket ping requests periodically and the WebSocket server should respond to it

A connection with the ngcp-websocket

When using your own system with CSTA (presumably this can be a web platform with GUI which sends WebSocket requests of XML format), this system will have to establish a connection or a pool of connections with the ngcp-websocket component.

For simplicity reasons, let us name a client/system getting connected to the CSTA/ngcp-websocket as web-interface-1

Each connection between the web-interface-1 (client) and the ngcp-websocket upon establishment, requires the CSTA RequestSystemStatus message to be sent from the web-interface-1. Once a response from the ngcp-websocket is received, a session is considered to be established. Consider:

CSTA RequestSystemStatus messages exchange
Figure 93. CSTA RequestSystemStatus messages exchange

An example of such messages exchange can be found here: CSTA Appendix, RequestSystemStatus.

Messages format

The content of CSTA messages is regulated with the ECMA-269 standard and is illustrated in the ECMA TR/82. XSD (XML Schema Definition) is described by ECMA-323

As described in “5.2 Request/Response Protocol Requirements” of ECMA-323, the XML part does not provide mechanism for correlating a CSTA request with a CSTA response.

CSTA has a server/client model (request/answer), this is quite similar to what HTTP or SIP protocols have. The content of such message has headers and has a body. Currently only bodies in XML format are supported.

At least two headers are required and must be presented in each request/response of the WebSocket messages exchange:

  • 'Content-Type:' - a content type of CSTA body, now it has only one possible value 'application/csta+xml'

  • 'X-CSTA-Seq-ID:' - a sequence Id of CSTA request/response transaction. It is recommended having a unique ID within each NGCP/CSTA environment. It is incremented by 1 with every new request. For e.g.: ab234_1, ab234_2, ab234_3, …​ ab234_N, where ab234 is an unique ID.

Telephony scenarios

In this section it is described how an interaction of the CSTA and SIP environment builds up 3PCC-controlled SIP sessions. In other words, how to use the CSTA (over the WebSocket protocol) to initiate, modify and properly terminate 3PCC-controlled sessions.

For CSTA to operate effectively, each device in the 3PCC-controlled SIP session must be monitored.
In certain scenarios, it may not be possible to monitor a remote side, for e.g. in case when a call with a remote side is established via the SIP peering/media gateway. In such situation, the monitoring can be applied to the SIP peering/media gateway as the last visible point Sipwise C5 interacts with.

Monitoring of device

The web-interface-1 (client) needs to start a CSTA monitor for a given SIP device in order to observe evaluations on CSTA calls via CSTA events. To start a monitoring, a CSTA MonitorStart service message is being sent (as the body of a WebSocket request). Consider:

CSTA MonitorStart messages exchange
Figure 94. CSTA MonitorStart messages exchange

One can see from the figure above that the sequence is as follows:

  • Monitoring is started for the device with AOR: sip:1000@sipwise.com, and a message is sent from the web-interface-1 (MonitorStart)

  • SIP device gets monitored and an unique monitor ID is generated for a given response (MonitorStartResponse)

Now, any time when certain event happens to this SIP device, ngcp-websocket will notify the web-interface-1 about the ongoing event using the WebSocket message (DeliveredEvent).

An example of such messages exchange can be found here: CSTA Appendix MonitorStart.

As well as a monitoring of any device can be started, it can also be stopped using the 'monitorCrossRefID', which was previously given when establishing the monitoring session using the WebSocket MonitorStart request. After it is complete, no notifications/events will be generated for a given device. Consider:

CSTA MonitorStop messages exchange
Figure 95. CSTA MonitorStop messages exchange

In some cases a particular device may be monitored by two monitors at the same time, in this situation when one of monitoring events has been stopped, the remaining one should continue delivering CSTA events.

Aspects of user identity

The CSTA requires a user identity, which includes the SIP URI as well as a display name (if present) and must be stored using the '<deviceIdentifier>' tag in the XML body of the message, for e.g.:

<callingDevice><deviceIdentifier>&lt;Carol&gt;
sip:1002@company1.sipwise.com</deviceIdentifier></callingDevice>

It corresponds to a real user identity taken from the SIP message (from the P-Asserted-Identity):

P-Asserted-Identity : “Carol” <sip:1002@company1.sipwise.com>
During the call forward type of event, once a call is established, a real/actual user identity has to be reflected in the 'P-Asserted-Identity' header of the SIP 200 OK message going to an initial caller.
In case of SIP legs changes (for example a call transfer), a distant identity will likely be changed. In this case INVITE with 'Replaces' parameter should be issued to the remote leg, in order to update the current user identity.

For inbound calls to the Sipwise C5, the user identity has to be provided in the incoming SIP INVITE request and can then be reflected in the WebSocket message (so on the CSTA level) by a proper setting of the '<callingDevice>' tag value. In the case of an incoming call, such CSTA events will be of 'DeliveredEvent' type and then of 'EstablishedEvent' type (the latter, if a call got connected). The priority for a source of this value is the following:

  1. the 'P-Asserted-Identity' header ;

  2. the 'From' header (if PAI does not exist) ;

For outbound calls, if we have the 'P-Asserted-Identity' header in the 200 OK response coming from a remote side, it has to be reflected as the value of the '<answeredDevice>' tag in the 'EstablishedEvent' WebSocket message. If PAI is not present, then the 'To' header is a source of the value.

Third-party call control, scenarios

These operations are usually issued by an application (using CSTA services) and known as 3PCC operations. Let us have a look at some examples.

Here is an example of the Make Call successful session, internal call:

This scenario illustrates a successful Make Call from device A to device B.

CSTA MakeCall within internal realm, messages exchange
Figure 96. CSTA MakeCall messages exchange

In this scenario both devices are registered and ready to process calls. The client of A sends a request to start a SIP session with B. The client of B is notified about the incoming call. B picks up the call and the media session is established between A and B. Both clients of A and B are notified about the delivered event.

The detailed content of CSTA messages is presented CSTA Appendix MakeCall.

If the default list of codecs (configured in the config.yml tpcc.codec_list) does not fit the requirements of the calling client, you may choose a specific list of codecs. This preference is being transferred using '<mediaSessionInfo>' XML element.

An example of the Make Call failed session, internal call:

The MakeCall scenario can fail for many reasons, this may happen for e.g. in case, when a destination or source device is busy, or one of them does not respond, not found, etc.

In the scenario shown below, device B is busy and cannot receive the call at the time of attempt to reach it.

Failed MakeCall scenario (destination is busy)
Figure 97. Failed MakeCall scenario (destination is busy)

The content of CSTA messages is presented in CSTA Appendix MakeCall failed.

A treatment of other errors:

  • if 'callingDevice' of MakeCall is unknown – the response to the MakeCall request will be a CSTAErrorCode with the 'invalidSourceDeviceID' error;

  • if 'calledDirectoryNumber' of MakeCall is unknown – the response to the MakeCall request will be a CSTAErrorCode with the 'invalidDestinationDeviceID' error.

An example of the Make Call successful session, outbound scenario:

The following scenario illustrates the Make Call service request from behalf of device A to an external device which is outside of the served domain.

Since the destination is located outside this CSTA domain, it cannot be directly monitored via the CSTA API and therefore no events can be generated for the remote side. Since the remote device is reachable via a SIP peering, this SIP peering technically represents a SIP endpoint visible for the system, and hence, can be instead monitored by the CSTA, since this SIP Peering is directly handled by the Sipwise C5. But this is not required.

CSTA MakeCall with a SIP Peering, messages exchange
Figure 98. CSTA MakeCall with a SIP Peering, messages exchange

The content of CSTA messages is presented in CSTA Appendix MakeCall outbound.

A treatment of other errors:

  • if the 'callingDevice' of MakeCall is unknown – the response to the MakeCall is 'CSTAErrorCode' with the 'invalidSourceDeviceID' error;

  • if the 'calledDirectoryNumber' of MakeCall is unknown – the response to the MakeCall is 'CSTAErrorCode' with the 'invalidDestinationDeviceID' error.

For outbound calls, if there is the 'P-Asserted-Identity' in the SIP 200OK coming from a distant participant, it has to be reflected in the ‘answeredDevice’ XML element of CSTA 'EstablishedEvent' event message.

An example of the Hold Call scenario:

This scenario illustrates a successful Hold Call request processing. A hold request is issued by a client and then a SIP re-INVITE transaction with the special content of SDP body will be sent to the remote side (sendonly / inactive / 0.0.0.0).

CSTA successful HoldCall scenario, messages exchange
Figure 99. CSTA MakeCall with a SIP Peering, messages exchange

The content of CSTA messages is presented in CSTA Appendix HoldCall.

A treatment of errors:

  • if a connection in the 'callToBeHeld' of HoldCall is unknown – the response to the HoldCall request is the 'CSTAErrorCode' with the 'invalidConnectionID' error;

  • if a connection of HoldCall is not in the ‘connected’ state – the response to the HoldCall request is the 'CSTAErrorCode' with the 'invalidConnectionState' error.

An example of the Retrieve call:

This scenario illustrates a successful Retrieve request processing. A prerequisite - SIP call must be on hold. After the retrieve operation, a conversation is to be continued.

Successful RetrieveCall scenario using SIP re-INVITE
Figure 100. Successful RetrieveCall scenario using SIP re-INVITE

The content of CSTA messages is presented in CSTA Appendix RetrieveCall.

A treatment of errors:

  • if a connection in the 'heldCall' of the 'RetrieveCall' is unknown – a response to the 'RetrieveCall' is the 'CSTAErrorCode' with the 'invalidConnectionID' error;

  • if a connection in the 'heldCall' of the 'RetrieveCall' is not in the ‘held’ state – a response to the 'RetrieveCall' is the 'CSTAErrorCode' with the 'invalidConnectionState' error.

An example of the Clear Connection:

This scenario illustrates how a normal call clearing (call termination) occurs. A session with a remaining device is cleared as well.

Successful ClearConnection scenario
Figure 101. Successful ClearConnection scenario

The content of CSTA messages is presented in CSTA Appendix ClearConnection.

A treatment of errors:

  • if a connection in the 'connectionToBeCleared' of the 'ClearConnection' is unknown – a response to the 'ClearConnection' is the 'CSTAErrorCode' with the 'invalidConnectionID' error ;

  • if a connection in the 'connectionToBeCleared' of the 'ClearConnection' is in the ‘Null’ state – a response to the 'ClearConnection' is the 'CSTAErrorCode with the 'invalidConnectionState' error.

Third-party call control, other scenarios not described in the handbook

  • ClearCall

  • DeflectCall

  • ConsultationCall

  • SingleStepTransferCall

  • TransferCall

Third-party call control, retrieve information about device / call

SnapshotCall:

An application uses the SnapshotCall service to obtain information about the CSTA connections of the particular call and supplementary information, like a CallingDevice, CalledDevice, etc.

The ngcp-websocket will provide a positive response with the list of zero or more connections and information about each connection as well as supplementary information.

A list of common elements in the snapshotDeviceResponseInfo element:

  • <deviceOnCall> – this mandatory element contains the endpoint device ID ;

  • <connectionIdentifier> – this mandatory element provides the 'connectionID' of the connection. This is the 'connectionID' that is used in CSTA services that are applied to the connection. The <connectionIdentifier> is combined of the called and the deviceID. The deviceID '<privateNumber'>' attribute may be set to true in case of privacy (CLIR/COLR) ;

  • <localCallState> – this mandatory element specifies a 'compoundCallState', which consists of one or more CSTA connection states. The first connection state in the list is the 'local' connection state of the connection being reported. Other connection states that reflect other connections in the same call (rest of devices) may also be provided, if known to the UAC ;

  • <calling>/<called> – a calling called device ;

  • <privateData> – an additional information about the call state: recorded connections, display names ;

Snapshot Call scenario
Figure 102. Snapshot Call scenario

If a SIP call does not exist, a response with the 'CSTAErrorCode' is returned to the 'SnapshotCall' with the 'invalidCallID' status.

SnapshotDevice:

An application uses the SnapshotCall service to obtain information about the CSTA connections of the particular device.

The ngcp-websocket service will provide a positive response with the connection details.

  • <deviceOnCall> – this mandatory element contains the endpoint device ID ;

  • <connectionIdentifier> – this mandatory element provides the 'connectionID' of the connection. This is the 'connectionID' that is used in CSTA services that are applied to the connection. The <connectionIdentifier> is combined of the called and the deviceID. The deviceID '<privateNumber'>' attribute may be set to true in case of privacy (CLIR/COLR) ;

  • <localCallState> – this mandatory element specifies a 'compoundCallState', which consists of one or more CSTA connection states. The first connection state in the list is the 'local' connection state of the connection being reported. Other connection states that reflect other connections in the same call (rest of devices) may also be provided, if known to the UAC ;

  • <calling>/<called> – a calling called device ;

  • <privateData> – an additional information about the call state: recorded connections, display names ;

Snapshot Call scenario for a device
Figure 103. Snapshot Call scenario for a device

If a requested device is for any reason out-of-service, a response with the 'CSTAErrorCode' is returned to the 'SnapshotDevice' with the 'deviceOutOfService' status.

Third-party call control, device got into/out of service

BackInService:

The 'BackInService' event indicates that a device has been returned to service and is available. Back into service means one of the following: SIP device register / configuration object enabled / out-of-service check with success result.

'BackInService' does not need to be sent upon SIP REGISTER refresh, only upon initial REGISTER.

OufOfService:

The 'OutOfService' event indicates that a device has entered a maintenance or a disabled state (for e.g. has been de-registered) and can no longer accept calls and some other categories of CSTA service requests (for e.g. Call Control services).

Out of service means one of the following: SIP device de-register / configuration object disabled / out-of-service check with failed result.

3PCC (TPCC) module of sems-b2b component

This is a module which allows to establish different call events, such as usual audio session between two points, based on the websocket/CSTA generated commands.

The main goal of the 3PCC (TPCC) SEMS module is to have an interconnection between the internal ngcp-websocket component and the SEMS-b2b in terms of translating actions to real call sessions (create call, hang-up, put on hold, transfer call etc.)

Two abstract (logical) endpoints that we have in such an architecture:

Two logical endpoints in the architecture
Figure 104. Two logical endpoints in the architecture

Interaction with the ngcp-websocket

The ngcp-websocket communicates with the CSTA environment (CSTA events) and translates this logic into the internal communication environment:

CSTA environment with SEMS
Figure 105. CSTA environment with SEMS

The ngcp-websocket communicates with the SEMS using specified (our internal) protocol (sending/receiving messages to/from SEMS). The communication between the web-socket and the SEMS is implemented using Redis channels (Redis queues).

The aim is to communicate via these channels also with other components, such as Kamailio Proxy.

This approach currently supports multi-nodes distributed environment. In scope of this chapter our interest is SEMS-b2b component.

Redis-channels (KeyDB)

The SEMS-b2b component is currently using at least three Redis channels:

  • Receiving Data (actions): 1) Subscription Channel (as a command interface), 2) Events Channel (for data)

  • Sending Data (updates / brand new SIP events): 1) Publish Channel (responses to the channel, or new requests to the channel)

Sometimes Redis channels can be also called as Redis queues.

By default it is been set to:

  • receiving commands via the ‘csta.websocket’ channel (separate thread in SEMS)

  • receiving any data additional via the 'sp.sems-b2b' channel (parent thread)

  • sending data to the channel ‘csta.sems’

The names of the channels can be controlled accordingly in the tpcc.conf of the sems-b2b component. Parameters: 'subscribe_channel', 'publish_channel' and 'output_dst'. If for any reason there is a rational need to change the names of these channels, please contact the Sipwise Operations team to get a consultation.

It is worth mentioning that in the multi-active setup with multiple SEMS-b2b components working simultaneously the 'subscribe_channel' and the 'output_dst' values will be set based on the hostnames. This allows to differentiate messages being sent from/to Redis channels between different SEMS-b2b instances.

SEMS component of Sipwise C5

The SEMS is working asynchronously (multi-threaded program). Inside the SEMS we have two main queues:

  • coming comands > FIFO input > 3PCC (TPCC) Handler (multi-threaded)

  • responses / outgoing requests > FIFO output > 3PCC (TPCC) Handler (multi-threaded)

The SEMS-b2b constantly sends keepalive messages (just dummy 'ping') to remote Redis (KeyDB) to keep connections with the Redis (KeyDB) alive.

It also has a multi-threaded processing of incoming/outgoing commands (FIFO). It picks an incoming message (command/metadata) from the input queue and passes it to its events processor. It also picks any pending messages in the output queue, serializes it into the text (JSON) representation and publishes it to an according Redis channel.

The events processor of SEMS will try to undertake something upon receiving of the command. Logically we can divide it into two categories of actions:

  • make a call between two participants. That means it calls an initiator (we can call it leg A) and then it calls the recipient of the call (we can call it leg B ), and it calls it from behalf of the A side.

  • perform an action on an existing session (as a simple example - we can hang-up it)

It is also worth mentioning another aspect of 3PCC handling - events happening on the SIP side of 3PCC session.

All things happening within the SIP session (not triggered by the 3PCC handling), will be reflected accordingly on the 3PCC/CSTA. This means, SEMS-b2b will do all the required work to notify the ngcp-websocket component of SIP messages received during an existing SIP session (re-INVITE for e.g.).

Here is a useful sequence description of the 3PCC dialog initiation:

  • the CSTA environment sends some command in the XML to the ngcp-websocket component;

  • the ngcp-websocket translates it to the internal protocol and puts the message in the JSON format into the dedicated Redis channel (Subscription Events / Events Redis);

  • the SEMS-b2b component receives this JSON message from Redis (KeyDB), parses it and translates it into the internal SEMS-b2b program usage (in other words make it convertible into c++ objects, hence machine code)

  • the SEMS-b2b starts processing the command using its events processor mechanism and will undertake all required actions, if they are applicable;

As a simple example of such event processing is a call from A-to-B. In such call scenario SEMS-b2b invites A without an SDP body present (no offer), waits until A responds with 200OK containing an SDP offer with certain media capabilities, and then will use these capabilities to build up an SDP offer to be sent to the B subscriber.

B gets invited into the SIP call, as soon as the call is accepted by B, the SDP answer contained by the 200OK response will be used to build up an SDP answer for A as well. Eventually this session gets acknowledged by SEMS for B (leg with B), and by A. A media session is established then through the SEMS-b2b and if needed, transcoding is to be applied.

3PCC dialog initiation
Figure 106. 3PCC dialog initiation
In case there is more than one active SEMS component working in the cluster, for e.g. Carrier grade setup, then the first SEMS who received and started processing this JSON message (new event), is responsible for this particular TPCC session. A very first SEMS-b2b, which has received this message, will RPOP this event from the end of the dedicated Redis list (channel) and will start processing it. Hence other active SEMS-b2b instances in the cluster, will not undertake anything.

Configuration of 3PCC (TPCC)

To start using 3PCC/CSTA functionality of the Sipwise C5 the following list of config.yml parameters must be activated:

  • tpcc.enable → yes

  • websocket.enable → yes

Detailed example of 3PCC (TPCC) config.yml block:

tpcc:
  add_header_to_detect_device: ''
  codec_list: PCMA,PCMU,g729,opus,g722
  enable: no
  instance_id: '*'
  publish_channel: csta.sems
  use_broadsoft_hold: no

Where:

  • add_header_to_detect_device: - this option defines, which header to add into the 3PCC originated calls in order to notify the caller/callee subscriber, who is the real device involved in the call

  • codec_list: - a list of preferred audio codecs

  • enable: - enabling of the 3PCC (TPCC) module

  • instance_id: - identification of the sems instance, only for the multi-active sems setup

  • publish_channel: - a channel to be used for publishing 3PCC events

  • use_broadsoft_hold: - use it to switch between initial and broadsoft-specific hold handling

websocket:
  allow_foreign_monitor_stop: yes
  enable: no
  inactivity_timeout: 0
  loglevel: info
  max_clients: 1000
  max_requests: 100
  mode: development
  port: 3443
  redis:
    csta_monitor_db: 31
    csta_publish_channel: csta.websocket
    csta_subscribe_channels:
    - csta.sems
    - csta.proxy
    csta_subscription_db: 32
  ssl:
    cert: /etc/ngcp-config/shared-files/ssl/myserver.crt
    enable: no
    key: /etc/ngcp-config/shared-files/ssl/myserver.key

Where:

  • allow_foreign_monitor_stop: - enable/disable MonitorStop with the 'monitor_id' belonging to another connection

  • enable: - an enabling of the websocket component

  • inactivity_timeout: - a timeout for the remote side in case of actions absence

  • loglevel: - the log level for the component

  • max_clients: - a maximum amount of clients can be processed simultaneously

  • max_requests: - a maximum amount of requests can be processed simultaneously

  • mode: - possible values 'full', 'development' and 'brief'

  • port: - the port to listen on

  • redis: - a block of options related to Redis (KeyDB)

  • redis.csta_monitor_db: - select needed db for the monitor

  • redis.csta_publish_channel: - a Redis channel for publishing events

  • redis.csta_subscribe_channels: - Redis channels to which sems-b2b and kamailio-proxy will subscribe

  • redis.csta_subscription_db: - select needed db for publishing events

  • ssl: - a block of options related to the SSL encryption

  • ssl.enable: - enable SSL encryption

  • ssl.cert: - a path to the certificate

  • ssl.key: - a path to the key

After both 'tpcc.enable' and 'websocket.enable' config.yml options are set to yes, changes must be applied with the following:

ngcpcfg apply 'enable tpcc and websocket'
by enabling these options a restart of the sems-b2b and kamailio-proxy services will be triggered, so it’s better to plan this maintenance out of business hours. If there are any doubts regarding how to properly enable CSTA/3PCC support in the system, please contact the Operations team of Sipwise.

After both the 3PCC (TPCC) module and the ngcp-websocket component are enabled you can start using the API to issue new 3PCC-controlled SIP calls.

SMS (Short Message Service) on Sipwise C5

The Sipwise C5 offers short messaging service to its local subscribers. The implementation is based on a widely used software module: Kannel, and it needs to interact with a mobile operator’s SMSC in order to send and receive SMs for the local subscribers. The data exchange with SMSC uses the SMPP (Short Message Peer-to-Peer) protocol.

SMS directions:

  • incoming / received: the destination of the SM is a local subscriber on the NGCP

  • outgoing / sent: the SM is submitted by a local subscriber

The Sipwise C5 behaves as a short message client towards the SMSC of a mobile operator. This means every outgoing SM will be forwarded to the SMSC, and every incoming SM will reach the Sipwise C5 through an SMSC.

The architecture of the SMS components of Sipwise C5 and their interaction with other elements is depicted below:

SMS Interactions
Figure 107. SMS Interaction
For the Sipwise C5 CE and PRO installations: the Kannel components and the ngcp-panel all run on the same single node. The description of SMS module will continue referring to a Sipwise C5 CARRIER installation in the handbook.

There are 2 components of the SMS module:

  • SMS Box: this component takes care of handling the messages locally, that means:

    • delivering them to subscribers (writing into database for later retrieval)

    • picking up the submitted SMs from the database and forwarding them to the Bearer Box component

  • Bearer Box: this component manages the transmission of SMs between Sipwise C5 and the mobile operator’s SMSC

Configuration

Main Parameters

The SMS functionality of Sipwise C5 is disabled by default. In order to enable SMS, change the value of configuration parameter sms.enable to yes in the main configuration file (/etc/ngcp-config/config.yml).

The second step of configuration is related to the SMSC where the Sipwise C5 will connect to. Set the following parameters:

  • sms.smsc.host: IP address of the SMSC

  • sms.smsc.port: Port number of the SMSC

  • sms.smsc.username: Username for authentication on the SMSC

  • sms.smsc.password: Password for authentication on the SMSC

Other parameters of the SMSC connection may also need to be changed from the default values, but this is specific to each deployment.

Then make the new configuration active:

$ ngcpcfg apply 'Enabled SMS'
$ ngcpcfg push all

Configuration Files of Kannel

There are a few configuration files for the Kannel module, namely:

  • /etc/default/ngcp-kannel: determines which components of Kannel will be started. This is auto-generated from /etc/ngcp-config/templates/etc/default/ngcp-kannel.tt2 file when SMS is enabled.

  • /etc/kannel/kannel.conf: contains detailed configuration of Kannel components. This is auto-generated from /etc/ngcp-config/templates/etc/kannel/kannel.conf.tt2 file when SMS is enabled.

  • /etc/logrotate.d/ngcp-kannel.conf: configuration of logrotate for Kannel log files. This is auto-generated from /etc/ngcp-config/templates/etc/logrotate.d/ngcp-kannel.conf.tt2 file when SMS is enabled.

Please do not change settings in the above mentioned template files, unless you have to tailor Kannel settings to your specific needs!

Finally: see the description of each configuration parameter in the Appendix.

Call Forwarding for SMS (CFS)

Any subscriber registered on the Sipwise C5 can apply a call forwarding setting for short messages, referred to as "CFS" (Call Forward - SMS). If the CFS feature is enabled, they can receive the SMs on their mobile phone, for example, instead of retrieving the SMs through the REST API. This is much more convenient for users if they do not have an application on their smartphone or computer that could manage the SMs through the REST API.

In order to enable CFS you have to set the forwarding as usual on the admin web interface, or through the REST API. Navigate to Subscribers → select the three dots → Details → Call Forwarding and press the Edit button on the Call Forward SMS row. There you can put the destination number where the SM has to be forwarded.

Call Forward for SMS
Figure 108. Call Forward for SMS

Monitoring, troubleshooting

Bearer Box (LB node of NGCP)

On the LB node you can see a process named "bearerbox". This process has 2 listening ports assigned to it:

  • 13000: this is the generic Kannel administration port, that belongs to the "core" component of Kannel.

  • 13001: this is the communication port towards the SMS Box component running on PRX nodes of NGCP.

The ngcp-service tool also shows the bearerbox process in its summary information:

$ ngcp-service summary
Ok Service                        Managed    Started   Status
-- ------------------------------ ---------- --------- ---------
…
   kannel-bearerbox               managed    by-ha     active
…

The following log files can provide information about the operation of Bearer Box:

  • status messages and high level, short entries about sent and received messages: /var/log/ngcp/kannel/kannel.log

    ...
2017-09-26 08:57:32 [15922] [10] DEBUG: boxc_receiver: heartbeat with load value 0 received
...
2017-09-26 11:12:06 [15922] [10] DEBUG: boxc_receiver: sms received
2017-09-26 11:12:06 [15922] [10] DEBUG: send_msg: sending msg to box: <192.168.1.4>
2017-09-26 11:12:06 [15922] [11] DEBUG: send_msg: sending msg to box: <192.168.1.4>
2017-09-26 11:12:06 [15922] [11] DEBUG: boxc_sender: sent message to <192.168.1.4>
2017-09-26 11:12:06 [15922] [10] DEBUG: boxc_receiver: got ack
...

  • detailed information and message content of sent and received messages, link enquiries: /var/log/kannel/smsc.log

    Sent and received message examples shown here do not contain the full phone number and content for confidentiality reason.

    • Example received message:

      ...
2017-09-26 12:09:36 [15922] [6] DEBUG: SMPP[default_smsc]: Got PDU:
2017-09-26 12:09:36 [15922] [6] DEBUG: SMPP PDU 0x7f2274025070 dump:
2017-09-26 12:09:36 [15922] [6] DEBUG:   type_name: deliver_sm
2017-09-26 12:09:36 [15922] [6] DEBUG:   command_id: 5 = 0x00000005
2017-09-26 12:09:36 [15922] [6] DEBUG:   command_status: 0 = 0x00000000
2017-09-26 12:09:36 [15922] [6] DEBUG:   sequence_number: 11867393 = 0x00b51501
2017-09-26 12:09:36 [15922] [6] DEBUG:   service_type: NULL
2017-09-26 12:09:36 [15922] [6] DEBUG:   source_addr_ton: 2 = 0x00000002
2017-09-26 12:09:36 [15922] [6] DEBUG:   source_addr_npi: 1 = 0x00000001
2017-09-26 12:09:36 [15922] [6] DEBUG:   source_addr: "0660......."
2017-09-26 12:09:36 [15922] [6] DEBUG:   dest_addr_ton: 1 = 0x00000001
2017-09-26 12:09:36 [15922] [6] DEBUG:   dest_addr_npi: 1 = 0x00000001
2017-09-26 12:09:36 [15922] [6] DEBUG:   destination_addr: "43668......."
2017-09-26 12:09:36 [15922] [6] DEBUG:   esm_class: 0 = 0x00000000
2017-09-26 12:09:36 [15922] [6] DEBUG:   protocol_id: 0 = 0x00000000
2017-09-26 12:09:36 [15922] [6] DEBUG:   priority_flag: 0 = 0x00000000
2017-09-26 12:09:36 [15922] [6] DEBUG:   schedule_delivery_time: NULL
2017-09-26 12:09:36 [15922] [6] DEBUG:   validity_period: NULL
2017-09-26 12:09:36 [15922] [6] DEBUG:   registered_delivery: 0 = 0x00000000
2017-09-26 12:09:36 [15922] [6] DEBUG:   replace_if_present_flag: 0 = 0x00000000
2017-09-26 12:09:36 [15922] [6] DEBUG:   data_coding: 3 = 0x00000003
2017-09-26 12:09:36 [15922] [6] DEBUG:   sm_default_msg_id: 0 = 0x00000000
2017-09-26 12:09:36 [15922] [6] DEBUG:   sm_length: 158 = 0x0000009e
2017-09-26 12:09:36 [15922] [6] DEBUG:   short_message:
2017-09-26 12:09:36 [15922] [6] DEBUG:    Octet string at 0x7f2274000f80:
2017-09-26 12:09:36 [15922] [6] DEBUG:      len:  158
2017-09-26 12:09:36 [15922] [6] DEBUG:      size: 159
2017-09-26 12:09:36 [15922] [6] DEBUG:      immutable: 0
2017-09-26 12:09:36 [15922] [6] DEBUG:      data: 5a <14 bytes> 46
2017-09-26 12:09:36 [15922] [6] DEBUG:      data: 72 <14 bytes> 68
2017-09-26 12:09:36 [15922] [6] DEBUG:      data: 61 <14 bytes> 67
2017-09-26 12:09:36 [15922] [6] DEBUG:      data: 20 <14 bytes> 57
2017-09-26 12:09:36 [15922] [6] DEBUG:      data: 65 <14 bytes> 63
2017-09-26 12:09:36 [15922] [6] DEBUG:      data: 68 <14 bytes> 73
2017-09-26 12:09:36 [15922] [6] DEBUG:      data: 2e <14 bytes> 61
2017-09-26 12:09:36 [15922] [6] DEBUG:      data: 6c <14 bytes> 73
2017-09-26 12:09:36 [15922] [6] DEBUG:      data: 3a <14 bytes> 73
2017-09-26 12:09:36 [15922] [6] DEBUG:      data: 4d <14 bytes> 6e
2017-09-26 12:09:36 [15922] [6] DEBUG:    Octet string dump ends.
2017-09-26 12:09:36 [15922] [6] DEBUG: SMPP PDU dump ends.
2017-09-26 12:09:36 [15922] [6] DEBUG: SMPP[default_smsc]: Sending PDU:
2017-09-26 12:09:36 [15922] [6] DEBUG: SMPP PDU 0x7f2274020790 dump:
2017-09-26 12:09:36 [15922] [6] DEBUG:   type_name: deliver_sm_resp
2017-09-26 12:09:36 [15922] [6] DEBUG:   command_id: 2147483653 = 0x80000005
2017-09-26 12:09:36 [15922] [6] DEBUG:   command_status: 0 = 0x00000000
2017-09-26 12:09:36 [15922] [6] DEBUG:   sequence_number: 11867393 = 0x00b51501
2017-09-26 12:09:36 [15922] [6] DEBUG:   message_id: NULL
2017-09-26 12:09:36 [15922] [6] DEBUG: SMPP PDU dump ends.
2017-09-26 12:09:36 [15922] [6] DEBUG: SMPP[default_smsc]: throughput (0.00,5.00)
...

    • Example sent message:

      ...
2017-09-26 12:04:08 [15922] [6] DEBUG: SMPP[default_smsc]: throughput (0.00,5.00)
2017-09-26 12:04:08 [15922] [6] DEBUG: SMPP[default_smsc]: Manually forced source addr ton = 1, source add npi = 1
2017-09-26 12:04:08 [15922] [6] DEBUG: SMPP[default_smsc]: Manually forced dest addr ton = 1, dest add npi = 1
2017-09-26 12:04:08 [15922] [6] DEBUG: SMPP[default_smsc]: Sending PDU:
2017-09-26 12:04:08 [15922] [6] DEBUG: SMPP PDU 0x7f2274025070 dump:
2017-09-26 12:04:08 [15922] [6] DEBUG:   type_name: submit_sm
2017-09-26 12:04:08 [15922] [6] DEBUG:   command_id: 4 = 0x00000004
2017-09-26 12:04:08 [15922] [6] DEBUG:   command_status: 0 = 0x00000000
2017-09-26 12:04:08 [15922] [6] DEBUG:   sequence_number: 98163 = 0x00017f73
2017-09-26 12:04:08 [15922] [6] DEBUG:   service_type: NULL
2017-09-26 12:04:08 [15922] [6] DEBUG:   source_addr_ton: 5 = 0x00000005
2017-09-26 12:04:08 [15922] [6] DEBUG:   source_addr_npi: 0 = 0x00000000
2017-09-26 12:04:08 [15922] [6] DEBUG:   source_addr: "any"
2017-09-26 12:04:08 [15922] [6] DEBUG:   dest_addr_ton: 1 = 0x00000001
2017-09-26 12:04:08 [15922] [6] DEBUG:   dest_addr_npi: 1 = 0x00000001
2017-09-26 12:04:08 [15922] [6] DEBUG:   destination_addr: "43676......."
2017-09-26 12:04:08 [15922] [6] DEBUG:   esm_class: 3 = 0x00000003
2017-09-26 12:04:08 [15922] [6] DEBUG:   protocol_id: 0 = 0x00000000
2017-09-26 12:04:08 [15922] [6] DEBUG:   priority_flag: 0 = 0x00000000
2017-09-26 12:04:08 [15922] [6] DEBUG:   schedule_delivery_time: NULL
2017-09-26 12:04:08 [15922] [6] DEBUG:   validity_period: NULL
2017-09-26 12:04:08 [15922] [6] DEBUG:   registered_delivery: 0 = 0x00000000
2017-09-26 12:04:08 [15922] [6] DEBUG:   replace_if_present_flag: 0 = 0x00000000
2017-09-26 12:04:08 [15922] [6] DEBUG:   data_coding: 0 = 0x00000000
2017-09-26 12:04:08 [15922] [6] DEBUG:   sm_default_msg_id: 0 = 0x00000000
2017-09-26 12:04:08 [15922] [6] DEBUG:   sm_length: 23 = 0x00000017
2017-09-26 12:04:08 [15922] [6] DEBUG:   short_message:
2017-09-26 12:04:08 [15922] [6] DEBUG:    Octet string at 0x7f227400c460:
2017-09-26 12:04:08 [15922] [6] DEBUG:      len:  23
2017-09-26 12:04:08 [15922] [6] DEBUG:      size: 24
2017-09-26 12:04:08 [15922] [6] DEBUG:      immutable: 0
2017-09-26 12:04:08 [15922] [6] DEBUG:      data: 44 <14 bytes> 73
2017-09-26 12:04:08 [15922] [6] DEBUG:      data: 74 <5 bytes> 39
2017-09-26 12:04:08 [15922] [6] DEBUG:    Octet string dump ends.
2017-09-26 12:04:08 [15922] [6] DEBUG: SMPP PDU dump ends.
2017-09-26 12:04:08 [15922] [6] DEBUG: SMPP[default_smsc]: throughput (1.00,5.00)
...

    • Example link enquiry:

      ...
2017-09-26 12:13:38 [15922] [6] DEBUG: SMPP[default_smsc]: throughput (0.00,5.00)
2017-09-26 12:13:38 [15922] [6] DEBUG: SMPP[default_smsc]: Got PDU:
2017-09-26 12:13:38 [15922] [6] DEBUG: SMPP PDU 0x7f2274020790 dump:
2017-09-26 12:13:38 [15922] [6] DEBUG:   type_name: enquire_link
2017-09-26 12:13:38 [15922] [6] DEBUG:   command_id: 21 = 0x00000015
2017-09-26 12:13:38 [15922] [6] DEBUG:   command_status: 0 = 0x00000000
2017-09-26 12:13:38 [15922] [6] DEBUG:   sequence_number: 90764 = 0x0001628c
2017-09-26 12:13:38 [15922] [6] DEBUG: SMPP PDU dump ends.
2017-09-26 12:13:38 [15922] [6] DEBUG: SMPP[default_smsc]: Sending PDU:
2017-09-26 12:13:38 [15922] [6] DEBUG: SMPP PDU 0x7f2274025070 dump:
2017-09-26 12:13:38 [15922] [6] DEBUG:   type_name: enquire_link_resp
2017-09-26 12:13:38 [15922] [6] DEBUG:   command_id: 2147483669 = 0x80000015
2017-09-26 12:13:38 [15922] [6] DEBUG:   command_status: 0 = 0x00000000
2017-09-26 12:13:38 [15922] [6] DEBUG:   sequence_number: 90764 = 0x0001628c
2017-09-26 12:13:38 [15922] [6] DEBUG: SMPP PDU dump ends.
2017-09-26 12:13:38 [15922] [6] DEBUG: SMPP[default_smsc]: throughput (0.00,5.00)
...

SMS Box (PRX node of NGCP)

On the PRX node you can see a process named "smsbox". This process has a listening port assigned to it: 13002, that is the communication port towards the Bearer Box component running on LB nodes.

The ngcp-service tool also shows the smsbox process in its summary information:

$ ngcp-service summary
Ok Service                        Managed    Started   Status
-- ------------------------------ ---------- --------- ---------
…
   kannel-smsbox                  managed    by-ha     active
…

The following log files can provide information about the operation of SMS Box:

  • sent and received messages using the API of WEB node: /var/log/kannel/smsbox.log

    Sent and received message examples shown here do not contain the full phone number and content for confidentiality reason.

    • Example sent message:

      ...
2017-09-26 12:16:42 [22763] [2] DEBUG: HTTP: Creating HTTPClient for `192.168.1.2'.
2017-09-26 12:16:42 [22763] [2] DEBUG: HTTP: Created HTTPClient area 0x7f5dcc000ad0.
2017-09-26 12:16:42 [22763] [3] INFO: smsbox: Got HTTP request </cgi-bin/sendsms> from <192.168.1.3>
2017-09-26 12:16:42 [22763] [3] INFO: sendsms used by <sipwise>
2017-09-26 12:16:42 [22763] [3] INFO: sendsms sender:<sipwise:43668.......> (192.168.1.3) to:<43676.......> msg:<...>
2017-09-26 12:16:42 [22763] [3] DEBUG: Stored UUID ab95eb45-1ec0-4932-9863-1a95609a025f
2017-09-26 12:16:42 [22763] [3] DEBUG: message length 52, sending 1 messages
2017-09-26 12:16:42 [22763] [3] DEBUG: Status: 202 Answer: <Sent.>
2017-09-26 12:16:42 [22763] [3] DEBUG: Delayed reply - wait for bearerbox
2017-09-26 12:16:42 [22763] [0] DEBUG: Got ACK (0) of ab95eb45-1ec0-4932-9863-1a95609a025f
2017-09-26 12:16:42 [22763] [0] DEBUG: HTTP: Destroying HTTPClient area 0x7f5dcc000ad0.
2017-09-26 12:16:42 [22763] [0] DEBUG: HTTP: Destroying HTTPClient for `192.168.1.3'.
...

    • Example received message:

      ...
2017-09-26 11:59:45 [22763] [5] INFO: Starting to service <...message content...> from <+43676-------> to <+43668------->
2017-09-26 11:59:45 [22763] [10] DEBUG: Queue contains 0 pending requests.
2017-09-26 11:59:45 [22763] [10] DEBUG: HTTPS URL; Using SSL for the connection
2017-09-26 11:59:45 [22763] [10] DEBUG: Parsing URL `https://192.168.1.2:1443/internalsms/receive?auth_token=fNLosMgwdNUrKvEfFMm9
&timestamp=2017-09-26+09:59:45&from=%2B43676-------&to=%2B43668-------&charset=UTF-8&coding=0&text=...':
2017-09-26 11:59:45 [22763] [10] DEBUG:   Scheme: https://
2017-09-26 11:59:45 [22763] [10] DEBUG:   Host: 192.168.1.2
2017-09-26 11:59:45 [22763] [10] DEBUG:   Port: 1443
2017-09-26 11:59:45 [22763] [10] DEBUG:   Username: (null)
2017-09-26 11:59:45 [22763] [10] DEBUG:   Password: (null)
2017-09-26 11:59:45 [22763] [10] DEBUG:   Path: /internalsms/receive
2017-09-26 11:59:45 [22763] [10] DEBUG:   Query: auth_token=fNLosMgwdNUrKvEfFMm9&timestamp=2017-09-26+09:59:45&from=%2B43676-------
&to=%2B43668-------&charset=UTF-8&coding=0&text=...
2017-09-26 11:59:45 [22763] [10] DEBUG:   Fragment: (null)
2017-09-26 11:59:45 [22763] [10] DEBUG: Connecting nonblocking to <192.168.1.2>
2017-09-26 11:59:45 [22763] [10] DEBUG: HTTP: Opening connection to `192.168.1.2:1443' (fd=31).
2017-09-26 11:59:45 [22763] [10] DEBUG: Socket connecting
2017-09-26 11:59:45 [22763] [9] DEBUG: Get info about connecting socket
2017-09-26 11:59:45 [22763] [9] DEBUG: HTTP: Sending request:
2017-09-26 11:59:45 [22763] [9] DEBUG: Octet string at 0x7f5dbc00f470:
2017-09-26 11:59:45 [22763] [9] DEBUG:   len:  382
2017-09-26 11:59:45 [22763] [9] DEBUG:   size: 1024
2017-09-26 11:59:45 [22763] [9] DEBUG:   immutable: 0
2017-09-26 11:59:45 [22763] [9] DEBUG:   data: 47 45 54 20 2f 69 6e 74 65 72 6e 61 6c 73 6d 73   GET /internalsms
2017-09-26 11:59:45 [22763] [9] DEBUG:   data: 2f 72 65 63 65 69 76 65 3f 61 75 74 68 5f 74 6f   /receive?auth_to
2017-09-26 11:59:45 [22763] [9] DEBUG:   data: 6b 65 6e 3d ...                                   ken=
                                                          ... 20 48 54 54 50 2f 31 2e 31 0d 0a         HTTP/1.1..
2017-09-26 11:59:45 [22763] [9] DEBUG:   data: 43 6f 6e 6e 65 63 74 69 6f 6e 3a 20 6b 65 65 70   Connection: keep
2017-09-26 11:59:45 [22763] [9] DEBUG:   data: 2d 61 6c 69 76 65 0d 0a 55 73 65 72 2d 41 67 65   -alive..User-Age
2017-09-26 11:59:45 [22763] [9] DEBUG:   data: 6e 74 3a 20 4b 61 6e 6e 65 6c 2f 31 2e 34 2e 34   nt: Kannel/1.4.4
2017-09-26 11:59:45 [22763] [9] DEBUG:   data: 0d 0a 48 6f 73 74 3a 20 31 39 32 2e 31 36 38 2e   ..Host: 192.168.
2017-09-26 11:59:45 [22763] [9] DEBUG:   data: 31 2e 32 3a 31 34 34 33 0d 0a 0d 0a               1.2:1443....
2017-09-26 11:59:45 [22763] [9] DEBUG: Octet string dump ends.
2017-09-26 11:59:45 [22763] [9] DEBUG: HTTP: Status line: <HTTP/1.1 200 OK>
2017-09-26 11:59:45 [22763] [9] DEBUG: HTTP: Received response:
2017-09-26 11:59:45 [22763] [9] DEBUG: Octet string at 0x7f5dbc006970:
2017-09-26 11:59:45 [22763] [9] DEBUG:   len:  333
2017-09-26 11:59:45 [22763] [9] DEBUG:   size: 1024
2017-09-26 11:59:45 [22763] [9] DEBUG:   immutable: 0
2017-09-26 11:59:45 [22763] [9] DEBUG:   data: 53 65 72 76 65 72 3a 20 6e 67 69 6e 78 0d 0a 44   Server: nginx..D
2017-09-26 11:59:45 [22763] [9] DEBUG:   data: 61 74 65 3a 20 54 75 65 2c 20 32 36 20 53 65 70   ate: Tue, 26 Sep
2017-09-26 11:59:45 [22763] [9] DEBUG:   data: 20 32 30 31 37 20 30 39 3a 35 39 3a 34 35 20 47    2017 09:59:45 G
2017-09-26 11:59:45 [22763] [9] DEBUG:   data: 4d 54 0d 0a 43 6f 6e 74 65 6e 74 2d 54 79 70 65   MT..Content-Type
2017-09-26 11:59:45 [22763] [9] DEBUG:   data: 3a 20 74 65 78 74 2f 68 74 6d 6c 3b 20 63 68 61   : text/html; cha
2017-09-26 11:59:45 [22763] [9] DEBUG:   data: 72 73 65 74 3d 75 74 66 2d 38 0d 0a 43 6f 6e 74   rset=utf-8..Cont
2017-09-26 11:59:45 [22763] [9] DEBUG:   data: 65 6e 74 2d 4c 65 6e 67 74 68 3a 20 30 0d 0a 43   ent-Length: 0..C
2017-09-26 11:59:45 [22763] [9] DEBUG:   data: 6f 6e 6e 65 63 74 69 6f 6e 3a 20 6b 65 65 70 2d   onnection: keep-
2017-09-26 11:59:45 [22763] [9] DEBUG:   data: 61 6c 69 76 65 0d 0a 53 65 74 2d 43 6f 6f 6b 69   alive..Set-Cooki
2017-09-26 11:59:45 [22763] [9] DEBUG:   data: 65 3a 20 6e 67 63 70 5f 70 61 6e 65 6c 5f 73 65   e: ngcp_panel_se
2017-09-26 11:59:45 [22763] [9] DEBUG:   data: 73 73 69 6f 6e 3d 34 35 30 32 64 64 66 65 31 62   ssion=4502ddfe1b
2017-09-26 11:59:45 [22763] [9] DEBUG:   data: 63 31 65 33 39 30 65 30 64 36 66 39 64 34 37 30   c1e390e0d6f9d470
2017-09-26 11:59:45 [22763] [9] DEBUG:   data: 35 30 37 62 64 64 33 61 65 32 36 62 64 63 3b 20   507bdd3ae26bdc;
2017-09-26 11:59:45 [22763] [9] DEBUG:   data: 70 61 74 68 3d 2f 3b 20 65 78 70 69 72 65 73 3d   path=/; expires=
2017-09-26 11:59:45 [22763] [9] DEBUG:   data: 54 75 65 2c 20 32 36 2d 53 65 70 2d 32 30 31 37   Tue, 26-Sep-2017
2017-09-26 11:59:45 [22763] [9] DEBUG:   data: 20 31 30 3a 35 39 3a 34 35 20 47 4d 54 3b 20 48    10:59:45 GMT; H
2017-09-26 11:59:45 [22763] [9] DEBUG:   data: 74 74 70 4f 6e 6c 79 0d 0a 58 2d 43 61 74 61 6c   ttpOnly..X-Catal
2017-09-26 11:59:45 [22763] [9] DEBUG:   data: 79 73 74 3a 20 35 2e 39 30 30 37 35 0d 0a 53 74   yst: 5.90075..St
2017-09-26 11:59:45 [22763] [9] DEBUG:   data: 72 69 63 74 2d 54 72 61 6e 73 70 6f 72 74 2d 53   rict-Transport-S
2017-09-26 11:59:45 [22763] [9] DEBUG:   data: 65 63 75 72 69 74 79 3a 20 6d 61 78 2d 61 67 65   ecurity: max-age
2017-09-26 11:59:45 [22763] [9] DEBUG:   data: 3d 31 35 37 36 38 30 30 30 0d 0a 0d 0a            =15768000....
2017-09-26 11:59:45 [22763] [9] DEBUG: Octet string dump ends.
2017-09-26 11:59:45 [22763] [6] WARNING: Tried to set Coding field, denied.
2017-09-26 11:59:45 [22763] [6] INFO: No reply sent, denied.
2017-09-26 11:59:55 [22763] [9] DEBUG: HTTP: Server closed connection, destroying it <192.168.1.2:1443:1::><0x7f5db0000b20><fd:31>.
...

  • short log of sent/received messages: /var/log/kannel/smsbox-access.log

    ...
2017-09-26 12:39:18 SMS HTTP-request sender:+43680------- request: '' url: 'https://192.168.1.2:1443/internalsms/receive?
auth_token=fNLosMgwdNUrKvEfFMm9&timestamp=2017-09-26+10:39:18&from=%2B43680-------&to=%2B43668-------&charset=UTF-8&coding=0
&text=<...message content...>' reply: 200 '<< successful >>'
...
2017-09-26 12:41:54 send-SMS request added - sender:sipwise:43668------- 192.168.1.3 target:43680-------- request: '<...message content...>'
...

REST API

Handling of short messages from the user perspective happens with the help of NGCP’s REST API. There is a dedicated resource: https://<IP of WEB node>:1443/api/sms that allows you to:

  • Get a list of sent and received messages. This is achieved by sending a GET request on the /api/sms collection, as in the following example:

    curl -i -X GET -H 'Connection: close' --cert NGCP-API-client-certificate.pem \
  --cacert ca-cert.pem 'https://example.org:1443/api/sms/?page=1&rows=10'

  • Retrieve an SM (both sent and received). This is achieved by sending a GET request for a specific /api/sms/id item, as in the following example:

    curl -i -X GET -H 'Connection: close' --cert NGCP-API-client-certificate.pem \
  --cacert ca-cert.pem 'https://example.org:1443/api/sms/1'

  • Send a new message from a local subscriber. This is achieved by sending a POST request for the /api/sms collection, as in the following example:

    curl -i -X POST -H 'Connection: close' -H 'Content-Type: application/json' \
  --cert NGCP-API-client-certificate.pem --cacert ca-cert.pem \
  'https://example.org:1443/api/sms/'  --data-binary '{"callee" : "43555666777", \
  "subscriber_id" : 4, "text" : "test"}'

As always, the full documentation of the REST API resources is available on the admin web interface of NGCP: https://<IP of WEB node>:1443/api/#sms