Building Software Defined Dial-Plans for Cisco IOS with Ruby
Overview
I was chatting with a friend recently and he mentioned if I had heard of the new Cisco IOS e164-pattern-map feature, I hadn’t and quickly looked it up and was amazed at what I saw. Something I had always wanted which was basically the ability to load a list of destinations or incoming-called numbers in a single dial peer. Not just by a pattern but very different destinations.
This feature allows you to load a list of destinations in a configuration file on a dial-peer by HTTP, FTP or TFTP. For the purpose of testing this I have built a small management platform in Ruby on Rails and hosted it on github for all.
https://github.com/Cloverhound/e164-pattern-map
What this e164-pattern-map feature in IOS allows us to do is essentially allow us the ability to finally flexibly and reliably manipulate the dial-plan in Cisco IOS from an outside source. Essentially Software Defined Dial-Plans! ☺
It is important to note for e164-pattern-map to be linked to an outbound dial-peer you must be at IOS 15.3 or higher.
If you would like to use it on an inbound dial-peer, you must use 15.4(1)T or higher!
The Architecture of Our Example
For the purpose of the blog we will focus on a hypothetical use case where a Cisco ISR would be configured as a CUBE and is splitting some incomings calls to Cisco CUCM and the rest of the calls to an Avaya over TDM. A good example may be a slow migration of a very large campus of Avaya to Cisco.
In this example we have only 3 phones on Cisco, and the rest of our phones on avaya. Once the calls enter the CUBE we would like to route 54321, 12345 and 43215 to CUCM and all the rest of the calls to Avaya.
The configuration snippet of our Gateway WITHOUT e164-pattern-maps is below
Dial-peer voice 10 pots Description **To Avaya** Destination-pattern ….. Port 0/3/0:23 ! Dial-peer voice 11 voip Description **To Cisco CUCM DID 1** Destination-pattern 54321 Session target ipv4:123.123.123.123 Session protocol sipv2 Dtmf-relay rtp-nte No vad ! Dial-peer voice 11 voip Description **To Cisco CUCM DID 1** Destination-pattern 12345 Session target ipv4:123.123.123.123 Session protocol sipv2 Dtmf-relay rtp-nte No vad ! Dial-peer voice 11 voip Description **To Cisco CUCM DID 1** Destination-pattern 43215 Session target ipv4:123.123.123.123 Session protocol sipv2 Dtmf-relay rtp-nte No vad !
As you can see the minimum we can do this configuration with is 4 dial-peers, what if we had to cutover 10,000 phones like this?!?! It would be a nightmare.
Now let’s look at the configuration of this using an e164-pattern-map using our custom HTTP app to host our configuration file (it actually dynamically generates it)
Voice class e164-pattern-map 100 Description EXTN to CUCM url http://server_ip/sites/1/numbers_ios ! Dial-peer voice 10 pots Description **To Avaya** Destination-pattern ….. Port 0/3/0:23 ! Dial-peer voice 11 voip Description **To Cisco CUCM** Destination e164-pattern-map 100 Session target ipv4:123.123.123.123 Session protocol sipv2 Dtmf-relay rtp-nte No vad !
That’s it!. That’s all it will ever be. Our webserver located at URL http://server_ip/sites/1/numbers_ios will host our configuration file, and will change dynamically as we add numbers through our web interface!!
The configuration file works exactly like a TCL file. It is loaded on router bootup from the remote location OR when initially configured with the e164-pattern-map command or the following command can be issued from exec mode on IOS to force a reload.
Router#voice class e164-pattern-map load
Raw Configuration File Format
It’s actually just a text file with a list of numbers or pattern. This is the exact same format as would go in a dial-peer. The ! symbol is used as a comment if wanted.
Example Below:
!!!This is a configuration file an e164-plan-map written by Chad Stachowicz
54321
12345
43215
91[2-9]…[2-9]……
The Web App
The web app really has 4 useful URLs and is super simple. It keeps a database that only has 2 tables. The ‘Sites’ table and the ‘Numbers’ table. The Site table, is really you list table… you would create a new site for any unique list you wanted to build. This can be found at http://server_ip/sites
The Numbers table is just a list of a TFN or DID, a description, its DNIS (DNIS is what is used to build the list, so if you need a pattern enter it in this field! It takes a string) and the site_id. This is what links the list to the DNIS and can be found at http://server_ip/numbers
Here is a screenshot of the specific number in a single list. http://server_ip/sites/1/numbers
Lastly here is the raw config file that IOS is reading. http://server_ip/sites/1/numbers_ios
Verification
The following command on the Cisco IOS Device will confirm the e164-pattern-map is applied.
CUBE#sh dial-peer voice 100 VoiceOverIpPeer10 peer type = voice, system default peer = FALSE, information type = voice, description = `', tag = 100, destination-pattern = `', destination e164-pattern-map tag = 100 status = valid, voice reg type = 0, corresponding tag = 0, allow watch = FALSE
The following command on the Cisco IOS Device will confirm the e-164-patter-map patterns that were loaded out of the actual configuration file.
CUBE#show voice class e164-pattern-map 100 e164-pattern-map 100 ----------------------------------------- Description: It has 3 entries It is populated from url http://192.168.1.34:3000/sites/1/numbers_ios. Map is valid. E164 pattern 1234 3233 5678
Conclusion
I am not sure I have been as excited about something in a long time, yet it is so simple! I will be recommending this as a way to cleanup a ton of CVP ingress gateways as well as help me when migrating large customers with small batch of people between phone systems. Make way for the age of SDDP, Software Defined Dial-Plans, you saw it coined here first folks! 🙂
Chad