The sip:provider PRO 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.
The Device Management is used by admins and resellers to define the list of device models, firmwares and configurations available for end customer usage. These settings are pre-configured for the default reseller up-front by 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 Section 15.1.12, “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.
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.
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.
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.
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 busy lamp field
option.
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 him 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:
Finally press Save to create the new device model.
A device model can optionally have one or more device firmware(s). Some devices like the Cisco SPA series don’t 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:
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.
Select the device model we’re going to upload the firmware for, then specify the firmware version and choose the firmware file, then press Save.
Repeat this step for every firmware in the list above (and any new firmware you want to support when it’s available).
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.
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.
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
).
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.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, on of private
, shared
or blf
.
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.
Within the configuration template itself, you can use any Template Toolkit directive and any own variables you like (just make sure to not override any of the ones specified above). For documentation on the syntax, please refer to the Template Toolkit Manual.
In order to change the provisioning base IP and port (default 1444), you have to access |
When the customer configures his own device, he doesn’t 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 Profile row in the Device Management section and press Create 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 he is selecting a device he wants to provision, so pick a descriptive name which clearly identifies a device. Press Save to create the profile.
Repeat the steps as needed for every device you want to make available to customers.
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.
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.
^([1-9][0-9]+)$
${caller_cloud_pbx_base_cli}\1
extension to e164
Inbound
Caller
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
^([1-9][0-9]+)$
${caller_cloud_pbx_base_cli}\1
extension to e164
Inbound
Callee
Local dialing without area code (use break-out code 0
)
^0([1-9][0-9]+)$
${caller_cc}${caller_ac}\1
local to e164
Inbound
Callee
National dialing (use break-out code 0
and prefix area code by 0
)
^00([1-9][0-9]+)$
${caller_cc}\1
national to e164
Inbound
Callee
International dialing (use break-out code 0
and prefix country code by 00
)
^000([1-9][0-9]+)$
\1
international to e164
Inbound
Callee
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 caller name will be shown (this is handled by implicitly setting domain preferences 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
)
^([1-9][0-9]+)$
000\1
e164 to full international
Outbound
Caller
Displaying the extension in the caller number for PBX-internal calls
^@{callee_cloud_pbx_account_cli_list}$
${caller_cloud_pbx_ext}
e164 to full international
Outbound
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.
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.
Go to Settings→Customers and click Create Customer. We need a Contact for the customer, so press Create Contact.
Fill in the desired fields (you need to provide at least the Email Address) and press Save.
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.
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.
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.
To create the subscriber, open the Subscribers row and click 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 just a subscriber) called |
To handle one domain per customer, you should create a wild-card entry into your DNS server like |
So to create a new domain for the customer, click Create Domain.
Specify the domain you want to create, and select the PBX Rewrite Rule Set which you created in Section 15.1.2, “Preparing PBX Rewrite Rules”, then click Save.
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:
Once the subscriber is created, he can log into the customer self-care interface at https://<your-ip>/login/subscriber
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 the 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.
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.
To create another subscriber for the customer PBX, open the Subscribers row and click Create Subscriber.
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:
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 just normal subscribers in the system, you can assign Alias Numbers to it for DID later, e.g. 43 1 9998
.
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.
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.
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.
Click Save to create the subscriber.
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:
The subscribers can be reached via 3 different ways. First, you can call them by their SIP URIs (e.g. by dialing |
Basically you can register any SIP phone to the system using the SIP credentials of your subscribers. However, the platform supports Device Provisioning of certain vendors and models, as described in Section 15.1.1, “Configuring the Device Management”.
To configure a physical device, open the PBX Devices row in the Customer Details view and click Create Device.
You have to set three general parameters for your new device, which are:
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:
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:
BLF Key: The Busy Lamp Field monitors the call state of another subscriber and provides three different functionalities, depending on the actual state:
In our example, we will first configure a private line on the first key, and BLF for another subscriber on the second key.
This configures the general options plus the first key. To configure the second key, click Add another Line/Key and fill out the second line config accordingly. Click Save to save your PBX device configuration.
Once the PBX device is saved, you will see it in the list of PBX Devices.
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.
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.
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.
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 applies them automatically. |
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:
Fill in the settings and click Save.
To upload files to your Sound Set, click the Files button for the Sound Set.
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 just once. Click Save to upload the file.
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 are other PBX subscribers or groups — when the called subscriber is not available.
The Auto Attendant feature can be activated for any subscriber in the Customer PBX individually. There are three steps involved:
1
should go to the marketing
subscriber, 2
to development
and 3
to some external number).
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.
Create a Sound Set and upload the Sound Files for it as described below. Afterwards in the Subscriber Preferences view, set the Customer Sound Set preference to the Sound Set to be used. To do so, click Edit on the Customer 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.
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 Section 15.1.7.3, “Configuring the Auto Attendant Slots”. |
An example configuration could look like this:
The illustration below shows the sequence of voice prompts played when Auto Attendant feature is activated and a caller listens the IVR menu.
In the Auto Attendant Slots section, click the Edit Slots button to configure the destination options.
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.
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.
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. |
The sip:provider PRO platform offers call queueing feature for Cloud PBX subscribers. For any subscriber within the PBX the NGCP system administrator or the subscriber himsef may activate the Call Queue. This is done individually for each subscriber on demand.
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 his call with the first caller and gets free.
The call queue configuration is available at the path: Subscribers → select one → Details → 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
In order to change the actual setting, press the Edit button in the relevant row.
Queued callers first hear a greeting message then information about their position in the queue and finally a waiting music / signal.
Table 20. Call Queue Voice Prompts
Prompt handle | Prompt content |
---|---|
| All lines are busy at the moment, you are being queued. |
| You are currently number… |
| … in the queue, please hold the line. |
| All lines are busy at the moment, please try again later. |
| <waiting music> |
The Cisco SPA phones can connect to the provisioning interface of the PBX via HTTP and HTTPS. When perform 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.
Only send the CSR file. Do NOT send the key file, as this is your private key! |
Ask for both the signed certificate AND a so-called combinedca.crt which is needed to perform client authentication via SSL. Otherwise you can not restrict access to Cisco SPAs only. |
You will receive a signed CRT file, which Sipwise can use to configure the PBX provisioning interface.
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.
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.
Initial Bootstrapping
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.
Initial Bootstrapping
Panasonic provides a zero-touch provisioning mechanism in their firmwares, which causes the factory-reset phones 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.
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:
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.
Initial Bootstrapping
Yealink provides a zero-touch provisioning mechanism in their firmwares, which causes the factory-reset phones to connect to a Yealink web service at https://rps.yealink.com 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.
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 firmwares don’t 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.
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 is pointing to the NGCP provisioning server (in case of NGCP 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 the NGCP provisioning interface.
The Audiocodes device should request the firmware file or CLI configuration file from the NGCP platform. The firmware versions and CLI config versions are decoupled from each other; the NGCP 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.
NGCP 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 the NGCP platform. The firmware and CLI config files are provided at the following URLs:
https://<NGCP_IP>:1444/device/autoprov/firmware/001122334455/from/0/latest
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 the NGCP provisioning interface.
Device management basics
The list of device models, firmwares and configurations are global to a reseller and are available for end customer. This data is initially provided by Sipwise as bulk upload of all supported phone models. The firmwares and settings are stored in the database on the DB node pair(s). The NGCP leverages the Cloud PBX module with its template system to generate the configurations and firmware files from database on the fly. Please refer to the following chapters in NGCP 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 the NGCP 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:
SIP account credentials:
"sip-definition account 0"
[username]
[password]
[domain]
"[country code][area code][extension]"
IP Groups:
"voip-network ip-group 1" and "voip-network ip-group 2"
[domain]
Proxy and registration settings:
"sip-definition proxy-and-registration"
[domain]
Manipulations:
manipulation-name "from trunk domain":
"sbc manipulations message-manipulations 3"
"[% line.domain %]"
manipulation-name "clip no screening":
"sbc manipulations message-manipulations 8"
"'<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"
[IPPBX_Hostname]
Manipulations:
"sbc manipulations message-manipulations 1"
[IPPBX_Hostname]
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 ISDN gateways and eSBCs are devices used to connect legacy (ISDN) PBX and IP-PBX to the Sipwise NGCP platform and maintain their operations within the Operator’s network. Sipwise NGCP offers a SipConnect 1.1 compliant signaling and media interface to connect SIP trunks to the platform. In addition to this interface, the Sipwise NGCP 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 NGCP in one way or the other to request its device configuration and subsequently download specific firmwares, 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:
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 the Sipwise NGCP is serving, before handing the devices over to field service engineers doing the truck rolls.
Field Configuration
The Sipwise NGCP provides a SipConnect 1.1 compliant interface on the network side for the Audiocodes devices. This interface clearly 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:
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’s why the network configuration mentioned above only serves as proposal and any feedback is highly welcome. However, it must be clearly communicated how the customer facing network is going to be configured, because the Sipwise NGCP needs to incorporate this configuration into the Audiocodes configuration templates.
Pre-Configuration on Sipwise NGCP platform
Next, the customer has to be created on the Sipwise NGCP. 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 1.1 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:
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:
Installation
Once the above requirements are fulfilled and the customer is created on the Sipwise NGCP, the Audiocodes device can be installed at the customer premise.
When the Audiocodes device boots, it requests the configuration file from the Sipwise NGCP by issuing a GET request via HTTPS.
For authentication and authorization purposes, the Sipwise NGCP requests an SSL client certificate from the device and will check whether it’s signed by a Certificate Authority known to the Sipwise NGCP. Therefore, Audiocodes must provide the CA certificate used to sign the devices' client certificates to Sipwise to allow for this process. Also, the Sipwise NGCP 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:
Once the secured HTTPS connection is established, the Sipwise NGCP 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’s still operational). For inbound calls to the customer, this will cause parallel ringing to take place, and it’s 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 the Sipwise NGCP.
Vendor | Model | Available from release |
---|---|---|
Audiocodes | Mediant800 | mr4.1.1.1 |
Cisco | ATA112 | mr3.4.1.1 |
Cisco | ATA122 | mr3.4.1.1 |
Cisco | SPA232D | mr3.4.1.1 |
Cisco | SPA301 | mr3.4.1.1 |
Cisco | SPA303 | mr3.4.1.1 |
Cisco | SPA501G | mr3.4.1.1 |
Cisco | SPA502G | mr3.4.1.1 |
Cisco | SPA512G | mr3.4.1.1 |
Cisco | SPA504G | mr3.4.1.1 |
Cisco | SPA504G + SPA500S | mr3.7.1.4 |
Cisco | SPA504G + two SPA500S | mr3.7.1.4 |
Cisco | SPA514G | mr3.4.1.1 |
Cisco | SPA508G | mr3.4.1.1 |
Cisco | SPA509G | mr3.4.1.1 |
Cisco | SPA525G | mr3.4.1.1 |
Innovaphone | IP2X2X | mr3.8.3.3 |
Innovaphone | IP230-X | mr3.8.3.3 |
Innovaphone | IP232 | mr3.8.3.3 |
Innovaphone | IP222 | mr3.8.3.3 |
Innovaphone | IP240 | mr3.8.3.3 |
Innovaphone | IP22 | mr3.8.3.3 |
Innovaphone | IP111 | mr3.8.3.3 |
Panasonic | KX-UT113 | mr3.7.1.1 |
Panasonic | KX-UT123 | mr3.7.1.1 |
Panasonic | KX-UT133 | mr3.7.1.1 |
Panasonic | KX-UT136 | mr3.7.1.1 |
Panasonic | KX-UT248 | mr3.7.1.1 |
Yealink | SIP-T19P | mr3.7.1.1 |
Yealink | SIP-T20P | mr3.7.1.1 |
Yealink | SIP-T21P | mr3.7.1.1 |
Yealink | SIP-T22P | mr3.7.1.1 |
Yealink | SIP-T23P | mr3.7.1.1 |
Yealink | SIP-T23G | mr3.7.1.1 |
Yealink | SIP-T26P | mr3.7.1.1 |
Yealink | SIP-T28P | mr3.7.1.1 |
Yealink | SIP-T32G | mr3.7.1.1 |
Yealink | SIP-T38G | mr3.7.1.1 |
Yealink | SIP-T41P | mr3.7.1.1 |
Yealink | SIP-T42G | mr3.7.1.1 |
Yealink | SIP-T46G | mr3.7.1.1 |
Yealink | SIP-T48G | mr3.7.1.1 |
Yealink | SIP-T28P + EXP39 | mr3.8.1.1 |
Yealink | SIP-T28P + two EXP39 | mr3.8.1.1 |
Yealink | W52P | mr3.7.1.6 |
IP Phones
Model | IPv6 | TLS | SRTP | Auto provisioning | Private Line | Shared Line | Busy Lamp | Extension Boards |
---|---|---|---|---|---|---|---|---|
SPA301 | N | Y | Y | http | 1 | 1 | 0 | N |
SPA303 | N | Y | Y | http | 1-3 | 1-3 | 1-2 | N |
SPA501G | N | Y | Y | http | 1-8 | 1-8 | 1-7 | N |
SPA502G | N | Y | Y | http | 1 | 1 | 0 | N |
SPA512G | N | N | Y | http | 1 | 1 | 0 | N |
SPA504G | N | Y | Y | http | 1-4 | 1-4 | 1-3 | 2 |
SPA514G | N | N | Y | http | 1-4 | 1-4 | 1-3 | N |
SPA508G | N | Y | Y | http | 1-8 | 1-8 | 1-7 | N |
SPA509G | N | Y | Y | http | 1-12 | 1-12 | 1-11 | N |
SPA525G | N | Y | N | http | 1-5 | 1-5 | 1-4 | N |
Analog Adapters
Model | IPv6 | TLS | SRTP | Auto provisioning | Private Line | Shared Line | Busy Lamp |
---|---|---|---|---|---|---|---|
SPA232D | N | Y | Y | http | 1-6 | 0 | 0 |
ATA112 | Y | Y | Y | http | 1-2 | 0 | 0 |
ATA122 | Y | Y | Y | http | 1-2 | 0 | 0 |
Extension Boards
Model | Ports | Buttons | Busy Lamp | Supported phones |
---|---|---|---|---|
SPA500S | 2 | 32 | 1-32 | SPA500 |
IP Phones
Model | IPv6 | TLS | SRTP | Auto provisioning | Private Line | Shared Line | Busy Lamp | Extension Boards |
---|---|---|---|---|---|---|---|---|
KX-UT113 | N | N | N | redirect | 1-2 | 1-2 | 0 | N |
KX-UT123 | N | N | N | redirect | 1-2 | 1-2 | 0 | N |
KX-UT133 | N | N | N | redirect | 1-4 | 1-4 | 1-23 | N |
KX-UT136 | N | N | N | redirect | 1-4 | 1-4 | 1-23 | N |
KX-UT248 | N | N | Y | redirect | 1-6 | 1-6 | 1-23 | N |
IP Phones
Model | IPv6 | TLS | SRTP | Auto provisioning | Private Line | Shared Line | Busy Lamp | Extension Boards |
---|---|---|---|---|---|---|---|---|
SIP-T19P | Y | Y | Y | redirect | 1 | 1 | 0 | N |
SIP-T20P | Y | Y | Y | redirect | 1 | 1 | 0 | N |
SIP-T21P | Y | Y | Y | redirect | 1-2 | 1-2 | 1 | N |
SIP-T22P | Y | Y | Y | redirect | 1-3 | 1-3 | 1-2 | N |
SIP-T23P | Y | Y | Y | redirect | 1-3 | 1-3 | 1-2 | N |
SIP-T23G | Y | Y | Y | redirect | 1-3 | 1-3 | 1-2 | N |
SIP-T26P | Y | Y | Y | redirect | 1-3 | 1-3 | 1-12 | N |
SIP-T28P | Y | Y | Y | redirect | 1-6 | 1-6 | 1-15 | 2 |
SIP-T32G | Y | Y | Y | redirect | 1-3 | 1-3 | 1-2 | N |
SIP-T38G | Y | Y | Y | redirect | 1-6 | 1-6 | 1-15 | N |
SIP-T41P | Y | Y | Y | redirect | 1-3 | 1-3 | 1-14 | N |
SIP-T42G | Y | Y | Y | redirect | 1-3 | 1-3 | 1-14 | N |
SIP-T46G | Y | Y | Y | redirect | 1-6 | 1-6 | 1-26 | N |
SIP-T48G | Y | Y | Y | redirect | 1-6 | 1-6 | 1-28 | N |
W52P | N | Y | Y | redirect | 1-5 | 1-5 | 0 | N |
IP Phones
Model | IPv6 | TLS | SRTP | Auto provisioning | Private Line | Shared Line | Busy Lamp | Extension Boards |
---|---|---|---|---|---|---|---|---|
IP232 | N | Y | Y | dhcp | 1 | 0 | 1-16 | 2 |
IP222 | N | Y | Y | dhcp | 1 | 0 | 1-16 | 2 |
IP240 | N | N | N | dhcp | 1 | 0 | 1-15 | 2 |
IP111 | N | Y | Y | dhcp | 1 | 0 | 1-16 | 0 |
Analog Adapters
Model | IPv6 | TLS | SRTP | Auto provisioning | Private Line | Shared Line | Busy Lamp |
---|---|---|---|---|---|---|---|
IP22 | N | Y | Y | dhcp | 1 | 0 | 0 |
Extension Boards
Model | Ports | Buttons | Busy Lamp | Supported phones |
---|---|---|---|---|
IP2X2X | 2 | 64 | 1-32 | IP2x2 |
IP230-X | 2 | 30 | 1-30 | IP230 |
SPA301
1) Soft keys
Not available.
2) Hard keys
3) Line keys
Not available.
4) VSC
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
3) Line keys
4) VSC
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
3) Line keys
4) VSC
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
3) Line keys
Not available.
4) VSC
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
3) Line keys
4) VSC
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
3) Line keys
Not available.
4) VSC
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
3) Line keys
4) VSC
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
3) Line keys
4) VSC
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
3) Line keys
4) VSC
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
3) Line keys
4) VSC
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
3) Line keys
Not available.
4) VSC
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
3) Line keys
4) VSC
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
3) Line keys
4) VSC
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
3) Line keys
4) VSC
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
3) Line keys
4) VSC
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
3) Line keys
4) VSC
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
3) Line keys
4) VSC
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
3) Line keys
4) VSC
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
3) Line keys
4) VSC
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
3) Line keys
4) VSC
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
3) Line keys
4) VSC
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
3) Line keys
4) VSC
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
3) Line keys
4) VSC
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
3) Line keys
4) VSC
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
3) VSC
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
3) Line keys
Not available.
4) VSC
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
3) Line keys
Not available.
4) VSC
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
3) Line keys
4) VSC
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
3) Line keys
4) VSC
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
3) Line keys
4) VSC
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
3) Line keys
4) VSC
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
3) Line keys
4) VSC
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
3) Line keys
4) VSC
IP240
1) Soft keys
Not available.
2) Hard keys
3) Line keys
4) VSC
You can order two commercial Unified Communication Clients for full end-to-end integration of voice, video, chat and presence features. There are two applications available:
Both clients are fully brandable to the customer’s corporate identity. The clients are not part of the standard delivery and need to be licensed separately. This handbook discusses the mobile client in details.
We continuously develop the mobile clients to provide new features, as they do not support the full range of features yet.
The sip:phone Mobile App is a mobile client for iOS and Android that supports voice calls via SIP, as well as presence and instant messaging via XMPP. The following sections describe the steps needed to integrate it into your sip:provider PRO.
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 the sip:provider PRO (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 just clicks the URL, and it automatically launches the app with the correct credentials. The following picture shows the overall 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.
The 3rd Party Sign-Up Form is a website the app shows to the end user when he taps the sign-up link on the app Login Screen. There, the end customer usually provides his contact details like name, address, phone number and email address, etc. After validation, the website creates an account and a subscriber in the sip:provider PRO 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.
Therefore, the 3rd Party Sign-Up Form needs to construct this string using the credentials defined while creating the subscriber via the sip:provider PRO API, then encrypt it via AES, and finally perform a Base64 encoding of the result.
Up until and including version mr5.1.2 of the sip:provider PRO, the SIP login credentials are used here. Future versions will connect to the REST interface of the sip:provider PRO using the web credentials first and fetch the SIP credentials along with other settings from there. |
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 specified 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 $crypted = $cipher->encrypt($plain); # store b64-encoded string and print to STDOUT my $b64 = encode_base64($crypted, ''); 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' \ | /path/to/encrypt.pl
This command would result in the output strings CI8VN8toaE40w8E4OH2rAuFj3Qev9QdLI/Wv/VaBCVK2yNkBZjxE9eafXkkrQfmYdeu01PquS5P40zhUq8Mfjg==
and 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' \ | /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.
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 simply 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 the sip:provider PRO will be shipped with this launch handler integrated into the system. Up until and including the version mr5.1.2, this script needs to be installed on any webserver manually. |
The mobile push functionality provides the remote start of a mobile application on incoming calls via the Google GCM 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. |
If the mobile push functionality is enabled and there are no devices registered for a subscriber, the call-flow looks as follows.
In the case of a time-out (no registration notification within a particular time), the application server rejects the call request with an error.
Follow this checklist to make sure you’ve completed all the steps. If you miss anything, the service may not work as expected.
Name | Description | Link |
---|---|---|
Obtain a trusted SSL certificate from a CA | Required for either application | |
Create an Apple developer account and enable the push notification service | For iOS mobile application | Section 15.2.2.4, “Create an Apple Account and Enable the Push Notification Service” |
Obtain the Apple certificate for the app | For iOS mobile application | Section 15.2.2.5, “Obtain an Apple SSL Certificate and a Private Key” |
Obtain the API key for the app from Google | For Android mobile application | Section 15.2.2.6, “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 | Section 15.2.2.7, “Provide the Required Information to Developers” |
Adjust the configuration | Adjust the config.yml file and apply the changes (usually performed by Sipwise) | Section 15.2.2.8, “Adjust the sip:provider PRO Configuration (Usually Performed by Sipwise)” |
Recheck your DNS Zone configuration | Check that the DNS Zone is correctly configured | |
Add DNS SRV records | Create specific DNS SRV records for SIP and XMPP services | |
Check NTP configuration | Ensure that all your servers show exact time | |
Enable Apple/Google Mobile Push in the Admin Panel | It can be enabled for a domain or separate subscribers | |
Configure a mobile application | Check that subscribers can easily install and use your application |
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 sip:provider PRO 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.
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. |
Register an App ID:
Sign into developer.apple.com/account.
Click Certificates, IDs & Profiles.
Under Identifiers, select App IDs.
Click the Add button (+) in the upper-right corner.
Enter a name for the App ID in the App ID Description block. This helps you identify the App ID later.
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 (*).
In the App Services section enable Push Notifications. Click Continue to submit the form
Create a CSR (Certificate Signing Request):
Sign into developer.apple.com/account/ios/certificate.
Click the Add button (+) in the upper-right corner.
Select Apple Push Notification service SSL (Sandbox & Production) as the certificate type and click Continue.
Select your App ID and click Continue.
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. |
Get the Certificate and Private Key
When you have the CSR file return to the browser and click Continue.
Click Choose File… in your browser.
Select the CSR file you just created and saved and click Continue.
Generate a PEM file from the p12 file:
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
You can use Google Cloud Messaging (GCM) 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 the NGCP 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, the NGCP identifies itself using an API key. To get it, follow the steps below.
Create a new project in the Google APIs Console page. For this go to code.google.com/apis/console.
Click Create a Project..
Input the project name, agree with the Terms of Service and click Create.
Click Google Cloud Messaging on the Overview page.
Click Enable for the Google Cloud Messaging.
Click Go to Credentials.
Select Google Cloud Messaging and Web Server from the corresponding lists and click What credentials do I need?
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. |
Copy your API key and click Done. Save the API key for future use.
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:
For the Android application, provide the following:
Specify the corresponding paths and names in the pushd section of the config.yml file:
apns: section (For iOS mobile application)
gcm: section (for Android mobile application)
sslcertkeyfile: /etc/ngcp-config/ssl/CAsigned.key
You can find an example of /etc/ngcp-config/config.yml configuration in the config.yml overview section.
ngcpcfg apply 'enabled the backup feature.' ngcpcfg push
Check that your NS and A DNS records are correctly configured.
Let’s 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 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
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
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 sip:provider PRO servers and works reliably. Execute the following command for quick test of time synchronization:
ntpq –p
If the current node synchronizes with an NTP server, this server will be marked by the star (*) symbol.
It can be enabled for a domain or separate subscribers in the Admin Panel.
To enable the service for a domain:
Perform tests when the application is available:
Make sure that the subscribers can start using your services in the easiest possible way.
The Sipwise sip:provider PRO, 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 the Sipwise NGCP 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:
Main interfaces of lawful interception according to ETSI standard:
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. |
Mechanism which passes information between an access provider or network operator or service provider and a handover interface.
Sipwise sip:provider PRO 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:
Sipwise NGCP behaves as the Administration Function (AF) but the actual call data capturing is carried out by other SIP endpoints. In this case NGCP 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:
This handbook will discuss the second setup in details in the following sections.
The below figure illustrates the logical connection of LI functions on Sipwise NGCP.
This kind of LI implementation will be phased out in future NGCP releases.
A short description is kept here for reference, as NGCP still (as of version mr4.5.2)
supports LI services with |
The captagent
based implementation of LI functions on Sipwise NGCP includes the
following components:
captagent: a software module provided by a third party; its operation can be summarized as follows:
captagent
process gets LI requests through an API
captagent
sends IRI through X2 interface
to the MF element
captagent
module, using X1, X2 and X3 interfaces.
Although the implementation of LI services with captagent
is still available and
configurable on sip:provider PRO, Sipwise suggests deploying a revised solution with
its voisniff-ng
software module. This newer implementation also relies on a 3rd
party LI provider representing the LI Mediation Function (MF), where Sipwise currently
(as of NGCP version mr4.5.2) cooperates with Group2000, Pine and Utimaco.
Sipwise NGCP components providing LI functions:
ngcp-panel: this module is responsible for managing REST API for the whole NGCP in general
sp1 / sp2
) on a sip:provider PRO platform
kamailio-proxy: this module serves as a generic call control function on the NGCP
sp1 / sp2
) on a sip:provider PRO platform
voisniff-ng: this module is a generic element for capturing SIP and RTP traffic on the NGCP
sp1 / sp2
) on a sip:provider PRO platform
The |
Authentication and Confidentiality
It is required that the communication between the telecommunication operator’s network element (that is: Sipwise NGCP) 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 Sipwise NGCP and the MF must authenticate themselves by certificates, for this reason the NGCP operator must ensure that valid certificates are deployed on the system. There is a need to contact the 3rd party LI provider, so that he can provide the necessary client certificates that NGCP will use to setup secured connection to the MF on X2 and X3 interfaces.
Similarly, the MF provider must contact the NGCP operator to offer him valid client certificates that the MF element will use to establish secured connection to the NGCP on X1 interface.
In order to enable LI services on sip:provider PRO the platform administrator has
to explicitly enable lawful interception through the main configuration file (config.yml
).
Here below is a sample configuration, which shows parameters of intercept
and
voisniff
sections.
intercept: captagent: cin_max: '3000' cin_min: '0' country_code: '49' debug: '7' filter: 'port 5080' license: '' port: '18090' prefix_len: '3' schema: http enabled: no peer: acc: no inbound_prefix: LI_ outbound_prefix: intercept_ type: none voisniff: admin_panel: yes daemon: bpf: 'port 5060 or 5062 or ip6 proto 44 or ip[6:2] & 0x1fff != 0' external_interfaces: 'eth0 eth2' filter: exclude: - active: '0' case_insensitive: '1' pattern: '\ncseq: *\d+ +(register|notify|options)' include: [] internal_interfaces: lo li_x1x2x3: call_id: suffix: - _pbx-1 - _b2b-1 client_certificate: '' enabled: no local_name: sipwise x1: port: '18090' mysql_dump: enabled: yes num_threads: '4' mysql_dump_threads: '2' start: yes threads_per_interface: '2' partitions: increment: '700000' keep: '10'
Configuration Parameters
intercept.enable
yes
if you want to activate LI service. Default: no
intercept.peer.acc
yes
if you want to enable billing for such calls.
Default: no
intercept.peer.inbound_prefix
LI_
intercept.peer.outbound_prefix
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
captagent
: LI service is activated and call data capturing is performed by captagent
module
voisniff
: LI service is activated and call data capturing is performed by voisniff
module
Default: none
voisniff.admin_panel
,
voisniff.daemon.mysql_dump.*
,
voisniff.partitions.*
voisniff.daemon.bpf
This sets the basic packet filter applied by voisniff-ng
module when capturing
packets on network interfaces.
Default: "port 5060 or 5062 or ip6 proto 44 or ip[6:2] & 0x1fff != 0"
The default value basically allows capturing SIP traffic only. It is usually
necessary to modify the parameter in order to capture both SIP and RTP traffic.
An example of such a value: |
voisniff.daemon.external_interfaces
voisniff-ng
should listen for and capture packets.
voisniff.daemon.filter.exclude
voisniff.daemon.filter.include
voisniff.daemon.internal_interfaces
voisniff-ng
and other NGCP components. Packets on these interfaces
are not captured.
voisniff.daemon.li_x1x2x3.call_id
voisniff-ng
listen for and
store as IRI (Intercept Related Information).
voisniff.daemon.li_x1x2x3.client_certificate
voisniff.daemon.li_x1x2x3.enabled
yes
to enable LI services via X1, X2 and X3 interfaces. Default: no
voisniff.daemon.li_x1x2x3.local_name
This parameter maps to the header.source
field of the X2 protocol. It’s an
arbitrary string and can be used to identify the sending NGCP system.
Default: sipwise
As of NGCP version mr4.5.2, this is currently not used. |
voisniff.daemon.li_x1x2x3.private_key
voisniff.daemon.li_x1x2x3.x1.port
The port number on which voisniff-ng
listens for incoming X1 messages.
Default: 18090
You should leave the parameter set to the default value, unless there is a
good reason to change it. The default value ensures backward compatibility with
|
voisniff.daemon.start
voisniff
service must be started on the platform. Set it
to yes
if you’d like to activate voisniff
that is needed for LI service too.
Default: yes
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’s set to 10 and 3 interfaces are enabled
for sniffing, a total of 30 threads will be launched.
Default: 2
Do not set it to a high number, or simply leave it at its default value,
unless there is a performance problem with |
Short description of Xn interfaces:
The resource used to work with interceptions is always https://ngcp-ip:1443/api/interceptions/
Authentication
Authentication and authorization on the NGCP 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 NGCP Panel 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:
With cURL use --cert /path/to/NGCPAPIclientcertificatexxxxx.pem
to specify
the client certificate, and --cacert /path/to/cacert.pem
to specify the CA certificate
in case of a self-signed server certificate.
curl -i -X GET --cert /path/to/NGCPAPIclientcertificatexxxxx.pem \ --cacert /path/to/cacert.pem https://example.org:1443/api/interceptions/
Additionally use the --insecure
option if you are testing against a self-signed
server certificate.
API Description
Allowed methods for the collection as in METHOD /api/interceptions/
Allowed methods for a collection item as in METHOD /api/interceptions/id
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).
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 ContentType: application/hal+json; profile="http://purl.org/sipwise/ngcpapi/"; charset=utf8 ContentLength: 634 Connection: keepalive Link: </api/interceptions/>; rel=collection Link: <http://purl.org/sipwise/ngcpapi/>; rel=profile Link: </api/interceptions/528>; rel="item self" SetCookie: ngcp_panel_session=35b56d921c36c1fc6edb8fcd0a86dd9af61ec62a; path=/; expires=Tue, 01Dec 2015 10:43:41 GMT; HttpOnly StrictTransportSecurity: maxage=15768000 { "_links" : { "collection" : { "href" : "/api/interceptions/" }, "curies" : { "href" : "http://purl.org/sipwise/ngcpapi/#rel{rel}", "name" : "ngcp", "templated" : true }, "profile" : { "href" : "http://purl.org/sipwise/ngcpapi/" }, "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 ContentType: application/hal+json; profile="http://purl.org/sipwise/ngcpapi/"; charset=utf8 ContentLength: 1283 Connection: keepalive SetCookie: ngcp_panel_session=238550c5737058db619b183d925b5f9a61261cfe; path=/; expires=Tue, 01 Dec 2015 10:47:36 GMT; HttpOnly StrictTransportSecurity: maxage=15768000 { "_embedded" : { "ngcp:interceptions" : { "_links" : { "collection" : { "href" : "/api/interceptions/" }, "curies" : { "href" : "http://purl.org/sipwise/ngcpapi/#rel{rel}", "name" : "ngcp", "templated" : true }, "profile" : { "href" : "http://purl.org/sipwise/ngcpapi/" }, "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/ngcpapi/#rel{rel}", "name" : "ngcp", "templated" : true }, "ngcp:interceptions" : { "href" : "/api/interceptions/520" }, "profile" : { "href" : "http://purl.org/sipwise/ngcpapi/" }, "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 ContentType: application/hal+json; profile="http://purl.org/sipwise/ngcpapi/"; charset=utf8 ContentLength: 2364 Connection: keepalive SetCookie: ngcp_panel_session=68398eea5bdd3885ad0517e1f6d367ccc80111fa; path=/; expires=Tue, 01 Dec 2015 10:43:18 GMT; HttpOnly StrictTransportSecurity: maxage=15768000 { "_embedded" : { "ngcp:interceptions" : [ { "_links" : { "collection" : { "href" : "/api/interceptions/" }, "curies" : { "href" : "http://purl.org/sipwise/ngcpapi/#rel{rel}", "name" : "ngcp", "templated" : true }, "profile" : { "href" : "http://purl.org/sipwise/ngcpapi/" }, "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/ngcpapi/#rel{rel}", "name" : "ngcp", "templated" : true }, "profile" : { "href" : "http://purl.org/sipwise/ngcpapi/" }, "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/ngcpapi/#rel{rel}", "name" : "ngcp", "templated" : true }, "ngcp:interceptions" : [ { "href" : "/api/interceptions/520" }, { "href" : "/api/interceptions/528" } ], "profile" : { "href" : "http://purl.org/sipwise/ngcpapi/" }, "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 ContentType: application/hal+json; profile="http://purl.org/sipwise/ngcpapi/"; charset=utf8 ContentLength: 1283 Connection: keepalive SetCookie: ngcp_panel_session=23960dde6bb90f0c5c84575890194c53cce120ce; path=/; expires=Tue, 01 Dec 2015 10:50:40 GMT; HttpOnly StrictTransportSecurity: maxage=15768000 { "_embedded" : { "ngcp:interceptions" : { "_links" : { "collection" : { "href" : "/api/interceptions/" }, "curies" : { "href" : "http://purl.org/sipwise/ngcpapi/#rel{rel}", "name" : "ngcp", "templated" : true }, "profile" : { "href" : "http://purl.org/sipwise/ngcpapi/" }, "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/ngcpapi/#rel{rel}", "name" : "ngcp", "templated" : true }, "ngcp:interceptions" : { "href" : "/api/interceptions/520" }, "profile" : { "href" : "http://purl.org/sipwise/ngcpapi/" }, "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 "ContentType: 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 TransferEncoding: chunked Connection: close Location: /api/interceptions/528 SetCookie: ngcp_panel_session=e7817079d121fae4d86448b10e1fa21d0201c526; path=/; expires=Tue, 01 Dec 2015 10:43:18 GMT; HttpOnly StrictTransportSecurity: maxage=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 "ContentType: 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 ContentType: application/hal+json; profile="http://purl.org/sipwise/ngcpapi/"; charset=utf8 ContentLength: 621 Link: </api/interceptions/>; rel=collection Link: <http://purl.org/sipwise/ngcpapi/>; rel=profile Link: </api/interceptions/530>; rel=self PreferenceApplied: return=representation SetCookie: 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/ngcpapi/#rel{rel}", "name" : "ngcp", "templated" : true }, "profile" : { "href" : "http://purl.org/sipwise/ngcpapi/" }, "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 "ContentType: application/jsonpatch+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 ContentType: application/hal+json; profile="http://purl.org/sipwise/ngcpapi/"; charset=utf8 ContentLength: 620 Connection: close Link: </api/interceptions/>; rel=collection Link: <http://purl.org/sipwise/ngcpapi/>; rel=profile Link: </api/interceptions/530>; rel=self PreferenceApplied: return=representation SetCookie: ngcp_panel_session=0693129d63d543a85f96d464ff9a8f807cfc4d18; path=/; expires=Tue, 01 Dec 2015 11:06:06 GMT; HttpOnly StrictTransportSecurity: maxage=15768000 { "_links" : { "collection" : { "href" : "/api/interceptions/" }, "curies" : { "href" : "http://purl.org/sipwise/ngcpapi/#rel{rel}", "name" : "ngcp", "templated" : true }, "profile" : { "href" : "http://purl.org/sipwise/ngcpapi/" }, "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: keepalive SetCookie: ngcp_panel_session=570c66b66732629766f86b8ed9bd0d64902ae73e; path=/; expires=Tue, 01 Dec 2015 11:08:49 GMT; HttpOnly XCatalyst: 5.90042 StrictTransportSecurity: maxage=15768000
The communication via the X2 interface consists of request-response pairs.
Request
The request is formatted as: X2/<bodylength>/<body>
Body part has the following items:
Table 21. 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": "20150311T09:18:04.729803Z" }, "body": { "dialogid": 4, "messageid": 0, "timestamp": "20150311T09:18:04.729123Z", "interceptions": [ { "liid": 174, "direction": "fromtarget" }, { "liid": 175, "direction": "totarget" } ], "data": "<base64 encoded ip,udp/tcp,sip frame>" } }
Response
X2-ACK/0/
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.
X2/0/
X2-ACK/0/
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 22. X3 Message Structure
Field | Length |
---|---|
Header | arbitrary |
CCCID | 4 bytes |
MessageId | 4 bytes |
Timestamp | 8 bytes |
Payload | arbitrary |
Header Details
Table 23. 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 24. 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.
X3/0/
X3-ACK/0/