Voice translation rules have tripped up many an engineer, especially when troubleshooting an existing router that you may not have installed. In those situations, it can be easy to misunderstand the subtleties of voice translation rules when quickly reviewing a production configuration.
So, by popular demand, this post will serve as a collection of many examples showing various methods of using voice translation rules. Check back periodically, as the number of examples on this page will grow quickly over time. As always, I'd love to have comments and suggestions for scenarios that should be included and explained.
In case you need to review the syntax of a voice translation rule, please review this earlier post that goes over syntax, including wildcards, number slicing and valid characters (and their meanings).
Applying Voice Translation-Rules
In order to apply a voice translation-rule, you must apply it to a voice translation-profile. Voice translation-profiles can then be applied in a number of ways to dial-peers and voice ports.
See a quick example below, or this very comprehensive document for much greater detail.
voice translation-rule 1
rule 1 /212/ /9/
voice translation-profile myprofile
translate calling 1
dial-peer voice 10 pots
translation-profile outgoing myprofile
Basic Match and Replace
example 1.1
In this example, only the first occurrence of the match-pattern will be changed to the replace-pattern.
voice translation-rule number
rule precedence /match-pattern/ /replace-pattern/
voice translation-rule 1
rule 1 /123/ /890/
rule 1 /123/ /890/
Matched with rule 1
Original number: 123 Translated number: 890
router#test voice translation-rule 1 1234
Matched with rule 1
Original number: 1234 Translated number: 8904
router#test voice translation-rule 1 1123
Matched with rule 1
Original number: 1123 Translated number: 1890
router#test voice translation-rule 1 1123123
Matched with rule 1
Original number: 1123123 Translated number: 1890123
example 1.2
In this example, the match-pattern will be changed to the replace-pattern only when it occurs at the beginning of a number. This is indicated by the leading "^" in the match-pattern.
voice translation-rule 1
rule 1 /^123/ /890/
router#test voice translation-rule 1 123
Matched with rule 1
Original number: 123 Translated number: 890
router#test voice translation-rule 1 1234
Matched with rule 1
Original number: 1234 Translated number: 8904
router#test voice translation-rule 1 1234123
Matched with rule 1
Original number: 1234123 Translated number: 8904123
router#test voice translation-rule 1 1123
No match. "123" does not occur at beginning.
rule 1 /^123/ /890/
router#test voice translation-rule 1 123
Matched with rule 1
Original number: 123 Translated number: 890
router#test voice translation-rule 1 1234
Matched with rule 1
Original number: 1234 Translated number: 8904
router#test voice translation-rule 1 1234123
Matched with rule 1
Original number: 1234123 Translated number: 8904123
router#test voice translation-rule 1 1123
No match. "123" does not occur at beginning.
example 1.3
In this example, the match-pattern will be changed to the replace-pattern only when it occurs at the end of a number. This is indicated by the trailing "$" in the match-pattern.
voice translation-rule 1
rule 1 /123$/ /890/
router#test voice translation-rule 1 123
Matched with rule 1
Original number: 123 Translated number: 890
router#test voice translation-rule 1 1234
No match. "123" does not occur at the end of the number.
router#test voice translation-rule 1 1234123
Matched with rule 1
Original number: 1234123 Translated number: 1234890
router#test voice translation-rule 1 1123
Matched with rule 1
Original number: 1123 Translated number: 1890
rule 1 /123$/ /890/
router#test voice translation-rule 1 123
Matched with rule 1
Original number: 123 Translated number: 890
router#test voice translation-rule 1 1234
No match. "123" does not occur at the end of the number.
router#test voice translation-rule 1 1234123
Matched with rule 1
Original number: 1234123 Translated number: 1234890
router#test voice translation-rule 1 1123
Matched with rule 1
Original number: 1123 Translated number: 1890
example 1.4
In this example, the match-pattern will be changed to the replace-pattern only when it matches exactly. This is indicated by using both the leading "^" and the trailing "$" in the match-pattern which has the combined effect of saying "match the pattern that both begins AND ends within the number".
voice translation-rule 1
rule 1 /^123$/ /890/
router#test voice translation-rule 1 123
Matched with rule 1
Original number: 123 Translated number: 890
rule 1 /^123$/ /890/
router#test voice translation-rule 1 123
Matched with rule 1
Original number: 123 Translated number: 890
router#test voice translation-rule 1 1234
No match. "123" does not occur at the end of the number.
router#test voice translation-rule 1 1123
No match. "123" does not occur at the beginning.
No match. "123" does not occur at the end of the number.
router#test voice translation-rule 1 1123
No match. "123" does not occur at the beginning.
Using Wildcards
example 2.1
Replace any number that is five digits in length that begins with "88" with the number "9999000".
voice translation-rule 1
rule 1 /^88.../ /9999000/
router#test voice translation-rule 1 88222
Matched with rule 1
Original number: 88222 Translated number: 9999000
router#test voice translation-rule 1 89123
No Match. The number does not begin with 88.
No Match. The number does not begin with 88.
router#test voice translation-rule 1 881234
No Match. The number contains too many digits.
router#test voice translation-rule 1 8812
No Match. The number contains too few digits.
example 2.2
Replace any numbers with "9995000". ".*" is a wildcard that includes all numbers, including null.
voice translation-rule 2
rule 1 /.*/ /9995000/
router#test voice translation-rule 2 123
Matched with rule 1
Original number: 123 Translated number: 9995000
router#test voice translation-rule 2 86573
Matched with rule 1
Original number: 86573 Translated number: 9995000
router#test voice translation-rule 2 ""
Matched with rule 1
Original number: <NULL> Translated number: 9995000
example 2.3
This example replaces all numbers, except null, with "9995000". ".+" includes all numbers, except null.
voice translation-rule 1
rule 1 /.+/ /9995000/
router#test voice translation-rule 1 89555
Matched with rule 1
Original number: 89555 Translated number: 9995000
router#test voice translation-rule 1 212
Matched with rule 1
Original number: 212 Translated number: 9995000
router#test voice translation-rule 1 ""
No match. <NULL> is not included in match pattern.
example 2.4
This example replaces any number that starts with a combination of eights with "999" instead of the eight(s).
voice translation-rule 5
rule 1 /^8+/ /999/
router#test voice translation-rule 5 85551212
Matched with rule 1
Original number: 85551212 Translated number: 9995551212
router#test voice translation-rule 5 885551212
Matched with rule 1
Original number: 885551212 Translated number: 9995551212
router#test voice translation-rule 5 8885551212
Matched with rule 1
Original number: 888123456 Translated number: 9995551212
router#test voice translation-rule 5 5551212
No match. Number does not begin with eight.
example 2.5
Translate any number to null, including null. The wildcard combination "^.*" matches all numbers, including null. If you had wanted to match only null, you could have used "^$".
voice translation-rule 1
rule 1 /^.*/ / /
router#test voice translation-rule 1 2001
Matched with rule 1
Original number: 2001 Translated number: <NULL>
router#test voice translation-rule 1 5551212
Matched with rule 1
Original number: 5551212 Translated number: <NULL>
router#test voice translation-rule 1 5551212
Matched with rule 1
Original number: <NULL> Translated number: <NULL>
Number Slicing (and Dicing)
Voice translation rules have the ability to slice the number into smaller parts, manipulate each part individually and then put the number back together again. This technique is called "number slicing". It can appear very complicated and gives many engineers difficulty at first, but with some practice you will soon master the technique.
example 3.1
This example is meant to provide some explanation of a typical voice translation rule using number slicing at a higher level. Consider the following rule:
/ (x\) y\ (z\) / / a \1 \2 /
- Split the matched number into three sets of x, y, and z.
- The backward slash (\) indicates the where to slice up the number.
- The brackets () indicate which sets you want to reuse in the replacement pattern.
- The a represents additional digits to insert into the replacement number.
Set 1 inherits the value of x.
Set 2 inherits the value of z.
Expression y is not reused.
The replacement number is a concatenated number: axz
example 3.2
In this example, the number of 55866 will be replaced with 85566 using number slicing. While this could be accomplished using a simpler rule, it serves our purposes here to demonstrate number slicing. Note that "^" and "$" are used to designate that the match pattern must exist at both the beginning and end of a number (essentially an explicit match).
voice translation-rule 1
rule 1 /^\(55\)8\(66\)$/ /8\1\2/
Set 1: 55
Set 2: 66
Ignore: 8
router#test voice translation-rule 1 55866
Matched with rule 1
Original number: 55866 Translated number: 85566
router#test voice translation-rule 1 12345
No match. The match pattern is not satisfied.
router#test voice translation-rule 1 55867
No match. The match pattern is not satisfied.
router#test voice translation-rule 1 55466
No match. The match pattern is not satisfied.
Manipulating Number Type and Plan
When interfacing with different telcos around the world, you will find that all are not created equally. Some will require that calls be send with a specific numbering plan for the type of call to be handled correctly. Using voice translation rules, the plan or type can be manipulated as required or the call can be blocked.
example 4.1
If a number starts with "4" and the type is "national", the rule adds "99" as a prefix. If the type is "international", the rule adds "999" as the prefix. This simulates the scenario in which the telco requires an access code when placing an national or international call.
voice translation-rule 1
rule 1 /^4/ /994/ type national national
rule 2 /^4/ /9994/ type international international
router#test voice translation-rule 1 442195555 type national
Matched with rule 1
Original number: 442195555 Translated number: 99442195555
Original number type: national Translated number type: national
Original number plan: none Translated number plan: none
router#test voice translation-rule 1 442195555 type international
Matched with rule 2
Original number: 442195555 Translated number: 999442195555
Original number type: international Translated number type: international
Original number plan: none Translated number plan: none
router#test voice translation-rule 1 842195555 type international
No Match. Does not begin with "4".
example 4.2
This rule simply matches any four-digit number that starts with "8" and adds the number "04421955" as a prefix while stripping the "8", and sets the plan to "isdn" and the type to "national".
voice translation-rule 1
rule 1 /^8\(...$\)/ /04421955\1/ type unknown national plan unknown isdn
router#test voice translation-rule 1 8150 type unknown plan unknown
Matched with rule 1
Original number: 8150 Translated number: 04421955150
Original number type: unknown Translated number type: national
Original number plan: unknown Translated number plan: isdn
router#test voice translation-rule 1 6150 type unknown plan unknown
No Match. Does not begin with 8.
router#test voice translation-rule 1 81501 type unknown plan unknown
No Match. Does not contain the correct number of digits (4).
Blocking Calls
Rejecting or blocking calls can easily be done with voice translation-rules. Add the reject keyword to the syntax as shown in these examples. The call must match the match-prefix in order to be dropped.
example 5.1
Rejects all calls starting with "900".
rule 1 reject /^900/
router#test voice translation-rule 10 8005551212
No Match. Does not begin with 900.
router#test voice translation-rule 10 9005551212
Call blocked by rule 1
Special Cases
This section contains examples that show strategies to accomplish very common digit manipulation requirements.
example 6.1
This is a very useful translation rule that will strip off all but the last 4 digits. Note that digits that will be retained must be enclosed in () within the match pattern.
rule 1 /^.*\(....\)/ /\1/
router#test voice translation-rule 1 5551212
Matched with rule 1
Original number: 5551212 Translated number: 1212
router#test voice translation-rule 1 2125551212
Matched with rule 1
Original number: 2125551212 Translated number: 1212
Suggestions Welcome
If you have a suggestion or example that should be included - please let me know! I'll give you credit and link back to your blog, website or twitter - your choice!
More Information
Voice Translations in Cisco IOS Gateways This is an 18-page PDF that goes into great detail about many types of translation rules, and how to apply them in different situations. Highly recommended!
if you want to try VTR's try this http://www.redsack.com/blogs/translation.aspx
ReplyDeleteCan you share more examples for Blocking / reject rules? Especially the international ones, like one I have shown below:
ReplyDeleterule 1 reject /^901153/ type international plan any
That's a great idea! I'll add some more uses for blocking in the near future.
ReplyDeleteMy situation is a little different. I am trying to figure out how to PERMIT calling numbers, based on ANI information, as opposed to blocking. I though maybe I could block on a negative result instead of permitting on a positive match, but I don't see where that is supported. Essentially I need a white-list, not a black-list. By default all calling numbers are blocked, EXCEPT for the ones I allow. I guess its something like an ANI ACL. Is that even possible? Oh, and to make things even more interesting, the "white-list" will probably need to reside on an ACS type external repository. First action will be to ask it if 555-1212 is allowed. If not, terminate the call. If it is, then begin a standard PPP CHAP session setup.
ReplyDeleteInteresting scenario! First, I don't know of an ACS-type method of doing this, but I'll instead focus on the Cisco IOS gateway portion of the question.
ReplyDeleteAs for the IOS gateway call blocking, check out this link: https://supportforums.cisco.com/docs/DOC-2907
I've not tested the config snippet below (and please let me know if you do) - but this may accomplish the "white list" portion of your requirements:
!
! Permit only calls from specific numbers
!
voice translation-rule 1
rule 1 /5551212/ /5551212/
rule 2 reject /.*/
!
voice translation-profile allow_certain_ani
translate calling 1
!
dial-peer 1 pots
direct-inward-dial
translation-profile incoming allow_certain_ani
this is some great stuff Dan!
ReplyDeleteGreetz,
Mohamed from Holland
Awesome post Dan,
ReplyDeleteWhat about dealing with calling other networked phone systems? as in calling other sites via a calling code ie 6788 xxxx
Good info.
ReplyDeleteHi All,
ReplyDeleteI have CCM with extention number 19100-19900. i need to add 4 line phone call with line 1 connect to GSM modem with operator A, line 2 connect to GSM modem with operator B and so on till 4 line with different mobile operator. when users make a call to external number, they should not know which line they use, but I must make sure that their call will be out from port that contain same operator with destination number. i have cisco 8925 router with 4 FXO as h323 gateway that it's FXO ports connect to each GSM modem.
Here are mobile operator prefix :
operator A : 0815
Operator B : 0856
Operator C : 0899
Operator D : PSTN (0XXX-XXXXXX)
the goal is, user should dial direct number and CCM/voice gateway will choose appropriate port
need your advise, is this possible to implement ? can you make me note, thanks
My apologies for the slow reply. First, let me start by saying that I'm not familiar with using GSM modems, but I assume the same principles will apply here.
DeleteThe FXO ports can placed in a common trunkgroup to facilitate outbound calls via a dial-peer. The dial-peer will send calls to the trunkgroup and the trunkgroup will select an available FXO to make the outbound call.
If you are trying to make the outbound "CALLING NUMBER" be the operators, so that they will get the return call themselves, it will depend upon the LEC and the service type. For example, class POTS lines will not allow this, however, some (if not most) PRI circuits will.
Assuming the GSM service provider will allow it, you'd do this using a unique external phone mask in CUCM for each operator's phone device. If the GSM service provider does not allow the CALLING NUMBER to be altered, it will default to the one assigned to the GSM modem [FXO port] that is selected by the trunkgroup.
voice-port 0/1/0
trunk-group GSM
!
voice-port 0/1/1
trunk-group GSM
!
voice-port 0/1/2
trunk-group GSM
!
voice-port 0/1/3
trunk-group GSM
!
dial-peer voice 150 pots
trunkgroup GSM
description Long Distance Dialing
destination-pattern 1[2-9]..[2-9]......
forward-digits all
!