Mod enum

From FreeSWITCH Wiki
Revision as of 02:26, 31 July 2013 by Karl Schmidt (Talk | contribs)

(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)
Jump to: navigation, search


ENUM Support

What is ENUM?

ENUM (Electronic Number Mapping System) is a system that uses standard phone numbers as a key to lookup addressing and identification information that can potentially let Freeswitch servers communicate directly, thus bypassing the PSTN, reducing cost, and improving audio quality. It is based on the E.164 standard and uses standard DNS systems to translate telephone numbers into a special DNS record type called a NAPTR record (Naming Authority PoinTer Resource Record) that might contain information for 1-(800)-555-1234 such as:

IN NAPTR 100 10 "U" "E2U+sip" "!^.*$!!" .
IN NAPTR 102 10 "U" "E2U+email" "!^.*$!!" .


The main file for configuring ENUM functionality (assuming you've done "make samples" and are working with the provided sample configuration files) is: conf/autoload_configs/enum.conf.xml

The contents of this file are as of such:

<configuration name="enum.conf" description="ENUM Module">
    <param name="default-root" value=""/>
    <param name="default-isn-root" value=""/>
    <param name="query-timeout" value="10"/>
    <param name="auto-reload" value="true"/>
    <route service="E2U+SIP" regex="sip:(.*)" replace="sofia/$${sip_profile}/$1"/>
    <route service="E2U+IAX2" regex="iax2:(.*)" replace="iax/$1"/>
    <route service="E2U+XMPP" regex="XMPP:(.*)" replace="dingaling/$${xmpp_server_profile}/$1"/>

Note the above configuration uses global variables $${sip_profile} and $${xmpp_server_profile}}, these must be set in vars.conf.xml. Or use static values. The above is only an example.


Name Description Example
auto-reload Whether to reload the XML configuration when reloadxml is run true
default-isn-root Default root to use when not specified.
default-root Default root to use when not specified.
query-timeout How long before ENUM DNS query times out (seconds) 10

ToDo: The difference between default-isn-root and default-root needs to be documented.

Dialplan interface

The enum module provides a dialplan interface which allows you only to dial a number and an ENUM lookup will be done. If results are found, the ones supported will be called in order of priority and weight of the DNS records. The results are mapped to dialstrings using the routes options from the configuration file.

The ENUM dialplan can be set from one of the Endpoints configuration XML as follows:

<param name="dialplan" value="enum"/>

It is also possible to transfer to the enum dialplan from another dialplan such as the XML one.

Dialplan apps


The ENUM application can be called from the dialplan by executing it from within your condition as follows:

 <action application="enum" data="$1"/>

You can specify a custom root domain as the second parameter, above it is "" the parameter $1 contains what has been dialed.

The lookup generates dialstrings for bridge using the routes set in the configuration file, for example:

  enum_route_1: sofia/internal/
  enum_route_2: sofia/internal/
  enum_route_3: sofia/internal/
  enum_route_count: 3
  enum_auto_route: sofia/internal/,sofia/internal/,sofia/internal/

The last variable enum_auto_route is convenient to pass directly to bridge. If the enum lookup fails it will be empty, one way to handle this would be to set continue_on_fail=true and fallback to another bridge, for example:

   <extension name="Outbound to US PSTN 11 Digits">
     <condition field="destination_number" expression="^(1[2-9][0-9][0-9][2-9][0-9][0-9][0-9][0-9][0-9][0-9])$">
       <action application="set" data="continue_on_fail=true"/>
       <action application="enum" data="$1"/>
       <action application="bridge" data="${enum_auto_route}"/>
       <action application="bridge" data="sofia/gateway/myVoIPGateWay/$1|sofia/gateway/myVoIPGateWay-backup/$1|sofia/gateway/LastVoIPGateWayAttempt/$1"/>



enum < reload | number [root] >

From the CLI issue something similar to the following to see a readable output of the ENUM lookup results:

enum 18002255288
enum 18002255288

Example output:

Offered Routes:
Order	Pref	Service   	Route
100	10	E2U+SIP   	sofia/internal/;transport=udp
100	10	E2U+SIP   	sofia/internal/;transport=udp

Supported Routes:
Order	Pref	Service   	Route
100	10	E2U+SIP   	sofia/internal/;transport=udp
100	10	E2U+SIP   	sofia/internal/;transport=udp

It can also be used to reload the XML configuration:

 enum reload


This API can be used to generate a dialstring compatible with bridge:

 enum_auto 18002255288



ENUM providers

Public E164

There are several popular ENUM providers for E164 numbers, including:

Hence, one could try:

<action application="set" data="continue_on_fail=true"/>
<action application="enum" data="$1"/>
<action application="bridge" data="${enum_auto_route}"/>
<action application="enum" data="$1"/>
<action application="bridge" data="${enum_auto_route}"/>

And there are numerous others spanned across the globe, but please research them fully before using them lest calls be "hijacked" to somewhere else. You could in fact institute your own dialplan within your own DNS domain by using ENUM lookups for particular extensions, however it has been reported that it might be possible to have your DOMAIN hijacked and in the process your telephone traffic may also be exploited. So do your own research into the security of such a deployment.

Registering your number with is a free service (supported by donations) that verifies your number by placing a phone call and reading a 6-digit PIN. However, the digits are read only once, rather fast, and it can't dial through an IVR, which makes it difficult to register a number on an operational system. One way to work with this problem is to place in your public dialplan an extension that routes a call from directly to your extension, using their caller-ID number (+12243336164) as a condition:

<condition field="caller_id_number" expression="^\+?(12243336164)$">
  <action application="transfer" data="1023 XML default"/>

After entering your number at, wait a few minutes at that extension, pick it up immediately, and get ready to write down the 6-digit PIN.

Incidentally, although this PIN method ensures that only the owner of a phone number can register it, it is not clear how or if they can detect numbers that have been "changed" or "disconnected", etc... Hence, they rely on the individual that "owns" the record to delete the record for their old number. Hence, over time it is possible that if enough people "forget" to delete their old numbers that a call could get improperly routed to the wrong (old) destination and not arrive to the person/organization that presently owns that PSTN number.

In short, use at your own risk.

Custom ENUM Server

You can use enum to store your internal phone number to user/phone mapping (often called carrier-enum), this python code use the twisted matrix DNS library ( apt-get install python-twisted-names ) to create a custom enum DNS server to that end.

Use different sofia profiles when using Enum

Should you want to use different profiles for with your enum entries, it is possible thanks to RFC 3761 section 2.4.2

In your enum.conf configuration, setup multiple services giving them names after the comma and then use those name as the NAPTR service name in DNS.

   <route service="E2U+SIP:MEDIA" regex="sip:(.*)" replace="sofia/media/$1"/>
   <route service="E2U+SIP:TRUNK" regex="sip:(.*)" replace="sofia/pstn/$1"/>
 $ cat ienum 
 # should stip here + or 00 from $1
 echo host -t naptr $(echo $1 | rev | sed -e 's/[0-9]/&./g')
 host -t naptr $(echo $1 | rev | sed -e 's/[0-9]/&./g')

replace with your enum root.

Example output :

 $ ienum 123456789
 host -t naptr has NAPTR record 10 100 "U" "E2U+sip:MEDIA" "!^.*$!sip:unallocated-123456789@!" .