Section 17.5. The Asterisk CLI

17.5. The Asterisk CLI

Asterisk's CLI is where you, the administrator, control and monitor the Asterisk PBX. The Asterisk CLI provides you with real-time information about voice channels, extensions, contexts, and more. Using the CLI, you can start and stop the Asterisk server, as described earlier in the chapter. You can do status queries about the voice channels, place and hang up calls, and add or remove extensions and contexts.

If the Asterisk server is already running, you can launch the Asterisk CLI by starting another instance of Asterisk in client mode:

 #  asterisk -r  

The first command you should probably learn is help , which displays a list of valid commands or, when used as follows , gives command-specific assistance:

 pbx*CLI>  help show channels  

Notice the pbx*CLI> prompt. This prompt will vary depending on the Unix hostname of your machinein this case, it's pbx .

17.5.1. Inspecting Channels

There are several types of voice channels in Asterisk. There can be analog FXO (foreign exchange office) channels, such as those facilitated by a POTS telephone company line and an X100P card. There can also be voice channels provided by H.323, SIP, IAX, SCCP, and MGCP (all different VoIP signaling protocols), as well as by FXS (foreign exchange station) devices like QuickNet's Phone Jack interface card and PRI interfaces, too.

You can use the Asterisk CLI to inspect each type of channel, but the details provided are different for each:

  • zap show channels

  • iax2 show channels

  • sip show channels

Each of these commands provides a list of channel numbers that can correspond to a numeric reference in the channel name , as described earlier (example: Zap/1 ). Take a look at a zap show channels command:

 pbx*CLI>  zap show channels  Chan. Num. Extension  Context    Language   MusicOnH       1                   incoming              default 

The command output shows that there is a single Zaptel channel available for use by the Asterisk PBX. In our experimental server, this logical channel represents the physical X100P interface with a telco line connected to it. The command output tells that the context for calls on this channel is incoming because the start extension in extensions.conf is established within that context. This channel is referred do in the dial-plan as Zap/1 .

You can dig deeper using the CLI, to the configuration of a specific channel, by running the zap show channel <channel#> command, like this:

 pbx*CLI>  zap show channel 1  Channel: 1     File Descriptor: 17     Span: 1     Extension:     Context: incoming     Caller ID string:     Destroy: 0     Signalling Type: FXS Kewlstart     Owner: <None>     Real: <None>     Callwait: <None>     Threeway: <None>     Confno: -1     Propagated Conference: -1     Real in conference: 0     DSP: no     Relax DTMF: yes     Dialing/CallwaitCAS: 0/0     Default law: ulaw     Fax Handled: no     Pulse phone: no     Echo Cancellation: 128 taps, currently OFF     Actual Confinfo: Num/0, Mode/0x0000 

There are many channel-specific settings, most of which are user -definable. You can see from this list that, even within the scope of a single Zaptel channel, Asterisk is extremely flexible. In our test server, this channel is an FXO channelthat is, a channel that connects to the telephone company. In order to interact correctly with the phone company's switch, the X100P (or other compatible) interface has to use FXS signaling, so that, to the phone company, it appears to be a regular telephone answering the line and not a newfangled Asterisk server (FXO/FXS signaling was introduced in Chapter 4). Other types of channels (SIP, H.323, etc.) have their own channel-specific settings.

17.5.2. Inspecting the Dial-Plan

The show dialplan CLI command can be used two ways: showing the entire system-wide dial-plan, or only showing a specific context or extension. Here's the output for a small, but complete, dial-plan:

 pbx*CLI>  show dialplan  [ Context 'default' created by 'pbx_config' ]       '3101' =>         1. Dial(SIP/3101@       [pbx_config]                         2. Voicemail(u4101)                [pbx_config]       '3102' =>         1. Dial(SIP/3102@       [pbx_config]                         2. Voicemail(u4101)                [pbx_config]       '3103' =>         1. Dial(SIP/3103@       [pbx_config]                         2. Voicemail(u4101)                [pbx_config]       '8500' =>         1. VoiceMailMain( )                 [pbx_config]       '_9NXXXXXX' =>    1. Dial(${PSTN}/{EXTEN:1})         [pbx_config]                         2. Congestion( )                    [pbx_config]       Ignore pattern => '9'                                 [pbx_config]     [ Context 'incoming' created by 'pbx_config' ]       's' =>            1. Answer( )                        [pbx_config]                         2. Dial(SIP/3103@    [pbx_config]                         3. Voicemail(u4101)                [pbx_config]                         4. Hangup( )                        [pbx_config] 

In the default context, several extensions are configured to ring calls on specific SIP telephones with static IP addresses and an extension pattern that matches outbound calls. The 8500 extension is one that allows private users of the Asterisk system to access the voice mail management greeting.

There's also an incoming context that attempts to ring a certain phone with the s extension and then transfers the call on the current channel to a voice mailbox if nobody answers the phone.

To get a specific extension's dial-plan only, run the show dialplan CLI command with an argument of extension@context :

 pbx*CLI> s  how dialplan 3102@default  [ Context 'default' created by 'pbx_config' ]       '3102' =>         1. Dial(SIP/3102@        [pbx_config]                         2. Voicemail(u4101)                 [pbx_config] 

In this case, only the extension definition for 3102 in the default context is shown.

17.5.3. Administering the Dial-Plan Using the CLI

Earlier, we covered the primary configuration file for the dial-plan: extensions.conf . You can also alter the dial-plan using CLI commands. The difference between using the CLI and using the configuration file is this: CLI dial-plan changes, such as additions and removals of extensions, occur immediately, whereas changes to extensions.conf require a restart of Asterisk (or at least a config-reload), which introduces downtime.

Consider the following CLI command:

 pbx*CLI>  add extension 120,1,Dial(SIP/ into local  

The command add extension is followed by the same definition string you would see in an exten directive in extensions.conf that is, the extension number, priority, and application command for the extension. The final part, into local , tells Asterisk which context to add the extension intoin this case, local .

The CLI can also be used to drop extensions, using the remove extension command, and to re-create the extensions.conf file based on the current "live" dial-plan, using the save dialplan command.

If you prefer to use the configuration file to maintain your dial-plan, you can avoid total Asterisk restarts by issuing a reload extensions command, which re-reads the extensions.conf file and affects the dial-plan accordingly . That said, using the CLI may be the preferred method for programming the dial-plan, because it gives you immediate feedback in case of syntax errors or other common mistakes. In order to save changes made at the CLI, your extensions.conf must contain the writeprotect=no setting in its general section, and you must issue a save dialplan command at the CLI. This will cause the current dial-plan configuration to overwrite anything in your extensions.conf file (including comments).

17.5.4. CLI Command Reference Administrator commands


Execute the following shell command. Example:

 pbx*CLI>  !ls AM*  AMP-1.10.002.tar     AMP-1.10.002 

abort halt

Cancel a running halt.

add extension

Add new extension into context. The spec of the extension is the same as it would be in extensions.conf .

add ignorepat

Add a new ignore pattern to the specified context.

 Pbx*CLI>  add ignorepat _25XX into default  

add indication

Create the given indication to the country specified. The indication is a tonelist similar to those found in indications .conf .

 Pbx*CLI>  add indication us busy 480+620/500.0/500  

debug channel

Enable debugging on a specific channel.

dont include

Remove a specified include from the named context.

 Pbx*CLI>  dont include longdistance in localonly  


Display help list or specific help on a commandi.e., help dont include .

include context

Include context in other context.

 Pbx*CLI>  include tollfree in localonly  


Load the specified Asterisk module.

logger reload

Reopen logfiles. For use after rotating the logfiles.


Shows information about currently ongoing conference calls, if any.

no debug channel

Disable debugging on the specified channel.

pri debug span

Enable debugging on a span that uses PRI.

 Pbx*CLI>  pri debug span 1  

pri intense debug span

Enable detailed PRI debugging on a span.

pri no debug span

Disables PRI debugging on a span.

remove extension

Remove the specified extension.

remove ignorepat

Remove the specified ignore pattern from the specified context.

 Pbx*CLI>  remove ignorepat _25XX from default  

remove indication

Remove the given indication from the country (see add indication ).

save dialplan

Overwrite your current extensions.conf file from the current state of the dialplan based on the commands you've issued at the CLI.

set verbose

Set level of verbosity for messages displayed on the console: means display as few as possible; 9 means display a lot of detail. This has the same effect as launching asterisk -vvvvvvvvv at the shell prompt.

show agents

Show status of agents. Agents are named users of the system.

show applications

Show all registered applicationsi.e., available dial-plan commands.

show application

Show a synopsis of the specified application.

show channel

Display information about the specified channel.

show channels

Show information about all channels.

show codecs

Display information about codecs.

The show codecs command doesn't indicate which codecs your system is using or can use. It just provides information about binary and decimal tokens used to refer to codecs within Asterisk.

show dialplan

Show the entire dial-plan or, if a context is specified, show only the dial-plan for that context.

show indications

Show a list of all countries and indication tones, per indications.conf .

show manager commands

Show a list of Asterisk Manager API commands.

show manager command

Show a synopsis of the specified Manager API command.

show manager connected

Show a list of connected Manager API users.

show parkedcalls

Display a list of currently parked calls.

show queues

Show a report of queue activity, including the current status of the queue and the utilization of each agent that receives calls from the queue.

show translation

Display codec transcoding matrix, a grid of latency times incurred by transcoding one channel's codec into another's.

show voicemail users

List active voice mailboxes, according to /etc/asterisk/voicemail.conf .

show voicemail zones

List active voice mail zones, according to /etc/asterisk/voicemail.conf .

soft hangup

Request a hangup on the specified channel, similar to SoftHangup( ) . Process control commands

extensions reload

Reload extensions and only extensions (not channels/peers).


Reload configuration, including channels/peers.

restart now

Restart Asterisk immediately, disconnecting all calls in progress.

restart when convenient

Restart Asterisk when there are no active calls, but not before.

show modules

List running modules and information about them.

show uptime

Show the Asterisk PBX's uptime, which may vary from the OS uptime.

show version

Display the Asterisk version.

stop now

Shut down Asterisk immediately, disconnecting all current calls in progress.

stop when convenient

Shut down Asterisk when there are no calls, but not before.


Unload an Asterisk module by name. AGI commands

dump agihtml

Print a list of AGI commands in HTML format.

show agi

Show AGI commands or specific help on a particular AGI command. Database commands

database del

Remove an Asterisk database key/value.

database deltree

Remove an Asterisk database key tree/value.

database get

Get an Asterisk database value, like DBGet( ) .

database put

Add/update an Asterisk database value, like DBPut( ) .

database show

Show the Asterisk database contents. IAX v2 commands

iax2 debug

Enable IAX2 debugging, dumping all IAX protocol debug info to the console.

iax2 no debug

Disable IAX2 debugging.

iax2 set jitter

Set IAX2 jitter buffer to a certain maximum length. Can be optionally supplied a call ID so that it only applies to a certain call.

iax2 show cache

Display IAX2 cached dial-plani.e., IAX2 destinations for which recent lookups have occurred, so calls can be connected without resolving them again.

iax2 show channels

Show the currently active IAX2 channels.

iax2 show peers

Show all defined IAX2 peers, per /etc/asterisk/iax.conf .

iax2 show registry

Show the status of IAX2 peers for which this server is a clienti.e., show a list of servers to whom this server is registered as an IAX2 client.

iax2 show stats

Display real-time statistics about IAX2 packets.

iax2 show users

Show all defined IAX2 users, per iax.conf .

iax2 trunk debug

Request an IAX2 trunk debug. IAX v1 commands

IAX Version 1 is deprecated. Use IAX Version 2 instead.

iax debug

Enables IAX (Version 1) debugging. Debug output goes to the console.

iax no debug

Disables IAX debugging.

iax set jitter

Sets IAX jitter buffer like IAX2 set jitter .

iax show cache

Displays IAX cached dial-plan like IAX2 show cache .

iax show channels

Shows active IAX channels like IAX2 show channels .

iax show peers

Shows defined IAX peers.

iax show registry

Shows the status of IAX peers for which this server is a client.

iax show stats

Displays real-time IAX statistics.

iax show users

Shows defined IAX users. Crypto commands

init keys

Initializes RSA key pass codes.

show keys

Displays RSA key information for peers with whom RSA keys are used in authentication. H.323 commands

H.323 media channels are supported by Asterisk but does not compile by default. Installation instructions for H.323 support are found in /usr/src/asterisk/channels/h323/README . Asterisk cannot act as an H.323 gatekeeper, only as a gateway. A fully H.323 VoIP network would also need an H.323 gatekeeper, such as the excellent GnuGK, which is covered in Chapter 7.

h.323 debug

Enable H.323 debugging if the H.323 module is installed.

h.323 gk cycle

Manually register with an external gatekeeper.

h.323 hangup

Manually hang up the specified call.

h.323 no debug

Disable H.323 debugging.

h.323 no trace

Disable H.323 stack tracing.

h.323 show codecs

Show available codecs.

h.323 trace

Enable H.323 stack tracing. SIP commands

SIP support is built in to Asterisk via the chan_sip module, which comes with it. Asterisk can act as a SIP proxy, a SIP registrar, and a SIP client. Named SIP call routes, which are created in /etc/asterisk/sip.conf , are called SIP peers, and their destinations can be SIP phones or other SIP servers. (Refer to "SIP Channels," earlier in this chapter.)

sip debug

Enables SIP debugging. Debug output goes to the console.

sip no debug

Disables SIP debugging.

sip reload

Reloads SIP configs , including peer changes, from sip.conf .

sip show channels

Shows active SIP channelsi.e., current ongoing calls.

sip show channel

Shows information about a SIP channel.

sip show inuse

Shows real-time call volume of each SIP peer.

sip show peers

Shows defined SIP peers that can register with the Asterisk server's SIP registrar.

sip show registry

Shows SIP registration status (when Asterisk registers as a client to a SIP registrar).

sip show users

Shows defined SIP users per sip.conf . MGCP channel commands

The Media Gateway Control Protocol is supported by Asterisk out of the box. The MGCP module is included in the standard distribution. MGCP channels are configured in /etc/asterisk/mgcp.conf .

mgcp audit endpoint

Displays the capabilities of the specified MGCP endpoint.

mgcp debug

Enables MGCP debugging. Debug output goes to the console.

mgcp no debug

Disables MGCP debugging.

mgcp show endpoints

Shows defined MGCP endpoints/peers. SCCP channel commands

SCCP (Skinny Client Control Protocol) is a leg-only signaling protocol for VoIP endpoints. It is supported most prominently by all Cisco IP phones, among others. The chan_skinny Asterisk module provides SCCP compatibility.

skinny debug

Enables SCCP (skinny) debugging.

skinny no debug

Disables SCCP (skinny) debugging.

skinny show lines

Shows SCCP lines on each registered client. CAPI channel commands

CAPI channels are used to support BRI channels with Asterisk. The CAPI module can be obtained from

capi debug

Enables CAPI debugging.

capi no debug

Disables CAPI debugging.

capi info

Shows CAPI information. Zaptel channel commands

Zaptel interface hardware for POTS, FXO/FXS, T1, and E1 links is manufactured by Digium, and it is supported natively by Asterisk using the chan_zap module, which is loaded by default when you install it.

zap destroy channel

Destroys the specified channel.

zap show channel

Shows information about a particular Zaptel channel.

zap show channels

Shows active Zaptel channels.

Switching to VoIP
Switching to VoIP
ISBN: 0596008686
EAN: 2147483647
Year: 2005
Pages: 172

Similar book on Amazon © 2008-2017.
If you may any questions please contact us: