Audible Diagnostics

[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(1)]

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.

Console Administration

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

Logs

Many messages from the dialplan (errors/info) are logged so refer the log files for historical messages.

$ sudo tail -f /var/log/asterisk/messages

Verbose and NoOp

[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})

Dialplan Console command

voip2*CLI> core show help dialplan
dialplan 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

reload

One of the things we have to remember, whenever you update your dialplan (e.g. /etc/asterisk/extensions.conf or any #include ) we need to load the new configuration into the running application.

server*CLI> dialplan reload

show

We 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 @ then you can use just the "@" without a context and Asterisk will try to find the context your number would be appropriately handled.

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' failed

I 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.

Diagnostics Dialplan

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.conf

We 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.conf

File: /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)

Main Menu

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.

  • 2 - Provide some background/information on this demonstration
  • 3 - Change the language if language files have been installed.
  • 500 - Call Digium and test whether the system can dial the Internet
  • 600 - Echo Test, hear the effect of latency on our call.
  • 601 - Tell us the time

Calling Internet Phone Company (e.g. Digium)

[ 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.

  • Dial(IAX2/guest@pbx.digium.com/s@default) ; Call the Asterisk demo

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 restart

To reload the IAX2 module from the Asterisk CLI.

*CLI> module load chan_iax2
Loaded chan_iax2

Once you've correctly configured IAX, please dial extension 500 to dial Digium, the Asterisk company.

Echo Test

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.

Time Test

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.conf

We 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.conf

File: /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)

Diagnostics - Menu Options

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.

  • 2 - Provide some background/information on this demonstration
  • 3 - Change the language if language files have been installed.
  • 500 - Call Digium and test whether the system can dial the Internet
  • 600 - Echo Test, hear the effect of latency on our call.
  • 601 - Tell us the time

Calling Internet Phone Company (e.g. Digium)

[ 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.

  • Dial(IAX2/guest@pbx.digium.com/s@default) ; Call the Asterisk demo

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 restart

To reload the IAX2 module from the Asterisk CLI.

*CLI> module load chan_iax2
Loaded chan_iax2

Once you've correctly configured IAX, please dial extension 500 to dial Digium, the Asterisk company.