Getting ZM to call you using Asterisk - Micro Howto
Posted: Sun Apr 02, 2006 12:14 pm
Zoneminder and Asterisk
Micro Howto
02 April 2006
Author: yoonix
----------------------------------
Quick and Dirty:
First I'm not going into the details of setting up Zoneminder. Nor am I going into the details of downloading Asterisk sources, and compiling Asterisk.
The setup I'm describing is a single Linux box (We used FC3 with all yum updates) with Zoneminder installed and configured with at least one local camera setup for motion detection. After this camera is configured in Zoneminder, and you have your zones performing where you are satisfied with the ratio of false/true alarms, then download the Asterisk sources and install.
The particular FC3 boxes we setup don't have any telephony interface devices installed. For our purposes we didn't need them on the ZM/Asterisk box.
I'll explain.
My organization is headquartered in two offices in the US. These offices contain our Network Ops Center and Security Center. The organization also has small data centers located in 30 or so countries around the world. Some of these data centers are very small, and we tend to do most admin (on the smaller centers) remotely. We were required to place some active security in the smaller centers where no permanent company staff was located. We needed to be 'alerted' anytime someone was in the smaller centers, (unscheduled).
Both NOCs in the US have large VoIP 'hubs' running for the most part Asterisk. We have PSTN gateways, SMS gateways, Email, etc... Additionally we also have routed VPN connections from the NOC to all remote data centers.
In a practical sense, when someone enters a remote data center, ZM detects the motion. A ZM filter runs a script which causes the locally installed Asterisk PBX to 'Call' a predefined extension on one of the VoIP gateways in the NOC. Once the extension in the NOC 'answers", it places another call to a cell phone, pager service, SMS service, whatever...
So now we have a VoIP connection from the ZM box in a remote data center to an Admin's cell phone in the US. Once this is established, the Asterisk instance on the ZM box 'plays' a pre-recorded message notifying the Admin of the ZM alarm.
The Admin can then login to the ZM box through the VPN, or check his email for the standard ZM jpg or mpg email alerts, and deal with the situation.
This has proven <very> effective, with only 3 false alarms in the last six months. One 'false' alarm was caused when a light bulb burned out. The other two seemed to be caused by some sort of RF leaking into the video cables and causing the image to 'shimmer', thus triggering ZM.
---------------------------------
How it works:
For obvious reasons I'm not going to show our actual scripts and configs. So what I have here are the basic scripts and conf files needed to make one ZM filter 'talk' to Asterisk and place a call to a remote PBX. If you use a distro other than FC3, YMMV. Script security is an excercise for the reader.
These are the basics, so if you have nothing better to do - flame away!
First the script:
It is a bash script named 'testcall'
This script is located in /var/www/cgi-bin/ and must be executeable by apache.
///----SNIP----///
#!/bin/bash ## Standard Bash Declaration
cd /var/www/cgi-bin/ ## Make sure we know where we are in the file system
cp alarm.call /var/www/html/events/test.call ## Copy the dot call file Apache can get to it
chmod 777 /var/www/html/events/test.call ## Change permissions on the copy
mv /var/www/html/events/test.call /var/spool/asterisk/outgoing/ ## Move the copy to Asterisk's outgoing call spool
///----SNIP----///
Discussion of testcall:
Line one - Self Explanitory
Line two - Starting point in the filesystem
Line three - Copy a pre-defined Asterisk 'dot call' file to another location readable by Apache. The original 'dot call file is located in /var/www/cgi-bin/ and should NOT be executeable.
Line four - Make the copy of the 'dot call' file world readable/writeable. (Don't worry, this file is going to the electron dust-bin in milliseconds.)
Line five - 'MOVE' the 777'd 'dot call' file to Asterisk's outgoing call spool. ***DO NOT COPY IT!*** Asterisk is VERY aggressive in reading the outgoing call spool. Copying the file requires too much system time to write the copy to the spool. It is likley Asterisk will try to 'grab' the dot call file before the file is completely written and this causes problems. Executing a move (mv) simply changes the inode of the file to indicate it is now in Asterisk's outgoing call spool.
Now Asterisk reads the dot call file, executes the call and erases the file from the spool.
Next - The Asterisk 'dot call' file.
It is a file named 'alarm.call'
It is located in /var/www/cgi-bin/
It is readable by apache, and it belongs to the apache group.
///----SNIP----///
Channel: IAX2/username:password@XXX.XXX.XXX.XXX/18005551212
Callerid: Alarm
MaxRetries: 5
RetryTime: 300
WaitTime: 45
Context: default
Extension: 5555
Priority: 1
///----SNIP----///
Discussion of alarm.call
Line 1 - 'Channel:' is the extension you wish to call on the REMOTE PBX.
IAX2 = The native Asterisk protocol for Inter-Axterisk-eXchange calls. Use it rather than SIP. It is more tolerant of NAT.
/ = field separtor
username:password@XXX.XXX.XXX.XXX = The IAX2 URL of an account on a remote Asterisk PBX. This account MUST exist on the remote PBX, and is defined in the /etc/asterisk/iax.conf file. The address of the remote PBX can be in dotted decimal or a resolveable FQDN.
/ = field separtor
18005551212 = The PSTN telephone number or Extension you want the remote PBX to call. This must be a valid number on the remote PBX, and is defined in /etc/asterisk/extensions.conf file.
Line 2 - 'Callerid:' is the callerid you want your ZM box to pass to the remote PBX
Line 3 - 'MaxRetries:' How many times (plus the initial try) to try to place the call before giving up.
Line 4 - 'RetryTime:' How many seconds between retrys.
Line 5 - 'WaitTime:' How mant seconds to wait for an answer, once the remote extension starts ringing.
Line 6 - 'Context:' The local (ZM box) Asterisk context where the extension containing the message is located.
Line 7 - 'Extension:' The local (ZM) Asterisk extension where the message is defined.
Line 8 - 'Priority:' The priority (or step) in the extension to begin.
Again, it is assumed that you know how to setup a basic ZM install, and have some experience with Asterisk. For more details on Asterisk 'dot call' files go here -> http://www.voip-info.org/tiki-index.php ... o-dial+out
Last - The extension that contains the message.
This extension is defined in the /etc/asterisk/extensions.conf file located on the local Zoneminder box, not the remote PBX!
First, this example is VERY basic. Just enough to demonstrate the method. Asterisk uses 8khz GSM audio files by default. Creating your owm GSM files for Asterisk is trivial using Audacity (audacity.sourceforge.net) and sox (sox.sourceforge.net).
READ THIS!
This is a one extension context, and is not the complete '/etc/asterisk/extensions.conf file. It is just ONE context, containing ONE extension!
The context is 'default' (line 6 of the dot call file)
The extension is '5555' (line 7 of the dot call file)
///----SNIP----///
[default]
;
exten => 5555,1,Answer
exten => 5555,n,Wait(10)
exten => 5555,n,Background(alerttone)
exten => 5555,n,Background(ha/intruder)
exten => 5555,n,Background(ha/alarm)
exten => 5555,n,Wait(2)
exten => 5555,n,Background(ha/intruder)
exten => 5555,n,Wait(2)
exten => 5555,n,Background(ha/living-room)
exten => 5555,n,Background(ha/intruder)
exten => 5555,n,Background(ha/alarm)
exten => 5555,n,Wait(2)
exten => 5555,n,Background(ha/intruder)
exten => 5555,n,Wait(2)
exten => 5555,n,Background(phonetic/alpha)
exten => 5555,n,Background(phonetic/lima)
exten => 5555,n,Background(phonetic/alpha)
exten => 5555,n,Background(phonetic/romeo)
exten => 5555,n,Background(phonetic/mike)
exten => 5555,n,Background(alerttone)
exten => 5555,n,Hangup
;
///----SNIP----///
For those of you familiar with Asterisk this should be fairly simple to modify for you own needs. For those of you who are just getting into Asterisk, check out the latest (and greatest) Asterisk book here ---> www.oreilly.com/catalog/asterisk/
It is also available for download as a pdf.
Cheers,
yoonix
Micro Howto
02 April 2006
Author: yoonix
----------------------------------
Quick and Dirty:
First I'm not going into the details of setting up Zoneminder. Nor am I going into the details of downloading Asterisk sources, and compiling Asterisk.
The setup I'm describing is a single Linux box (We used FC3 with all yum updates) with Zoneminder installed and configured with at least one local camera setup for motion detection. After this camera is configured in Zoneminder, and you have your zones performing where you are satisfied with the ratio of false/true alarms, then download the Asterisk sources and install.
The particular FC3 boxes we setup don't have any telephony interface devices installed. For our purposes we didn't need them on the ZM/Asterisk box.
I'll explain.
My organization is headquartered in two offices in the US. These offices contain our Network Ops Center and Security Center. The organization also has small data centers located in 30 or so countries around the world. Some of these data centers are very small, and we tend to do most admin (on the smaller centers) remotely. We were required to place some active security in the smaller centers where no permanent company staff was located. We needed to be 'alerted' anytime someone was in the smaller centers, (unscheduled).
Both NOCs in the US have large VoIP 'hubs' running for the most part Asterisk. We have PSTN gateways, SMS gateways, Email, etc... Additionally we also have routed VPN connections from the NOC to all remote data centers.
In a practical sense, when someone enters a remote data center, ZM detects the motion. A ZM filter runs a script which causes the locally installed Asterisk PBX to 'Call' a predefined extension on one of the VoIP gateways in the NOC. Once the extension in the NOC 'answers", it places another call to a cell phone, pager service, SMS service, whatever...
So now we have a VoIP connection from the ZM box in a remote data center to an Admin's cell phone in the US. Once this is established, the Asterisk instance on the ZM box 'plays' a pre-recorded message notifying the Admin of the ZM alarm.
The Admin can then login to the ZM box through the VPN, or check his email for the standard ZM jpg or mpg email alerts, and deal with the situation.
This has proven <very> effective, with only 3 false alarms in the last six months. One 'false' alarm was caused when a light bulb burned out. The other two seemed to be caused by some sort of RF leaking into the video cables and causing the image to 'shimmer', thus triggering ZM.
---------------------------------
How it works:
For obvious reasons I'm not going to show our actual scripts and configs. So what I have here are the basic scripts and conf files needed to make one ZM filter 'talk' to Asterisk and place a call to a remote PBX. If you use a distro other than FC3, YMMV. Script security is an excercise for the reader.
These are the basics, so if you have nothing better to do - flame away!
First the script:
It is a bash script named 'testcall'
This script is located in /var/www/cgi-bin/ and must be executeable by apache.
///----SNIP----///
#!/bin/bash ## Standard Bash Declaration
cd /var/www/cgi-bin/ ## Make sure we know where we are in the file system
cp alarm.call /var/www/html/events/test.call ## Copy the dot call file Apache can get to it
chmod 777 /var/www/html/events/test.call ## Change permissions on the copy
mv /var/www/html/events/test.call /var/spool/asterisk/outgoing/ ## Move the copy to Asterisk's outgoing call spool
///----SNIP----///
Discussion of testcall:
Line one - Self Explanitory
Line two - Starting point in the filesystem
Line three - Copy a pre-defined Asterisk 'dot call' file to another location readable by Apache. The original 'dot call file is located in /var/www/cgi-bin/ and should NOT be executeable.
Line four - Make the copy of the 'dot call' file world readable/writeable. (Don't worry, this file is going to the electron dust-bin in milliseconds.)
Line five - 'MOVE' the 777'd 'dot call' file to Asterisk's outgoing call spool. ***DO NOT COPY IT!*** Asterisk is VERY aggressive in reading the outgoing call spool. Copying the file requires too much system time to write the copy to the spool. It is likley Asterisk will try to 'grab' the dot call file before the file is completely written and this causes problems. Executing a move (mv) simply changes the inode of the file to indicate it is now in Asterisk's outgoing call spool.
Now Asterisk reads the dot call file, executes the call and erases the file from the spool.
Next - The Asterisk 'dot call' file.
It is a file named 'alarm.call'
It is located in /var/www/cgi-bin/
It is readable by apache, and it belongs to the apache group.
///----SNIP----///
Channel: IAX2/username:password@XXX.XXX.XXX.XXX/18005551212
Callerid: Alarm
MaxRetries: 5
RetryTime: 300
WaitTime: 45
Context: default
Extension: 5555
Priority: 1
///----SNIP----///
Discussion of alarm.call
Line 1 - 'Channel:' is the extension you wish to call on the REMOTE PBX.
IAX2 = The native Asterisk protocol for Inter-Axterisk-eXchange calls. Use it rather than SIP. It is more tolerant of NAT.
/ = field separtor
username:password@XXX.XXX.XXX.XXX = The IAX2 URL of an account on a remote Asterisk PBX. This account MUST exist on the remote PBX, and is defined in the /etc/asterisk/iax.conf file. The address of the remote PBX can be in dotted decimal or a resolveable FQDN.
/ = field separtor
18005551212 = The PSTN telephone number or Extension you want the remote PBX to call. This must be a valid number on the remote PBX, and is defined in /etc/asterisk/extensions.conf file.
Line 2 - 'Callerid:' is the callerid you want your ZM box to pass to the remote PBX
Line 3 - 'MaxRetries:' How many times (plus the initial try) to try to place the call before giving up.
Line 4 - 'RetryTime:' How many seconds between retrys.
Line 5 - 'WaitTime:' How mant seconds to wait for an answer, once the remote extension starts ringing.
Line 6 - 'Context:' The local (ZM box) Asterisk context where the extension containing the message is located.
Line 7 - 'Extension:' The local (ZM) Asterisk extension where the message is defined.
Line 8 - 'Priority:' The priority (or step) in the extension to begin.
Again, it is assumed that you know how to setup a basic ZM install, and have some experience with Asterisk. For more details on Asterisk 'dot call' files go here -> http://www.voip-info.org/tiki-index.php ... o-dial+out
Last - The extension that contains the message.
This extension is defined in the /etc/asterisk/extensions.conf file located on the local Zoneminder box, not the remote PBX!
First, this example is VERY basic. Just enough to demonstrate the method. Asterisk uses 8khz GSM audio files by default. Creating your owm GSM files for Asterisk is trivial using Audacity (audacity.sourceforge.net) and sox (sox.sourceforge.net).
READ THIS!
This is a one extension context, and is not the complete '/etc/asterisk/extensions.conf file. It is just ONE context, containing ONE extension!
The context is 'default' (line 6 of the dot call file)
The extension is '5555' (line 7 of the dot call file)
///----SNIP----///
[default]
;
exten => 5555,1,Answer
exten => 5555,n,Wait(10)
exten => 5555,n,Background(alerttone)
exten => 5555,n,Background(ha/intruder)
exten => 5555,n,Background(ha/alarm)
exten => 5555,n,Wait(2)
exten => 5555,n,Background(ha/intruder)
exten => 5555,n,Wait(2)
exten => 5555,n,Background(ha/living-room)
exten => 5555,n,Background(ha/intruder)
exten => 5555,n,Background(ha/alarm)
exten => 5555,n,Wait(2)
exten => 5555,n,Background(ha/intruder)
exten => 5555,n,Wait(2)
exten => 5555,n,Background(phonetic/alpha)
exten => 5555,n,Background(phonetic/lima)
exten => 5555,n,Background(phonetic/alpha)
exten => 5555,n,Background(phonetic/romeo)
exten => 5555,n,Background(phonetic/mike)
exten => 5555,n,Background(alerttone)
exten => 5555,n,Hangup
;
///----SNIP----///
For those of you familiar with Asterisk this should be fairly simple to modify for you own needs. For those of you who are just getting into Asterisk, check out the latest (and greatest) Asterisk book here ---> www.oreilly.com/catalog/asterisk/
It is also available for download as a pdf.
Cheers,
yoonix