Tag Archives: CLI

Almost two years ago, we introduced Phone Genie for Asterisk®. It let you reconfigure your Asterisk system remotely using your favorite web browser. This included the ability to set and adjust call forwarding, call waiting, and Do Not Disturb for any Asterisk extension. In addition, you could enter Asterisk CLI commands and execute a number of Linux system commands, all from the convenience of your web browser. Phone Genie for Asterisk remains one of the all-time favorite downloads of our readers.

Unfortunately, you don't always have access to a web browser when you're away from your Asterisk server. So today we introduce the perfect complement to the original Phone Genie with our new Email Edition. By following this quick tutorial, you can configure your Asterisk server to respond to any Asterisk CLI command which can be sent from almost any email client on the planet. And we'll perform all this magic with less than a dozen lines of bash scripting. Asterisk CLI commands have almost limitless possibilities. Use Phone Genie to check the status or change the functionality of just about any component on your server.

How It Works. The best way to explain how all of this works is to use a simple example. Let's assume you've left home and forgot to transfer your inbound calls for extension 701 to your cellphone. What we'll do is send a simple email message to a special user account on your Asterisk server that we've set up specifically to handle email directives for your server. Unlike most email addresses, we want this one to be unintuitive so strangers aren't sending messages to your server all the time. Let's assume the address is kxt1498@myserver.dyndns.org for this example. Using any email client, just address a message to that account. For the subject of the message, we'll use the following:

Asterisk: database put CF 701 6781234567

It doesn't really matter whether you include a message with the email. As long as the subject of the email is in the proper form, that's all that matters. The command above activates call forwarding for extension 701 and sends the calls to 6781234567. The command uses standard Asterisk CLI syntax.

On your Asterisk server, we'll have a simple bash script that runs every minute or two to check for new emails in the kxt1498 user's mailbox. If it finds a new message, it will parse the subject line, make certain there is a password match, and then send the command (unaltered) to the Asterisk Command Line Interface for processing. Here's an overview of all the CLI commands. The results of executing the command will be emailed to the address you've configured in the script. This works as both confirmation that your command has been executed and a security alert that your Asterisk system has been accessed using the Email Edition of Phone Genie. In the above example, you would receive an email at the address you've configured in the script with a subject of PhoneGenie. The body of the email would look like this:

Updated database successfully...database put CF 701 6781234567

Prerequisites. This software assumes you are using one of the Asterisk aggregations built on CentOS 5. We've tested it with PBX in a Flash. You'll also need an SMTP server (SendMail or Postfix) that is configured to send and receive emails to and from destinations on the Internet. You do not need a POP3 or IMAP mail server! We've tested this with Asterisk 1.4, but it should work fine with Asterisk 1.6 as well. FreePBX 2.5 or later is required for some functions.

Security Warning. Before we begin, let's pause for a moment to review the enormity of your problems if you do this wrong and to remind you that YOU ARE PROCEEDING AT YOUR OWN RISK. PBX in a Flash in particular is shipped with all outside access to your SMTP server blocked. We've obviously got to remove that layer of security for this software to function properly. But you need to be especially careful with SMTP servers because they can be used to relay SPAM to the entire world if you fiddle with settings that you don't understand. So... DON'T MAKE IMPROVEMENTS THAT AREN'T COVERED HERE UNLESS YOU KNOW WHAT YOU'RE DOING!

This software also gives certain email messages elevated privileges on your Asterisk server so that Asterisk itself can be reconfigured. If you compromise the email account name and password for this application, anybody worldwide can pretty much destroy the functionality of your server. In addition, calls to a certain extension could be rerouted to a very expensive destination on a cruise ship sailing around the world. If your dialplan permitted these calls and you had an account with automatic replenishment from a credit card or bank account, you've got a very expensive problem on your hands. That's one reason that reliable email notification of every Phone Genie transaction is critically important. If you're not getting timely notifications of each Phone Genie transaction, DO NOT USE THIS SOFTWARE until that problem is resolved!

Should you detect that your system has been compromised by receiving an email that indicates a command has been executed on your Asterisk server that you did not initiate, you should immediately disable or remove the script so that no further Phone Genie emails are processed on your server. Be sure to preserve any unprocessed Phone Genie emails for authorities as these may contain important information regarding the source of the emails. These email messages usually are deleted once Phone Genie completes execution of the associated Asterisk commands.

Overview. Here's the drill for today. First, we'll adjust both your hardware- based and IPtables firewalls to allow inbound email delivery to your Asterisk server. Second, we'll remove SendMail from your system and install and configure Postfix to handle the SMTP email chores. This will greatly simplify the security issues in locking down your server from unwanted emails. Depending upon your Internet service provider, installation of Postfix may break outbound email delivery from your server if your provider happens to block outbound traffic on port 25. We'll show you how to fix it. Third, we'll add a new user account on your Asterisk server that will be used exclusively to handle Phone Genie messages. Fourth, you're going to need a fully-qualified domain name for your Asterisk server so that email can be delivered reliably to your server. We'll walk you through getting this set up. Fifth, we'll install and configure the Phone Genie software and run some simple tests to make certain everything is working as it should. Sixth, we'll add the Phone Genie script as a cron job which will be run every couple of minutes to check for incoming Phone Genie emails. Finally, we'll review some of the Asterisk commands that can be executed using the Email Edition of Phone Genie for Asterisk.

Security Design. We've obviously given a great deal of thought to the security issues surrounding this application. The security model we've adopted works like this. First, for an email to get through to your Asterisk server, one and only one email address will work from the Internet. All other inbound email from the Internet will be rejected by Postfix. We strongly suggest you leave it that way. Your email address consists of the special username that we will create on your server plus a (hopefully new) fully-qualified domain name that points to your server. You are well advised to use and keep secret both a non-intuitive and complicated username AND a non-intuitive and complicated, fully-qualified domain name. Only this combination will let the email message through the Postfix filter! Using the correct username and a different FQDN that may also point to your server's correct IP address will nevertheless be rejected by Postfix. The third piece in the security model is the password. If you examine the sample Subject above, you will note that it begins with the word "Asterisk" followed by a colon, a space, and then the Asterisk CLI command. The word "Asterisk" is actually the password, and it can be changed to any password you like. So, if you change your password to FooBaR, then the subject of your message should look like this. Note that the colon followed by a space are also required!

FooBaR: database put CF 701 6781234567

Finally, it should be obvious but... DON'T SEND THESE EMAILS FROM AN UNTRUSTED CLIENT OR A PC IN A PUBLIC PLACE because your email message may get stored in a place that someone else could decipher how to access your server. If you wouldn't leave a $1000 bill beside the computer from which you're sending the email, don't send it! Otherwise, you may lose a good bit more than $1,000. To give you some idea of what's at risk with a compromised system, try sending the following email using your correct email address and password:

FooBaR: help

</sermon>

Firewall Configuration. For purposes of our example today, we're assuming that your Asterisk server is sitting behind a hardware-based firewall/router on a private subnet and that your Asterisk server includes a functioning software-based IPtables Linux firewall. This is the default PBX in a Flash setup that we always recommend. On your hardware-based firewall, you will need to redirect incoming TCP port 25 traffic to TCP port 25 on the private IP address of your Asterisk server. This change often requires a reboot of your firewall/router. Once that change is complete, log into your Asterisk server as root and edit /etc/sysconfig/iptables on PBX in a Flash systems. We need to add a new rule to IPtables which allows incoming TCP port 25 traffic through the firewall. Scroll to the bottom of the file and insert the following lines just above the COMMIT line:

# Allow inbound SMTP traffic on TCP port 25
-A INPUT -p tcp -m tcp --dport 25 -j ACCEPT

Save your additions to the file and then reload IPtables and your network:

service iptables stop
service iptables start
service network restart
service iptables status | grep "tcp dpt:25"

The last command should return an entry from IPtables showing TCP port 25 traffic is now being ACCEPTed into the server. If not, check your entries and repeat the process until this works.

Postfix Installation. Let's continue by removing SendMail from your server and installing Postfix. They both perform the same email functions, but the complexity of SendMail makes the likelihood of a configuration error too risky for us to sleep well. If you understand the intricacies of SendMail and feel comfortable implementing the security model we've described above, by all means, have at it. We'll be happy to share your results with the rest of our user community. In the meantime, here's the Postfix solution. While still logged into your server as root, issue the following commands to uninstall SendMail and install Postfix:

rpm -e --nodeps sendmail
yum -y install postfix

Choosing a Username and FQDN. Before we configure Postfix, you need to decide upon a user account name for your Asterisk server to manage Phone Genie messages. And you also need a fully-qualified domain name which points to the public IP address of your Asterisk server. As mentioned above, we strongly recommend that the username and FQDN be obscure and unguessable. For example, a combination of letters and numbers that don't spell words are good choices. Something like dlrpzh7b3@dhf34.nerdvittles.com will help you sleep well. If you don't have a static IP address and dedicated domain for your server that you can manage, then use an equally obscure FQDN from a provider such as dyndns.org. Something like dhf34.dyndns.org works. You then can configure your Asterisk server to automatically keep your dynamic IP address current. We're going to use these entries as examples below. Obviously, you should choose different entries!

To create the new user account on your server using whatever name you have chosen, here are the commands to issue while still logged into your server as root. Just substitute your chosen username for dlrpzh7b3 in both commands. Be sure to choose a secure password, too.

useradd dlrpzh7b3
passwd dlrpzh7b3

Configuring Postfix. Now let's get Postfix set up for maximum protection. First, move to postfix directory: cd /etc/postfix. Now edit main.cf: nano -w main.cf. Search for the inet_interfaces line in the file: Ctrl-W, inet_interfaces =. Add a hash mark to the beginning of each uncommented inet_interfaces line so that your entries look like this:

#inet_interfaces = $myhostname
#inet_interfaces = $myhostname, localhost
#inet_interfaces = localhost


Next, search for mydestination in the file: Ctrl-W,mydestination =. Comment out each of the lines except the one that looks like this:

mydestination = $myhostname, localhost.$mydomain, localhost


Now add the private IP address of your Asterisk server and your FQDN chosen above to the line so that it looks like this. Don't forget the commas and keep everything on one line.

mydestination = $myhostname, localhost.$mydomain, localhost, 192.168.0.118, dhf34.nerdvittles.com

Finally, move to the last line in the file and make it look like this, all on one line:

smtpd_recipient_restrictions = check_recipient_access hash:/etc/postfix/access, permit_mynetworks, reject_unauth_destination

Save your changes to the file: Ctrl-X, Y, then Enter. Now edit /etc/postfix/access. Move to the very bottom of the file and add two new lines with the following entries using the actual email address and FQDN you chose above instead of the examples. The first line tells Postfix to allow emails addressed to the specified email recipient. The next line tells Postfix to reject all other emails addressed to anyone at this domain. Other domains and public IP addressing are blocked by our mydestination entry above.

dlrpzh7b3@dhf34.nerdvittles.com OK
dhf34.nerdvittles.com REJECT recipient rejected


Save your changes to the file: Ctrl-X, Y, then Enter. Now issue the following two commands:

postmap /etc/postfix/access
service postfix restart

Testing Postfix. Now comes the important part. We need to make sure that outbound emails from your Asterisk server are delivered. And we need to make sure that incoming emails ONLY to the one email address you've designated are received and that all other emails from the Internet are rejected. We can't stress enough how important all three of these tests are. If your Postfix implementation doesn't pass all three, DO NOT PROCEED!

Testing outbound email with Postfix is easy. While logged into your server as root, issue the following command using a destination email address (instead of yourname@gmail.com) where you regularly receive emails:

echo "Hi there" | mail -s Test yourname@gmail.com

Count to 20 and refresh your email's Inbox. If the message is there, you've passed Test #1. If not, check your junk mail folder. If it's still not there, try another email address if you have one. Still no cigar? Then your Internet Service Provider is probably blocking email generated from downstream email servers. For tips on remedying the problem, see this message thread on the PBX in a Flash forums. You might also want to review the Postfix tutorial on dyndns.com. Here's another good tutorial on setting up a Gmail relay using Postfix. Then run the test again until you achieve success.

Testing inbound email to your designated email address is Test #2. Use a web client and send an email message to dlrpzh7b3@dhf34.nerdvittles.com substituting the actual email address you have chosen for your server. Count to 20, log into your server as root and type the following command to retrieve email for user dlrpzh7b3: mail -u dlrpzh7b3. The server should report that you have one new message. Type "d 1" and then "q" to delete the message and quit the mail app. If no email arrives, check the Inbox on your sending client to see if the message bounced and, if so, why. Check your email entries in /etc/postfix/access and /etc/postfix/main.cf for typos and review the steps in Configuring Postfix above. Then repeat the test until you successfully send a message to your designated email address.

Testing inbound email to an unauthorized email address on your Asterisk server is Test #3. For this test, we want to make sure that an email sent to the root account on your server fails. What you'll need for this test is the FQDN that was chosen above. Then, using a mail client, send an email message to root@dhf34.nerdvittles.com using your actual FQDN. Count to 20, log into your server as root, and type: mail. The message you sent should NOT be in the Inbox. Repeat the test by sending a message to root and dlrpzh7b3 @the actual IP address of your Asterisk server. These, too, should both fail. Once you get a passing grade on all three tests, we can move on. The hard part is behind you!

Installing Phone Genie. While logged into your server as root, issue the following commands:

cd /root
wget http://pbxinaflash.net/source/nv/phonegenie.tgz
tar zxvf phonegenie.tgz
rm phonegenie.tgz

Configuring Phone Genie. While still logged into your server as root, edit phonegenie.sh. You will note that there are 3 fields that need to be configured at the top of the file: user, pw, and notify. The user field is the designated user account name that will be used for incoming emails (dlrpzh7b3 in our example). The pw field is the word in every email Subject that precedes the colon, space, and Asterisk CLI command (Asterisk in our example). The notify field is a reliable email address where you regularly receive emails promptly. This is where the results of your Phone Genie email commands will be sent. Choose this email address wisely, as if your bank account depended upon it. It does! Once you have filled in the 3 fields (preserving the quotation marks around each entry), save the file with your changes.

Testing Phone Genie. Now we're ready to try everything out. Using an email client, send an email message to dlrpzh7b3@dhf34.nerdvittles.com (using your actual Phone Genie email name and FQDN). For the Subject, enter the following (substituting the password you created above for Asterisk)... Asterisk: help

After counting to 20, log into your Asterisk server as root and issue the following command:

/root/phonegenie.sh

You should see a display of all of the Asterisk CLI commands and within a minute or so, you should receive an email with the same information at the email address you entered into the notify field in phonegenie.sh in the previous step.

Installing Phone Genie as a Cron Job. Once you have tested several Phone Genie emails manually and you're satisfied that everything is working reliably, you can set up the Phone Genie shell script as a cron job. It should be set to execute every minute or every couple of minutes throughout the day and night. Edit /etc/crontab and insert the command shown below to have the script execute every 2 minutes:

*/2 * * * * root /root/phonegenie.sh > /dev/null

Sample Phone Genie Commands. In addition to all of the traditional Asterisk CLI commands, Phone Genie also supports a number of commands that are specific to FreePBX. These additional commands let you configure call forwarding, call waiting, do not disturb, system speed dials, and blacklist entries on your Asterisk server. For Asterisk CLI command syntax, consult voip-info.org. For FreePBX command syntax, see the listing below. Enjoy!

We wish all of you a very Merry Christmas!

Need help with Asterisk? Visit the PBX in a Flash Forum.
Or Try the New, Free PBX in a Flash Conference Bridge.

whos.amung.us If you're wondering what your fellow man is reading on Nerd Vittles these days, wonder no more. Visit our new whos.amung.us statistical web site and check out what's happening. It's a terrific resource both for us and for you.

Special Thanks to Our Generous Sponsors

FULL DISCLOSURE: ClearlyIP, Skyetel, Vitelity, DigitalOcean, Vultr, VoIP.ms, 3CX, Sangoma, TelecomsXchange and VitalPBX have provided financial support to Nerd Vittles and our open source projects through advertising, referral revenue, and/or merchandise. As an Amazon Associate and Best Buy Affiliate, we also earn from qualifying purchases. We’ve chosen these providers not the other way around. Our decisions are based upon their corporate reputation and the quality of their offerings and pricing. Our recommendations regarding technology are reached without regard to financial compensation except in situations in which comparable products at comparable pricing are available from multiple sources. In this limited case, we support our sponsors because our sponsors support us.

BOGO Bonaza: Enjoy state-of-the-art VoIP service with a $10 credit and half-price SIP service on up to $500 of Skyetel trunking with free number porting when you fund your Skyetel account. No limits on number of simultaneous calls. Quadruple data center redundancy. $25 monthly minimum spend required. Tutorial and sign up details are here.

The lynchpin of Incredible PBX 2020 and beyond is ClearlyIP components which bring management of FreePBX modules and SIP phone integration to a level never before available with any other Asterisk distribution. And now you can configure and reconfigure your new Incredible PBX phones from the convenience of the Incredible PBX GUI.

VitalPBX is perhaps the fastest-growing PBX offering based upon Asterisk with an installed presence in more than 100 countries worldwide. VitalPBX has generously provided a customized White Label version of Incredible PBX tailored for use with all Incredible PBX and VitalPBX custom applications. Follow this link for a free test drive!
 

Special Thanks to Vitelity. Vitelity is now Voyant Communications and has halted new registrations for the time being. Our special thanks to Vitelity for their unwavering financial support over many years and to the many Nerd Vittles readers who continue to enjoy the benefits of their service offerings. We will keep everyone posted on further developments.
 

Some Recent Nerd Vittles Articles of Interest...