Copyright © 2004-2013, Ward MundyAll Rights Reserved. Contents licensed under the GPLv2.
Last updated: Tuesday, July 23, 2013 - 12:35 AM (GMT -7)
Phone Genie for Asterisk 2.0 (Web Edition)
Web-Based Controller for the Asterisk Manager API and CLI
Nerd Vittles' Phone Genie for Asterisk (Web Edition) provides almost complete control over the Asterisk Manager API and Asterisk Command Line Interface (CLI) using simple HTML web commands. In addition, you can set and adjust many freePBX functions on your Asterisk PBX phone system by issuing a single HTML request, e.g. call forwarding, call waiting, call tracing, do not disturb. Version 2.0 adds support for executing Linux system commands and scripts as well. And now there's even an Email Edition which lets you control your Asterisk system from the convenience of any email client.
Prerequisites
To get Phone Genie for Asterisk working, we recommend either a PBX in a Flash, trixbox, or version 2 Asterisk@Home system. Any other Asterisk 1.2.x system (or later) with a web server on the same box should also work. To control things such as call forwarding, call waiting, call tracing, and do not disturb, you'll need an Asterisk server running any version of freePBX. Some of the later versions of the Asterisk Management Portal also work. For optimum use so that you can control your Asterisk system from remote locations including cellphones with a web browser, you'll need an Internet connection to your Asterisk server with a fully-qualified domain name. In addition, your firewall should be configured to redirect incoming port 80 HTTP traffic to the web site on your Asterisk server. Instead of a dedicated Asterisk server, you also can use our VMware version of PBX in a Flash if you just want to experiment a bit. It runs in a window on your Windows Vista/XP/2000 desktop. There's also a version for Intel Macs.
Asterisk Server Download
![[zip]](../../images/zip-file.gif){kind=small}
Phone Genie for Asterisk v. 2.0 (3KB)
PHP Script Setup
Log into your Asterisk system as root. Copy the Phone Genie for Asterisk PHP script into the main directory for the web server on your Asterisk system. For PBX in a Flash systems, here are the commands:
cd /var/www/html wget http://nerdvittles.com/trixbox123/phonegenie.zip unzip phonegenie.zip rm -f phonegenie.zip chown asterisk:asterisk nv-genie.php chmod +x nv-genie.php
Securing Phone Genie for Asterisk
Individuals with web access to Phone Genie for Asterisk can completely control (and destroy!) your Asterisk system. For that reason, it needs a very secure password. While still logged into your Asterisk system as root, edit line 2 of the nv-genie.php script and replace 1234 with a numeric administrator password that only you know: nano -w /var/www/html/nv-genie.php. Do not use non-numeric characters in the password or PHP will change your password to zero which is obviously not secure. Once you have made the change, save the file: Ctrl-X, Y, then Enter. IMPORTANT: Always run Phone Genie on a server positioned behind a hardware-based firewall with no Internet port exposure.
Activating Apache HTTPS Support
Although the risk is remote, HTTP traffic is unencrypted and passwords do traverse the web as plain text. If you want additional security for Phone Genie queries, you may prefer secure Internet web access to Phone Genie. For HTTPS support, log into your server as root and issue the following commands. Once https support is installed, you can access Phone Genie securely by prefixing all commands with https:// instead of http://.
yum -y install mod_ssl shutdown -r now
Application Overview
Phone Genie for Asterisk is run by issuing commands using your favorite web browser. Most cell phone browsers and some VoIP phones can also execute HTTP commands if your phone has browser support. With more to come, four basic Asterisk database manipulation commands are supported. These are a subset of the commands available in the Asterisk Manager API. In addition, version 1.2 adds support for all of the Asterisk CLI commands.
- DBget - Reads data from Asterisk's internal database
- DBput - Writes data to Asterisk's internal database
- DBdel - Deletes records from Asterisk's internal database
- DBshow - Displays all or part of Asterisk's internal database (admin password required)
- CLI - Executes almost any Asterisk CLI command (admin password required)
- SYS - Executes Linux system commands and scripts (admin password required)
Information in Asterisk's internal database is stored in records with the following attributes:
The easiest way to get a handle on this database syntax is to actually view entries which already are stored in the database. Using the IP address of your Asterisk server and your own password, issue the following command with your web browser to retrieve a listing of everything currently in your Asterisk internal database:
http://192.168.0.129/nv-genie.php?action=dbshow&pw=1234
The results will look something like the following:
/AMPUSER/500/cidname : Office /AMPUSER/500/device : 500 /AMPUSER/500/outboundcid : /AMPUSER/500/recording : out=Adhoc|in=Adhoc /AMPUSER/500/voicemail : default /CALLTRACE/500 : FreeDigits /DEVICE/500/dial : SIP/500 /DEVICE/500/type : fixed /DEVICE/500/user : 500
In the first listing above, AMPUSER is the family, 500/cidname is the key and Office is the value. Another syntax is shown with the CALLTRACE entry where CALLTRACE is the family, 500 is the key, and FreeDigits is the value assigned to the key.
Phone Genie Commands and Syntax
The dbput function puts data into or changes data already in the Asterisk database. The dbput syntax for issuing Phone Genie commands using a web browser is shown in the following example which forwards calls to 678-234-5678 from extension 200. Replace the IP address or fully-qualified domain name with the appropriate entry for your server. Substitute the actual extension on your system instead of extension 200. Replace the call forwarding number with the number desired using the dialing format expected by your outbound dialing rules. Replace the password 1234 with the password you assigned on your system above.
http://192.168.0.123/nv-genie.php?action=dbput&family=CF&key=200&value=6782345678&pw=1234
http://asterisk.dyndns.org/nv-genie.php?action=dbput&family=CF&key=200&value=6782345678&pw=1234
The dbget function retrieves information from Asterisk's internal database. The syntax is similar to the entries shown above except no value entry is required. To retrieve the call forwarding settings for extension 200, use a command like one of the following:
http://192.168.0.123/nv-genie.php?action=dbget&family=CF&key=200&pw=1234
http://asterisk.dyndns.org/nv-genie.php?action=dbget&family=CF&key=200&pw=1234
The dbdel function deletes records from Asterisk's internal database. The syntax is almost identical to the dbget entries shown above. No value entry is required. To deactivate call forwarding for extension 200 with freePBX, you simply delete the CF entry for extension 200 in the Asterisk database. Use a command like one of the following:
http://192.168.0.123/nv-genie.php?action=dbdel&family=CF&key=200&pw=1234
http://asterisk.dyndns.org/nv-genie.php?action=dbdel&family=CF&key=200&pw=1234
The dbshow function displays the entire Asterisk database or a subset of it. The admin password is required to execute DBshow commands with Phone Genie. If a family entry is specified, the command retrieves all records in the specified family from the database. If no family entry is specified, the entire database is retrieved. The syntax for both retrieval methods is shown below:
http://192.168.0.123/nv-genie.php?action=dbshow&family=CF&pw=1234
http://asterisk.dyndns.org/nv-genie.php?action=dbshow&pw=1234
The CLI function executes almost any Asterisk CLI command except the shell (!) command. Simply provide the desired CLI command as either a family entry or a command entry in your query. Note that some of the more primitive browsers do not permit spaces in an HTML request. %20 can be substituted for spaces in CLI commands. The admin password is required to execute any CLI command with Phone Genie.
http://192.168.0.123/nv-genie.php?action=CLI&family=help&pw=1234
http://asterisk.dyndns.org/nv-genie.php?action=cli&command=show applications&pw=1234
The SYS function executes Linux system commands and shell scripts. It's basically the same functionality provided by the CLI shell (!) command. Simply provide the desired SYS command or script name as either a family entry or a command entry in your query. The SYS command could be used for virtually anything: kick off a backup script, review a system log, restart Asterisk (amportal restart), or anything else you could do while logged into your server as user asterisk in the case of PBX in a Flash, trixbox and Asterisk@Home systems. Note that some of the more primitive browsers do not permit spaces in an HTML request. %20 can be substituted for spaces in SYS commands. The admin password is required to execute any SYS command with Phone Genie.
http://192.168.0.123/nv-genie.php?action=SYS&family=ls -all&pw=1234
http://asterisk.dyndns.org/nv-genie.php?action=sys&command=date&pw=1234
Using Phone Genie for Asterisk with freePBX
Because freePBX and more recent versions of the Asterisk Management Portal (AMP) utilize Asterisk's internal database to control many Asterisk PBX functions, you can use the above commands to query and configure extensions on your Asterisk system for call forwarding, call waiting, call tracing, and do not disturb. In Version 1 of Phone Genie, we chose to implement freePBX support first because it provides enhanced control of your PBX out of the box. Shown below are sample commands to execute many freePBX functions using Phone Genie:
Dialcode: *72
Phone Genie: http://192.168.0.123/nv-genie.php?action=dbput&family=CF&key=200&value=6782345678&pw=1234
Dialcode: *73
Phone Genie: http://192.168.0.123/nv-genie.php?action=dbdel&family=CF&key=200&pw=1234
Dialcode: *90
Phone Genie: http://192.168.0.123/nv-genie.php?action=dbput&family=CFB&key=200&value=6782345678&pw=1234
Dialcode: *91
Phone Genie: http://192.168.0.123/nv-genie.php?action=dbdel&family=CFB&key=200&pw=1234
Dialcode: *52
Phone Genie: http://192.168.0.123/nv-genie.php?action=dbput&family=CFU&key=200&value=6782345678&pw=1234
Dialcode: *53
Phone Genie: http://192.168.0.123/nv-genie.php?action=dbdel&family=CFU&key=200&pw=1234
Dialcode: *69
Phone Genie: http://192.168.0.123/nv-genie.php?action=dbget&family=CALLTRACE&key=200&pw=1234
Dialcode: *70
Phone Genie: http://192.168.0.123/nv-genie.php?action=dbput&family=CW&key=200&value=ENABLED&pw=1234
Dialcode: *71
Phone Genie: http://192.168.0.123/nv-genie.php?action=dbdel&family=CW&key=200&pw=1234
Dialcode: *78
Phone Genie: http://192.168.0.123/nv-genie.php?action=dbput&family=DND&key=200&value=YES&pw=1234
Dialcode: *79
Phone Genie: http://192.168.0.123/nv-genie.php?action=dbdel&family=DND&key=200&pw=1234
The Power of the Browser
The hidden beauty of Phone Genie lies in its simplicity and ease of use with virtually any web browser. The browser can even be character-based. Most cell phone browsers and some VoIP phones are capable of issuing appropriate commands to Phone Genie. Once the correct command is issued, it's a simple matter to save the command as a Favorite with most web browsers. Then subsequent calls to the same function can be executed with a single click. This is especially handy, for example, if you want to save Favorites to transfer and cancel transfers of calls to your cellphone.
Configuring Extension Passwords for Phone Genie
For individual use, the original Phone Genie administrator password provided ample security. However, in the business environment particularly for those wishing to deploy PhoneGenie for use on individual employee's cell phones or VoIP phones supporting web services, the single admin password was less than optimal because it gave everyone complete access and control over the Asterisk Manager API. In short, it was equivalent to giving every employee the root password to your Asterisk server. One disgruntled employee and your entire phone system becomes a boat anchor. So version 1.1 now supports individual passwords for each extension on your Asterisk system in addition to an admin password with complete access.
Setting up Extension Passwords is easy. The passwords are actually stored in the Asterisk database using the family name of PW with the extension number being the actual key for each record. The value is the password for the given extension. To create these entries, use the admin password for your Phone Genie system instead of 1234 shown below. Then issue commands like the following. Here is the syntax for setting a password of 3456 for extension 200:
http://192.168.0.123/nv-genie.php?action=dbput&family=PW&key=200&value=3456&pw=1234
http://asterisk.dyndns.org/nv-genie.php?action=dbput&family=PWF&key=200&value=3456&pw=1234
The syntax for Phone Genie web access using the extension passwords remains identical except individual employees now are issued a customized password that only works for settings pertaining to their individual extensions. Stated another way, using an extension password, a user can only access data in the Asterisk database pertaining to the extension associated with that password. No access to dbshow or CLI is available using an extension password. You must use the admin password to execute these commands.
| Nerd Vittles Original Article (2/28/2007): Introducing Nerd Vittles Phone Genie for Asterisk |
| Be Sure To Check Out the Latest (12/21/2009): Introducing Phone Genie for Asterisk (Email Edition) |