[Ref: OpenBSD 5.5, Asterisk 11.9 (from ports), Asterisk the Definitive Guide, Secure Communications with OpenBSD and Asterisk, Asterisk: The Future of Telephony, pkg_add(5)]
Table of Contents
Providing users and support staff with tools to assist in diagnosing problems with the phone system can’t be bad can it?
The Telephony Administrator (support staff) with access to the console have a number of tools available to them, and a well constructed “diagnostics” context will allow diagnosing issues by calling, interacting with the PBX.
For support staff with access to the console, there are two methods of improving visability of what the dialplan is doing.
a. Check the logs b. Add Screen Output messages to you dialplan c. Use the dialplan console command
Many messages from the dialplan (errors/info) are logged so refer the log files for historical messages.
$ sudo tail -f /var/log/asterisk/messages[Ref: The Verbose and NoOp Applications]
Our dialplans are sprinkled with a number of lines which only serve the purpose of printing information to the command-line console.
The current recommendation is to use the Verbose() application as it gives the console user greater control of when to view the errors.
NoOp(message) : displays message when verbosity level is 3 or higher. Verbose([level,]message) : displays message when verbosity level is [level] or higher. Default for ’level’ is 0.
exten => stdexten-CONGESTION,1,Verbose(1,Congestion)
exten => stdexten-BUSY,1,NoOp(Busy)[Ref: Variables] The verbose mode of the Asterisk Console will give you a lot of information, step-by-step feedback, but some things require explicit notes, such as finding out what the actual status of a call returns.
File extract: extensions.conf
exten => _X.,1,NoOP(1st line)
same => n,Dial(${EXTEN})
same => n,Verbose(1,Status Return: ${DIALSTATUS})voip2*CLI> core show help dialplandialplan add extension -- Add new extension into context dialplan add ignorepat -- Add new ignore pattern dialplan add include -- Include context in other context dialplan debug -- Show fast extension pattern matching data structures dialplan reload -- Reload extensions and *only* extensions dialplan remove context -- Remove a specified context dialplan remove extension -- Remove a specified extension dialplan remove ignorepat -- Remove ignore pattern from context dialplan remove include -- Remove a specified include from context dialplan save -- Save current dialplan into a file dialplan set chanvar -- Set a channel variable dialplan set extenpatternmatchnew false -- Use the Old extension pattern matching algorithm. dialplan set extenpatternmatchnew true -- Use the New extension pattern matching algorithm. dialplan set global -- Set global dialplan variable dialplan show chanvar -- Show channel variables dialplan show globals -- Show global dialplan variables dialplan show -- Show dialplan
One of the things we have to remember, whenever you update your dialplan
(e.g. /etc/asterisk/extensions.conf or any #include
server*CLI> dialplan reloadWe use dialplan show with the following options
server*CLI> dialplan show <exten>@<context>Use the above to drill down on what the dialplan will do, as opposed to how you think the dialplan will do things.
When you don’t have the explicit @
For example:
I want to see whether an extension is picked up by the system.
server*CLI> dialplan show 6521@[ Context 'dial_trunk' created by 'pbx_config' ]
'_X.' => .
.
[ Content 'localexten' created by 'pbx_config' ]
'_X.' => .
.
[ Content 'dial_branch' created by 'pbx_config' ]
'_X.' => .
.
[ Content 'internal' created by 'pbx_config' ]
'_65XX' => .
.Whoa, that’s surprising.
Basically, the number can be picked up by a number of contexts, depending on who comes first and how each of the above context’s are reached.
I ignore the 1st three contexts, because they are contexts called by extensions (i.e. a call will not fall through to those extensions.)
So, the only valid context from the above list is ‘internal’. SUCCESS.
I want to see if I can call home? 0211111111 (yes, that is not a valid number)
server*CLI> dialplan show 0211111111@[ Context 'dial_trunk' created by 'pbx_config' ]
'_X.' => .
.
[ Content 'localexten' created by 'pbx_config' ]
'_X.' => .
.
[ Content 'dial_branch' created by 'pbx_config' ]
'_X.' => .
.Oops, looks like that number can never be reached? Why?
If we take a look at the message file, we should see something like the below:
File extract: /var/log/asterisk/messages
[date] NOTICE[nnnnn] chan_sip.c: Call from '6521' (my-ip-address) to extension '0211111111' rejected because extension not found in context 'authorised-domestic'
Where ‘authorised-domestic’ is the special context for phones/extensions in our environment that are allowed to make calls to the domestic phone system.
Why can’t I call out? 02-1111-1111 is my home number!!!! I call it all the time!!!
server*CLI> dialplan show 0211111111@authorised-domestic
There is no existence of 0211111111@authorised-domestic
Command 'dialplan show 0211111111@authorised-domestic' failedI wrack my brain, to realise that our defined dialplans require a ‘0’ as a prefix for calling external numbers (211111111) is not a valid numbering sequence in Australia.
Some people choose ‘9’ as the outgoing call ‘prefix,’ the important thing is that the above will lead you to the failure, we still have to think it through.
server*CLI> dialplan show 00211111111@[ Context 'dial_trunk' created by 'pbx_config' ]
'_X.' => .
.
[ Content 'localexten' created by 'pbx_config' ]
'_X.' => .
.
[ Content 'dial_branch' created by 'pbx_config' ]
'_X.' => .
.
[ Content 'domestic' created by 'pbx_config' ]
'_00[235678]XXXXXXXX' => 1. Goto(dial_trunk,${EXTEN},1) [pbx_config]
[ Included Content 'domestic' created by 'pbx_config' ]
'_00[235678]XXXXXXXX' => 1. Goto(dial_trunk,${EXTEN},1) [pbx_config]Ahhhh, so I can call home (with the outgoing call ‘prefix’ which is ‘0’) but I need to somehow be part of the ‘domestic’ context, which is included by at least one other context.
The following are adaptations from the standard configurations that I’m deploying, and helps you validate certain performance metrics as you update/change your system.
File: /etc/asterisk/extensions.conf
[default]
;-- block-comment
stuff left out
--;
exten => *901,1,Goto(diagnostics,s,1)
#include dialplan/diagnostics.confWe add a new dial extension *901 that will use the Goto application to continue at a new context [diagnostics]
We’re not going to copy/paste the base [demo] into the production extensions.conf but use a diaplan option to "#include" configurations from external files.
; You can include other config files, use the #include command ; (without the ';'). Note that this is different from the "include" command ; that includes context within other contexts. The #include works ; in all asterisk configuration files.
The sample [demo] dialplan context demonstrates features that users and support staff can use to ‘validate’ the phone system so we’re calling it [diagnostics] and plan to extend it in production.
$ sudo mkdir -p /etc/asterisk/dialplan/
$ sudo vim /etc/asterisk/dialplan/diagnostics.confFile: /etc/asterisk/dialplan/diagnostics.conf
[diagnostics]
exten => s,1,Wait(1) ; Wait a second, just for fun
same => n,Answer ; Answer the line
same => n,Set(TIMEOUT(digit)=5) ; Set Digit Timeout to 5 seconds
same => n,Set(TIMEOUT(response)=10) ; Set Response Timeout to 10 seconds
same => n(restart),BackGround(demo-congrats) ; Play a congratulatory message
same => n(instruct),BackGround(demo-instruct) ; Play some instructions
same => n,WaitExten ; Wait for an extension to be dialed.
exten => 2,1,BackGround(demo-moreinfo) ; Give some more information.
same => n,Goto(s,instruct)
exten => 3,1,Set(LANGUAGE()=fr) ; Set language to french
same => n,Goto(s,restart) ; Start with the congratulations
;
; Create an extension, 500, for dialing the Digium/Asterisk demo.
;
exten => 500,1,Playback(demo-abouttotry); Let them know what's going on
same => n,Dial(IAX2/guest@pbx.digium.com/s@default) ; Call the Asterisk demo
same => n,Playback(demo-nogo) ; Couldn't connect to the demo site
same => n,Goto(s,instruct) ; Return to the start over message.
;
; Create an extension, 600, for evaluating echo latency.
;
exten => 600,1,Playback(demo-echotest) ; Let them know what's going on
same => n,Echo ; Do the echo test
same => n,Playback(demo-echodone) ; Let them know it's over
same => n,Goto(s,instruct) ; Start over
;
; Create an extension, 601, for saying the time.
;
exten => 601,1,Answer()
same => n,Playback(welcome)
same => n,Playback(current-time-is)
same => n,SayUnixTime(,,kMbdY)
same => n,Playback(vm-goodbye)
same => n,Goto(s,instruct)Inside the [diagnostics] context, WaitExten waits for the user to enter an extensions on the dialpad.
same => n,WaitExten Our basic system supports the following extensions. Once we’ve dialed into the diagnostics context, we can enter the following extensions and follow the PBX response.
[ Ref: iax.conf]
If your Asterisk box has unlimited outgoing connections to the Internet, then the extension 500 will be enlightening. It is a very simple demonstration of how more powerful Asterisk can be.
File extract: ./dialplan/diagnostics.conf
exten => 500,1,Playback(demo-abouttotry); Let them know what's going on
same => n,Dial(IAX2/guest@pbx.digium.com/s@default) ; Call the Asterisk demo
same => n,Playback(demo-nogo) ; Couldn't connect to the demo site
same => n,Goto(s,6) ; Return to the start over message.Dial extension 500 and the Asterisk host will play the audio recording “demo-abouttotry” before it attempts to connect with Digium’s Internet based demonstration system.
To get the above demonstration working, you need to have a valid iax.conf configuration file, such that the IAX modules are loaded. The simplest solution is to use the sample configuration file.
Sample configuration is at: /usr/local/share/examples/asterisk/default/iax.conf
File: /etc/asterisk/iax.conf
[general]
bandwidth=low
disallow=lpc10
jitterbuffer=no
forcejitterbuffer=no
autokill=yes
After you’ve copied the files to its new location, you can either restart asterisk or manually load the module on the console.
To restart Asterisk from the Unix Shell.
$ sudo /etc/rc.d/asterisk restartTo reload the IAX2 module from the Asterisk CLI.
*CLI> module load chan_iax2Loaded chan_iax2
Once you’ve correctly configured IAX, please dial extension 500 to dial Digium, the Asterisk company.
The echo test repeats back your audio to give you a ‘sense’ indication of the latency of voice traffic between you and the PBX.
Obviously, if the audio is response is delayed or ‘choppy’ then there is either a problem with the capabilities of your network, or potentially the box running the PBX is heavily loaded.
Remember, network problems do include the ability of your PBX box to process network traffic.
Another use of the Echo Test is to confirm the configuration of RTP is correct. If you connect and either you can’t here the recording, or the echo test does not work at all (no echo responses) then there is something wrong with the RTP traffic between destination points.
I just wanted to play around with a function other than the standard telephony.
With multiple PBXs at different timezones, this function does give my users audio feedback about the time configuration on the server, which is related to the timestamp they will recieve in voicemail.
We can check that our system is recieves calls and sends us through, by creating another device user/account and calling between our two phones.
For our example, purpose, we want to be able to test the phone system without requiring another user/device is also connected. To achieve this we are adapting the [demo] dial plan from the sample configuration.
We want to reach our new configuration items, so we add the following to our [default] dialplan context.
File: /etc/asterisk/extensions.conf
[default]
;-- block-comment
stuff left out
--;
exten => *901,1,Goto(diagnostics,s,1)
#include dialplan/diagnostics.confWe add a new dial extension *901 that will use the Goto application to continue at a new context [diagnostics]
We’re not going to copy/paste the base [demo] into the production extensions.conf but use a diaplan option to "#include" configurations from external files.
; You can include other config files, use the #include command ; (without the ';'). Note that this is different from the "include" command ; that includes context within other contexts. The #include works ; in all asterisk configuration files.
The sample [demo] dialplan context demonstrates features that users and support staff can use to ‘validate’ the phone system so we’re calling it [diagnostics] and plan to extend it in production.
$ sudo mkdir -p /etc/asterisk/dialplan/
$ sudo vim /etc/asterisk/dialplan/diagnostics.confFile: /etc/asterisk/dialplan/diagnostics.conf
[diagnostics]
exten => s,1,Wait(1) ; Wait a second, just for fun
same => n,Answer ; Answer the line
same => n,Set(TIMEOUT(digit)=5) ; Set Digit Timeout to 5 seconds
same => n,Set(TIMEOUT(response)=10) ; Set Response Timeout to 10 seconds
same => n(restart),BackGround(demo-congrats) ; Play a congratulatory message
same => n(instruct),BackGround(demo-instruct) ; Play some instructions
same => n,WaitExten ; Wait for an extension to be dialed.
exten => 2,1,BackGround(demo-moreinfo) ; Give some more information.
same => n,Goto(s,instruct)
exten => 3,1,Set(LANGUAGE()=fr) ; Set language to french
same => n,Goto(s,restart) ; Start with the congratulations
;
; Create an extension, 500, for dialing the Digium/Asterisk demo.
;
exten => 500,1,Playback(demo-abouttotry); Let them know what's going on
same => n,Dial(IAX2/guest@pbx.digium.com/s@default) ; Call the Asterisk demo
same => n,Playback(demo-nogo) ; Couldn't connect to the demo site
same => n,Goto(s,instruct) ; Return to the start over message.
;
; Create an extension, 600, for evaluating echo latency.
;
exten => 600,1,Playback(demo-echotest) ; Let them know what's going on
same => n,Echo ; Do the echo test
same => n,Playback(demo-echodone) ; Let them know it's over
same => n,Goto(s,instruct) ; Start over
;
; Create an extension, 601, for saying the time.
;
exten => 601,1,Answer()
same => n,Playback(welcome)
same => n,Playback(current-time-is)
same => n,SayUnixTime(,,kMbdY)
same => n,Playback(vm-goodbye)
same => n,Goto(s,instruct)Inside the [diagnostics] context, WaitExten waits for the user to enter an extensions on the dialpad.
same => n,WaitExten Our basic system supports the following extensions. Once we’ve dialed into the diagnostics context, we can enter the following extensions and follow the PBX response.
[ Ref: iax.conf]
If your Asterisk box has unlimited outgoing connections to the Internet, then the extension 500 will be enlightening. It is a very simple demonstration of how more powerful Asterisk can be.
File extract: ./dialplan/diagnostics.conf
exten => 500,1,Playback(demo-abouttotry); Let them know what's going on
same => n,Dial(IAX2/guest@pbx.digium.com/s@default) ; Call the Asterisk demo
same => n,Playback(demo-nogo) ; Couldn't connect to the demo site
same => n,Goto(s,6) ; Return to the start over message.Dial extension 500 and the Asterisk host will play the audio recording “demo-abouttotry” before it attempts to connect with Digium’s Internet based demonstration system.
To get the above demonstration working, you need to have a valid iax.conf configuration file, such that the IAX modules are loaded. The simplest solution is to use the sample configuration file.
Sample configuration is at: /usr/local/share/examples/asterisk/default/iax.conf
File: /etc/asterisk/iax.conf
[general]
bandwidth=low
disallow=lpc10
jitterbuffer=no
forcejitterbuffer=no
autokill=yes
After you’ve copied the files to its new location, you can either restart asterisk or manually load the module on the console.
To restart Asterisk from the Unix Shell.
$ sudo /etc/rc.d/asterisk restartTo reload the IAX2 module from the Asterisk CLI.
*CLI> module load chan_iax2Loaded chan_iax2
Once you’ve correctly configured IAX, please dial extension 500 to dial Digium, the Asterisk company.