Serval Project, Sept 2014
This repository contains the source code for the Serval Project's VoMP channel driver for [Asterisk 11][] implemented in GNU C, together with an AGI script in Python and a set of configuration file templates for Asterisk.
The VoMP channel driver allows users of a Serval mesh network to dial numbers outside the local mesh and vice versa, for example, to the PSTN via a VoIP provider, or to a telephone network with an Asterisk gateway, such as the Mesh Potato by VillageTelco or Commotion OpenBTS by the Commotion Wireless project.
See README-OpenBTS for more information about Commotion OpenBTS integration.
The channel driver has been tested with Asterisk 11.7.0 and will probably work with higher versions of 11.x.
The VoMP Asterisk channel driver is only available in source code form, not in pre-built (binary) form. The channel driver source code must be compiled into a shared library (binary) which must be placed in the directory from which Asterisk loads modules. Asterisk must then be configured with a dial plan that uses the VoMP channel driver module to route calls to and from the Serval mesh. These steps are described below.
A VoMP gateway is a server or node connected to both the Serval mesh network and to an external network (such as the Internet), and running the integrated [Asterisk 11][] and Serval DNA daemons integrated using this channel driver. The gateway has its own SID (Serval subscriber identifier).
Calls are routed out of the Serval mesh by having the VoMP gateway respond to DNA (phone lookup) requests by invoking a DNA Helper script to test whether the DID (phone number) is reachable via Asterisk. If so, the gateway responds to the DNA request with a VoMP URI containing its own SID. The caller then places the call by sending a VoMP CALL request to the gateway's SID, specifying the final (destination) phone number that was originally queried. The Serval DNA daemon on the gateway then initiates the call through Asterisk by sending commands via the channel driver, and bridges the VoMP audio stream to and from Asterisk via the channel driver.
Calls are routed into the Serval mesh if an Asterisk dial plan invokes the channel driver's AGI script to resolve a DID. The AGI script invokes the Serval DNA binary to perform a DNA request on the Serval mesh network. All the reachable nodes in the Serval mesh which match the DID (including other gateways) will reply to the request with a VoMP URI containing theid SID. If any DNA reply is received, the AGI script will return a positive result to the Asterisk dial plan, which will choose one of the URIs. If the chosen URI is a VoMP URI, then Asterisk will command the Serval DNA daemon via the channel driver to initiate a call to the given SID, and the channel driver will then bridge the VoMP audio stream between Asterisk and the Serval DNA daemon.
The channel driver performs audio stream conversion between the VoMP codec and Asterisk's internal audio stream format. The channel driver also handles codec negotiation and call tear-down.
In order to compile the VoMP Asterisk channel driver from source code, a current build of [Asterisk 11][] from source code is needed. The channel driver compilation reads build options (such as compiler flags) and header files from the Asterisk build. (If you know of any way to get these from an Asterisk installation or development package without downloading and compiling the entire Asterisk source code, please let us know!)
In order to compile the VoMP Asterisk channel driver from source code, a current build of Serval DNA from source code is needed. The channel driver compilation reads header files and the monitor client library from the Serval DNA build. (It is planned to eventually revise the monitor client interface and provide a Serval development kit that does not require the whole source code of Serval DNA, but until then, the Serval DNA source code must be downloaded and built.)
Asterisk 1.8 must be built from source code. The following example downloads and builds the latest stable 1.8 series:
$ cd $HOME/src
$ wget -q http://downloads.asterisk.org/pub/telephony/asterisk/asterisk-1.8-current.tar.gz
$ tar xzf asterisk-1.8-current.tar.gz
$ cd asterisk-1.8.20.0
$ ./configure
...
$ make
...
This step is not necessary in order to compile the VoMP channel driver, but is provided to illustrate the steps needed to build an Asterisk node from scratch.
The following example installs the Asterisk software under the default prefix
(/usr) and installs the basic Asterisk ("factory") configuration under
/etc/asterisk without modification. This is unlikely to suit your needs, and
is for illustration only:
$ sudo su
# make install
...
# make config
...
#
You may have to edit the installed /etc/defaults/asterisk to set the
AST_USER and AST_GROUP variables appropriately.
Serval DNA source code is available from the serval-dna repository on GitHub: You can use Git to download the latest version:
$ cd $HOME/src
$ git clone -q git://github.com/servalproject/serval-dna.git
$ cd serval-dna
$
Follow the build instructions in Serval DNA INSTALL.md.
This step is not necessary in order to compile the VoMP channel driver, but will simplify the configuration of Asterisk by making Serval DNA executables available at a known path. For example, on Linux:
$ sudo su
# cp -p servald directory_service /usr/sbin
#
Follow the configuration instructions in Servald-Configuration.md.
The Serval DNA daemon must be configured with the UID of the running
Asterisk daemon process, to allow the channel driver to communicate with the
Serval DNA daemon. This must match the AST_USER variable in the
/etc/defaults/asterisk file and must be numeric, not a login name.
For example, add the following line to /var/serval-node/serval.conf:
monitor.uid=106
Without this line, or with an incorrect UID, Serval DNA will reject connections from the channel driver.
The source code for the VoMP channel driver is is available from the app_servaldna repository on GitHub. You can use Git to download the latest version:
$ cd $HOME/src
$ git clone -q git://github.com/servalproject/app_servaldna.git
$ cd app_servaldna
$
The AST_ROOT and SERVAL_ROOT variables defined at the top of the
Makefile must be set to the directories containing the built
Asterisk source code and the built serval-dna source code respectively (see
above). This can be done in two ways:
-
EITHER edit the two lines in Makefile then run the
makecommand, -
OR pass arguments to the
makecommand (which will override the settings inMakefile), eg:$ make AST_ROOT=$HOME/src/asterisk-1.8.20.0 SERVAL_ROOT=$HOME/src/serval-dna $
The channel driver build process creates app_servaldna.so, which is the VoMP channel driver module shared library for Asterisk 1.8. In addition to this, servaldnaagi.py is an AGI script invoked by Asterisk which resolves a DID (phone number) to a SID (Serval subscriber identifier) or SIP URI.
Copy the shared library and AGI script into the proper Asterisk configuration directories. For example, on Linux:
$ cp -p app_servaldna.so /usr/lib/asterisk/modules
$ cp -p servaldnaagi.py /usr/lib/asterisk
$
For example, on Mac OS X:
$ cp -p app_servaldna.so "/Library/Application Support/Asterisk/Modules/modules"
$ cp -p servaldnaagi.py "/Library/Application Support/Asterisk/"
$
Two alternative sample configurations are provided, basic and advanced:
-
the conf directory contains a set of basic sample Asterisk configuration files. See below for instructions.
-
the conf_adv directory contains an advanced set of sample Asterisk configuration files that were developed for Commotion OpenBTS integration testing. It does not provision numbers statically in
extensions.conf, but instead looks up the OpenBTS registered subscriber database. See README-OpenBTS for instructions.
The basic sample configuration provisions all extensions statically in
extensions.conf. This allows the channel driver to resolve numbers directly
by asking Asterisk what is in the dialplan if resolve_numbers is true (false
by default). This will result in servald responding to incoming DNA requests
with its own SID for all numbers provisioned in extensions.conf.
For example, on Linux, copy the Asterisk configuration files:
$ sudo su
# cp conf/* /etc/asterisk
#
then update the extensions.conf and servaldna.conf files as described
below.
Edit the copied /etc/asterisk/extensions.conf to set the paths of the AGI
script, the Serval DNA executable, and the Serval DNA instance directory.
For example, to use the paths from previous examples and Serval DNA's default
built-in instance path:
SERVAL_AGI = /usr/lib/asterisk/servaldnaagi.py
SERVAL_BIN = /usr/sbin/servald
SERVALD_INSTANCE = /var/serval-node
Edit the copied /etc/asterisk/servaldna.conf to set the instancepath
variable to the absolute path of the instance directory used by the Serval
DNA daemon. This will allow the channel driver to communicate with the
daemon. For example, to use Serval DNA's default built-in instance path:
instancepath = /var/serval-node
The examples in this document are Bourne shell commands, using standard
quoting and variable expansion. Commands issued by the user are prefixed with
the shell prompt $ or # to distinguish them from the output of the command.
A prompt of # indicates that the command must be executed as the super user.
Single and double quotes around arguments are part of the shell syntax, so are
not seen by the command. Lines ending in backslash \ continue the command on
the next line.
The directory paths used in the examples are for illustrative purposes only, and are not the recommended values for a production system.
The VoMP Asterisk channel driver is free software initially produced by the Serval Project. It is licensed to the public under the GNU General Public License version 2. All source code is freely available from the Serval Project's app_servaldna Git repository on GitHub.
The copyright in the source code is held by Serval Project Inc., a not-for-profit association incorporated in the state of South Australia in the Commonwealth of Australia for the purpose of developing the Serval mesh software.
The Serval Project will accept contributions from individual developers who have agreed to the Serval Project Developer Agreement - Individual, and from organisations that have agreed to the Serval Project Developer Agreement - Entity.
For further information about this software, including bug reports, development policies and practices, etc., please see the Serval Project Wiki.