Topics...

Introduction

I have a number of xAP interfaces to asterisk. Two of them are presented here. The first, the Asterisk Manager Interface, provides a mechanism for receiving notification of anything that happens within asterisk in real-time via xAP - incoming calls, outgoing calls, even handsets being hungup.

The second provides a mechanism for setting up calls. This can be useful for auto-dialling. A simple outlook macro can be used to create a xAP dialer message, for example, to set up a call between your extension and any other number.

Asterisk Manager Interface

The call manager interface is a simple interface that relays all Asterisk events to the xAP network. It currently does not allow for the remote invocation of Asterisk commands. Using the xAP connector for asterisk, you can determine the state of all extensions, and track all internal, incoming and outgoing call progress in realtime. The xAP messages generated by the connector mirror the asterisk event reports. For full details of all the reports, and more details on the capabilities of the Asterisk Manager Interface, see here: http://www.voip-info.org/wiki/view/Asterisk+manager+API

Command Line Options

xap-asterisk <asterisk user> <asterisk pass> <asterisk server ip> [asterisk server port] [instance name] [network interface] [udp port] [debug level]

 where:
<asterisk user> and <asterisk pass> are the user name and password for the Asterisk Manager Interface connection as configured in /etc/asterisk/manager.conf. If you are using asterisk@home, you can use the pre-configured user “admin” and pass “amp111”.

<asterisk server ip> and [asterisk server port] identify the ip address and port used for the asterisk manager interface connection. If you are running xap-asterisk on the same host as the asterisk server, then specify the loopback interface as the IP address (127.0.0.1). If not specified, the port defaults to 5038.

instance name is the xAP instance name assigned to this asterisk server. The default instance name is server1.

network interface is the network interface used for outgoing xAP messages. On a Linux and Windows PC host these are named eth0, eth1. Under OSX they are named ne0 etc. By default, eth0 is used. On a Windows PC which has multiple adapters installed, even if they are not active, eth0 may not represent the active interface - some experimentation may be required!

udp port is the UDP port xAP broadcasts on. By default xAP uses its officially allocated port, 3639. Using an alternative port can be useful during isolated testing, however. Be aware that the use of ports below 1024 will fail unless the application is run by a user with administrative privileges. The use of ports below 1024 therefore has security implications and is not recommend.

debug level determines the verbosity of the output written to stdout. Verbose output can be useful for debugging unexpected behaviour. By default, the debug level is 0. Increasing levels of detail may be specified, up to a maximum of 4.

Installation Tips

• You can run the connector on the asterisk box itself, or via a remote tcp connection.
• If running on a local box, specify the host <asterisk server ip> as 127.0.0.1, the port as 5038 and ensure that /etc/asterisk/manager.conf reads something similar to:

[general]
enabled = yes
port = 5038
bindaddr = 0.0.0.0

[admin]
secret = amp111
deny=0.0.0.0/0.0.0.0
permit=127.0.0.1/255.255.255.0
read = system,call,log,verbose,command,agent,user
write = system,call,log,verbose,command,agent,user

You should now be able to login as user admin, pass amp111 from the connector. If successful, the login will be reported on the asterisk console, and the connector will generate a virtually continuous stream of asterisk-related event reports.

• If running on a remote host, specify the host parameter <asterisk server ip> as the IP address of the network interface card installed in the asterisk box (e.g. 192.168.0.33) and the port as 5038 and ensure that /etc/asterisk/manager.conf reads something similar to:

[general]
enabled = yes
port = 5038
bindaddr = 0.0.0.0

[admin]
secret = amp111
deny=0.0.0.0/0.0.0.0
permit=192.168.0.33/255.255.255.0
read = system,call,log,verbose,command,agent,user
write = system,call,log,verbose,command,agent,user

You should now be able to login as user admin, pass amp111 from the connector. If successful, the login will be reported on the asterisk console, and the connector will generate a virtually continuous stream of asterisk-related event reports.

• (13Feb06) The connector should now compile correctly under Centos (on which asterisk-at-home is built). In addition to changes to the event manager source code, the fix also required a small change to xAPlib, so please download an updated v.14 of the libraries as well as the manager source and do a “make clean” before rebuilding.
  I know that the connector currently makes a poor job of reporting connection to asterisk. If the incorrect credentials are specified, or the permissions in manager.conf have not been set correctly, the connector may claim to have connected, but will do nothing. The acid test is to watch the asterisk console (asterisk -vvvr or similar) as the connector starts. Successful authentication will be reported as:

== Manager 'admin' logged on from 192.168.0.33

And soon the connector will display relayed events such as:

Relayed asterisk event
xAP-header
{
v=12
hop=1
uid=FF000E00
class=asterisk.event
source=Rocket.asterisk.server1
}
event
{
Event=Registry
Privilege=system,all
Channel=SIP
Domain=voiptalk.org
Status=Registered
}

 

Unfortunately the changes made to ensure a clean build under centOS have broken Windows portability. I will fix this - it’s pretty trivial - but I just don’t have time right now, sorry.

Download

Asterisk Manager xAP Connector

Windows executable (requires cygwin dll) Back soon!

Full Windows/Linux source (requires xAPlib)

Schema

Asterisk Manager Schema

Asterisk Dialer Interface

The dialer interface is a simple daemon that listens for xAP dialer messages. On receipt of a valid message, it will set up a call by writing a call setup file to the asterisk outgoing spool directory. For this reason, the dialer must run on the asterisk server itself.

The xAP dialer message (see schema) must include a destination number. This can be specified in international or local dialling format (e.g. +44 1123 4455 is reformatted to 01123 4455 automagically). Brackets, dashes and other non-numeric characters are automatically discarded.

Optionally, the dialer message may also include a context and extension. If these are incorrect, asterisk will simply consume the dial instruction silently - if you have problems setting up a call, an incorrect context or extension could well be the cause.

Command Line Options

xap-dialer [instance name] [network interface] [udp port] [debug level]

 where:
instance name is the xAP instance name assigned to this asterisk dialer instance. The default instance name is xap-dialer.

network interface is the network interface used for outgoing xAP messages. On a Linux and Windows PC host these are named eth0, eth1. Under OSX they are named ne0 etc. By default, eth0 is used. On a Windows PC which has multiple adapters installed, even if they are not active, eth0 may not represent the active interface - some experimentation may be required!

udp port is the UDP port xAP broadcasts on. By default xAP uses its officially allocated port, 3639. Using an alternative port can be useful during isolated testing, however. Be aware that the use of ports below 1024 will fail unless the application is run by a user with administrative privileges. The use of ports below 1024 therefore has security implications and is not recommend.

debug level determines the verbosity of the output written to stdout. Verbose output can be useful for debugging unexpected behaviour. By default, the debug level is 0. Increasing levels of detail may be specified, up to a maximum of 4.

Download

Asterisk Dialer xAP Connector

Full Linux source (requires xAP-lib)

Schema

Asterisk Dialer Schema

Copyright (c) 2002-2006 Patrick Lidstone unless otherwise stated.
All rights reserved.