Tag: Programming

A Perl script to send Caller ID popups from Asterisk to computers running Notify OSD (such as Ubuntu Linux) or any command-line invoked notification system


This is an edited version of a post that originally appeared on a blog called The Michigan Telephone Blog, which was written by a friend before he decided to stop blogging. It is reposted with his permission. Comments dated before the year 2013 were originally posted to his blog.

This is basically an update to my article, A Perl script to send Caller ID popups from Asterisk to computers running Growl under OS X on a Mac or Growl for Windows, and you should still use that article if you are sending notifications to a computer on your local network that runs Growl or Growl for Windows as the notification system.

I wanted to find a way to send Caller ID popups to a Ubuntu Linux box, and in the process I discovered a different method of sending such notifications.  There are pros and cons to using the new method, so let me explain those first:


  • Can send notifications to any computer that supports command line generated notifications (so it could also be used with Growl, if you can use growlnotify from a command prompt to generate a notification).
  • Can send notifications to any computer that you can SSH into, provided you have it set up to use public/private key authentication rather than password authentication.


  • Notifications typically display a couple of seconds later than under the previous method.  I suspect this is due to the SSH authentication taking a second or two.
  • It’s a little bit more complicated to set this up, though not horribly so.
  • Because this uses SSH and requires that Asterisk be granted permission to establish an SSH connection as the super user (by using sudo), there may be unforeseen security risks.

Read that last point again, and please understand that as with all projects on this site, I offer this for experimental purposes only.  I explicitly do not warrant this method as being 100% secure, nor will I tell you that it could not be exploited to do bad things on your system.  I don’t think it can (and feel free to leave a comment if you think I’m wrong), but I just don’t know that for sure.  So, if you decide to use anything in this article, you agree to assume all risks. If you’re the type that likes to sue other people when something goes wrong, then you do not have permission to use this code.  We’re all experimenters here, so no guarantees!

As with the previous method, you must have the Perl language installed on your Asterisk server, and you must have the Asterisk::AGI module installed (I’m going to assume you know how to install a Perl module from the CPAN repository – if you have Webmin installed, it can be done from within Webmin). Chances are you already have Asterisk::AGI installed, unless you built your Asterisk server “from scratch” and never installed it.

There’s one additional thing you must do on the Asterisk server before this will run, and that’s allow Asterisk to run the ssh command as root. So, add this to your /etc/sudoers file (probably at the very end, but in any case it should be obvious where to add this because it will be in a section where Asterisk is granted similar privileges with regard to other programs):

asterisk ALL = NOPASSWD: /usr/bin/ssh

Next you want to copy and paste the following Perl script to the filename /var/lib/asterisk/agi-bin/notifysend.agi on your Asterisk server (to create a non-existent file, you can use the touch command, and after that you can edit it in Midnight Commander or by using the text editor of your choice). If this code looks somewhat familiar, it’s because it’s adapted from some code that originally appeared in a FreePBX How-To, which I have modified.

use strict;
use warnings;
use Asterisk::AGI;
my $agi = new Asterisk::AGI;
my %input = $agi->ReadParse();

# Next two lines fork the process so Asterisk can get on with handling the call
open STDOUT, '>/dev/null';
fork and exit;

my $num = $input{'callerid'};
my $name = $input{'calleridname'};
my $ext = $input{'extension'};
my $user = $ARGV[0];
my $ip = $ARGV[1];

if ( $ip =~ /^([0-9a-f]{2}(:|$)){6}$/i ) {
    $ip = $agi->database_get('growlsend',uc($ip));

# OMIT this section if you don't want IP address
# checking (e.g. you want to use foo.bar.com)
unless ( $ip =~ /^(d+).(d+).(d+).(d+)$/ ) {

if ( $ARGV[2] ne "" ) {
 $ext = $ARGV[2];

my @months = (
    "January", "February", "March", "April", "May", "June",
    "July", "August", "September", "October", "November", "December"
my @weekdays = (
    "Sunday", "Monday", "Tuesday", "Wednesday",
    "Thursday", "Friday", "Saturday"
my (
    $sec,  $min,  $hour, $mday, $mon,
    $year, $wday, $yday, $isdst
) = localtime(time);
my $ampm = "AM";
if ( $hour > 12 ) {
    $ampm = "PM";
    $hour = ( $hour - 12 );
elsif ( $hour eq 12 ) { $ampm = "PM"; }
elsif ( $hour eq 0 )  { $hour = "12"; }
if ( $min < 10 ) { $min = "0" . $min; }
$year += 1900;
my $fulldate =
"$hour:$min $ampm on $weekdays[$wday], $months[$mon] $mday, $year";

# Next two lines normalize NANP numbers, probably not wanted outside of U.S.A./Canada/other NANP places
$num =~ s/^([2-9])(d{2})([2-9])(d{2})(d{4})$/$1$2-$3$4-$5/;
$num =~ s/^(1)([2-9])(d{2})([2-9])(d{2})(d{4})$/$1-$2$3-$4$5-$6/;

my $cmd = qq(./remotenotify.sh "$name" "$num calling $ext at $fulldate");
$cmd = "sudo ssh $user@$ip '$cmd'";
exec "$cmd";

Also, if you want to be able to specify computers that you wish to send notifications to using MAC addresses rather than IP addresses (in case computers on your network get their addresses via DHCP, and therefore the IP address of the target computer can change from time to time), then you must in addition install the following Perl script (if you have not already done so when using the previous method). Note that if you have a mix of computers on your network and you are using both the new and old methods, you only need to do this once — it works with both methods (hence the reference to “growlsend” in the database and “gshelper” as the name of this script). Call it /var/lib/asterisk/agi-bin/gshelper.agi and note that there is a line within it that you may need to change to reflect the scope of your local network:

use strict;
use warnings;
my ($prev, @mac, @ip);
# Change the in the following line to reflect the scope of your local network, if necessary
my @nmap = `nmap -sP|grep -B 1 MAC`;
foreach (@nmap) {
    if (index($_, "MAC Address:") >= 0) {
        @mac = split(" ");
        @ip = split(" ",$prev);
        `/usr/sbin/asterisk -rx "database put growlsend $mac[2] $ip[1]"`;

Make sure to modify the permissions on both scripts to make them the same as other scripts in that directory (owner and group should be asterisk, and the file should be executable), and if you use the gshelper script, make sure to set up a cron job to run it every so often (I would suggest once per hour, but it’s up to you).

Now go to this page and search for the paragraph starting with, “After you have created that file, check the ownership and permissions” (it’s right under a code block, just a bit more than halfway down the page) and if you are using FreePBX follow the instructions from there on out (if you are not using FreePBX then just read that section of the page so you understand how this works, and in any case ignore the top half of the page, it’s talking about a different notification system entirely). However, note that the syntax used in extensions_custom.conf differs from what is shown there, depending on whether you are specifying an IP address or a MAC address to identify the target computer.

First, if you are specifying the IP address of the target computer, then instead of using this syntax:

exten => ****525,1,AGI(growlsend.agi,,GrowlPassWord,525)

You will need to use this:

exten => ****525,1,AGI(notifysend.agi,username,,525)

Note that username is the account name you use when doing an ssh login into the destination system, and it should also be the desktop user on the system (not root!). Let’s say that the system is currently at IP address In order for this to work, you need to be able to ssh into your Ubuntu box from your Asterisk server, using the following command from the Asterisk server’s command line:

ssh username@

If it asks for a password, then you need to follow the instructions at Stop entering passwords: How to set up ssh public/private key authentication for connections to a remote server, and get it set up so that it will not ask for a password (if you don’t like my article, maybe this one will make it clearer).

It’s probably easiest to configure each computer that is to receive notifications to use a static IP address. But note that if you use the above code and have the gshelper.agi program running as a cron job, then after the first time it has run while the computer to receive the notifications is online you should be able to use a computer’s MAC address instead of the IP address. This only works if you’ve used the modified script on this page, not the one shown in the FreePBX How-To. As an example, instead of

exten => ****525,1,AGI(growlsend.agi,,GrowlPassWord,525)

as shown in the example there, you could use

exten => ****525,1,AGI(notifysend.agi,username,01:23:45:AB:CD:EF,525)

(the above is all one line) where 01:23:45:AB:CD:EF is the MAC address of the computer you want to send the notification to. Once again, just in case you missed it the first time I said it, this won’t work until the gshelper.agi script has been run at least once while the computer to receive the notifications was online. If for some reason it still doesn’t appear to work, run the nmap command (from gshelper.agi) including everything between the two backticks (`) directly from a Linux command prompt and see if it’s finding the computer (depending on the size of your network, it might be several seconds before you see any output, which is why I don’t try to run this in real time while a call is coming in).

If you are NOT running FreePBX, but instead writing your Asterisk dial plans by hand, then you will have to insert a line similar to one of the above examples into your dial plan, except that you don’t need the four asterisks (****) in front of the extension number, and if it’s not the first line in the context, you’ll probably want to use n rather than 1 for the line designator (and, you won’t be putting the line into extensions_custom.conf because you probably don’t have such a file; instead you’ll just put it right in the appropriate section of your dial plan). In other words, something like this (using extension 525 as an example):

exten => 525,n,AGI(notifysend.agi,username,,525)

This line should go before the line that actually connects the call through to extension 525. I do not write Asterisk dial plans by hand, so that’s about all the help I can give you. And if you don’t write your dial plans by hand, but you aren’t using FreePBX, then I’m afraid you’ll have to ask for help in whatever forum you use for advice on the particular software that you do use to generate dial plans, because I can’t tell you how to insert the above line (or something like it) into your dial plan.

Now is where it gets just a bit more complicated than in the original method. If you have followed the above instructions, you’ll be able to send the notifications to the remote system using SSH, but there will be nothing there to receive them. So we have to create a small script on the receiving system to do something with the received notifications. That script will vary depending on the receiving system, but it must be named remotenotify.sh and it must be placed in the destination user’s home directory, and don’t forget to make it executable! Here’s one that will work in most Ubuntu installations that have Notify OSD installed:

export DISPLAY=:0
notify-send --urgency="critical" --icon="phone" "$1" "$2"

Those two lines are all you need. On a different type of system (or if you have multiple displays) you may need to or wish to do something different. For example, as I mentioned above, if the destination system is running Growl then your remotenotify.sh script will need to call growlnotify, but beyond that I wouldn’t know what to use there (EDIT: But if the target system is a Mac that is running OS X, a pretty good guess would probably be that you’d only need one line, something like this:

growlnotify -s -p 1 -a Telephone -m "$2" $1

In this case it should make the notification sticky until dismissed by the user, give it a priority of 1 — the default is 0 — and use the application icon from the “Telephone” application if you have it installed. Instead of -a to specify an application’s icon you could use -I followed by a path to an .icns file that contains an icon you want to use.  Type growlnotify –help to see all the growlnotify options.  Oh, and before you can make an SSH connection to a Mac you have to go into System Preferences | Sharing and turn on Remote Login).

The beauty of this approach is that you can make the remotenotify.sh script as simple or as complicated as you need — you could even make it forward a notification to other devices if you wish, but figuring out how to do that is up to you (if you come up with something good, please leave a comment and tell us about it!).

If you’re running Ubuntu on the target system, here’s a few articles you may wish to use to help you get your notifications to look the way you want them to appear:

Tweak The NotifyOSD Notifications In Ubuntu 10.10 Maverick Meerkat [Patched NotifyOSD PPA Updated]
Get Notifications With A Close Button In Ubuntu
Configurable NotifyOSD Bubbles For Ubuntu 11.04: Move, Close On Click, Change Colors And More

If you want to be able to review missed notifications, you may be able to use this (as a side note, why don’t they have something like this for Growl?):

Never Miss A NotifyOSD Notification With “Recent Notifications” GNOME Applet

The idea behind the shell script that runs on the target system was found in a comment on the following article, which may be of special interest to MythTV users:

Send OSD notification messages to all systems on a network

There are links to other original sources throughout the article, so feel free to follow those if you want more in-depth commentary.

BETA Perl script for Caller ID popups when using Linksys/Sipura devices


This is an edited version of a post that originally appeared on a blog called The Michigan Telephone Blog, which was written by a friend before he decided to stop blogging. It is reposted with his permission. Comments dated before the year 2013 were originally posted to his blog.

Creative Commons License photo credit: bcostin

PLEASE NOTE: This  article has been updated as of December 30, 2008.  This now works with a Mac or Win32 computer (and Linux computers with libnotify installed or readily available, such as those running Ubuntu) and has been updated to reflect that fact. Also, please note that previous versions may have failed on devices/phones with more than two lines – this is (hopefully) fixed as of version 0.7.

If all of the following are true:

You have a Macintosh computer with OS X installed, or a PC with any 32-bit version of Windows installed (basically Windows ’98 through XP), or any version of Linux with libnotify installed

Growl icon
Image via Wikipedia

You have Growl (if you have a Mac) or Snarl (if you have a PC) notifications installed (EDIT: There is now a version of Growl for Windows but at the moment I only have an experimental version of the script for that – see bottom of this page for more information.  It MIGHT work with 32-bit OR 64-bit Windows 7 – feel free to test it).

You have a Linksys or Sipura VoIP adapter on your local subnet or home network and receive calls over it

You would like to see Growl, Snarl or libnotify popups on your computer when a call comes in, showing the caller’s name and number, along with the line that the call came in on and the time and date the call arrived (in case you are out when the call comes in)

You have previously run Perl scripts on your computer, OR are reasonably good at following instructions and problem-solving

AND you are willing to run a script that comes with NO WARRANTY whatsoever (if it breaks, you can keep all the pieces)

Then download this file (now at version 0.92), unzip it and read the Instructions.txt file in the folder appropriate to your computer.

This script is being offered under the GNU General Public License, so if you want to modify it to work on other platforms, you can do that under certain conditions (see the Instructions.txt file for details). Mainly, I’d hope that you’d contribute the modifications back (and please leave a comment on this article if you do that).

I don’t have any kind of regular web page up for this yet, for one thing it’s very rough (very little error-checking) and for another I’m very tired, having spent way too many late nights trying to get this to work. So this post will be more terse than most of my posts, but I think most everything you need to know is in Instructions.txt (and for Mac users, the “How to run at login.rtfd” file) inside the .zip file. Feel free to repost this information to other forums if you think anyone else might be interested.

For those Mac users that wish this were an app: I understand that there is an app called Platypus that allows Perl scripts (and any other types of scripts) to be converted to OS X app bundles. However, what it does not seem to include is any way to specify the command line options, or to load any missing Perl modules. So for now, this script will probably only be usable by those with sufficient knowledge to run a Perl script on their Mac. If I were a bit more knowledgeable, I’d build a preference pane to go in System Preferences, and then have the script read that for its configuration options. But I still have no idea how to make an app install missing Perl modules, particularly when OS X does not come with “make” installed until and unless the Developer Tools are installed (adding something like 3 GB of stuff that is mostly useless to non-developers to your hard drive!).

EDIT: I read somewhere that you can install make without installing the bloated Developer Tools package if you instead install Fink. Then, from a terminal prompt, you can type fink -b install make and supposedly that will do the trick. However, I am told that Fink has not been updated for Snow Leopard, but there is a make package in Rudix that should work with Snow Leopard (mind your paths – Rudix installs make in the /usr/local/bin directory and by default CPAN expects it in /usr/bin, so you may want to adjust the path during CPAN setup, or make a symbolic link in /usr/bin). Since I have not personally tried either of these I have not updated the instructions in the download to reflect this, but if it works you can skip the whole process involved in installing the Developer Tools.

Because this is a Perl script, it lends itself to custom modifications. For example, let’s suppose you have this script running on a Mac, and you are sending Growl notifications to the Mac, but you also have a home theater PC that runs XBMC and/or Boxee, and you’d like to send Caller ID notifications to it as well.  Assuming that Boxee and/or XBMC is configured to allow control via a Web interface, at a fixed IP address and port ( port 8080 in this example), you could add a line such as this to the script (this is all one line; select and copy to get it all if it gets truncated on your display):

eval {get "$displayname%22%2C$phonenum%20calling%20$lineid[$count]%2C15000%2C%2Fhome%2Fusername%2Fphone.png)"};

The above assumes that you have placed the icon file phone.png (shown at right — right click on the icon and save it) in the user home directory on the destination system (the one running XBMC or Boxee), and that you change ‘username’ to the actual name of the user’s home directory. Note that the icon path requires %2F in place of forward slashes (therefore %2Fhome%2Fusername%2Fphone.png really means /home/username/phone.png) Phone icon - right click and copy imageand this refers to the icon directory and filename — if you choose not to use an icon then leave that part out, along with the %2C that comes just before it.  If you are running XBMC or Boxee on the same system that’s running the script then you should be able to replace with localhost or The above line should be inserted just above the comment line “# Make output string in chosen format” near the end of the Perl script. Keep in mind that this won’t work if you don’t enable control via Web server in XBMC or Boxee, and make sure the port number matches the port in your added line.  Depending on the skin you use, this is generally accomplished by going to Settings, then Network (and in Boxee, then Servers). Then check “Allow control of XBMC via HTTP” (in XBMC) or enable the Web server (in Boxee) and verify the port number is correct.

Starting in Version 0.7 there is a minimal logging function, allowing all detected incoming calls (whether answered or not) to be saved to a text file and/or a comma-quote delimited file. I probably could support other simple formats, but don’t even think about asking for anything more complex (like a rather humorous friend of mine who asked for MySQL integration – considering that he knows how little knowledge I have about Perl programming, and that I have even less knowledge about databases, I’m sure he thought it extremely amusing to make that request). The one thing I really don’t like about offering these scripts in Perl is that it requires the user to know how to install modules from CPAN (or an alternative source if using Win32), but I barely know how to do this stuff in Perl and don’t know any other languages (well, except for QBASIC under MSDOS, but that’s even less compatible across platforms than Perl!).

Starting in Version 0.9 you can use a plain-text file of number-name substitutions, so (for example) if calls from a particular number always display a cryptic Caller ID name, you can change them to say “Uncle Bob” (or some other name if Bob’s not your Uncle, or it’s someone else’s number!). Read the sample config file to see the file formats. Note that the plain text file of number-name substitutions is a separate file, not a section of the optional configuration file, and also note that you must enter the numbers exactly as your VoIP provider sends them (in other words, if they send 8005551234 and you use 18005551234 or 800-555-1234 it will NOT match!).

Starting in Version 0.91 you can use a plain-text file of number-path/file substitutions, so (for example) if calls from a particular number are always from Uncle Bob, you can display Uncle Bob’s picture as the icon whenever a call arrives from that number. Read the sample config file for more information. Note that the plain text file of number-path/file substitutions is a separate file, not a section of the optional configuration file, and also note once again that you must enter the numbers exactly as your VoIP provider sends them.

Version 0.92 sets a rather short timeout on page fetches (still much longer than should be necessary to get the data), in an attempt to resolve a problem where very occasionally the script would just go into a coma, not exiting cleanly but still using memory and CPU cycles, without doing anything useful. I have been running this version for over six months now and have yet to see the script go into a coma, as it often seemed to do in previous versions.

(EDIT added September, 2010:) NOTE regarding EXPERIMENTAL version to work with Growl for Windows.  You should still download the main archive to get the instructions and such, but if you’d prefer to use Growl for Windows rather than Snarl, you can try this experimental version of the script. If you do try it, please let me know if it works as expected (and thanks to Andy Singh for his help with getting this working under Windows 7). Please read the Perl source code to find the module requirements (mentioned on or near line 15 of the script) as they differ slightly from the Snarl version.

Recent Posts

Recent Comments




GiottoPress by Enrique Chavez

%d bloggers like this: