End Point Configuration Manager Module for FreePBX - Part 1

tshif · #1 05-26-09, 09:29 AM

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 TFTP 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-tftp. In just a few seconds, the TFTP 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:

Code:

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.

TFTP Folder Configuration
The folder used as the TFTP 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 TFTP service and folder the potential of great mischief and rather terrible security breaches. Do not enter any circumstances expose the contents of the TFTP 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 TFTP folder and files.

Code:

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/projec...es/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 · #2 05-26-09, 09:35 AM

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 · #3 05-26-09, 11:05 AM

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 · #4 05-26-09, 01:22 PM

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 · #5 05-26-09, 01:45 PM

Originally Posted by 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.

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 · #6 05-26-09, 02:04 PM

Originally Posted by 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, 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 · #7 05-26-09, 09:25 PM

two more things:

1. possibility of using FTP instead of tftp....tftp 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 · #8 05-26-09, 11:00 PM

Originally Posted by therock112

two more things:

1. possibility of using FTP instead of tftp....tftp 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 tftp. 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 · #9 05-28-09, 08:16 AM

The tool seems awesome.
I do not quite figure out how you can ask the device to tftp 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 · #10 05-28-09, 09:10 AM

Quote:

I do not quite figure out how you can ask the device to tftp it's config.

Taken from the instructions at the top of this thread:
http://www.pbxinaflash.com/forum/sho...84&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.