What is SRAPS?
SRAPS stands for Secure Redirection and Provisioning Service which enables phone to use ZeroTouch Provisioning (ZTP) deployment. With SRAPS you can remotely manage Snom phones without any on-site configuration which saves money, human-errors and time.
Moreover, SRAPS is capable of pushing firmware updates to all phones to a custom version.
This lets updating dozens of phones even before auto-provisioning has happened. Furthermore, SRAPS provides redirection feature which points the phone toward system where configuration file is located but also can provide general custom settings beside original configuration file.
How to get SRAPS access?
User can sign up and create free SRAPS user account at https://sraps.snom.com and enter basic account information (i.e company name, country, city).
Afterwards, user is able to use touchless provisioning feature.
NOTE : In order to use touchless provisioning on PBXware, it needs to be enabled in the PBXware licence. To get more information about this, contact your account manager.
NOTE : Once enabled in PBXware licence, Touchless provisioning must be enabled on Master Tenant.
Navigate to Master Tenant -> Settings -> Tenants -> Master tenant -> Advanced and look for Touchless Provisioning Mode option.
User should see following modes:
Master : phones from all tenants are on one SRAPS account
Per Tenant : phones from each tenant are on separate SRAPS accounts and each tenant has their own configuration page.
PBXware integration with SRAPS
Once user has created SRAPS account, first step in integrating PBXware with SRAPS is creating API keys.
Open your SRAPS account and navigate to SRAPS Dashboard -> API Keys section.
NOTE: Make sure to select Role because SRAPS does not let device registration if None is chosen.
After clicking Save button, API Access Key ID and Access Key Secret should be generated.
Next, on PBXware side user has to integrate PBXware with SRAPS via API keys.
To do so, click on Master Tenant -> Settings -> Touchless Provisioning -> Configuration section, find Snom provider, click on 'Edit' and insert API keys provided by SRAPS:
After inserting credentials click on Save and then on Test button. The following message indicates PBXware is integrated with SRAPS account.
How phone redirection works?
Within Devices section on PBXware, we see our recognized devices that can be used for touchless provisioning, their MAC addresses, name, extension number, UAD type, status, registration date and last message.
If registration was successful, the following message should appear:
User can see status of registered devices, date when registration has happened.
The Last Message column shows potential errors that might happen. If everything went right you will see "-" symbol.
When user selects device and clicks on Register , PBXware generates access details in its database and integrates them via API on SRAPS server.
The dynamically generated details are following:
- HTTP Username
- HTTP Password
- URL http://$PBXWARE_IP/ztprov/snom{$MODEL}-{$MAC}.htm
The URL, HTTP username and HTTP password are passed to SRAPS server which will be given to the phone for successful authorization to the PBXware. This tells phone had visited SRAPS server and collected credentials.
Phone then visits URL and provides HTTP username and password for authentication.
If credentials are right, PBXwares approves the request and phone receives Autoprovisioning template generated by PBXware.
After this step, phone reboots and provisions itself with regular provisioning configuration file using HTTP username and HTTP password set in tenant settings.
Creating endpoint on SRAPS
During this entire process, user only creates API keys and integrates PBXware with SRAPS.
The SRAPS account is untouched and no devices are present. However, when on PBXware side user clicks on Register button, SRAPS account gets populated with new device(s) and URL, username and password are generated.
This is seen by clicking on one device's MAC address which opens up a Phone Settings page:
Phone is now ready to be factory resetted as everything is ready for its touchless provisioning.
User can factory reset Snom phone in two ways:
- Via GUI
- Manually
Factory reset via GUI
Login to your Snom web interface and on the left panel click on Advanced , then on Update and finally click on Reset button which will factory reset the phone.
Factory reset manually
User can also dial * * # # and then hold # . This should boot phone in rescue mode. Then select Settings reset .
If each step is followed so far, phone should be auto-provisioned successfully and extension will become online.
User can dial *123 to confirm registration.
Log files
During the provisioning process, phone will authenticate itself to the web server in order to access its configuration file.
User can observe requests at /opt/pbxware/pw/var/log/nginx/localhost.access_log
Requesting /ztprov
The first GET request is sent by phone without credentials. However, Nginx service replies with 401 Unauthorized response message asking for authorization.
<snip> GET /ztprov/snomd717-ABC123EFG456.htm HTTP/1.1" 401 <snip>
The initial request should be followed with next one. When 200 is returned, Nginx allowed phone to access /ztprov/snomd717-ABC123EFG456.htm as phone authenticated itself with credentials received while visiting SRAPS server.
The request in log should look like this:
<snip> GET /ztprov/snomd717-ABC123EFG456.htm HTTP/1.1" 200 <snip>
File that phone just received contains, among other general default settings, credentials that will be used as authentication while requesting next file - /prov/snom{model}-{mac}.htm .
Those settings are:
setting_server$:http://<PBXWARE_IP>/prov/snomd717-ABC123EFG456.htm
http_client_user$:<HTTP_USERNAME_FROM_PBXWARE>
http_client_password$:<HTTP_PASSWORD_FROM_PBXWARE>
The http_client_user$ and http_client_password$ are set by PBXware administrator in tenant settings under Auto Provisioning section and will be used for authentication while requesting /prov/snom{model}-{mac}.htm
Requesting /prov
Next step is to request /prov/snom{model}-{mac}.htm after which web server responds with 401 Unauthorized .
<snip> GET /prov/snomd717-ABC123EFG456.htm HTTP/1.1" 401 <snip>
Phone sends request once again but includes credentials received from /ztprov/snom{model}-{mac}.htm file and the request/response look like this:
<snip> GET /prov/snomd717-ABC123EFG456.htm HTTP/1.1" 200 <snip>
This request should have 200 response code which completes touchless provisioning process.
Phone will reboot and use auto-provisioning credentials received from /prov/snomd717-ABC123EFG456.htm for each continuous reboot.
The phone will not visit SRAPS server until factory resetted again.
Troubleshooting
Configuration file for touchless provisioning service is located at /opt/pbxware/pw/etc/rps/rps.ini .
You will find few contexts (section) which define service behavior. In general context, user can control event queueing for rps service. Since every action in GUI creates an event , events need to be queued (first come first served). The following two directives define number of queues and number of events per queue:
queuenum : number of queues.
queuecap : number of events per queue
In general, there is HTTP listener inside rps service which listens on port 15777 and all changes made from GUI will be sent as events to the service over that 15777 port.
Any event (i.e register device, de-register device) will be fetched by DISTRIBUTOR and distributed into queues.
For example this is one line from rps.log file which explains what the service is doing (Distributing events)
[2021-10-26 10:20:40] INFO (DISTRIBUTOR): Distributing events. Num=1)
Then, the QUEUE fetches events and sends them as requests toward SRAPS server to add (register) one device. This request can look like this:
INFO (Snom): Sending Request. Mac=ABC123EFG456 Url=https://secure- provisioning.snom.com/api/v1/tokens/**ACCESS_KEY_ID**
INFO (Snom): Sending Request. Mac=ABC123EFG456 Url=https://secure-provisioning.snom.com/api/v1/settings/
INFO (Snom): Sending Request. Mac=ABC123EFG456 Url=https://secure- provisioning.snom.com/api/v1/companies/5fab351853094e129cc2c1185ff329cf/endpoints/ABC123EFG456
The DATABASE adds device in the MySQL database. Lastly, the QUEUES are cleaned up as there are no events to be handled. DISTRIBUTOR sees queues are empty and tries to fetch more events to be sent in QUEUE. If there are more events, they will be sent to QUEUE for execution
Most common errors
403 Forbidden
ERROR Error while handling Event. Action=add Err=403: Forbidden
Mac=ABC123EFG456 Provider=snom Server=8
User can see this error when SRAPS account lacks permissions. This is solved by chosing Role in SRAPS account when creating API keys.