End Point Configuration Manager Module for FreePBX - Part 1

[tshif]

There's an exciting new module being released from the Dev Support site by forum friends John Mullinix and Ed Macri. It turns out - they are busy-busy introducing it at Regional Asterisk users meeting today - so I get to write it up here! Cooool.
------------------------------------------------------------------------------------------------

End Point Configuration Manager Module for FreePBX
As I'm sure somebody has said out there, in the VoIP business, It's all fun and games until somebody sells a system. Then, the real work begins.

Thanks to the good people who brought us PBX in a flash, creating and configuring a new PBX takes a fraction of the time it would otherwise.

But when it comes time to configure, and deliver the telephones themselves -- the situation is not quite as rosy. Depending upon the manufacturer of the phone, the experience of going through the configuration process to prepare the device for use with the PBX can range anywhere from mind "numbingly dull and extremely time-consuming" all the way to "absurdly complex and completely befuddling". Even when the configuration process goes as smoothly as you would hope, it still takes time. Some estimates suggest that up to 60% of all time spent in new PBX deployments is spent on configuring the telephones.

Configuring "endpoints", or telephones, automatically has been possible for a long time, but there is no support for that within the FreePBX platform. Some distributions have had semi functional configuration systems available for some time –and let's face it, we know PBX in a flash is the best distribution; it's time for us to have the best Endpoint Manager also.

Today, with any luck we take our first step toward that goal.

I am Pleased to Announce the Immediate Availability of Endpoint Configuration Manager Module for FreePBX, version 1.0.0.

Illustration 1​

Release 1.0.0 of the module provides support for Snom, Polycom, Linksys, Aastra and GrandStream telephones. More models and manufacturers will be added to future versions of this module.

The software relies upon Mac addresses to uniquely identify every telephone on the system. Mac addresses are then associated with extensions. The system has several safeguards to prevent operator error. For example, each Mac address may only be registered with the Endpoint Configuration Manager once.

The software has been specifically designed to work well with barcode scanners, enhancing your ability to configure large numbers of telephones very quickly. (Most telephones today have a barcode depicting their Mac address on the outside of their package)

There are several modes of entry, supporting a wide variety of workflows. For example, you may choose to scan and save all Mac addresses into the system at one time, and associate them with extensions later. Alternately, you may choose to enter Mac address and extension affiliations one at a time.

Once the telephones Mac address has been associated with the correct user extension, the telephone need only be plugged into the network and powered up for it to automatically configure itself and connects to the PBX.

Prerequisite
The endpoint configuration manager utilizes and requires a functional t*f*t*p server on the PBX platform. This capability must be set up according to the instructions that are appropriate for the distribution you are running. For us lucky devils running PBX in a flash, the task could not be easier. When logged in as root, execute the script setup-t*f*t*p. In just a few seconds, the t*f*t*p service will be installed and functional.

Installation and Configuration
Like anything else, before we go, we have to get started -- so let's get started with the installation and configuration of Endpoint Configuration Manager. Initial configuration is an easy three-part deal. First, we perform two simple procedures while logged in as ROOT at the command line prompt, then we install the Endpoint Configuration Manager module into FreePBX, and finally we configure option 66 of the site DHCP server. So – here we go -

Grandstream Support
Grandstream telephones are unique to the supported manufacturers in that the configuration files produced for them must be encoded to a binary format before use. To make a long story short, if you will be using Endpoint Configuration Manager to manage Grandstream telephones, you must add support for the Grandstream configuration compiler to your PBX. This must be done while logged in as root at the command line prompt.

Log into your PBX console (or your favorite program, such as putty), as ROOT, and paste the following SINGLE LINE:

cd /usr/src/ && yum -y install jre && wget http://www.grandstream.com/DOWNLOAD/Configuration_Tool/Linux_Unix/GS_CFG_GEN.tar.gz && tar -zxvf GS_CFG_GEN.tar.gz && sed -i 's/\/java\/j2sdk1.4.2_07/\/lib\/jvm\/jre/g'  /usr/src/GS_CFG_GEN/bin/encode.sh && sed -i 's/local\/src/src/g'  /usr/src/GS_CFG_GEN/bin/encode.sh

This code will download and install the grand stream configuration compiler, and the Java runtime environment upon which it depends. On a typical system, this will take about one minute. At the end, you're all ready to support Grandstream telephones.

t*f*t*p Folder Configuration
The folder used as the t*f*t*p root folder (/tftpboot typically) must be writable by the asterisk user. By default, on most PBX in a flash systems, this folder is owned by ROOT: ROOT, with permissions set as 0755.

Make no mistake about it, the t*f*t*p service and folder the potential of great mischief and rather terrible security breaches. Do not enter any circumstances expose the contents of the t*f*t*p folder to the general public. Most telephones’ configuration files are in plain text, and will absolutely expose your SIP IDs and passwords to anyone with eyes. Off-site telephones to be configured via the Endpoint Configuration Manager, must be configured to operate through a VPN tunnel to maintain PBX security.

The settings we are about to recommend may not be right for all users in all circumstances. Please consider your particular situation carefully before making the following recommended changes to ownership and permission over the t*f*t*p folder and files.

chown –hR root:asterisk  /tftpboot 
chmod g+w /tftpboot

DHCP Support
(If you Dont DO THIS step, this Module will NOT WORK for you. This is how your phones get told to look at the PBX for their config files!)
When the telephones are first plugged into power in the network, the very first thing will attempt to do is to acquire a network address via DHCP. Along with the standard DHCP configuration information, it is necessary to establish option number 66 in the DHCP server. You will probably find this option is not presently configured in most of the DHCP servers you encounter.

Set DHCP option number 66 to the IP address or FQDN of your PBX.

It's very important that the IP address, or FQDN and that you provide for DHCP option 66 is a private address, not accessible from the outside world. Allowing your plain text configuration files to be examined by the public would be an immediate ticket to massive fraud potential. Trust us, and Steer Clear.

The method used to establish the DHCP configuration items varies with the DHCP server you are using, so step-by-step instructions about how to accomplish this task are outside the scope of this documentation. Please consult the documentation available from the DHCP server’s manufacturer.

Module Installation
Step 1: Download the module to your desktop From here.
http://projects.colsolgrp.net/projects/list_files/endpointman

(Generally, you'll want to select the most recent release of the Version 1.X Series.) Don’t decompress the archive!

Step 2: Use a web browser to access FreePBX on your PBX. Choose Tools, Module Admin, Upload Module.
Now, browse to the endpointman-1.X.X.tgz file on your Desktop and click the Upload button. Now click local module administration, scroll down and click on PBX Endpoint Manager, and then the Install radio button. Now click Process, and complete the usual FreePBX install and reload process.

Step 3: Use a web browser to access FreePBX on your PBX. Under Setup, Select PBX Endpoint Manager.
You will be presented with the module user interface

Illustration 2

System Use

Initial Configuration
In version 1 of the module, the first screen you are delivered to is depicted in illustration 2, above. This is the global settings screen – and it contains the first configuration items we need to set up.

In the places provided, enter the IP address or FQDN. And select the time zone that the server operates in. Click ADD GLOBALS when you have the info as you want it.

It's very important that the IP address, or FQDN and that you put into this configuration screen is a private address, not accessible from the outside world. Allowing your plain text configuration files to be examined by the public would be an immediate ticket to massive fraud potential. Unless you really know what your doing, trust us, and Steer Clear.


See - End Point Configuration Manager Module for FreePBX - Part 2
​

 

[tshif]

End Point Configuration Manager Module for FreePBX - Part 2

End Point Configuration Manager Module for FreePBX - Continued

UOI List
The UOI list is the area of the program which keeps track of Mac addresses as they relate to equipment manufacturers. Under typical circumstances, the manufacturer of a telephone may be identified by the first six digits of its Mac address. Five manufacturers Mac address ranges are currently preinstalled and ready for use in the module.

Illustration 3​

To help assure the user does not inadvertently enter an incorrect Mac address, the Endpoint Configuration Manager module will not allow you to assign a Mac address to a telephone whose manufacturers assigned UOI range does not encompass the Mac address being registered.

The interface does allow you to delete entries from the OUI list, but there are a few good reasons to do so. It is also possible to add an additional six character Mac address range manually. The purpose of this capability is to allow for the entry of unique Mac addresses, or Mac addresses which may have been changed from their original values, into the system. These Mac addresses must be associated with a currently supported brand of equipment, and not a new currently unsupported brand. (Support for new brands is added to the system in another way.)

Model List
The model list depicts the currently supported telephone models. The user interface allows for the deletion of pre-existing models, but there is little reason to do so. The presence of models not currently used in no way slows the performance of the Endpoint Configuration Manager.

Illustration 4​

The model list permits the addition of new telephone models to the Endpoint Configuration Manager. Ultimately, when your favorite manufacturer releases a brand-new telephone model to the marketplace, this is the place you will come to add that telephone model to the list of known models in the system.

In this version of the software, only Aastra telephones may be added manually through this interface successfully. To do so, type the name of the model into the field called "model", in the same format as you see the other Aastra telephones, then click the "Add Model" button.

In future releases of this module, it will be possible to add new telephone models to all of the supported manufacturers, not only Aastra.

Mac List
The Mac list screen is the screen where you will probably spend most of your time interacting with the Endpoint Configuration Manager. Is the screen where we register telephones with the system, and the screen that generates the telephone config files themselves.

Illustration 5​

Registering Telephones with Endpoint Configuration Manager
Several potential workflows are supported when registering telephones with the Endpoint Configuration Manager. In all cases, remember, the endpoint configuration manager will only allow you to register each Mac address and extension one time.

To register a single telephone at a time, start by entering the Mac address in the Mac address field. Next select the model of phone from the "model of phone" drop-down box. Finally, from the "extension number" drop-down box, select the extension to which you want this telephone assigned. When you have all three entries as you desire them, click the "Add" button. The extension is now registered, and will configure itself when connected to the network.

Because the endpoint configuration manager is designed to work well with bar code scanners, for installations with more than just a few telephones, you may wish to use the "machine gun method". With the machine gun method all you need do is place the cursor in the Mac address field, and point the scanner at the bar code of the Mac address, and click the scanner trigger. The trigger will activate the add button, and the Mac address will be recorded, and the cursor will be returned to the Mac address field ready to accept the next scanned Mac address. The machine gun method allows for extremely rapid registration of Mac addresses to the system. Once you have entered all of the Mac addresses, you may go back and edit each one, assigning it to the proper model of phone, and extension number. Once these assignments are complete, your telephones will register, and configure themselves when they are connected to the network.

The Mac list user interface also allows for the deletion and editing of already configured telephones. Once the phone is deleted, it can be re-registered with the system at a future time if desired. To edit an entry, click the left-hand icon next to the phone you wish to change. To delete the phone, click the right-hand icon.

Under the Hood
The actual telephone configuration files are created by the Endpoint Configuration Manager when you press the "Add" button (when adding a new phone), or when you click the "Edit” , or the "Edit and Reboot" button.

Rebooting the Phones
The telephones only assess their configuration files when they are booting up. If you make changes to a telephone's configuration, it will be necessary to reboot the telephone before the changes can take effect. The Endpoint Configuration Manager application allows you to reboot the telephone from the Mac address screen after editing its configuration. The Main screen also contains controls to allow you to reboot multiple phones at a time. These controls include the ability to reboot all phones of a specific manufacturer, or all phones throughout the system all at once.

As with any good programming project, the endpoint configuration manager will continue to grow and evolve from its present form. It is our goal to provide extremely rapid support for any new telephone models introduced by any of the currently supported vendors, and to move as quickly as possible toward being able to add additional supported manufacturers in the same ways.

We hope that you find the endpoint configuration manager useful, and easy to work with.

Project Credits:
This program was designed and created by John Mullinix and Ed Macri. The program was put into FreePBX Module format by Tony Shiffer. Joe Roper provided the dependencies scripting, and lots of good design and security help.

As always please let us know how this module works for you.

Until next time -
tshif

 

[drmurdoch]

What a great idea !
Is it possible to maintain a simple list of the Makes and Models of "Supported" phones ? I think the list would get used alot.

 

[therock112]

this is fascinating.

How does the Endpoint manager handle things such as manfacturers firmware updates, newer bootroms and such.

is there a way to update the ip phones firmware in a simple manner when the manufacturer release new firmware etc?

Polycom tends to continually release firmware to address bugs and feature enhancements etc.

things like, which phone is running which firmware could be ideally gleaned out of the phones log files if logs from each phone are stored in a seperate folder......

I can see this module making PIAF very very popular. I realize few bumps will need to be addressed and not to mention the constant changes phone manufacturers are making to their firmwares almost on a very regular basis.

some good developers are involved with this, thats great.

 

[tshif]

What a great idea !
Is it possible to maintain a simple list of the Makes and Models of "Supported" phones ? I think the list would get used alot.

The real goal is for the system to ultimately be able to support just about any widely distributed phone and model. We started out with a reasonable selection - and (shhhh!) There's even built in support for a few GrandStream models that aren't showing on the list yet! (Theres a few little kinks left to work out.)

I cant (on threat of pain and agony) let any cats out of the bag, but rest assured, the things the developers are talking about for future releases are nothing short of super cool.

I can say this - everyone working on this project agrees - one of the biggest shortcomings of other End Point Manager type solutions that have been out there - they just don't support any of the newer phones, and that just makes them a serious tease, but not a serious tool. Making sure the supported manufacturers and models keep up to date is a primary concern to us.

-tshif

 

[tshif]

this is fascinating.

How does the Endpoint manager handle things such as manfacturers firmware updates, newer bootroms and such.

is there a way to update the ip phones firmware in a simple manner when the manufacturer release new firmware etc?

Polycom tends to continually release firmware to address bugs and feature enhancements etc.

things like, which phone is running which firmware could be ideally gleaned out of the phones log files if logs from each phone are stored in a seperate folder......

I can see this module making PIAF very very popular. I realize few bumps will need to be addressed and not to mention the constant changes phone manufacturers are making to their firmwares almost on a very regular basis.

some good developers are involved with this, that's great.

Like with anything else, the devil's in the details. The capability to include firmware/bios updates is there. But there is no awareness of this process in the End Point Manager. Plus, the current template set for each phone may not configure and enable these particular update process. So at the moment, it may be hit - and miss.

Its a very good suggestion for a feature request. "Modify Supported Phone Models templates to cause the phones to look to the server folder for firmware updates." There are some concerns such as when the firmware upgrades take place, the templates for the phones could be come outdated - thus the firmware update could break the systems ability to support a given phone. That being said, I have opened a ticket at the dev site to study the possibilities.

-tshif

 

[therock112]

two more things:

1. possibility of using FTP instead of t*f*t*p....t*f*t*p being unsafe in an office type environment where staff can easily do some monkey business scanning for open services.

2. possibility of configuring Enhanced Feature Keys and such, for example with polycom phones and others, I know Aastra phones can be programmed using xml files as well.

thx

 

[tshif]

two more things:

1. possibility of using FTP instead of t*f*t*p....t*f*t*p being unsafe in an office type environment where staff can easily do some monkey business scanning for open services.

2. possibility of configuring Enhanced Feature Keys and such, for example with polycom phones and others, I know Aastra phones can be programmed using xml files as well.

thx

1. Not likely based on the current thinking of the developers. They seem to prefer t*f*t*p. But - they usually keep listening to suggestions, so feel free to share your reasons and see what happens. Cant hurt to try, right?

2. You can do that right now - by directly editing the configurations files the system produces to include your extended configuration information.

I also like the idea of being able to edit more of the extended parameters for each phone from within the EPM, so Ill be suggesting that myself. By all means, keep suggesting also. Good, logical reasoning seems to get listened to the best - so keep on keepiong on!

(I created a feature request about this just now - )

Tony

 

[sri2talk]

Awsome tool

The tool seems awesome.
I do not quite figure out how you can ask the device to t*f*t*p it's config. I have the following tedious procedure:

1. Buy the phones/ATAs.
2. Connect them to my local network.
3. Access their GUI and change the URL where they download their firmware and config.

Meanwhile:
4. Generate their config files by making a list:
{mac,extension#,password} and using this to generate config files. So far, I have been using Grandstream. I "sed" the config files for the needed parameters. So, I have the java tool to encode.
5. Copy the config files to the url where the phones are going to look.

6. Reboot the phone and verify it got it's new config by looking at it's web page.
Because of this, I am not concerned about security.
I just bought an Aastra 57i. They use plain text config. They also have a tool to encode it so we do not need to worry about snoopers.

 

[tshif]

I do not quite figure out how you can ask the device to t*f*t*p it's config.

Taken from the instructions at the top of this thread:
http://www.pbxinaflash.com/forum/showpost.php?p=27684&postcount=1

DHCP Support
When the telephones are first plugged into power in the network, the very first thing will attempt to do is to acquire a network address via DHCP. Along with the standard DHCP configuration information, it is necessary to establish option number 66 in the DHCP server. You will probably find this option is not presently configured in most of the DHCP servers you encounter.

Set DHCP option number 66 to the IP address or FQDN of your PBX.

It's very important that the IP address, or FQDN and that you provide for DHCP option 66 is a private address, not accessible from the outside world. Allowing your plain text configuration files to be examined by the public would be an immediate ticket to massive fraud potential. Trust us, and Steer Clear.

The method used to establish the DHCP configuration items varies with the DHCP server you are using, so step-by-step instructions about how to accomplish this task are outside the scope of this documentation. Please consult the documentation available from the DHCP server’s manufacturer.

 

[jroper]

Hi

There is an option called Option 66 in DHCP. This setting tells any device that gets an IP address, where to find a t*f*t*p server if it goes looking for one.

Not all routers expose all the DHCP options, so your solution is to do what you are doing, or configure a DHCP server on the PBX with that option enabled. Don't forget to switch off the other DHCP servers. Multiple DHCP servers do not play well on one network.

Joe

 

[jmullinix]

FWIW, I am consulting on an installation at a Hotel. I installed the Endpoint Manager on their new phone server and showed their network guy how to use it. He then took 40 Grandstream BT-201's to the hotel rooms, unboxed them, plugged them in and they lit right up and connected. We set option 66, which is called "t*f*t*p-server-name" in dhcpd on Linux, to the IP of the phone server,.

 

[voipgkavek]

two questions

1) what should the correct permissions be for the complete list of files already in the TFTPBOOT directory? the command you wrote on your instructions
chmod g+w /tftpboot

adds write for group. Which is fine, but for some reason unknown to me
all my permissions were 777. what are the correct permissions for
everything?

2) I created a test cfg file and it creates it as asterisk:asterisk
so why do you want us to initially change the permissions
to root:asterisk ?

thanks,
-guillermo
PS.- I am a linux newbie as you can tell.

 

[jmullinix]

Guillermo,

If there permissions of tftpboot were already 777, the module will work without further modification in this area. Just be aware that 777 means the owner, the group and everybody have read, write and execute privileges, which is about as insecure as it can be. On the other side, you are probably not going to expose the t*f*t*p server to the Internet, so security can be a little relaxed.

On my installation I change the permissions on tftpboot to 775 and the group to asterisk.

I think the best thing is to keep you t*f*t*p server inside you network. The config files for these phones are plain text. Even a hacker with read priviledges can clone a phone with the information in these files.

 

[ou812]

I previously installed the Aastra 2.2.1 scripts which includes Auto-Discovery I take it this is conflicting with this EPM I am trying to test, I have looked at there user guide but can't find how to turn of the auto-discovery.
Also (the discovery mechanism selected by Aastra to go beyond DHCP option 66 which might not commonly be available is multicastDNS (mDNS) also known as "Bonjour" in the Apple Computer community.) is this something that can be used by your EPM for networks that do not have option 66 available.

Gary

 

[voipgkavek]

thanks for the info jmullinix. I will change the permissions ASAP.
thank you.
-guillermo

 

[mac]

We have not used aastra auto-discovery, and I have not been able to look into it.
Depending on what it tells the phones to do, it may conflict, if you can brief me on how the auto discovery works, I might be able to give you a better answer.

 

[edisoninfo]

Beware!

Probably my haste to have fun first then read the directions later <grin>, but I easily and quietly blew away my aastra.cfg file by messing with this module. The module installed fine and then I started clicking on adding mac addresses, setting the global stuff and didn't see much that interested me since I already use the aastra-xml scripts. Later I went to edit my aastra.cfg file and Wow! What Happened? It's empty! Almost! The only thing in it was the couple of lines the module put in it. Fortunately I keep backup copies but "panic mode" for a second!

Please, again, nothing against this module at all. It is just that a nice warning or something? Maybe if I had some common sense? Ha!

 

[jmullinix]

The Aastra part moves two files. The master files live in ../admin/modules/endpointman/aastra/ If you have a tricked out file that your are using, you might want to take a look at the master file and add your stuff to it. The aastra.cfg file has some global variables in it, so the software has to use it.

One of the beauties of the software is that you can create your own configs in the folder mentioned above. Just leave the stuff that starts with "$" alone and create your own configs.

 

[BelMarduk]

Is it possible to add support for Aastra 9133i phones?

THanks.