Localization and Practical Security in Asterisk 1.4: Part 1


Let's work from the inside out. The types of call progress tones played to the callers once they are within Asterisk are set in indications.conf, which is, of course, one of the many .conf files to be found in the /etc/asterisk directory.

On opening indications.conf, you will find that the default set of tones to be used (by the pbx_indications module) is specified in the [general] section with a two letter country code.

The next example, shows the way the first few lines of the file look on a fresh installation, prior to any changes:

; indications.conf
; Configuration file for location specific tone indications
; used by the pbx_indications module.
; When adding countries to this file, please keep them in
; order according to the 2-character country codes!
; The [general] category is for certain global variables.
; All other categories are interpreted as location specific
country=us ; default location

The highlighted code shows the country specified by the two letter country code. If indications.conf is missing, Asterisk will assume that you want to use the US tone set.

There are a number of separate sections in the files, each headed with a two letter country code in square brackets, which describe the actual tones for that country in terms of frequencies and cadences, along with the odd explanation or cryptic note left there by the compiler of the tones for a given country.

Here we see the entry for the UK:

description = United Kingdom
ringcadence = 400,200,400,2000
; These are the official tones taken from BT SIN350. The actual tones
; used by BT include some volume differences so sound slightly
; different from Asterisk-generated ones.
dial = 350+440
; Special dial is the intermittent dial tone heard when, for example,
; you have a divert active on the line
specialdial = 350+440/750,440/750
; Busy is also called "Engaged"
busy = 400/375,0/375
; "Congestion" is the Beep-bip engaged tone
congestion = 400/400,0/350,400/225,0/525
; "Special Congestion" is not used by BT very often if at all
specialcongestion = 400/200,1004/300
unobtainable = 400
ring = 400+450/400,0/200,400+450/400,0/2000
callwaiting = 400/100,0/4000
; BT seem to use "Special Call Waiting" rather than just "Call
Waiting" tones
specialcallwaiting = 400/250,0/250,400/250,0/250,400/250,0/5000
; "Pips" used by BT on payphones. (Sounds wrong, but this is what BT
; claim it
; is and I've not used a payphone for years)
creditexpired = 400/125,0/125
; These two are used to confirm/reject service requests on exchanges
; that don't do voice announcements.
confirm = 1400
switching = 400/200,0/400,400/2000,0/400
; This is the three rising tones Doo-dah-dee "Special Information
; Tone",
; usually followed by the BT woman saying an appropriate message.
info = 950/330,0/15,1400/330,0/15,1800/330,0/1000
; Not listed in SIN350
record = 1400/500,0/60000
stutter = 350+440/750,440/750

So, once you have chosen your country by changing (if necessary) the two letter country code, you just need to save the file and reload.

You will now hear those tones when a call is being handled inside Asterisk. The word "inside" has been stressed as all calls are initiated outside of Asterisk, and will come in from SIP, IAX2, or analog phones, or trunks of one description or another. The nature of the tones you hear through these devices is not the responsibility of Asterisk, although Asterisk will dictate the type (busy, ringing, and so on) that you hear. Therefore, now we need to step outside of Asterisk and deal with those tones.

SIP and IAX phones are easy to deal with, as these devices generate the tones themselves. So, when you lift the handset on say, an SIP phone, you will hear a dial tone whether the device is connected to an IP telephony network or not.

Contrast this scenario to the original reason for the dial tone. The clue is in the name "dial tone". It was originally a "confidence tone" to signal to the users that they were indeed connected to a telephone exchange, and that they could now dial a number. Of course, this is still the case with traditional telephony connections. How things changed in the world of IP—all a dial tone in the earpiece of an IP phone will tell you is that your IP phone is alive, and the curly cord to the handset works.

In order to change the nature of the tones you hear from your SIP or IAX phones, you will need to change parameters on the phones themselves, usually, via their web interfaces. Asterisk only tells these telephones which tones to play (through the protocol being used for call control). It is on the phones themselves that you will need to change the tones.

We have now seen how to change the tones that Asterisk provides to calls which it is terminating, and we have seen that the tones heard through SIP and IAX phones (prior to the call being terminated by Asterisk) must be changed on the devices themselves.

Let us now consider the tones that will be used (both recognized and generated) for analog telephony. If analog devices are connected through ATAs (Analog Telephony Adaptor), then the tones will again be changed on the ATA devices themselves, as tone generation and recognition is part of their job.

However, if we connect our analog devices to Asterisk through a Digium card, we will need to configure these tones as part of the DAHDI (formerly Zaptel) setup.

In the /etc/dahdi/ directory a file called system.conf (formerly etc/zaptel.conf) will be found with the code:


We are interested in two parts of the configuration in this file—loadzone that loads a set of tones to be used with the analog card(s), you can load as many sets as you want (details of the actual tones are found in zonedata.c), and, defaultzone that defines the tone set you will use as standard when handling calls.

Remember, we are only talking about the tones that will be recognized or generated on analog channels here.

If you want to employ some tones which are loaded, but not default, this is easily done within the dialplan using the Playtones() application.

That was about the tones. Here is a quick list and a picture to help you remember:

  • Tones that will be heard once a call is inside Asterisk are chosen and specified in indications.conf
  • Tones heard on SIP or IAX phones (prior to the call being answered by Asterisk) are set on the devices themselves

Take a look at the next figure to reinforce this:


Time and date and localization

Although the actual system time and date for your Asterisk machine will only be affected by the setting in Linux, it is quite possible to make Asterisk aware of as many time zones as necessary, and to alter the way time and date are set out and spoken within Asterisk.

When you think about the need to manifest different time zones and spoken localization (other than the language itself—we'll come to that), it really occurs only in voicemail transactions.

When you are being told at what time and on which date a message was left, you will want to hear it in your local time zone, regardless of where the Asterisk server is located. Moreover, you will want to hear the time and date spoken in a way that you naturally understand, rather than having to struggle to interpret the information while it is given to you in some alien form.

Fortunately, Asterisk recognizes this fact and allows different "voicemail zones" to be set, which dictate the time zone and the way in which the time and date are announced. These settings are created in the [zonemessages] section of voicemail.conf, and further down the file, the voicemail zone for each voicemail box can be specified as an option (if required) where voicemail boxes are specified.


Here is a look inside voicemail.conf to see what we have been talking about. This example starts with comments (identified by a leading semicolon—";"), which explain each of the options that could be used to construct a voicemail zone. This is followed by the [zonemessages] section where each of the zones is set, and finally we see the use of two of the defined zones (Eastern and European), by being set as options, in the mailbox definitions at the end of the file in the following example:

; Users may be located in different timezones, or may have different
; message announcements for their introductory message when they enter
; the voicemail system. Set the message and the timezone each user
; hears here. Set the user into one of these zones with the tz=
; attribute in the options field of the mailbox. Of course, language
; substitution still applies here so you may have several directory
; trees that have alternate language choices.
; Look in /usr/share/zoneinfo/ for names of timezones.
; Look at the manual page for strftime for a quick tutorial on how the
; variable substitution is done on the values below.
; Supported values:
; 'filename' filename of a soundfile (single ticks around the
; filename required)
; ${VAR} variable substitution
; A or a Day of week (Saturday, Sunday, ...)
; B or b or h Month name (January, February, ...)
; d or e numeric day of month (first, second, ...,
; thirty-first)
; Y Year
; I or l Hour, 12 hour clock
; H Hour, 24 hour clock (single digit hours preceded by
; "oh")
; k Hour, 24 hour clock (single digit hours NOT preceded
; by "oh")
; M Minute, with 00 pronounced as "o'clock"
; N Minute, with 00 pronounced as "hundred" (US military
; time)
; P or p AM or PM
; Q "today", "yesterday" or ABdY
; (*note: not standard strftime value)
; q "" (for today), "yesterday", weekday, or ABdY
; (*note: not standard strftime value)
; R 24 hour time, including minute
; Each mailbox is listed in the form <mailbox>=<password>,<name>,
; <email>,<pager_email>,<options> if the e-mail is specified, a
; message will be sent when a message is received, to the given
; mailbox. If pager is specified, a message will be sent there as
; well. If the password is prefixed by '-', then it is considered to
; be unchangeable.
; Advanced options example is extension 4069
; NOTE: All options can be expressed globally in the general section,
; and overridden in the per-mailbox settings, unless listed otherwise.
; tz=central Timezone from zonemessages below. Irrelevant if
; envelope=no.
; attach=yes ; Attach the voicemail to the notification
; email *NOT* the pager email
; attachfmt=wav49 ; Which format to attach to the email.
; Normally this is the
; first format specified in the format parameter above, but this
; option lets you customize the format sent to particular mailboxes.
; Useful if Windows users want wav49, but Linux users want gsm.
; [per-mailbox only]
; saycid=yes ; Say the caller id information before the
; message. If not described, or set to no, it will be in the
; cidinternalcontexts=intern ; Internal Context for Name Playback
; instead of extension digits when saying caller id.
; sayduration=no ; Turn on/off the duration information before
; the message. [ON by default]
; saydurationm=2 ; Specify the minimum duration to say. Default
; is 2 minutes
; dialout=fromvm ; Context to dial out from [option 4 from
; mailbox's advanced menu].
; If not specified, option 4 will not be listed and dialing out
; from within VoiceMailMain() will not be permitted.
sendvoicemail=yes ; Allow the user to compose and send a
; voicemail while inside VoiceMailMain()
; [option 5 from mailbox's advanced menu].
; If set to 'no', option 5 will not be listed.
; searchcontexts=yes ; Current default behavior is to search only
; the default context
; if one is not specified. The older behavior was to search all
; contexts.
; This option restores the old behavior [DEFAULT=no]
; callback=fromvm ; Context to call back from
; if not listed, calling the sender back will not be permitted
; exitcontext=fromvm ; Context to go to on user exit such as * or 0
; The default is the current context.
; review=yes ; Allow sender to review/rerecord their
; message before saving it [OFF by default
; operator=yes ; Allow sender to hit 0 before/after/during
; leaving a voicemail to
; reach an operator [OFF by default]
; envelope=no ; Turn on/off envelope playback before message
; playback. [ON by default]
; This does NOT affect option 3,3 from the advanced options menu
; delete=yes ; After notification, the voicemail is deleted
; from the server. [per-mailbox only]
; This is intended for use with users who wish to receive their
; voicemail ONLY by email. Note: "deletevoicemail" is provided as
; an equivalent option for Realtime configuration.
; volgain=0.0 ; Emails bearing the voicemail may arrive in
; a volume too quiet to be heard. This parameter allows you to
; specify how much gain to add to the message when sending a
; voicemail.
; NOTE: sox must be installed for this option to work.
; nextaftercmd=yes ; Skips to the next message after hitting 7 or
; 9 to delete/save current message.
; [global option only at this time]
; forcename=yes ; Forces a new user to record their name. A
; new user is determined by the password being the same as the
; mailbox number. The default is "no".
; forcegreetings=no ; This is the same as forcename, except for
; recording
; greetings. The default is "no".
; hidefromdir=yes ; Hide this mailbox from the directory
; produced by app_directory
; The default is "no".
; tempgreetwarn=yes ; Remind the user that their temporary
; greeting is set
; vm-password=custom_sound
; Customize which sound file is used instead of the default
; prompt that says: "password"
; vm-newpassword=custom_sound
; Customize which sound file is used instead of the default
; prompt that says: "Please enter your new password followed by
; the pound key."
; vm-passchanged=custom_sound
; Customize which sound file is used instead of the default
; prompt that says: "Your password has been changed."
; vm-reenterpassword=custom_sound
; Customize which sound file is used instead of the default
; prompt that says: "Please re-enter your password followed by
; the pound key"
; vm-mismatch=custom_sound
; Customize which sound file is used instead of the default
; prompt that says: "The passwords you entered and re-entered
; did not match. Please try again."
; listen-control-forward-key=# ; Customize the key that fast-
; forwards message playback
; listen-control-reverse-key=* ; Customize the key that rewinds
; message playback
; listen-control-pause-key=0 ; Customize the key that pauses/unpauses
; message playback
; listen-control-restart-key=2 ; Customize the key that restarts
; message playback
; listen-control-stop-key=13456789 ; Customize the keys that
; interrupt message playback, probably all keys not set above
; Maximum number of messages allowed in the 'Deleted' folder. If set
; to 0
; or no then no deleted messages will be moved. If non-zero (max 9999)
; then up
; to this number of messages will be automagically saved when they are
; 'deleted' on a FIFO basis.
; defaults to being off
; backupdeleted=100
eastern=America/New_York|'vm-received' Q 'digits/at' IMp
central=America/Chicago|'vm-received' Q 'digits/at' IMp
central24=America/Chicago|'vm-received' q 'digits/at' H N 'hours'
military=Zulu|'vm-received' q 'digits/at' H N 'hours' 'phonetic/z_p'
european=Europe/Copenhagen|'vm-received' a d b 'digits/at' HM
; Define maximum number of messages per folder for partcular context.
1234 => 4242,Example Mailbox,root@localhost
6001 => 9999,David Duffett,dduffett@packt.com,,tz=european
6002 => 9999,Jared Smith,jsmith@packt.com,,tz=eastern

Changing the language of system prompts

Asterisk users know that sound files are usually kept in the /var/lib/asterisk/sounds directory. If you look into this directory on an Asterisk 1.6.x.x installation, you will find that it does not have any sounds in it at all. It actually has three subdirectories called en, es, and fr.

As you can guess, each of these subdirectories represents a language, en (English) being the default. In fact, neither es (Spanish) nor fr (French) have any prompts on installation, but are put there to show the way things are done.

You can create as many other directories as you need, such as de, nl, it, and so on for the storage of prompts in whatever language(s) you need.


Within these directories, the system prompts must be in the file names known to Asterisk. So, the file called /var/lib/asterisk/sounds/en/hello.gsm will contain "Hello" whereas the file called /var/lib/asterisk/sounds/fr/hello.gsm will contain "Bonjour".

You may have already seen this principal at work—some prompt companies offer a standard package of Asterisk sounds in a given language or accent, which are all recorded in the standard filenames. Thus, they can be dropped into the appropriate directory, and you are ready to go.

The way you select the prompts to be used during a call is by specifying it in the concerned channel configuration file.

In sip.conf and iax.conf, you can set the language in the [general] section of the files:

language=en ;default language
Or you can set the language for a given user:
language=fr ;user-specific language

Thus you can have a default language (as identified in the [general] section) and/or select a language for each specific user, and as a call comes in through that channel, the language will be set.

The same is true for DAHDI channels. You can set the default language channel-specific languages in the [channels] section of chan_dahdi.conf:

language=en ;default language
channels=>24 ;channel-specific language

There you have it, a very short section, because changing the language of your prompts or using multiple language prompts in Asterisk is very easy.


The most important thing to do concerning the localization of the telephony systems you implement, is to walk in your customer's (and their customers') shoes. This means that you go through every contact and scenario that they would go through with the system (making a call, retrieving a voicemail, and so on) to ensure that everything sounds and appears "normal" to them.

Customers will have certain expectations when they pick up a phone. If that phone is on your system, then it's your job to meet those expectations such as familiar dial tone, local language/accent announcements, and so on.

In the next part, we will cover local telephony interfaces, localizing caller ID signaling on Digium analog interfaces, checklist for applying localizations to your Asterisk-based solutions, and security measures.

You've been reading an excerpt of:

Asterisk 1.4 - The Professional's Guide

Explore Title