Hack53.Put a Happy Face on Asterisk Using AMP | VoIP Hacks: Tips & Tools for Internet Telephony

Hack 53. Put a Happy Face on Asterisk Using AMP

When you've got Apache and MySQL on your Asterisk PBX, you've got the makings of a web-based administration interface for your whole phone system.

Since Asterisk runs on Unix, it is able to leverage many of the niceties of a modern Unix environment: shell scripts, Perl programs, sockets, and so on. Historically, one of the chief shortcomings of Unixand of Linux in particularis the lack of a graphical user interface (GUI). Asterisk shares Unix's general inferiority in the user-interface department. But there's something you can do about it.

Asterisk Management Portal (AMP) gives you some real interface power tools: a web-based configuration tool suitable for nontechnical administrators, database routines for storing and retrieving the PBX's dial plan, and some handy preconfigured call flow and fax features that make day-to-day life with Asterisk much easier. For instance, AMP lets you upload music-on-hold files using a web interface and lets you create IVR menus without having to type them directly into extensions.conf or to program Asterisk macros.

4.14.1. How AMP Works

AMP provides a web-based GUI using Apache and connects to Asterisk using a combination of techniquesmost notably, via the Asterisk Manager API. It uses PHP to build the web pages you interact with, and it controls Asterisk with code written in Perl. MySQL provides a repository where the entire dial-plan configuration is stored, retrieved, and modified by the web interface.

4.14.2. The Setup Process

AMP has a ton of software prerequisites, as you can see. But it's fairly easy to install. The basic steps are spelled out here and are detailed in the following sections:

Get the prerequisites, including Apache and MySQL.
Install Perl modules and custom telecom tools.
Build the MySQL database.
Run AMP's install script and finish up.

4.14.2.1. Get the prerequisites.

A few dependencies are standing between your Linux server and AMP. Check to make sure that your Linux box is running Apache, libtiff, MySQL with development libraries installed, PHP (version 3 or higher), OpenSSL, Perl, ncurses, SoX, and curl. If you're running a Red Hat 7 or later distribution, you should have all of these packages either preinstalled or available via RPM. If you're not using Red Hat, chances are still pretty good that you've got everything you need, because most of these packages are either commonplace or required by Asterisk, and therefore are already installed on your machine.

Before you can go any further, though, you need to be certain that your Asterisk instance is running as a nonroot user. To do so, follow the recommendations in "Run Asterisk Without Root, for Security's Sake" [Hack #54], because the rest of the AMP installation is going to assume your Asterisk instance runs as a nonprivileged user. But keep your finger on this page, because there's a lot more to do!

4.14.2.2. Install Perl modules and telecom tools.

You can download AMP from http://amportal.sourceforge.net. Unpack the AMP source distribution using tar (there are numerous examples of tar-unpacking throughout this book) into the /usr/src/ directory. Once it's unpacked, install the Net: Telnet Perl module from CPAN, which allows Perl-based packages such as AMP to use Telnet sockets:

 # perl -MCPAN -e "install Net::Telnet"

Now, to enable AMP's music-on-hold upload feature, you can use vi to make a few modifications to the PHP configuration (PHP 4 users might need to substitute /etc/php4/apache2/php.ini in place of /etc/php.ini). The idea here is to increase the upload_max_filesize value to 20M and to change the corresponding LimitRequestBody value to 20000000. This way, you'll be able to use AMP to upload large files, like music-on-hold MP3s.

 # vi +482 /etc/php.ini upload_max_filesize=20M # vi +14 /etc/httpd/conf.d/php.conf LimitRequestBody 20000000

If you've already modified your PHP configuration files, these commands will not work correctly, and you should find the appropriate lines manually instead.

Next, you'll need to install the Asterisk Perl modules for Asterisk, like this:

 # wget http://asterisk.gnuinter.net/files/asterisk-perl-0.08.tar.gz # tar xvgf asterisk-perl-0.08.tar.gz # cd asterisk-perl-0.0.8 # perl Makefile.PL # make all # make install

Then, grab a couple more Perl modules from CPAN and install them (these enable the forwarding of faxes received, if you want AMP to handle faxes):

 # perl -MCPAN -e "install IPC::Signal" # perl -MCPAN -e "install Proc::WaitStat"

To make sure that AMP's email integration works correctly, grab a copy of the MIME Construct package from Roderick Schertler (http://search.cpan.org/src/ROSCH/mime-construct-1.9) and unpack it to /root or /usr/src, whichever you prefer. Then, from the directory where it's been unpacked, install it as follows:

 # make Configure.PL # make install

To add fax-receiving support to AMP, install the spandsp package per the instructions in "Turn Your Linux Box into a Fax Machine" [Hack #90]. Then, you'll need to set up the MySQL CDR interface for Asterisk. (When you downloaded the Asterisk CVS, this was downloaded to /usr/src/asterisk-addons.)

 # cd /usr/src/asterisk-addons # make clean # make # make install

4.14.2.3. Configure the MySQL database.

Now you're getting to the meat of the hack: the MySQL database for storing the CDRs and AMP's replica of the Asterisk configuration. To set this up, blow the dust off your latent MySQL skills, and issue the following commands:

 # /usr/bin/mysql_install_db # /etc/init.d/mysqld start (or /etc/init.d/mysql start) # mysqladmin -u root password 'db_root_pwd' # mysqladmin create asteriskcdrdb -p # mysql --user=root --password=db_root_pwd asteriskcdrdb < \ /usr/src/AMP/SQL/cdr_mysql_table.sql # mysqladmin create asterisk -p # mysql --user root -p asterisk < /usr/src/AMP/SQL/newinstall.sql

The text files directed to MySQL's standard input are provided as a part of the AMP distribution, and they contain all the queries needed to set up AMP's database. Now, launch the MySQL client:

 # mysql --user root -p

Once you get to the mysql prompt, you can begin entering the access privileges for the database:

 mysql> GRANT ALL PRIVILEGES ON asteriskcdrdb.* \ TO asteriskuser@localhost IDENTIFIED BY 'amp109'; Query OK, 0 rows affected (0.00 sec) mysql> GRANT ALL PRIVILEGES ON asterisk.* \ TO asteriskuser@localhost IDENTIFIED BY 'amp109'; Query OK, 0 rows affected (0.00 sec) mysql> quit

4.14.2.4. Run AMP's install script and finish up.

About the only conventional part of this configuration is AMP's shell script for installing its standard files, which you need to run now:

 # /usr/src/AMP/install_amp

Finally, add /usr/local/lib to the /etc/ls.so.conf file, which will include the spandsp fax libraries you loaded earlier. Add the following lines to your /var/lib/asterisk/.bash_profile file:

 # PATH=$PATH:/usr/sbin:$HOME/bin # export PATH # export LD_LIBRARY_PATH=/usr/local/lib

Then open /etc/rc.d/rc.local in your favorite text editor. Replace the line that currently loads Asterisk (probably something like asterisk vvv &) with this:

 /usr/sbin/amportal start

Are you still reading? Excellent! You've just installed AMP. Now, to try it out, you can restart Asterisk, Apache, and MySQL, or you can just reboot to achieve the same effect. Once your reset or reboot is done, point your browser to http://AsteriskServerAddress. You'll be greeted with the Asterisk Management Portal, the ultimate Asterisk GUI. Now, go have fun configuring. (If you want this page to be secured by a username and password, you can use Apache's htpasswd utility. For more info on this, check out http://www.apache.org/.)