Difference between revisions of "Phones"

From FusionPBX
Jump to: navigation, search
(Linksys/Cisco SPA3102-specific notes: add info for bootstrapping via SPA3102 web browser)
Line 2: Line 2:
  
 
This section of FusionPBX is used for automatic phone provisioning.
 
This section of FusionPBX is used for automatic phone provisioning.
* it allows you to automatically configure phone functionality and set up the phone as a specific extension on your FusionPBX phone system\
 
* it is useful when you have a large number of phones to configure with common settings and the only difference between them being the mac address and the extension details (saves you having to use the phones' own web administration pages)
 
* enables you to at any time in the future, edit the configuration template on the FusionPBX server in order to make a change to all the phones next time they reboot, rather than having to manually change each one
 
* it is useful only if your phone models support automatic provisioning
 
* it relies on you having a DHCP server that supports supplying options 66 or 43 to DHCP clients
 
* depending on the model of phone you are using it will require either a TFTP server or an FTP server or an HTTP or HTTPS server to provide the provisioning files.  Note that if the phone supports http or https then you are in luck since your FusionPBX already has a web server and so you can put the files there.
 
  
Before going into detail about the functionality on this screen of the FusionPBX GUI it may be helpful to provide an overview of provisioning first.
+
=Requirements=
 +
* The phone/ata must support automatic provisioning.
 +
* If your DHCP server supports supplying options 66 or 43 to DHCP clients, then you can start provisioning more easily.
 +
* Your phone will require either a TFTP server or an FTP server or an HTTP or HTTPS server to provide the provisioning files.  If you are using http, FusionPBX is set up to handle that automatically.
  
==Provisioning overview (untested)==
+
=Benefits of Provisioning=
 +
* It allows you to automatically configure phone functionality and set up the phone as a specific extension on your FusionPBX phone system.
 +
* It is useful when you have a large number of phones to configure with common settings and the only difference between them being the mac address and the extension details (rather than making the edits manually via the phones' own web administration pages)
 +
* If the phones are "out in the field" you can still make changes to the configuration files.
  
1. setup a DHCP server where you can set options 66 and 43 to point to an HTTP or TFTP server (most phones capable of auto-provisioning support TFTP, but some also support HTTP) - dnsmasq is an example of a DHCP server that can do this
+
=Benefits of Provisioning with FusionPBX=
 +
* At any time in the future, you can edit the configuration template on the FusionPBX server in order to make a change to all the phones next time they provision/reboot, rather than having to manually change each one.
 +
* From the extensions page, you can select which device, and which line on that device, that phone should register to.
  
2. point the URL in option 66 and 43 to a directory on your FusionPBX server.  An example using dnsmasq syntax and assuming Yealink phone would be:
+
 
 +
=Provisioning Step By Step=
 +
There are two ways to start - Option 66 or manually adding the provisioning URL.
 +
 
 +
==Provisioning, Option 66 (untested)==
 +
 
 +
1. Setup a DHCP server where you can set options 66 and 43 to point to an HTTP or TFTP server (most phones capable of auto-provisioning support TFTP, but some also support HTTP) - dnsmasq is an example of a DHCP server that can do this
 +
 
 +
2. Point the URL in option 66 and 43 to a directory on your FusionPBX server.  An example using dnsmasq syntax and assuming Yealink phone would be:
 
<pre>
 
<pre>
 
log-dhcp
 
log-dhcp
Line 23: Line 33:
 
</pre>
 
</pre>
 
Note that normally option 66 will only be a hostname or IP address, but it is possible that some phones might be smart enough to have a URL there and work out the server type from it.
 
Note that normally option 66 will only be a hostname or IP address, but it is possible that some phones might be smart enough to have a URL there and work out the server type from it.
 +
[[Phones#Provisioning General]]
 +
 +
==Provisioning, Simple==
 +
If your phone can use http for provisioning, e.g. Yealink and all Linksys, then you can manually add the provision URL to the device.
 +
This way, you only have to make one change to your phones manually - to make it look for the provisioning server.
 +
(Note for Yealink: you have to enable "check new config")
 +
 +
For example, in the Linksys, to provision via the web ONCE simply load: <code>http://{Linksys-IP}/admin/resync?http://{PBX-Box}/mod/provision/?mac=$MA</code>
 +
(To find out the IP of the device, pick up a phone and press ****. Then, 1 1 0 #. If the page is unreachable, the web config may be disabled. In that same menu, press 7 9 3 2 # followed by 1 # then 1 to save.)
  
3. the phone will theoretically then request two files from the server - one is a config file specific to the phone model (for the Yealink T-20 this is y000000000007.cfg) and a file specific to the mac address of your phone.  The former file should be provided on your webserver at the URL you specify, and will set all the standard parameters of your phones.  The latter file is provided in the next few steps below by the FusionPBX server and allows the setting of the settings specific to each phone eg. the extension to connect to.
 
  
4. add a rewrite rule to your web server so that http://fusionpbx/provisioning/yealink/001565aabbcc.cfg gets rewritten to the fusionpbx provisioning URL eg. The rewrite rule should forward the request to http://fusionpbx/mod/provision/index.php?mac=001565aabbcc. FusionPBX uses apache as a web server by default in the iso, but you might be using a different web server so you'll need to work this out for the server you are using.  There are some Apache rewrite rule examples in the FusionPBX [http://code.google.com/p/fusionpbx/source/browse/trunk/fusionpbx/.htaccess .htaccess] file.  An example for Nginx is:
+
==Provisioning, All==
 +
''After either Option 66 or manual entry, we continue here:''
 +
 
 +
1. The phone will then request the relevant files from the server.
 +
Yealink will request two - a config file, e.g. Yealink T-20->y000000000007.cfg and a file specific to the mac address of your phone.
 +
The linksys boxes only request one file. ''(but it seems you can set up multiple files to provision)''
 +
A general config file should be provided on your webserver at the URL you specify, and will set all the standard parameters of your phones.
 +
The specific file is provided in the next few steps below by the FusionPBX server and allows the setting of the settings specific to each phone eg. the extension to connect to.
 +
 
 +
2. FusionPBX requires a rewrite rule in the web server so that http://fusionpbx/provisioning/yealink/001565aabbcc.cfg gets rewritten to the fusionpbx provisioning URL e.g. The rewrite rule should forward the request to http://fusionpbx/mod/provision/index.php?mac=001565aabbcc.
 +
FusionPBX uses apache as a web server by default in the iso, but you might be using a different web server so you'll need to work this out for the server you are using.  There are some Apache rewrite rule examples in the FusionPBX [http://code.google.com/p/fusionpbx/source/browse/trunk/fusionpbx/.htaccess .htaccess] file.  An example for Nginx is:
 
<pre>
 
<pre>
 
location / {
 
location / {
Line 33: Line 61:
 
</pre>
 
</pre>
  
5. when the phone requests that URL FusionPBX will add the MAC address of the phone to the database and it will show up in the phones database (and therefore on the phones screen in FusionPBX).  However at this time it will not have a template assigned to it. So now you go to the phones screen and add an entry for the new phone's mac address and fill in the missing template, model and description values. Then apply your changes
+
3. When the phone requests that URL, FusionPBX will add the MAC address of the phone to the database and it will show up in the phones screen in FusionPBX.
 +
For the linksys-2102 and 3102, the user_agent enables FusionPBX to automatically assign a template, which includes setting a permanent provisioning.
  
6. reboot the phone
+
If FusionPBX does not automatically assign a template, you will need to edit the new entry (which has the info "auto") and set a template.
 +
You will now need to wait for option66 again, or set your device to provision once more.
 +
 
 +
4. The phone will re-configure itself from that config file and then register with freeswitch.
  
7. when the phone boots after the template has been set the http request to http://fusionpbx/mod/provision/index.php?mac=001565aabbcc should give the phone a real configuration file.  Theoretically then the phone will re-configure itself from that config file and then register with freeswitch.
 
  
 
There are many things that can go wrong in automated provisioning.  When you are first setting it up you might want to set your DHCP server to provide you with verbose logging so you can diagnose it.  You also might want to set your phone to use verbose logging too.
 
There are many things that can go wrong in automated provisioning.  When you are first setting it up you might want to set your DHCP server to provide you with verbose logging so you can diagnose it.  You also might want to set your phone to use verbose logging too.
 +
  
 
As an example of what will happen when your phone makes a request to FusionPBX for provisioning you can try this URL (changing fusionpbx to the IP address of your server):  http://fusionpbx/mod/provision/index.php?mac=00085daabbcc.  You can then go to the phones page and you'll see a new phone with this mac address added.  Press the X to delete it since it was just an experiment anyway!
 
As an example of what will happen when your phone makes a request to FusionPBX for provisioning you can try this URL (changing fusionpbx to the IP address of your server):  http://fusionpbx/mod/provision/index.php?mac=00085daabbcc.  You can then go to the phones page and you'll see a new phone with this mac address added.  Press the X to delete it since it was just an experiment anyway!
  
==Provisioning simple (untested)==
 
Theoretically, if you don't have a DHCP server capable of sending additional information, you can still use provisioning if your phone is capable of it using http (for example a Yealink phone).  You can put the provisioning URL on the upgrade tab of the Yealink and you can do steps 4 onwards above to configure the web server and the fusionpbx provisioning.  This way, you only have to make one change to your phones manually - to make it look for the provisioning server.  Note that with the Yealink phones though, it looks like you have to make one change to the phone anyway - by default "check new config" is disabled, and it appears that it will not work without that set.
 
  
 
==Linksys/Cisco SPA3102-specific notes==
 
==Linksys/Cisco SPA3102-specific notes==

Revision as of 22:01, 2 November 2010

Menu: (Apps-Phones)

This section of FusionPBX is used for automatic phone provisioning.

Requirements

  • The phone/ata must support automatic provisioning.
  • If your DHCP server supports supplying options 66 or 43 to DHCP clients, then you can start provisioning more easily.
  • Your phone will require either a TFTP server or an FTP server or an HTTP or HTTPS server to provide the provisioning files. If you are using http, FusionPBX is set up to handle that automatically.

Benefits of Provisioning

  • It allows you to automatically configure phone functionality and set up the phone as a specific extension on your FusionPBX phone system.
  • It is useful when you have a large number of phones to configure with common settings and the only difference between them being the mac address and the extension details (rather than making the edits manually via the phones' own web administration pages)
  • If the phones are "out in the field" you can still make changes to the configuration files.

Benefits of Provisioning with FusionPBX

  • At any time in the future, you can edit the configuration template on the FusionPBX server in order to make a change to all the phones next time they provision/reboot, rather than having to manually change each one.
  • From the extensions page, you can select which device, and which line on that device, that phone should register to.


Provisioning Step By Step

There are two ways to start - Option 66 or manually adding the provisioning URL.

Provisioning, Option 66 (untested)

1. Setup a DHCP server where you can set options 66 and 43 to point to an HTTP or TFTP server (most phones capable of auto-provisioning support TFTP, but some also support HTTP) - dnsmasq is an example of a DHCP server that can do this

2. Point the URL in option 66 and 43 to a directory on your FusionPBX server. An example using dnsmasq syntax and assuming Yealink phone would be:

log-dhcp
dhcp-range=192.168.1.100,192.168.1.149,12h
dhcp-host=00:15:65:aa:bb:cc,net:YEA,192.168.1.101,yealink_ext101
dhcp-option=YEA,66,"http://fusionpbx/provisioning/yealink"

Note that normally option 66 will only be a hostname or IP address, but it is possible that some phones might be smart enough to have a URL there and work out the server type from it. Phones#Provisioning General

Provisioning, Simple

If your phone can use http for provisioning, e.g. Yealink and all Linksys, then you can manually add the provision URL to the device. This way, you only have to make one change to your phones manually - to make it look for the provisioning server. (Note for Yealink: you have to enable "check new config")

For example, in the Linksys, to provision via the web ONCE simply load: http://{Linksys-IP}/admin/resync?http://{PBX-Box}/mod/provision/?mac=$MA (To find out the IP of the device, pick up a phone and press ****. Then, 1 1 0 #. If the page is unreachable, the web config may be disabled. In that same menu, press 7 9 3 2 # followed by 1 # then 1 to save.)


Provisioning, All

After either Option 66 or manual entry, we continue here:

1. The phone will then request the relevant files from the server. Yealink will request two - a config file, e.g. Yealink T-20->y000000000007.cfg and a file specific to the mac address of your phone. The linksys boxes only request one file. (but it seems you can set up multiple files to provision) A general config file should be provided on your webserver at the URL you specify, and will set all the standard parameters of your phones. The specific file is provided in the next few steps below by the FusionPBX server and allows the setting of the settings specific to each phone eg. the extension to connect to.

2. FusionPBX requires a rewrite rule in the web server so that http://fusionpbx/provisioning/yealink/001565aabbcc.cfg gets rewritten to the fusionpbx provisioning URL e.g. The rewrite rule should forward the request to http://fusionpbx/mod/provision/index.php?mac=001565aabbcc. FusionPBX uses apache as a web server by default in the iso, but you might be using a different web server so you'll need to work this out for the server you are using. There are some Apache rewrite rule examples in the FusionPBX .htaccess file. An example for Nginx is:

location / {
    rewrite "^/provisioning/[a-z]+/([A-Fa-f0-9]{12})(\.(xml|cfg))$" /mod/provision/index.php?mac=$1 last;
}

3. When the phone requests that URL, FusionPBX will add the MAC address of the phone to the database and it will show up in the phones screen in FusionPBX. For the linksys-2102 and 3102, the user_agent enables FusionPBX to automatically assign a template, which includes setting a permanent provisioning.

If FusionPBX does not automatically assign a template, you will need to edit the new entry (which has the info "auto") and set a template. You will now need to wait for option66 again, or set your device to provision once more.

4. The phone will re-configure itself from that config file and then register with freeswitch.


There are many things that can go wrong in automated provisioning. When you are first setting it up you might want to set your DHCP server to provide you with verbose logging so you can diagnose it. You also might want to set your phone to use verbose logging too.


As an example of what will happen when your phone makes a request to FusionPBX for provisioning you can try this URL (changing fusionpbx to the IP address of your server): http://fusionpbx/mod/provision/index.php?mac=00085daabbcc. You can then go to the phones page and you'll see a new phone with this mac address added. Press the X to delete it since it was just an experiment anyway!


Linksys/Cisco SPA3102-specific notes

TODO: This information probably belongs on its own wiki page. Putting it here temporarily under the assumption that it's better to publish it in rough form somewhere rather than not at all.

This information may also benefit SPA2102 and PAP2T users.

Using dnsmasq and TFTP option 66 to bootstrap provisioning:

# /etc/dnsmasq.d/pbx

# Assumes 00:0e:08:aa:bb:cc is the mac address of the SPA3102 you are provisioning
# and you want to assign the SPA3102 address 10.1.2.50 and hostname "my3102".

log-dhcp

# "=eth1" below is optional.  Leave it off if you don't mind dnsmasq's
# mini-TFTP server listening on all interfaces.
enable-tftp=eth1
tftp-root=/etc/dnsmasq.d/pbx.tftp

# dnsmasq replaces 0.0.0.0 with its IP
dhcp-option=SPA,66,0.0.0.0
dhcp-host=00:0e:08:aa:bb:cc,net:SPA,10.1.2.50,my3102
# add additional dhcp-host lines here as needed for other 3102s
<!-- /etc/dnsmasq.d/pbx.tftp/spa3102.cfg -->

<!--
  Assumes FusionPBX is at http://pbx.local/ and there is a syslog server
  accepting remote UDP packets listening at 10.1.2.1:514.
-->
<flat-profile>
  <!-- Device being provisioned automatically replaces $MA with its own MAC address. -->
  <Profile_Rule>http://pbx.local/mod/provision/?mac=$MA</Profile_Rule>
  <Resync_Periodic ua="na">10</Resync_Periodic>
  <Syslog_Server>10.1.2.1</Syslog_Server>
  <Debug_Server>10.1.2.1</Debug_Server>
  <Debug_Level>2</Debug_Level>
</flat-profile>

Or, using the SPA3102 web interface without TFTP, visit http://10.1.2.50/admin/resync?http://pbx.local/mod/provision/?mac=$MA in your browser, assuming 10.1.2.50 is the address of the device you want to provision and pbx.local is the hostname of your FusionPBX server.