Provisioning

Martijn
Written by

Provisioning is the process of providing a SIP phone with settings. Compass provides automatic provisioning for Compass certified Snom and Yealink phone models. This document describes the details of this process.

What is phone provisioning?

Provisioning is the process of providing a SIP phone with settings so that it can connect to a PBX and is ready to make calls. This can be done manually or automatically:

  • Manual provisioning: entering all the settings by hand. This can, for example, be done using the built-in web portal on a SIP phone or using the phone’s display and buttons.
  • Automatic provisioning: sending the settings to the SIP phone from the PBX platform.

In Compass we provide automatic provisioning for Compass certified Snom and Yealink phone models.

Generic overview of how phone provisioning works in Compass

In Compass, provisioning can be divided into two steps:

  1. Provisioning by manufacturer
  2. Provisioning by Compass

Provisioning by manufacturer

This provisioning step is automatically activated for a maximum of 7 daysNote 1, when:

  • a Compass certified phone is newly added to an organisation in Compass
  • or, when the Provisioning by manufacturer: Activate button is pressed

When you add a certified phone to Compass, you enter the hardware MAC address of the phone. Compass registers that MAC address at the manufacturer provisioning service, and tells it that Compass knows the settings for the phone with that MAC. When the phone is started for the first time, the factory default setting is to contact the manufacturer provisioning service and send its MAC address. The provisioning service will check its registry and if the MAC address of the phone is registered, it will refer the phone to the PBX platform that has its settings.

If a phone is reset to defaults but is not registered at the provisioning service, it will not know what PBX platform to get its settings from. In those cases the phone will still boot to allow you to configure it manually.

Note 1: if provisioning by manufacturer is activated, it will only stay active for a *maximum* of 7 days. Every Wednesday at midnight (CET) phones that did not contact the manufacturer provisioning service will be de-registrered. This is a security measure.
    
Make sure that phones for which you activate provisioning by manufacturer, are reset to factory defaults and contact the manufacturer provisioning service before the next Wednesday at midnight. If this did not work out, the registration can be reactivated using the Activate button on the phone settings page.

Provisioning by Compass

Once a phone has gone through the provision by manufacturer process and knows what PBX platform it can get its settings from, the phone will remember and keep asking that platform every time it starts up. It can also receive updates to its configuration from the PBX platform during normal operation. The manufacturer provisioning service will no longer be contacted.

Provisioning diagrams

These diagrams show both provisioning steps

What exactly happens when a phone provisions?

Provisioning is a complex process with many steps that differ depending on the phone model, firmware version, settings and the reachability of required services on the network or the internet. This is a summary of common steps most phones go through when booting and provisioning:

When a phone boots

  • Boot internal software, verify the validity of the firmware boot image.
  • Turn on any (button) lights so a user can verify they all work.
  • Set up the network devices on the phone, set a VLAN if any was previously configured.
  • Request an IP address using DHCP, or assume previously configured network settings like IP address, netmask, gateway and DNS.
  • Contact a NTP server to synchronise time.

When provisioning by manufacturer is activated

  • Use the configured DNS and a hostname embedded in the firmware to find the IP address of the manufacturer provisioning servers.
  • Contact the provisioning service over HTTPS.
  • Checking the validity of the TLS certificate of the provisioning service.
  • Download a configuration file containing temporary settings to reach the Compass PBX provisioning endpoint for definitive settings.

When a phone is already configured on Compass

  • Contact the Compass PBX provisioning endpoint over HTTPS.
  • Download a configuration file containing phone settings.
  • Verify the validity of the configuration file and apply those settings one by one. These settings could include a reference to a firmware image to upgrade the phone software to a different version.
  • Set the time based on provisioned time zone.
  • Register at the provisioned SIP server.
  • If needed, reboot to process new settings.

Where can I see what provisioning step a phone is in? / What step should it be in?

On the phone settings page in Compass Studio you can see the currently active provisioning step. The value for Provisioning by manufacturer can be:

  • active, when the phone is registered at the manufacturer provisioning service but has not visited it yet.
  • disabled, when the phone is allowed to get settings from the Compass PBX platform.
  • provision, when Compass has tried to register the phone at the manufacturer provisioning service, but this has failed.
  • deprovision, when Compass has tried to remove the phone registration at the manufacturer provisioning service, but this has failed.

To determine what step a phone is supposed to be in, here are some simple guidelines:

  • When a phone is in normal operation and used to make calls, its Provisioning by manufacturer status should always be disabled because the phone already knows to get settings from the Compass PBX platform and does not need to ask the manufacturer.
  • When a phone is booting for the first time, or has just been reset to defaults, the provisioning status should always be active so the manufacturer provisioning service will instruct the phone to get settings from Compass.

If a phone should have received settings from Compass but is not working properly, and its provisioning status is active, provision or deprovision, then it is in a suboptimal state. Try these steps to resolve the problem:

  • Remove the phone from Compass if possible, then re-add it. If that is not feasable for some reason, then activate provisioning by manufacturer.
  • Reset the phone to factory defaults.
  • Allow the phone to fully start up. A phone could automatically reboot multiple times during this process. Make sure to not touch the phone until the display is idle for about 30 seconds.
  • Now look at the phone settings page and confirm that Provisioning by manufacturer is disabled. This is the only correct value for provisioning if a phone is in normal operation.

What is being sent to a phone exactly, and by who?

What is sent to the phone by the Compass platform?

For a phone who receives settings from Compass, the settings that are sent by the platform can be viewed from the phone settings page. Click the View button for View provisioning to see the contents of the settings file that is sent to the phone.

If no user is logged in on a phone, Compass will provision only common settings. This includes:

  • Name, SIP host and outbound proxy for the Compass organisation the phone is in.
  • NTP server address and timezone.
  • Display language and other localization settings.
  • Dial pad settings for when the phone is not logged in.
  • Default audio codec priorities.
  • Call waiting setting.
  • Speaker and microphone sensitivity level.
  • Configuration of called ID on the display.
  • Phone web portal access username and password.
  • Any custom provisioning settings configured in Compass Studio.

Although no user is logged in, the settings above are still required so a phone can be used to call *1, or to call emergency services.

When a user logs in on the phone, more settings are provisioned to enable that specific user to call using that phone. These settings include:

  • SIP account username and password of the user that is logged in. If a user has multiple identities, multiple SIP accounts will be provisioned.
  • Settings of function buttons on the phone, if configured.
  • A reference to the voicemail box of the logged in user.
  • Ring tone choices for internal and external calls.

How to reset a phone to factory defaults

Make sure you have activated provisioning by manufacturer in Compass first before taking these steps, otherwise the phone will end up in a suboptimal state.

Factory resetting a Snom phone

  • If the phone is powered on:
    • End all calls and exit all menus shown on the phone display.
    • Reboot the phone. For most models this can be done by pressing * * # # - the display should go blank shortly after.
  • If the phone is off, then power it on.
  • From the moment the phone is starting up, press and hold #. Note: this should be done right from the start of the booting process!
  • Keep # pressed until the display shows the question if you want to reset to defaults. Use the keypad to select that option.

If this does not work your Snom model may require a different method. Consult the manual of the phone model for the latest instructions.

  • Make sure the phone is powered on and fully started.
  • End all calls and exit any menus shown on the phone display.
  • Press and hold the OK button (not the X button).
  • After several seconds, the phone display shows the question if you want to reset to factory defaults. Use the buttons near the display to answer YES.

If this does not work your Yealink model may require a different method. Consult the manual of the phone model for the latest instructions.

Which manufacturer provisioning services are used?

Compass provisioning supports selected Snom and Yealink phone models. Each phone manufacturer has its own provisioning service.

Snom SRAPS (Secure Redirection and Provisioning Service)

Phones contact SRAPS on these hostnames:

  • provisioning.snom.com (HTTP)
  • secure-provisioning.snom.com (HTTPS)

For more information, visit the Snom Service Hub website.

Yealink offers a free provisioning service. More information can be found on the Yealink website. Compass offers firmwares altered by Lydis, a Dutch Yealink distributor. These firmwares are altered to contain the Dutch language and may contain other changes.

Yealink RPS is reachable on:

  • rps.yealink.com
  • updateyealink.com (Lydis)

Moving phones between organisations on the same environment

If you are faced with a situation in which you want to move a phone from one organisation to another on the same environment, these are the available options:

Advantages

  • Fast: nearly instant.
  • Phone settings are saved during the move.
  • No provisioning by manufacturer required.
  • No need to reset phone to factory defaults.
  • Can be scripted/automated.

You can try this out for yourself using the Compass API reference, which is interactive and provides forms to fill in the values and execute the request. Some technical knowledge is required.

Requirements

To execute a request with the Compass API reference, you will need:

  • Access to the interactive Compass API reference (Swagger). The URL is listed in the developers manual on your Compass environment, in the API Reference section.
  • Credentials with write permissions on the original and target organisation of the phone.
  • The resource ID of the phone you wish to move. This number can be found at the end of the URL of the phone info page.
  • The resource URL of the organisation you wish to move the phone to. Use the organisation/company ID and the GET /company/{id} endpoint in the API reference. In the response, you will find the property self which is the resource URL that points to that organisation.

Steps

Steps to move a phone using the interactive Compass API reference:

  1. Navigate to the API Reference and authorize yourself with credentials with sufficient permissions.
  2. Then, navigate to the /phone/{id}/migrateToCompany API endpoint and expand it. Click Try it out.
  3. A form will be displayed with two fields: ID and Request body.
    • Enter the resource ID of the phone you wish to move in the ID form field.
    • In the request body, replace string with the resource URL that points to the organisation (company) you want to move the phone to. It should look similar to this: 
      {
 "newCompany": "https://rest.[compass-domain.com]/company/[target-company-ID]"
}
  4. Click Execute to try the API request.

On success:

  • the API returns a HTTP 200 OK status code.
  • the name of the new organisation appears on the phone’s display nearly instantly.

2. Move manually

It is also possible to move a phone fully manually, using Compass Studio.

Advantages

  • Can be done from Compass Studio, does not require knowledge of API usage.

Caveats

  • Phone settings will be lost when the phone is removed from Compass.

Steps

  1. On the phone overview page, note the MAC address.
  2. Then, remove the phone from its original organisation in Compass.
  3. Re-add the MAC address of the phone to the new organisation.
  4. Reset the phone to factory defaults.

The phone needs to be removed from the original organisation first because a phone MAC address can only be added to an environment once.

Moving phones between two or more environments

Moving a phone between the production and staging environment can be useful for testing. Because production and staging are different environments, we can add the MAC address on both environments at the same time! To switch between environments quickly, follow these steps:

Setup

On both environments you want to use the phone on, add the phone and provision it. For example, if you want to switch a phone between production and staging, then:

  1. Add the phone to the production environment.
  2. Reset the phone to factory defaults and check that it registers after it is fully booted.
  3. Repeat these steps on the staging environment. Add the phone and again reset it to factory defaults, check it registers.

From this point on, the phone can be easily switched from one environment to another.

How to switch

  1. Click the Provisioning by manufacturer: Activate button on the environment you want to use the phone on.
  2. Reset the phone to factory defaults.

When the phone is finished booting it will be active on the environment you activated provisioning by manufacturer on last, and its info page will read Provisioning by manufacturer: disabled.

Note that you do not need to remove the phone from an environment.

Provisioning and firmware settings/updates

Changing phone firmware

Up- or downgrading firmwares of phone is a different process for every phone model. In general, the process is as follows:

  • By default, every phone that is added to Compass will start with the firmware setting: Use installed firmware. With this setting, Compass does not send any settings to the phone that request a firmware update at all.
  • To request a firmware update, a firmware version must be set in Compass Studio. This can be done for one or multiple individual phones, or for all phones of a specific model.
  • A firmware version will become available for selection in Compass Studio after it is certified.
  • If a firmware version is selected in Compass Studio, a URL to a new firmware file is added to the settings that are sent to the phone. This instructs the phone to download the firmware and start a firmware change process.

When up- or downgrading phone firmware by selecting firmware from the menu in Compass Studio, the firmware image files are downloaded from a Compass webserver and not directly from the manufacturers website.

Note that downgrading a firmware via provisioning settings is not always supported by the manufacturer or by the firmware that is currently installed.

Reading firmware versions numbers

It can be helpful to understand the version numbers that are used for phone firmware. This assists in checking which version of firmware is currently installed and to determine if other available versions are older or newer.

Snom firmware versions

  • Format: x.x.x.x - 4 numbers separated by dots. Example: 8.9.3.80
  • First number: the major version.
    • Going from 8.x.x.x to 10.x.x.x means there have been major changes in the firmware.
    • Snom will also note this as “V8” or “V10” firmware for 8.x.x.x and 10.x.x.x respectively.
  • Other numbers: minor version and patch version numbers.
  • In general:
    • Every number further to the right means the changes are smaller. Changes from x.x.30.x to x.x.36.x are smaller than from 8.x.x.x to 10.x.x.x.
    • Higher numbers mean a more recent firmware. x.x.10.x is slightly newer than x.x.9.x.
  • Format: x.x.x.x - 4 numbers separated by dots. Example: 66.86.188.2
  • First number: the phone model. Example: firmware for the T41P will always start with 36.x.x.x
  • Second number: the major version.
    • Going from x.81.x.x to x.86.x.x means there have been major changes in the firmware.
    • Yealink will also note this as “V81” or “V86” firmware for x.81.x.x and x.86.x.x respectively.
  • Third number: indicates custom firmware versions.
    • 188: custom firmware by Lydis, the Benelux distributor of Yealink phones. This custom firmware comes with the Dutch language built-in by default.
    • 0: international firmwareNote 2
    • Other numbers indicate custom firmware for other distributors or customers.
  • Fourth number: the minor version.
    • Going from x.x.x.4 to x.x.x.5 indicates minor changes in the firmware.
Note 2: It is not easily possible to change between custom and international firmwares versions. Compass provides and certifies only Lydis firmwares at this moment due to its built-in support for the Dutch language.

Related Posts

Docs