<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>DUNDi</title><link rel="stylesheet" href="styles.css" type="text/css" /><meta name="generator" content="DocBook XSL Stylesheets V1.69.1" /><link rel="start" href="index.html" title="Asterisk™: The Future of Telephony" /><link rel="up" href="asterisk-CHP-14.html" title="Chapter 14. Potpourri" /><link rel="prev" href="asterisk-CHP-14-SECT-5.html" title="Call Files" /><link rel="next" href="I_sect114_tt1735.html" title="Alternative Voicemail Storage Methods" /></head><body><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">DUNDi</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="asterisk-CHP-14-SECT-5.html">Prev</a> </td><th width="60%" align="center">Chapter 14. Potpourri</th><td width="20%" align="right"> <a accesskey="n" href="I_sect114_tt1735.html">Next</a></td></tr></table><hr /></div><div class="sect1" lang="en" xml:lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="asterisk-CHP-14-SECT-6"></a>DUNDi</h2></div></div></div><p>If there were any concerns that Mark Spencer was in danger of
running out of good ideas, <a id="ch14_distributed" class="indexterm"></a><a id="ch14_dundi" class="indexterm"></a>Distributed Universal Number Discovery (DUNDi) ought to lay
such thoughts to rest. DUNDi is poised to be as revolutionary as Asterisk.
The DUNDi web site (<a href="http://www.dundi.com" target="_top">http://www.dundi.com</a>) says it best:
“DUNDi™ is a peer to peer system for locating Internet gateways to
telephony services. Unlike traditional centralized services (such as the
remarkably simple and concise <span class="emphasis"><em>ENUM</em></span> standard; <a href="http://www.faqs.org/rfc/rfc2916.txt" target="_top">http://www.faqs.org/rfc/rfc2916.txt</a>),
DUNDi is fully distributed with no centralized authority whatsoever.”
DUNDi is somewhat of a routing protocol for VoIP.</p><div class="sect2" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="asterisk-CHP-14-SECT-6.1"></a>How Does DUNDi Work?</h3></div></div></div><p>Think of DUNDi as a large phone book that allows you to ask peers
if they know of an alternative VoIP route to an extension number or PSTN
telephone number.</p><p>For example, assume that you are connected to the
<span class="emphasis"><em>DUNDi-test</em></span> network (a free and open network that
terminates calls to traditional PSTN numbers). You ask your friend Bob
if he knows how to reach 1-212-555-1212, a number for which you have no
direct access. Bob replies, “I don’t know how to reach that number, but
let me ask my peer Sally.”</p><p>Bob asks Sally if she knows how to reach the requested number, and
she responds with, “You can reach that number at
<code class="literal">IAX2/dundi:</code><em class="replaceable"><code>very_long_password@hostname/extension</code></em>.”
Bob then stores the address in his database and passes on to you the
information about how to reach 1-800-555-1212 via VoIP, allowing you an
alternative method of reaching the same destination through a different
network.</p><p>Because Bob has stored the information he found, he’ll be able to
provide it to any peers who later request the same number from him, so
the lookup won’t have to go any further. This helps reduce the load on
the network and increases response times for numbers that are looked up
often. (However, it should be noted that DUNDi creates a rotating key
and, thus, stored information is valid for a limited period of
time.)</p><p>DUNDi performs lookups dynamically, either with a <code class="literal">switch =></code> statement in your
<span class="emphasis"><em>extensions.conf</em></span> file or with the use of the
<code class="literal">DUNDiLookup()</code> application. DUNDi is
available only in Asterisk version 1.2 or higher.</p><p>You can use the DUNDi protocol in a private network as well. Say
you’re the Asterisk administrator of a very large enterprise
installation, and you wish to simplify the administration of extension
numbers. You could use DUNDi in this situation, allowing multiple
Asterisk boxes (presumably located at each of the company’s locations
and peered with one another) to perform dynamic lookups for the VoIP
addresses of extensions on the network.</p></div><div class="sect2" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="asterisk-CHP-14-SECT-6.2"></a>Configuring Asterisk for Use with DUNDi</h3></div></div></div><p>There are three files that need to be configured for DUNDi:
<span class="emphasis"><em>dundi.conf</em></span>, <span class="emphasis"><em>extensions.conf</em></span>,
and <span class="emphasis"><em>iax.conf</em></span>.<sup>[<a id="asterisk-CHP-14-FN-7" href="#ftn.asterisk-CHP-14-FN-7">149</a>]</sup> The <span class="emphasis"><em>dundi.conf</em></span> file
controls<a id="I_indexterm14_tt1703" class="indexterm"></a> the authentication of peers whom we allow to perform
lookups through our system. This file also manages the list of peers to
whom we might submit our own lookup requests. Since it is possible to
run several different networks on the same box, it is necessary to
define a different section for each peer, and then configure the
networks in which that peer is allowed to perform lookups. Additionally,
we need to define which peers we wish to use to perform <span class="keep-together">lookups</span>.</p><div class="sect3" lang="en" xml:lang="en"><div class="titlepage"><div><div><h4 class="title"><a id="asterisk-CHP-14-SECT-6.2.1"></a>The General Peering Agreement</h4></div></div></div><p>The General Peering Agreement (GPA) <a id="I_indexterm14_tt1704" class="indexterm"></a><a id="I_indexterm14_tt1705" class="indexterm"></a>is a legally binding license agreement that is designed
to prevent abuse of the DUNDi protocol. Before connecting to the
<span class="emphasis"><em>DUNDi-test</em></span> group, you are required to sign a GPA.
The GPA is used to protect the members of the group and to create a
“trust” between the members. It is a requirement of the
<span class="emphasis"><em>DUNDi-test</em></span> group that your complete and accurate
contact information be configured in <span class="emphasis"><em>dundi.conf</em></span>,
so that members of your peer group can contact you. The GPA can be
found in the <span class="emphasis"><em>doc/</em></span> subdirectory of the Asterisk
source.</p></div><div class="sect3" lang="en" xml:lang="en"><div class="titlepage"><div><div><h4 class="title"><a id="asterisk-CHP-14-SECT-6.2.2"></a>General configuration</h4></div></div></div><p>The <code class="literal">[general]</code> section
<a id="I_indexterm14_tt1706" class="indexterm"></a>of <span class="emphasis"><em>dundi.conf</em></span> contains parameters
relating to the overall operation of the DUNDi client and
server:</p><a id="I_programlisting14_tt1707"></a><pre class="programlisting">; DUNDi configuration file
;
[general]
;
department=IT
organization= toronto.example.com
locality=Toronto
stateprov=ON
country=CA
email=support@toronto.example.com
phone=+19055551212
;
; Specify bind address and port number. Default is 4520
;bindaddr=0.0.0.0
port=4520
entityid=FF:FF:FF:FF:FF:FF
ttl=32
autokill=yes
;secretpath=dundi</pre><p>The entity identifier defined by <code class="literal">entityid</code> should generally be the<a id="I_indexterm14_tt1708" class="indexterm"></a><a id="I_indexterm14_tt1709" class="indexterm"></a> Media Access Control (MAC) address of an interface in
the machine. The entity ID defaults to the first Ethernet address of
the server, but you can override this with <code class="literal">entityid</code>, as long as it is set to the MAC
address of <span class="emphasis"><em>something</em></span> you own. The MAC address of
the primary external interface is recommended. This is the address
that other peers will use to identify you.</p><p>The Time To Live (<code class="literal">ttl</code>)
field<a id="I_indexterm14_tt1710" class="indexterm"></a><a id="I_indexterm14_tt1711" class="indexterm"></a> defines how many peers away we wish to receive replies
from and is used to break loops. Each time a request is passed on down
the line because the requested number is not known, the value in the
TTL field is decreased by one, much like the TTL field of an ICMP
packet. The TTL field also defines the maximum number of seconds we
are willing to wait for a reply.</p><p>When you request a number lookup, an initial query (called a
<code class="literal">DPDISCOVER</code>) is<a id="I_indexterm14_tt1712" class="indexterm"></a> sent to your peers requesting that number. If you do
not receive an acknowledgment (<code class="literal">ACK</code>)
of your query (<code class="literal">DPDISCOVER</code>) within
2,000 ms (enough time for a single transmission only) and <code class="literal">autokill</code> is equal to <code class="literal">yes</code>, Asterisk will send a <code class="literal">CANCEL</code> to the peers. (Note that an
acknowledgment is not necessarily a reply to the query; it is just an
acknowledgment that the peer has received the request.) The purpose of
<code class="literal">autokill</code> is to keep the lookup from
stalling due to hosts with high latency. In addition to the <code class="literal">yes</code> and <code class="literal">no</code> options, you may also specify the number
of milliseconds to wait.</p><p>The <span class="emphasis"><em>pbx_dundi</em></span> module creates a rotating key
and stores it in the local Asterisk database (AstDB). The key name
<code class="literal">secret</code> is stored in the <code class="literal">dundi</code> family. The value of the key can be
viewed with the <code class="literal">database show</code>
command at the Asterisk console. The database family can be overridden
with the <code class="literal">secretpath</code> option.</p></div><div class="sect3" lang="en" xml:lang="en"><div class="titlepage"><div><div><h4 class="title"><a id="asterisk-CHP-14-SECT-6.2.3"></a>Creating mapping contexts</h4></div></div></div><p>The <span class="emphasis"><em>dundi.conf</em></span> file defines DUNDi contexts
that are mapped to dialplan contexts in your<a id="I_indexterm14_tt1713" class="indexterm"></a> <span class="emphasis"><em>extensions.conf</em></span> file. DUNDi
contexts are a way of defining distinct and separate directory service
groups. The contexts in the mapping section point to contexts in the
<span class="emphasis"><em>extensions.conf</em></span> file, which control the numbers
that you advertise. When you create a peer, you need to define which
mapping contexts you will allow this peer to search. You do this with
the <code class="literal">permit</code> statement (each peer may
contain multiple <code class="literal">permit</code>
<span class="keep-together">statements</span>). Mapping contexts
are related to dialplan contexts in the sense that they are a security
boundary for your peers.</p><p>Phone numbers must be advertised in the following format:</p><a id="I_programlisting14_tt1714"></a><pre class="programlisting">
<em class="replaceable"><code><country_code><area_code><prefix><number></code></em>
</pre><p>For example, a complete North American number could be
advertised as 14165551212.</p><p>All DUNDi mapping contexts take the form of:</p><a id="I_programlisting14_tt1715"></a><pre class="programlisting"><em class="replaceable"><code>dundi_context</code></em> => <em class="replaceable"><code>local_context</code></em>,<em class="replaceable"><code>weight</code></em>,<em class="replaceable"><code>technology</code></em>,<em class="replaceable"><code>destination</code></em>[,<em class="replaceable"><code>options</code></em>]]</pre><p>The following configuration creates a DUNDi mapping context that
we will use to advertise our local phone numbers to the
<span class="emphasis"><em>DUNDi-test</em></span> group. Note that this should all
appear on one line:</p><a id="I_programlisting14_tt1716"></a><pre class="programlisting">dundi-test => dundi-local,0,IAX2,dundi:${SECRET}@toronto.example.com/
${NUMBER}, nounsolicited,nocomunsolicit,nopartial</pre><p>In this example, the mapping context is <code class="literal">dundi-test</code>, which points to the <code class="literal">dundi-local</code> context within
<span class="emphasis"><em>extensions.conf</em></span> (providing a listing of phone
numbers to reply to). Numbers that resolve to the PBX should be
advertised with a <em class="replaceable"><code>weight</code></em> of zero (directly
connected). Numbers higher than 0 indicate an increased number of hops
or paths to reach the final destination. This is useful when multiple
replies for the same lookup are received at the end that initially
requested the number; a <em class="replaceable"><code>weight</code></em> with a lower
number will be the preferred path.</p><p>If we can reply to a lookup, our response will contain the
method by which the other end can connect to the system. This includes
the technology to use (such as IAX2, SIP, H323, and so on), the
username and password with which to authenticate, which host to send
the authentication to, and finally the extension number.</p><p>Asterisk provides some shortcuts to allow us to create a
“template” with which we can build our responses. The following
channel variables can be used to construct the template:</p><div class="variablelist"><dl><dt><span class="term">
<code class="literal">${SECRET}</code>
</span></dt><dd><p>Replaced <a id="I_indexterm14_tt1717" class="indexterm"></a>with the password stored in the local AstDB</p></dd><dt><span class="term">
<code class="literal">${NUMBER}</code>
</span></dt><dd><p>The number<a id="I_indexterm14_tt1718" class="indexterm"></a> being requested</p></dd><dt><span class="term">
<code class="literal">${IPADDR}</code>
</span></dt><dd><p>The IP address<a id="I_indexterm14_tt1719" class="indexterm"></a> to connect to</p></dd></dl></div><div class="warning" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title"><a id="asterisk-CHP-14-NOTE-51"></a>Warning</h3><p>It is generally safest to statically configure the hostname,
rather than making use of the <code class="literal">${IPADDR}</code> variable. The <code class="literal">${IPADDR}</code> variable will sometimes reply
with an address in the private IP space, which is unreachable from
the Internet.</p></div></div><div class="sect3" lang="en" xml:lang="en"><div class="titlepage"><div><div><h4 class="title"><a id="asterisk-CHP-14-SECT-6.2.4"></a>Defining DUNDi peers</h4></div></div></div><p>DUNDi peers <a id="I_indexterm14_tt1720" class="indexterm"></a>are defined in the<a id="I_indexterm14_tt1721" class="indexterm"></a> <span class="emphasis"><em>dundi.conf</em></span> file. Peers are
identified by the unique layer-two MAC address of an interface on the
remote system. The <span class="emphasis"><em>dundi.conf</em></span> file is where we
define what context to search for peers requesting a lookup and which
peers we want to use when doing a lookup for a particular
network:</p><a id="I_programlisting14_tt1722"></a><pre class="programlisting">[00:00:00:00:00:00] ; Remote Office
model = symmetric
host = montreal.example.com
inkey = montreal
outkey = toronto
include = dundi-test
permit = dundi-test
qualify = yes
dynamic=yes</pre><p>The remote peer’s identifier (MAC address) is enclosed in
<a id="I_indexterm14_tt1723" class="indexterm"></a><a id="I_indexterm14_tt1724" class="indexterm"></a>square brackets (<code class="literal">[]</code>).
The <code class="literal">inkey</code> and <code class="literal">outkey</code> are the public/private key pairs that
we use for authentication. Key <a id="I_indexterm14_tt1725" class="indexterm"></a>pairs are generated with the <code class="filename">astgenkey</code> script, located in the <code class="filename">./asterisk/contrib/scripts/</code> source
directory. Be sure to use the -<code class="literal">n</code>
flag <a id="I_indexterm14_tt1726" class="indexterm"></a>so that you don’t have to initialize passwords every
time you start Asterisk:</p><a id="I_programlisting14_tt1727"></a><pre class="programlisting"># <strong class="userinput"><code>cd /var/lib/asterisk/keys</code></strong>
# <strong class="userinput"><code>/usr/src/asterisk/contrib/scripts/astgenkey -n toronto</code></strong></pre><p>The resulting keys, <code class="filename">toronto.pub</code> and <code class="filename">toronto.key</code>, will be placed in your
<code class="filename">/var/lib/asterisk/keys/</code>
directory. The <code class="filename">toronto.pub</code> file
is the public key, which you should post to a web server so that it is
easily accessible for anyone with whom you wish to peer. When you
peer, you can give your peers the HTTP-accessible public key, which
they can then place in their <code class="filename">/var/lib/asterisk/keys/</code> directories.</p><p>After you have downloaded the keys, you must reload<a id="I_indexterm14_tt1728" class="indexterm"></a><a id="I_indexterm14_tt1729" class="indexterm"></a> the <code class="filename">res_crypto.so</code>
and <code class="filename">pbx_dundi.so</code> modules in
Asterisk:</p><a id="I_programlisting14_tt1730"></a><pre class="programlisting">*CLI> <strong class="userinput"><code>module reload res_crypto.so</code></strong>
-- Reloading module 'res_crypto.so' (Cryptographic Digital Signatures)
-- Loaded PRIVATE key 'toronto'
-- Loaded PUBLIC key 'toronto'
*CLI> <strong class="userinput"><code>module reload pbx_dundi.so</code></strong>
-- Reloading module 'pbx_dundi.so' (Distributed Universal Number
Discovery
(DUNDi))
== Parsing '/etc/asterisk/dundi.conf': Found</pre><p>Then, create the <code class="literal">dundi</code> user
in the <code class="filename">iax.conf</code> file <a id="I_indexterm14_tt1731" class="indexterm"></a>to allow connections into your Asterisk system. When a
call is authenticated, the extension number being requested is passed
to the <code class="literal">dundi-local</code> context in the
<code class="filename">extensions.conf</code> file, where the
call is then handled by Asterisk.</p></div><div class="sect3" lang="en" xml:lang="en"><div class="titlepage"><div><div><h4 class="title"><a id="asterisk-CHP-14-SECT-6.2.5"></a>Allowing remote connections</h4></div></div></div><p>Here is the user definition for the <code class="literal">dundi</code> user:</p><a id="I_programlisting14_tt1732"></a><pre class="programlisting">[dundi]
type=user
dbsecret=dundi/secret
context=dundi-local
disallow=all
allow=ulaw
allow=g726</pre><p>Instead of using a static password, Asterisk regenerates
passwords every 3,600 seconds (1 hour). The value is stored in
<span class="emphasis"><em>/dundi/secret</em></span> of the Asterisk database and
advertised using the <code class="literal">${SECRET}</code>
variable defined within the mapping context lines in <code class="filename">dundi.conf</code>. You can see the current keys
for all peers, including your local public and private keys, by
performing a <code class="literal">show keys</code> at the Asterisk CLI.</p><p>The <code class="literal">context</code> entry <code class="literal">dundi-local</code> is where authorized callers are
sent in <code class="filename">extensions.conf</code>. From
there, we can manipulate the call just as we would in the dialplan of
any other incoming connection.</p></div><div class="sect3" lang="en" xml:lang="en"><div class="titlepage"><div><div><h4 class="title"><a id="asterisk-CHP-14-SECT-6.2.6"></a>Configuring the dialplan</h4></div></div></div><p>The <code class="filename">extensions.conf</code> file
handles what numbers you advertise and what you do with the calls that
connect to them. The <code class="literal">dundi-local</code>
context performs double duty:</p><div class="itemizedlist"><ul type="disc"><li><p>It controls the numbers we advertise, referenced by the
<code class="literal">dundi</code> mapping context in
<code class="filename">dundi.conf</code>.</p></li><li><p>It controls what to do with the call, referenced by the
<code class="literal">dundi</code> user in <code class="filename">iax.conf</code>.</p></li></ul></div><p>You have the power of dialplan pattern matching to advertise
ranges of numbers and to control the incoming calls. In the following
dialplan, we are only advertising the number +1-416-555-1212, but
pattern matching could just as easily have been employed to advertise
a range of <a id="I_indexterm14_tt1733" class="indexterm"></a>numbers or extensions:</p><a id="I_programlisting14_tt1734"></a><pre class="programlisting">[dundi-local]
exten => 14165551212,1,NoOp(dundi-local: Number advertisement and incoming)
exten => 14165551212,n,Answer()
exten => 14165551212,n(call),Dial(SIP/1000)
exten => 14165551212,n,Voicemail(u1000)
exten => 14165551212,n,Hangup()
exten => 14165551212,n(call)+101,Voicemail(b1000)
exten => 14165551212,n,Hangup()</pre></div></div><div class="footnotes"><br /><hr width="100" align="left" /><div class="footnote"><p><sup>[<a id="ftn.asterisk-CHP-14-FN-7" href="#asterisk-CHP-14-FN-7">149</a>] </sup>The <span class="emphasis"><em>dundi.conf</em></span> and
<span class="emphasis"><em>extensions.conf</em></span> files must be configured. We
have chosen to configure <span class="emphasis"><em>iax.conf</em></span> for our
address advertisement on the network, but DUNDi is
protocol-agnostic—thus <span class="emphasis"><em>sip.conf</em></span>,
<span class="emphasis"><em>h323.conf</em></span>, or <span class="emphasis"><em>mgcp.conf</em></span>
could be used instead.</p></div></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="asterisk-CHP-14-SECT-5.html">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="asterisk-CHP-14.html">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="I_sect114_tt1735.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Call Files </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right" valign="top"> Alternative Voicemail Storage Methods</td></tr></table></div><div xmlns="" id="svn-footer"><hr /><p>You are reading <em>Asterisk: The Future of Telephony</em> (2nd Edition for Asterisk 1.4), by Jim van Meggelen, Jared Smith, and Leif Madsen.<br />
This work is licensed under the <a href="http://creativecommons.org/licenses/by-nc-nd/3.0/">Creative Commons Attribution-Noncommercial-No Derivative Works License v3.0</a>.<br />
To submit comments, corrections, or other contributions to the text, please visit <a href="http://oreilly.com/catalog/9780596510480/">http://www.oreilly.com/</a>.</p></div></body></html>
