The heart of the freenum.org concept is the ITAD Subscriber Number (ISN). The ISN is a numeric string that is composed of an extension number on your system, an asterisk character separator (*),^[116] and a number that is unique to your organization called an IP Telephony Administrative Domain (ITAD) number. The advantage of the ISN is that it can be dialed from any telephone. An ISN would look something like this:

0*1273

which would represent extension zero at ITAD 1273^[117] and would resolve to sip:0@shifteight.org.

You control your extension numbers (everything to the left of the *). Your ITAD is assigned by IANA (the same organization that controls IP and MAC addresses).

Once your ITAD is assigned, you will be able to publish ISNs on your website, or on business cards, or wherever you would normally publish phone numbers. Any system capable of dialing ISNs will allow its users to call you by dialing your ISN. Calls will be routed directly between the two systems using the SIP URI that freenum.org returns.

The ISN does not replace a SIP URI, but rather complements it by allowing dialing of VoIP numbers using only characters found on a standard telephone dialpad. In order to resolve an ISN into a valid URI, the DNS system will query the ISN against the freenum.org domain. Any DNS lookup against your ISN will return a URI that defines how your system expects to receive calls to that ISN.^[118]

The Internet Assigned Numbers Authority (IANA) is the body responsible for managing any numbering system that exists as a result of an RFC that requires a numerical database of some kind. The most well-known responsibility of IANA is the delegation of IP addresses to the five Regional Internet Registries that control all of the public IP addresses on the planet.^[119] These organizations are responsible for the assignment of IP addresses within their regions.

There are many other numbering schemes that have been created as a result of an RFC. Other IANA-managed numbers include MAC addresses—specifically, the Organizationally Unique Identifier (OUI) portion of the MAC addressing space.

Several years ago, a protocol named TRIP (Telephony Routing over IP) was created. While this protocol never took off, and is unlikely to see any future growth, it did offer us one incredibly useful thing: the ITAD. Since ITADs are part of an RFC, the IANA is mandated to maintain a database of ITADs. This is what makes freenum.org possible.

Freenum.org takes advantage of IANA’s responsibility to maintain a database of ITAD numbers and allows us to build simple, standards-based, globally relevant, and community-driven numbering plans for VoIP.^[120] You can find the list of currently assigned ITAD numbers at http://www.iana.org/assignments/trip-parameters/trip-parameters.xml#trip-parameters-5.

You will want to obtain your own ITAD number by submitting the form located at http://www.iana.org/cgi-bin/assignments.pl.

This form should be filled out as shown in Figure 12.1, “Request for Assignments form”.

Figure 12.1. Request for Assignments form

Your application will be reviewed by a Real Human Being™, and within a few days you should be assigned an ITAD by IANA. A few days later, you will also receive information for your freenum.org account (there is currently a simple review process to ensure that bots and spammers don’t abuse the system). You will then need to log onto the freenum.org site and define the parameters for your ITAD.

In the top-right corner of the freenum.org site, you will see a Sign in here link. Your username is the email address you registered with IANA, and your password will have been emailed to you by the freenum.org system.^[121]

You will be presented with a list of your assigned ITADs. In order for your new ITAD to work, you will need to ensure the DNS records are up-to-date.

The freenum.org folks have created the Freenum Automated Self-Service Tool (FASST) to simplify DNS record entry for you. The essential fields will already be filled out. The only thing you need to change is under the DNS Setting section of the form: specify the hostname of your PBX and save the changes. The FASST tool uses a regular expression to convert an ISN lookup to a SIP URI.

In order to specify your hostname, you will need to modify the sample regular expression provided by FASST, changing the sample hostname sip.yourdomain.com to the hostname of your PBX. So, for example, in our case we would want to change:

!^\\+*([^\\*]*)!sip:\\1@sip.yourdomain.com!

to:

!^\\+*([^\\*]*)!sip:\\1@pbx.shifteight.org!

The other fields in the DNS entry should not be changed unless you know what you are doing. The rest of the fields in the form are optional, and can be filled out as you see fit.

As is often the case with DNS changes, it can take a few days for your changes to propagate through the system. To check, you can Google for “online dig tool” to find a web-based lookup tool, or use the dig tool under Linux:

$ dig NAPTR 4.3.2.1.1273.freenum.org

Once your record is updated in the system, the result will include the following:

;; ANSWER SECTION: 
4.3.2.1.1273.freenum.org. 86400 IN NAPTR 100 10 "u" "E2U+sip" 
"!^\\+*([^\\*]*)!sip:\\1@shifteight.org!" .

If the answer section does not include the regular expression containing your domain name, the records have not updated and you should wait a few more hours (or even leave it for a day).

So now that you’ve got your own ITAD (you did sign up, right?), you’ll want to make it available to others, and also configure your dialplan to allow you to dial other ITADs.

Under the [globals] section of your dialplan (/etc/asterisk/extensions.conf), add a global variable that contains your ITAD:

[globals]
ITAD = 1273 ; replace '1273' with your own ITAD number

To allow calling to ITADs from your system, you will need something like the following dialplan code^[122]:

[OutgoingISN]
exten => _X*X!,1,GoSub(subFreenum,start,1(${EXTEN}))
exten => _XX*X!,1,GoSub(subFreenum,start,1(${EXTEN}))
exten => _XXX*X!,1,GoSub(subFreenum,start,1(${EXTEN}))
exten => _XXXX*X!,1,GoSub(subFreenum,start,1(${EXTEN}))
exten => _XXXXX*X!,1,GoSub(subFreenum,start,1(${EXTEN}))
; you may need to add more lines here to handle XXXXXX*X, XXXXXXX*X, and so forth

[subFreenum]
exten => start,1,Verbose(2,Performing ISN lookup)
   same => n,Set(ISN=${FILTER(0-9*,${ARG1})})
   same => n,Set(Result=${ENUMLOOKUP(${ISN},sip,s,,freenum.org)})
   same => n,GotoIf($[${EXISTS(${Result})}]?call,1:no_result,1)

exten => call,1,Verbose(2,Placing call to ISN --${ISN}-- via ${Result})
   same => n,Dial(SIP/${Result})
   same => n,Return()

exten => no_result,1,Verbose(2,Lookup for ISN: --${ISN}-- returned no result)
   same => n,Playback(silence/1&invalid)
   same => n,Return()

We have added two new contexts to our dialplan: OutgoingISN and subFreenum. The OutgoingISN context controls who can dial ISN numbers from within your dialplan. If you have been following our examples throughout this book, you should have a context called LocalSets, which is the context where all your telephones enter the dialplan. Including OutgoingISN within LocalSets enables dialing of ISN numbers:

[LocalSets]
include => OutgoingISN  ; include the context that enables ISN dialing
include => CallPlace    ; use subroutine to determine what you can dial

The magic for dialing ISN numbers is handled in the subFreenum context. Our OutgoingISN context will pass the requested extension (e.g., 1234*256) to the subFreenum subroutine. After the initial call to Verbose() on the first line, the subroutine will filter the request for numbers and the asterisk (*) character to make the extension safe. The result will then be assigned to the ISN channel variable:

exten => start,n,Set(ISN=${FILTER(0-9*,${ARG1})})

The subroutine will then perform a lookup for the ISN via the DNS system using the ENUMLOOKUP() dialplan function. Options passed to the ENUMLOOKUP() function include:

Our code for performing the lookup then looks like this:

exten => start,n,Set(Result=${ENUMLOOKUP(${ISN},sip,s,,freenum.org)})

Following the lookup and storing the result in the ${Result} channel variable, our subroutine will verify whether we received a result or not:

exten => start,n,GotoIf($[${EXISTS(${Result})}]?call,1:no_result,1)

If no result is received, the call will be handled in the no_result extension. If a result is received back from our lookup, then execution will continue at the call extension where the call will be placed using the result stored in the ${Result} channel variable.