PBXware 3.8.5 Dynamic Auto Provisioning

From Bicom Systems Wiki

Revision as of 15:02, 25 September 2014 by Vesna Selimovic (Talk | contribs)

(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)

General information

In version v3.8.2 we introduced dynamic TFTP/HTTP provisioning.

Instead of writing configuration files to disk, files are now dynamically created by PBXware HTTP application and server to device when it sends a request to the server.

NOTE:

By default (with no username and password set) HTTP provisioning is disabled.

Setting HTTP Username and HTTP Password will automatically enable HTTP provisioning as well. Devices that do not support Digest HTTP authentication (username and password) cannot be auto-provisioned via HTTP, only via TFTP.

HTTP Username and HTTP Password are set under:

Settings -> Servers -> YourServerName (edit) -> Auto Provisioning (section) -> HTTP Username/HTTP Password

HTTP server

HTTP application is running under following location:

http://ip-address/prov

HTTP application can handle the following scenarios (in this particular order):

  • HTML/XML Directory requests
http://ip-address/prov/_directory/mac-address
  • PUT requests
Only for debugging purposes, for more information check Polycom information section.
  • MAC configuration requests
Some examples of requests:
http://ip-address/prov/mac.cfg
http://ip-address/prov/cfg.mac
http://ip-address/prov/phonemac.cfg

Check Filename in each device section.

  • Filesystem files (firmwares etc)
http://ip-address/prov/sip.ld
  • Custom config files
http://ip-address/prov/aastra.cfg

MAC configuration files

To get configuration, devices ask for files that contain its MAC address. This configuration requires username and password.

Testing with curl

In order to perform testing of auto provisioning and to verify validity of content, one needs to use curl or web browser.

More information about curl you can find here:

http://curl.haxx.se

Here is an example of command:

curl -i -u user:pass --digest http://ip-address/prov/mac.cfg

Parameters:

 -i

Include HTTP protocol in output

 -u 

Specify username:password for authentication

 --digest

We support only digest HTTP authentication, therefore this is a mandatory parameter. If you do not specify it, curl will use Basic HTTP Authentication and it won't work.

 --user-agent

This is how you can send a different User-Agent string, if you want to test HTML/XML Directory pages.

For instance:

 --user-agent "Yealink SIP-T38"


Testing in browser is advisable, if you want to test validity of large XML output. Devices that require XML configuration will be served with text/xml Content-Type and this will be understood by browsers. You will then know if XML document is valid or not.


Testing with wget

In case curl is not installed (this will most often be the case on VPSes), users can use wget to perform testing.

Example command:

wget -S -q http://username:password@ip-address/prov/mac.cfg -O-

Parameters:

 -q

Turns off verbosity and progress bar from wget.

 -S

Output should include HTTP headers.

 --user

HTTP username, if not specified as part of the URL.

 --password

HTTP password, if not specified as part of the URL.

 -O-

Output to stdout instead of file.

 -U=user-agent

Use it to set User-Agent.

For more options consult:

 wget --help

in your PBXware shell.

Test HTTPS mode

HTTPS also works and will work on devices that support HTTPS. Some devices do not support self-signed certificate, therefore you will need to buy signed certificate.

curl command:

 curl -i -u user:pass --digest --insecure https://ip-address/prov/mac.cfg

Additional options:

 --insecure

This options accepts self-signed certificate as valid certificate.

HTTP response codes

Here is the list of HTTP response codes from HTTP service and its meaning:

 401 Authentication Required

This header will appear when username and password is not supplied. This lets device know it has to send username and password in next request.

 200 OK 

should follow after this request, in all other cases provisioning failed.

 403 Forbidden

This error will appear if you do not specify valid authentication information. It will also appear if tenant/server do not have HTTP username and password set.

 404 Not Found

This error has multiple meanings but some are:

- MAC address doesn't exist
- Device doesn't exist or can't be used for auto provisioning
- Device cannot handle HTML/XML Directory
- Custom route doesn't exist
- File path is wrong
- File doesn't exist
- Request can't be handled
 500 Internal Server Error

Something went horribly wrong. Usually some problematic SQL error. Please consult Bicom Systems support.

 200 OK

This happens if all is good and content is delivered to device.

HTTP logs

You can watch all devices and requests with this command (for HTTP traffic)

cd /opt/pbxware
tail -f pw/var/log/nginx/localhost.access_log

for HTTPS:

cd /opt/pbxware
tail -f pw/var/log/nginx/localhost.ssl_access_log


Output example:

10.1.0.138 - - [23/Apr/2013:11:43:27 +0200] "GET /prov/_directory/001565267db9 HTTP/1.0" 200 2654 "-" "Yealink SIP-T38G 38.0.23.22 00:15:65:26:7d:b9" "-" 


Important bits are:

GET filename 

This is what devices asked for.

200 2654

200 OK was sent, Content-Legth was 2654.

Please note, if authentication is needed, correct sequence is 401, then 200 OK.

Yealink SIP-T38G 38.0.23.22

Device User-Agent.

Syslog

Some devices can send logs via syslog.

In order to setup syslog-ng on Gentoo as syslog host, do this:

Edit /etc/syslog-ng/syslog-ng.conf

nano /etc/syslog-ng/syslog-ng.conf

and add these lines on bottom:

source net { udp(); };
destination remote { file("/var/log/remote/$FULLHOST"); };
log { source(net); destination(remote); };

Create directory /var/log/remote/

mkdir /var/log/remote

Restart syslog-ng with:

/etc/init.d/syslog-ng restart

Cisco Information

The only provisioning method supported for Cisco 79xx devices is TFTP. HTTP provisioning works only for Cisco SPA-Linksys devices (>= v6.x firmware).

Cisco 79XX devices

Cisco 7940, Cisco 7960 support.

Documentation: http://www.voip-info.org/wiki/view/Asterisk+phone+cisco+79xx


Filename: SIPmac.cnf

Supported features

  • Basic authentication support
  • Additional UAD configuration (per extension)
  • Cisco XML Directory

NOT supported:

  • General UAD config

Cisco 79X1 devices

Cisco 7941, 7961 support.

Cisco 79X1 have very complicated XML output.

It is possible to provide default XML template for each device by creating template in:

/tftp/SEP_Default.xml /tftp/SEP_Device_7941.xml Template is attached in the document.

Documentation: http://www.voip-info.org/wiki/view/Asterisk+phone+cisco+79x1+xml+configuration+files+for+SIP

Firmware: http://software.cisco.com/download/navigator.html?mdfid=269065653&flowid=5255 (requires Cisco login)


Filename

  • SEPmac.cnf.xml

Content Type

  • XML format

Supported features

  • Basic authentication support
  • Cisco XML Directory
  • Voicemail access code

NOT supported

  • General UAD config
  • Additional UAD configuration (per extension)

Asterisk NAT

Make sure nat=no is set in sip.conf, otherwise nothing will work.

Table 1: Cisco 79xx supported features

01-cisco79xx-supported-features.png

00-symbols.png


WARNING: Cisco 79xx devices, other than 7940 and 7960, will not be able to work if PBXware is not in the same LAN.

These devices send UDP SIP requests from a high source port but expect a reply on port 5060. Because of this behavior and the way NAT works, phones will always receive response on the port their UDP SIP request was sent from and will not be able to register. Even if devices are in the same LAN, customers will have to manually set option NAT to No on PBXware, in Extensions -> Edit EXT -> Network Related section, in order for Cisco 79xx devices to successfully register.

Cisco SPA5xx/Cisco-Linksys SPA devices

Cisco SPA501, 502, 504, 508, 509 525 support. Cisco-Linksys SPA941, 942, 962 support.


IMPORTANT: These phones by default search for spa.cfg and then PBXware redirects them to /$MA.cfg. However this only works if DHCP option 66 works properly.

HTTP

To use HTTP provisioning with authentication, username and password have to be provided in this form:

[--uid http-username --pwd http-password] http://x.x.x.x/prov/$MA.cfg

Above works only on >=v6.x firmware, it doesn't work on firmware v5.x (Cisco-Linksys 941...)

HTTPS

HTTPS doesn't work without special server configuration and is not supported (Cisco signed server certificate and Client SSL certificate verification).

Filename:

  • spa.cfg
  • mac.cfg

Content Type:

  • XML format

Supported features

All models:

  • Basic authentication support
  • Voicemail access code
  • Preferred codec (first codec in list)
  • Default Dialplan
  • Timezone and Daylight Saving time support (via Voicemail Timezone)
  • General UAD config
  • Additional UAD config (per extension)
  • DHCP settings
  • DNS SRV field in Servers -> Edit
  • Control of max lines by internal devices list

Some models only:

BLF (With sidecart only)

  • Cisco-Linksys SPA962
  • Cisco SPA5XX

Table 2: Cisco SPA supported features

02-cisco-spa-supported-features.png

00-symbols.png

General UAD config

Any content in UAD provisioning templates must be a valid XML config, and should have start and end tag like this:

<flat-profile> <field>value</field> </flat-profile>

If XML config is invalid, it will not be included in configuration file and your phone will not be provisioned for additional settings. Start and end tags above are not required.

Cisco firmware and files

Users have to download Cisco firmware themselves from Cisco web site.

Polycom Information

Provisioning method

Both TFTP and HTTP are supported.

HTTPS should work but requires valid certificate signed by pre-installed Certificate Authority. It cannot be a wildcard certificate.

Polycom devices

Filenames

  • MAC.cfg
Asks for where config files are, where SIP firmware is.
  • phoneMAC.cfg
Main configuration file.
  • MAC-directory.cfg
BLF/Directory list.

Content Type

  • XML format

Supported features

Supported

  • Basic authentication support
  • Voicemail access code
  • Timezone, 12/24 clock and Daylight Saving time support (via Voicemail Timezone)
  • DNS SRV field in Servers -> Edit
  • BLF/Directory list
  • HTTP HTML Directory

NOT supported

  • Additional UAD configuration (per extension)

Table 3: Polycom supported features

03-polycom-supported-features.png

00-symbols.png

General UAD config

NOTE: General UAD config must be valid XML for that particular firmware otherwise all configuration will fail.


PUT requests Polycom phones will send PUT requests to server and these files can be saved on disk if upload mode is turned on.

What Polycom phones like to send:

  • Log files
  • Configuration override files
  • Configuration saved in web interface, set on phone.
  • Directory

This is not supported, as it conflicts with Enhanced Services Directory. It is not safe to turn this feature on public internet. To turn it on, create upload directory:

cd /opt/pbxware/pw/tftp
mkdir upload
chown 101:1003 upload

It is not required to have WebDAV enabled in nginx for above to work.

For information on how to prepare your PBXware for Polycom multiple firmware support please check our HowTo create Polycom Firmware Pack

NOTE: If you are not sure how to create Polycom firmware package please contact our support and we will be glad to help you.

Yealink Information

Provisioning method

Either HTTP or TFTP.

HTTPS works with any certificate if "Only Accept Trusted Certificates" is Disabled.

Yealink devices

Filename

  • MAC.cfg

File Format

  • Format is different for T2xP and T3xP devices unless v.70 firmware is used.

Supported features

  • Basic authentication support
  • General UAD config
  • Additional UAD configuration (per extension)
  • Codecs
  • DTMF mode
  • BLF/Directory list
  • Voicemail access code
  • Timezone (no Daylight Saving Time at the moment)
  • Remote HTTP XML Directory
  • DNS SRV support via Servers -> Edit

Notes:

  • DST is not supported
  • Yealink T18 has auto provisioning bug. If provisioning server is assigned through Option 66, manually assigned provisioning server will not work unless phone is set to work with static IP address.

Table 4: Yealink supported features

04-yealink-supported-features.png

Table 5: Yealink firmware v70 supported features

05-yealink-v70-supported-features.png

00-symbols.png

Firmware v70

Due to Yealink omission, we are not able to detect phone firmware version, when using TFTP. If you would like to auto provision Yealink phone with v70 firmware, please create file v70.txt in tftp directory, like this:

cd /opt/pbxware/pw/tftp
touch v70.txt

If file v70.txt exists in /opt/pbxware/pw/tftp folder, all auto provisioning data for Yealink phones will be in v70 format, hence all phones should be on v70 or pre-v70 version. Mixing is not supported.

Known issues

Make sure you do factory reset after upgrade to latest V70 firmware. This is known to fix at least one problem - wrong User-Agent string for T46G device.

Wrong User-Agent:

  • Yealink-T46G 28.71.0.85 28.1.0.128.0.0.0

Correct User-Agent:

  • Yealink SIP-T46G 28.71.0.85 00:15:65:45:70:71

Problem with firmware older than 28.71.0.85 and T46G

Yealink T46G does not send User-Agent when requesting remote directory file, which is required due to security reasons, hence remote directory will not work. This issue has been fixed in 28.71.0.85 firmware.

Grandstream Devices

Provisioning method

TFTP only.

Some Grandstream devices support HTTP, but only in these two ways:

  • Without username/password
  • With username/password, but Basic authentication only

Therefore HTTP provisioning is not supported.

Grandstream devices

Filename

  • cfgMAC

File Format Format is binary and is not really human-readable. It consists of PXX=value fields.

You can pipe output to following command:

curl ... | hexdump -C -v

Supported features

Supported:

  • Basic authentication support
  • Additional UAD configuration (per extension)
  • Codecs
  • DHCP
  • DTMF mode (not all devices)
  • Default dialplan (not all devices)
  • Max lines per device limit

Not supported:

  • General UAD config

Table 6: Grandstream supported features

06-grandstream-supported-features.png

00-symbols.png

Aastra Information

Provisioning method

TFTP only, HTTP not possible as Aastra devices does not support username and password.

Aastra devices

Filenames:

  • aastra.cfg
  • mac.cfg
  • mac-directory.csv
Directory list in CSV format.

File Format

  • Plain text

Supported features

  • Basic authentication support
  • General UAD config
  • Additional UAD configuration (per extension)
  • DHCP values
  • Directory/BLF list
  • Max lines per device limit


Table 7: Aastra supported features

07-aastra-supported-features.png

00-symbols.png

Snom Information

Provisioning Method

TFTP only,, HTTP not possible as Snom devices doesn't support username and password.

Snom devices

Filenames:

  • snomXXX-mac.htm (XXX=320, 360..)

File Format

  • Plain text

Supported features

  • Basic authentication support
  • General UAD config
  • Additional UAD configuration (per extension)
  • DHCP values

Table 8: Snom supported features

08-snom-supported-features.png

00-symbols.png


Glossary Next -> 24. Glossary