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

 

Important
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:

Pros:

  • 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.

Cons:

  • 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.

#!/usr/bin/perl
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+)$/ ) {
    exit;
}

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:

#!/usr/bin/perl
use strict;
use warnings;
my ($prev, @mac, @ip);
# Change the 192.168.0.0/24 in the following line to reflect the scope of your local network, if necessary
my @nmap = `nmap -sP 192.168.0.0/24|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]"`;
    }
    $prev=$_;
}

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,192.168.0.123,GrowlPassWord,525)

You will need to use this:

exten => ****525,1,AGI(notifysend.agi,username,192.168.0.123,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 192.168.0.123. 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@192.168.0.123

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,192.168.0.123,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,192.168.0.123,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.

Why your brand new router may cause your VoIP to stop working

 

Important
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.
I quote directly from Voip-Info.org:

Many of today’s commercial routers implement SIP ALG (Application-level gateway), coming with this feature enabled by default. While ALG could help in solving NAT related problems, the fact is that many routers’ ALG implementations are wrong and break SIP.

The article goes on to explain why the implementation is broken, and how to disable it in several brands of routers.  Certain VoIP adapter manufacturers also recommend disabling this feature if you are having problems with SIP registration, not being able to receive a call or one-way audio.  But note that this issue can affect any type of SIP-based communications, regardless of hardware or software used.

EDIT (May, 2018): For information on another issue that may cause problems when you switch routers, see this DSLReports thread: SIP registration times.

Link: Interesting security technique for Asterisk and FreePBX users (may work with other SIP-based PBX’s also)

 

Important
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 article was originally posted in November, 2010.

NOTE: For some reason WordPress absolutely hates it when I try to edit this post, and turns links and other things into piles of steaming poo.  If things don’t look right here please e-mail me or leave a comment and I’ll check it out.  WordPress, I KNOW how I want my articles to look, why can’t you just leave them alone?

One problem faced by some SIP-based VoIP PBX administrators is the issue of security when you have external extensions (that is, extensions located anywhere in the world that’s not a part of your local network). You want to allow those extensions (the ones you’ve authorized) to connect to your system, but you prefer to keep everyone else out, and preferably not even tip them off that there’s a PBX there. The idea is, if the bad guys that would like to break into PBX’s don’t even realize that there is a PBX at your IP address, they won’t waste any time trying to crack into your system.

There have been other suggestions for how to handle this but many of them require your users to take some additional action(s) that they would not normally have to take, and users hate having to lift a finger to do anything to enhance their security. Which brings us to a rather clever technique that doesn’t require user to do anything other than use their phones as they normally would. It might be a tiny bit of a pain to set up initially, but the results may be worth it. I would call this medium level security because if someone is sniffing your packets, this alone may not keep them out, but most of the lowlifes that try to break into PBX’s don’t actually have sufficient access to sniff your packet stream (and also, they’d have to know the exact technique you’re using to be able to crack this). So without further ado…

Secure your VoIP server with the SunshineNetworks knock

(As of October 24, 2012, the above link appears to be DEAD — see the edit at the end of this article)

Note that while the article recommends changing the SIP port to something other than 5060, their basic technique (the “knock”) should still work even if you feel you need to stay on 5060. My only fear about changing the SIP port would be the possibility of losing communications with VoIP providers and with other systems I legitimately send/receive voice traffic to/from. They’re probably going to keep using 5060 even if I don’t. EDIT: My concern here may be unfounded — note the comment below from Alex of Sunshine Networks, who said that “changing the SIP port is quite safe. Your SIP server will send this SIP port along in it’s first SIP invite registration to the VoIP provider. So unless your VoIP provider is actively blocking out anything else than port 5060, it should work fine. We use this technique with 3 different major SIP providers in Australia and never had problems. So far we haven’t seen any unintended consequences.”

I haven’t personally tested this, so if you do, please consider leaving a comment to let me know how it worked for you. The two things I wonder are, do these rules survive a reboot, and can you have more than one secret phrase that would let people in (in case you want to use a different one for each external extension)? EDIT: Those questions are also addressed in Alex’s comment below. Also, those of you running PBX in a Flash should take note of Ward Mundy’s comment about changing an entry in /etc/sysconfig/iptables in this thread. In that same thread, there appears a method to view the “knock” each extension is currently sending — just do “sip debug” from the Asterisk CLI for an hour or so (long enough for all your endpoints to register, after which you can use “sip no debug” to turn it off), then run this at the Linux command prompt (not from the CLI!):

grep "From: " /var/log/asterisk/full|cut -f1 --delimiter=; | sort -u

For each of your remote extensions, you’ll see a line that looks something like this:

From: The Knock <sip:234@nn.nn.nn.nn>

“The Knock” may or may not be enclosed in quotation marks, but it apparently doesn’t matter (you don’t include them in the iptables rules). If you haven’t used a specific “knock”, it could be the actual user’s name, if you set that up when you first set up the endpoint. Anyway, I’d suggest running this BEFORE you actually implement the iptables rules, so you know ahead of time what each endpoint is sending.

EDIT (Added January 8, 2012): I am now using a slight variation on this technique on one of the systems I administer. Without going into too many specifics, I will just note that some SIP devices and VoIP adapters actually already send a unique string that you can use as a “knock” – you do not have to configure a new one, you just need to find out what the device is already sending and use that. For example, let’s say you have an VoIP device connecting to your Asterisk server as extension 234. All you have to do is go to the Asterisk CLI (NOT the Linux command prompt) and enter this:

sip set debug peer 234

(Replace 234 with the actual extension number). Now, assuming that the device is connecting to your server, you will start to see SIP packets scroll across your screen. Within a few minutes you should see one like this (IP addresses have been xx’ed out):

<--- SIP read from UDP:xx.xx.xx.xx:5061 --->

REGISTER sip:xx.xx.xx.xx:5060 SIP/2.0
Call-ID: e10700c2@xx.xx.xx.xx
Content-Length: 0
CSeq: 56790 REGISTER
From: <sip:234@xx.xx.xx.xx>;tag=SP8f427e45f1e19cb24
Max-Forwards: 70
To: <sip:234@xx.xx.xx.xx>
Via: SIP/2.0/UDP xx.xx.xx.xx:5061;branch=z4b9hGK-4f0473a8;rport
Authorization: DIGEST algorithm=MD5,nonce=”37cd169d”,realm=”asterisk”,response=”a726bfed5db321a7bc967b997b5157c2″,uri=”sip:xx.xx.xx.xx:5060″,username=”234″
User-Agent: xxxxxx/xxxxxx-x.x.x.x
Contact: <sip:234@xx.xx.xx.xx:5061>;expires=60;+sip.instance=”<urn:uuid:nnnnnnnn-nnnn-nnnn-nnnn-nnnnnnnnnnnn>”
Allow: ACK,BYE,CANCEL,INFO,INVITE,NOTIFY,OPTIONS,REFER
Supported: replaces

<————->

If you don’t see this you may need to increase the debug level. After you see a packet like this, you can turn off sip debugging:

sip set debug off

The string you are looking for is in the Contact: string above (the nnnnnnnn-nnnn-nnnn-nnnn-nnnnnnnnnnnn is replaced by a unique string). So, where in the instructions for the “knock” they show a sample string such as:

iptables -I door 1 -p udp --dport 5060 -m string --string "mysecretpass" --algo bm -m recent --set --name portisnowopen

I would change the --dport parameter to 5060:5061 (since an VoIP adapter sometimes uses port 5061 for the second service provider — for an device that allows up to fours service providers, use 5060:5063) and the --string parameter to “<urn:uuid:nnnnnnnn-nnnn-nnnn-nnnn-nnnnnnnnnnnn>”, but using the actual string sent by the device, of course. I know the Sunshine Network people recommend using something other than port 5060 but I just can’t bring myself to go quite that far, and even their examples show 5060.

Some other SIP-compliant devices also send unique strings in their REGISTER packets. One that does NOT do so, as far as I am aware, is the venerable Linksys PAP2. And I also do not believe that any of the Sipura line of devices send such a unique string.

Naturally, if an intruder KNOWS you are using that technique, they could try a brute-force attack on the unique string. So I recommend only using this with “uncommon” extension numbers (not 200 or 1000, for example) and with a VERY strong secret/password on the SIP connection. But it is another line of defense against would-be intruders!

EDIT (Added October 24, 2012): The original article, and most of the original site for that matter, seems to have gone offline. While I’m not going to repost the original article here without permission, I will give you a few more details and a couple of excerpts. First, they advised that you change the SIP port to something other than 5060 – they suggested using something in the range 20001 through 49000, though I am not sure why. They uses port 34122 in their examples, and noted that if you are running PBX software that has a “SIP Settings” module, if your find a setting for “Bind Port”, that would be the one to change. Of course if you do this, you then have to change the SIP port on ALL your SIP-based phones and VoIP adapters.

With regard to the “knock” itself, they said this:

Technical information :
… Technically, our knock consists of a secret passphrase which is sent together with the first SIP packet from the phone to the server. SIP packets are text files, very much readable like http packets are. The SIP headers in a REGISTER invite packet have a lot of information, and one of those headers is called the “Display Name”. This display name is used only internally in your Asterisk server and has no other use, so we figured we could fill in anything and the Asterisk functionality would still work fine. We decided to use it as a port knock password.

How does it work :
The Asterisk administrator sets up a simple iptables rule. The iptables rule checks for a secret phrase inside packets sent to the SIP port ( 5060 by default, 34122 after having changed it ). Unless it finds this secret phrase, it will drop the packets to this port. All the remote phone has to do is fill in the “User Name” SIP property on his SIP phone with the secret phrase, and he will be able to connect.

What you then needed to do was to go to into your Asterisk server and from a Linux command prompt, issue the following command:

iptables -N door

Then for EACH “knock” string you want to use, you would do this from the command prompt (note this is only one line, and note that 34122 is the example port and “mykn0ckstr1ng” is an example “knock”):

iptables -I door 1 -p udp –dport 34122 -m string –string “mykn0ckstr1ng” –algo bm -m recent –set –name portisnowopen

If you have anyone that needs to register with your server but cannot send the “knock”, but is at a fixed IP address, you’d add a line like this for each instance (again the port and ip address would probably need to be changed, and note that an entire subnet can be specified as in this example — just leave off the /24 if it’s a single ip address):

iptables -A INPUT -p udp –dport 34122 –source 10.10.1.0/24 -j ACCEPT

Then you would enter these three lines, but again using the correct port rather than 34122. In the first line you see the number 4000 — that is amount of time in seconds that the port will be open, and should be greater than 3600 because that’s the default registration timeout for many sip phones and VoIP adapters. The original article notes that you could use 86400, which is a full day:

iptables -A INPUT -p udp –dport 34122 -m recent –rcheck –seconds 4000 –name portisnowopen -j ACCEPT
iptables -A INPUT -p udp –dport 34122 -j door
iptables -A INPUT -p udp –dport 34122 -j DROP

And finally, to make iptables use these rules, you’d enter:

service iptables save

The original Sunshine Networks article notes that…

This code keeps port 34122 closed ( DROP ) unless someone has opened the door ( door ) in which case they are allowed to pass the door for a little more than 1 hour ( 4000 seconds ). Each time the phone re-registers , the SIP secret pass header is sent, and the door is reopened for 4000 seconds. Since the default SIP reregistration time on many phones is 3600, the 4000 seconds will make sure that as long as the phone is connected to the SIP server, or needs to be connected, the dynamic firewall rule is always active.

Once you have done this, if you configure the Display Name or User Name setting with the “knock” string, it should be able to get through your firewall. Any phone that doesn’t have this string won’t. Of course you can always make the “knock” something that a phone already sends (in a SIP register packet), as noted in the previous edit, and then you don’t have to reconfigure the phone at all. If a phone or device tries to connect without sending the “knock”, the firewall won’t allow it (assuming you haven’t previously created some other rule that allows the traffic to pass) and the connection will fail, or at least that is how it’s supposed to work (I make no guarantees because I didn’t come up with this).

If you enter the command cat /proc/net/ipt_recent/portisnowopen you will get a list of IP addresses that have successfully used the “knock” to connect. Remember that after you implement this, it can take up to an hour for a device to attempt to reconnect.

If anyone ever spots the original article back online, please let me know and I’ll remove this edit. I’d rather you get the information direct from the original source anyway, and the short excerpts I have provided here don’t give the complete overview that the original article provided.

EDIT (February 23, 2014): It appears that there is an archived copy of that original article on the Wayback Machine, although we do not know if it is the most recent edit of that article prior to the site disappearing.

A Perl script to send Caller ID popups from Asterisk to computers running Growl under OS X on a Mac or Growl for Windows

 

Important
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.
Notice
EDIT March, 2014 and August 2020: If you are running OS X Mavericks or later, or any version of MacOS we recommend that you do NOT use the script shown here, but instead send notifications to a XMPP/Jabber account and use either Apple’s Messages app (formerly iChat) or a third party messaging program such as Adium to receive them, since the message will then display in the Notifications Center and you do not need Growl. See How to send various types of notifications on an incoming call in FreePBX for more information. You may also find this thread on the RasPBX forum useful.

What follows will probably not work on ANY currently supported version of MacOS and is left here as a historical reference only.

Quite some time ago, I wrote a post explaining how you could poll a Linksys or Sipura VoIP adapter or phone once per second, and whenever there was an incoming call, generate a notification popup on your computer, if you have the Growl notification service installed.  However, that method doesn’t work if you’re not using a Linksys or Sipura phone or device.

If you are running Asterisk, there’s another way to do it, and that’s to get Asterisk to send the notifications directly. In order for this to work, the computer on which you want to receive the notifications has to be running Growl (under Mac OS X) or Growl for Windows. You must also configure Growl to receive network notifications. I will note here that if you are using a Mac and have never done that before, you may want to make sure that Growl network notifications work before proceeding, because it appears that under OS X, it’s pretty much a crap shoot whether Growl network notifications will work at all, and when they don’t the Growl folks apparently have no clue as to why they don’t. It seems to be a machine-specific thing – on some Macs they work fine, while on others they don’t work at all.

You must have the Perl language installed on your Asterisk server, and you must have the Net::Growl and Asterisk::AGI modules 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, but if you’ve never installed Net::Growl you’ll need to do that first.

Next you want to copy and paste the following Perl script to the filename /var/lib/asterisk/agi-bin/growlsend.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 modified.

#!/usr/bin/perl
use strict;
use warnings;
use Net::Growl;
use Asterisk::AGI;
my $agi = new Asterisk::AGI;
my %input = $agi->ReadParse();
my $num = $input{'callerid'};
my $name = $input{'calleridname'};
my $ext = $input{'extension'};
my $ip = $ARGV[0];

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

unless ( $ip =~ /^(d+).(d+).(d+).(d+)$/ ) {
    exit;
}

open STDOUT, '>/dev/null';
fork and exit;

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

# Define months and weekdays in English

my @months = (
    "January", "February", "March", "April", "May", "June",
    "July", "August", "September", "October", "November", "December"
);
my @weekdays = (
    "Sunday", "Monday", "Tuesday", "Wednesday",
    "Thursday", "Friday", "Saturday"
);

# Construct date/time string

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/;

register(host => "$ip",
    application=>"Incoming Call",
    password=>"$ARGV[1]", );
notify(host => "$ip",
    application=>"Incoming Call",
    title=>"$name",
    description=>"$numnfor $extn$fulldate",
    priority=>1,
    sticky=>'True',
    password=>"$ARGV[1]",
    );

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. It requires a command-line utility caller arp-scan so install that if you need to – I used to use nmap for this but they changed the output format, making it harder to parse, and arp-scan is much faster anyway. Call it /var/lib/asterisk/agi-bin/gshelper.agi and note that there are two references to 192.168.0… within it that you may need to change to reflect the scope of your local network, if your network’s IP addresses don’t start with 192.168.0.:

#!/usr/bin/perl
use strict;
use warnings;
my @mac;
# Change the following lines to reflect the scope of your local network, if necessary
my @arp = `arp-scan --quiet --interface=eth0 192.168.0.0/24`;
foreach (@arp) {
        if (index($_, "192.168.0.") == 0) {
                @mac = split(" ");
                `/usr/sbin/asterisk -rx "database put growlsend \U$mac[1] $mac[0]"`;
        }
}

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 also, 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).  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,192.168.0.123,GrowlPassWord,525)

as shown in the example there, you could use

exten => ****525,1,AGI(growlsend.agi,01:23:45:AB:CD:EF,GrowlPassWord,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 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(growlsend.agi,192.168.0.123,GrowlPassWord,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.

Virtually everything in this article has already been published in one place or another, but I wanted to get it into an article with a relevant title and cut out some of the extraneous explanations and such.  There are links to all the original sources throughout the article, so feel free to follow those if you want more in-depth commentary.

Review of Ring Voltage Booster II™ from Mike Sandman Enterprises

 

Important
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. In order to comply with Federal Trade Commission regulations, I am disclosing that he received a free product sample of the item under review prior to writing the review.

This article was originally published in April, 2008.

Once in a while you run into a situation where someone wants to put a whole bunch of phones on one physical phone pair. This can often happen in a home with many rooms, where every room has been prewired with a phone jack. You start out with a phone in the kitchen or living room, then you want one in the master bedroom, then each of the kids wants one, then you want one in the workshop down in the basement, and so on. Okay, so granted that the above example would probably have been more appropriate 20 years ago (before all the family members started wanting their own cell phones) but you can still run into such situations, both in homes and in small businesses that only have one or two phone lines and a bunch of phones hanging off each line.

In the old days the phone company let you have enough current to ring five standard telephone ringers – 5 REN in telco-speak – and that was five of the old mechanical style ringers with real bells. But nowadays people have started replacing their old wireline lines with newer stuff, like VoIP, and VoIP adapters can be notoriously stingy with ring current. Sometimes when people convert to VoIP, they find that they either have to disconnect some phones (or at least, shut off or disconnect the ringers in those phones) or figure out a way to boost the ring current.

Yet another problem with both certain makes of VoIP adapters, and even with some low-cost telephone switches sold to businesses, is that they don’t produce enough ringing voltage or current to begin with. That might be particularly true if the adapter or switch was designed to standards other than those typically used in the U.S.A. and Canada. In those two countries, phones and phone equipment have always been designed to expect ringing current at approximately 90 volts AC at 20 Hertz (cycles per second), but in some other countries both the ringing voltage and frequency can be quite different, causing equipment designed for the North American standard to not ring properly. Even with a VoIP adapter set to the correct voltage and frequency (not all are; it’s left to the provider to set those parameters on some devices), most VoIP adapters are only rated at 3 REN or less.

Ring Voltage Booster II™

Recently I discovered that Mike Sandman Enterprises has started offering their Ring Voltage Booster II™ – this is the successor to the original Ring Voltage Booster™ that Mike has been selling for several years now, and it looked to me as though it would be just the thing to cure those ringing problems. The Ring Voltage Booster II is used in series with a telephone wire pair entering the premises (or coming out of a VoiP adapter or similar device), and it senses ringing voltage on the line and increases it (actually regenerates it) to the North American standard 90VAC RMS at 20 cycles, and increases ringing current to 7.5 REN.

I wanted to obtain a unit and try it out. I did just that and I thought I’d share the results of my test with you folks, because I was very favorably impressed with the unit. If all you want to know is whether it works as advertised, I would say that based on my experience the answer is an unqualified yes (with one very minor caveat, which I will mention in a moment).

The way I tested it was this. I had a Sipura SPA-2000 VoIP adapter which was connected to the existing phone wiring in a home where the wireline service has recently been disconnected. There was already quite a collection of phone equipment on the line, and I hung a couple of extra items on to load it down. When we got through adding phones we had the following on the line: two modern phones with warble-type ringers, three old 2500-series touch-tone wall phones with real mechanical ringers, one old 2500-series desk set with a real mechanical ringer, and just for fun, one old Western Electric 302 desk set with original ringer and ringing capacitor.

I want everyone reading to pause for a moment and consider that, apart from the fact that this 1940’s-era phone has a rotary dial rather than a touch tone pad, it works great today with the original ringer and capacitor. I’ve had several computer power supplies fail on me in recent years, usually within a year or two of purchase, due to bad capacitors (in a couple cases, exploding capacitors!). For all the bad things about the old Bell System, they sure knew how to build a telephone that would survive just about anything, except the elimination of switching equipment that accepts rotary dial pulses.

Anyway, I had the aforementioned relatively huge load (well above 3 REN, no matter how you count it) hooked up to the Sipura SPA-2000, and I placed a call to it.

And darned if the phones didn’t ring!

I stood there open-mouthed for a moment. Granted the ringing was a bit weak, but all the phones were ringing. I really hadn’t expected that. I could tell I was putting a significant load on the SPA-2000, but not enough to make a very noticeable difference in the quality of ringing. Then it dawned on me – I remember reading somewhere that early Sipura adapters were conservatively rated, but such was not necessarily the case with their successor, the PAP-2 from Linksys. Well, I have one of those, too.

So I disconnected the SPA-2000 and hooked up the newer PAP-2, and placed a call to the PAP-2, and did that make a difference! With the same load as described above, the phones were still ringing, but they were really struggling. The W.E. 302 and one of the new warblers were having the most trouble, both giving only partial rings. The others were ringing very anemically.

I then inserted the Ring Voltage Booster II™ and placed several test calls. The ringing was clear and strong, in fact, each phone rang as if it were the only phone on the line, and the ringing seemed loud and crisp on all phones. Granted this is a bit of a subjective observation since I was, after all, listening to mechanical telephone bells ring, but I grew up with those and I know what they sound like when they are ringing as they should, and these were.

There were two other things I wanted to observe. One was whether the unit interfered in any way with Caller ID. Only one of the phones in this test had a Caller ID display, but it got the correct Caller ID information every time. The other thing was whether it would have any problem with a distinctive ringing signal, and again, I can report that it did not. I happen to have that adapter programmed so that when a particular friend calls it rings with a distinctive ring, since this particular friend seems to have a peculiar form of psychic ability – he always seems to call when I am indisposed (usually in the bathroom or some such thing). So if it rings with his ring, I know I can wait until I’m through with whatever I’m doing, then call him back and share a laugh over yet another occurrence of his weird form of E.S.P. So, in order to test distinctive ringing, I called him and asked him to call me back and let it ring, and once the ringing commenced I checked several phones and all were ringing with the correct distinctive ring cadence (two approximately one-half second rings followed by a one second ring, or at least that’s what it sounds like). Also, I could hear a relay inside the Ring Voltage Booster II™ clicking on and off in time with the distinctive ring patterns.

In fact, the unit worked perfectly, save for one very minor nit: Sometimes, if I picked up a phone during a ring, it would continue to apply ringing voltage for the duration of that ring – in other words, it didn’t seem to always sense that the phone had been picked up and stop the ringing until that ring had ended. In all fairness, I’ve seen this happen before with other types of equipment, including real phone switches (particularly on long loops in rural areas, etc.). What this means is that if you pick up the phone at the very start of a ring and press it to your ear immediately, you could get a pretty loud buzz in the ear for a second or so. I don’t think this will be a major issue for most users, particularly since the unit solves a much greater problem (phones not ringing at all, or ringing very weakly). But for a few people, it might be an annoyance (Edit: One way to reduce this would be to always use a ring pattern that has rings that are one second long or less.  Some VoIP providers will let you set a “distinctive ringing” pattern for each line or each incoming number – if you pick one that has a two or more short rings instead of a single long one, you greatly reduce your chance of hearing the loud buzz when you pick up the phone.  Now that I think of that, I’ll bet that explains why many independent telephone companies used one-second long rings, instead of the two-second rings common in the Bell System).  I don’t know if this was an issue with just the unit I was using, or with all of the units of this model, but it was the only thing I noticed about the unit that wasn’t “perfect” – in every other way, it delivered all you’d expect from such a device.

There are a couple of other pleasant surprises about this unit. Neither the unit itself nor its power supply seem to generate excessive heat in normal standby mode (I did not test an extended ringing cycle lasting several minutes or more, because that would have required shutting off voicemail) – in fact the small “wall wart” was very cool to the touch a couple hours after being plugged in. That’s more than I can say about many of the “wall wart” power supplies i normally use, and as you know, heat is wasted energy, so I’m very happy that Mike is including what appears to be a quality power supply. But what really shocked me was the small size of the unit. Perhaps it’s because I’m an “olde pharte” that equates a ringing generator with, at the very least, a large steel box hanging on the wall in a basement or phone closet, but this thing blew me away because it’s even smaller than any of my VoIP adapters! The longest dimension on it is only about three and a half inches. You’re almost certainly not going to have any problem finding a place to put it.

Hookup couldn’t be simpler, but you must observe that you get the connections right to avoid damaging the unit – in other words, don’t connect the side that’s supposed to be connected to the phones to the incoming phone line, or you will damage the unit. There are only three connections, one for power, one for the incoming line (labeled “line in” – this is the side you’d connect to a VoIP adapter), and one to go to the phones. If you are connecting it to a VoIP adapter you can probably do it in under a minute, once you have it out of the packaging.

In summary, if for any reason you don’t have enough ringing voltage or current on your phone line (or coming out of a VoIP adapter) and you need to boost it, this is the unit that will do it, at least up to 7.5 REN. And if you have a ridiculous number of phones on one line, remember that you can connect some of them before the Ring Voltage Booster II™ (using the original ringing voltage and current from the line or adapter) and the rest after (using the regenerated ringing current from the Ring Voltage Booster II™).

One caveat, this unit does not increase the gain (circuit loss), talk battery, or loop current of a line – if you need to boost loop current then Mike sells a separate Loop Current Booster™ that will do that. But the Ring Voltage Booster II™ basically gets out of the way when the phone isn’t ringing, and should not have any effect whatsoever on transmit or receive volume levels.

Mike Sandman has been selling quality phone equipment for many years now, so I expected this to be a quality unit. Even so, I was very favorably impressed with it. If you have problems related to low ringing voltage or current, get this device. If you have problems related to wrong-frequency ringing current (something that’s putting out ringing current at a frequency other than 20 Hertz), I’m pretty sure this will solve that problem as well, though I did not test that personally. Here is one more link to the page that describes this unit (and some others) and please note this is a plain-vanilla link – I’m not making any commission or anything if you buy one. I hope this review helps someone that’s having a problem getting their phones to ring!

Disclosure:  I have not been and will not be paid anything for writing this article, and I do not receive any commission or other compensation from sales of this item, and the links in this article are not affiliate links.  I did, however, request and receive a complementary Ring Voltage Booster II™ for review purposes (which I was allowed to keep after writing the review, and for that I am most grateful).

Linksys and Sipura adapter users – check your RTP Packet Size and Network Jitter Level

 

Important
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.

Edit: Reader Christopher Woods notes in a comment that the following is also applicable to at least some models of Linksys phones, e.g. SPA942 and SPA962.

Do you use a Linksys or Sipura VoIP adapter? Do the people you are talking to ever complain about your voice breaking up, or missing or dropped syllables, or unexplained clicks or noise?

There is an obscure setting in Linksys/Sipura VoIP adapters that is usually set incorrectly for most applications, at least on a factory-fresh adapter. Go to the SIP tab and check the RTP Packet Size – for most users, it should be set to 0.020 rather than the factory preset of 0.030. If you are running a connection where latency is critical (say you have a cable or satellite box that requires a phone connection to “phone home”, or you are trying to use a FAX machine) then you may even wish to set this to 0.010, which further reduces latency, at the expense of using a bit more bandwidth. In any case, the default 0.030 is not the correct setting when using the most commonly-used codecs. For more discussion of this issue, see this thread at DSLreports.com, which discusses how the RTP Packet Size and Network Jitter Level settings can be tweaked to achieve lower latency, along with the tradeoffs.

Be aware that the RTP Packet Size setting is found under the SIP tab, and that setting is applied to all lines served through that adapter. However, the Network Jitter Level can be set individually for each line, under the Line tabs. One interesting comment in the above-mentioned thread is that if a provider forces you to use a low-bandwidth codec, decreasing the RTP Packet Size may increase the quality of your calls, but again at the expense of increasing bandwidth used.

Changing the RTP Packet Size on one VoIP adapter resolved a few strange issues with audio quality. In this case the adapter was being used to connect to an Asterisk box on the same local network, so bandwidth usage wasn’t an issue. We set the RTP Packet Size to 0.020 and the Network Jitter Level to low, and it made a noticeable difference in the reduction of strange noises and breakups heard by the party on the other end of the conversation. However, changing the Network Jitter Level isn’t as critical as changing the RTP Packet Size, and in fact, changing the Network Jitter Level may be entirely the wrong thing to do on certain types of connections (probably not a good idea if your adapter is connected through a Wireless ISP, for example).

I must thank Paul Timmins for being the first to point out that the Linksys PAP2 has a default packet size of 0.030, which is incompatible with the uLaw (G711u) codec (or at least in violation of the standard). With that lead, I then discovered other articles (including the discussion thread linked above) that said essentially the same thing. So check those adapter settings, folks!

(And by the way, this advice probably does apply to some other makes of VoIP adapters, and even some IP telephones, but since I don’t have any readily available to look at, I can’t say for sure. If you know of any others that need to have a similar setting tweaked, please feel free to add a comment to this post).