texto16.pdf

8/11/2019 texto16.pdf

1/31

8/11/2019 texto16.pdf

2/31

echo SAY ALPHA "Helio World.........read RESPONSE

exit O

Now, cali extensin 500 with AGI debugging turned on and listen to Allison spell out

Helio World:

*CLI> agi set debug on

AGI Debugging Enabled

-- Executing [500@phones:l] AGI("SIP/0004F2060EB4-00000009",

"hello-world.sh") in new stack

-- Launched AGI Script /var/lib/asterisk/agi-bin/hello-world.sh

AGI Tx

AGI Tx

AGI Tx

AGI Tx

AGI Tx

AGI Tx

AGI Tx

AGI Tx

AGI Tx

AGI Tx

AGI Tx

AGI Tx

< SIP/0004F 2060E B4-00000009 >AGI Tx

AGI Tx

AGI Tx

AGI Tx

AGI Tx

AGI Tx

AGI Tx

AGI Tx

AGI Tx

AGI Rx

AGI Tx

< SIP/0004F 2060EB4-00000009 >AGI Rx

-- Playing

-- Playing

-- Playing

-- Playing

-- Playing-- Playing

-- Playing

-- Playing

-- Playing

-- Playing

agi_request: hello-world.sh

agi_channel: SIP/0004F2060EB4-00000009

agi_language: en

agi_type: SIP

agi_uniqueid: 1284382003.9

agi_version: l.8.0-beta4

agi_callerid: 2563619899

agi_calleridname: Russell Bryant

agi_callingpres: 0

agi_callingani2: 0

agi_callington: 0

agi_callingtns: 0

agi_dnid: 7010

agi_rdnis: unknown

agi_context: phones

agi_extension: 500

agi_priority: 1

agi_enhanced: 0.0

agi_accountcode:

agi_threadid: 140071216785168

ANSWER

200 resulto

SAY ALPHA "Helio World...

letters/h.gsm' (language 'en')

letters/e.gsm' (language 'en')

letters/l.gsm' (language 'en')


letters/o.gsm' (language 'en')letters/space.gsm' (language 'en')

letters/w.gsm' (language 'en')

letters/o.gsm' (language 'en')

letters/r.gsm' (language 'en')


letters/d.gsm' (language 'en')-- Playing

AGI Tx >> 200 result=0

-- AGI Script hello-world.sh completed, returning 0

476 | Chapter 21: Asterisk Gateway Interface (AGI)

8/11/2019 texto16.pdf

3/31

8/11/2019 texto16.pdf

4/31

Pros o f EnhancedAGI

It has the simplicity of processbased AGI, with the addition of a simple readonly

stream of the channels audio. This is the only variant that offers this feature.

Cons o f Enhanced AGI

Since a new process must be spawned to run your application for every cali, it has

the same efficiency concerns as regular processbased AGI.

*- 1 For an alternative way of getting access to the audio outside of

J.

Asterisk, consider using JACK (http:// jackaudio.org/). Asterisk has

v a module for JACK integration, called appjack. It provides the

3ACKQ dialplan application and the 3ACK_H00K() dialplan function.

DeadAGI Is DeadIn versions of Asterisk prior to 1.8, there was a dialplan application called DeadAGlQ.

Its purpose was similar to that ofAGI () , except you used it on a channel that had already

been hung up. This would usually be done in the special h extensin, when you wanted

to use an AGI application to aid in some type of postcall processing. Invoking Dead

AGI () from the dialplan will still work, but you will get aWARNING message in the Asterisk

log. It has been deprecated in favor of usingAG I() in all cases. The code for AGI() has

been updated so it knows how to correctly adjust its operation after a channel has been

hung up.

Pros o f DeadAGI

None. Its dead.

Cons o f DeadAGI

Its dead. Really, dont use it. If you do, your configuration may break if Dead

AGI() is completely removed from Asterisk in a future versin.

FastAGIAGI over TCP

FastAGI is the term used for AGI cali control over a TCP connection. With process

based AGI, an instance of an AGI application is executed on the system for every cali

and communication with that application is done over stdinand stdout.With FastAGI,

a TCP connection is made to a FastAGI server. Cali control is done using the same AGI

protocol, but the communication is over the TCP connection and does not require a

new process to be started for every cali. The AGI protocol is discussed in more detail

in AGI Communication Overview on page 480. Using FastAGI is much more scal

able than processbased AGI, though it is also more complex to implement.

FastAGI is used by invoking theAGI() application in the Asterisk dialplan, but instead

of providing the ame of the application to execute, you provide an a g i :// URL. For

example:

exten => 1234,l,AGI(agi://l27.0.0.l)

http://jackaudio.org/http://jackaudio.org/http://jackaudio.org/

8/11/2019 texto16.pdf

5/31

The default port number for a FastAGI connection is 4573. A different port number can

be appended to the URL after a colon. For example:

exten => l234,l,AGI(agi://l27.0.0.1:4574)

Just as with processbased AGI, arguments can be passed to a FastAGI application. Todo so, add them as additional arguments to the AGI () application, delimited by commas:

exten => 1234,l,AGI(agi://l92.168.1.199,argl,aig2,arg3)

FastAGI also supports the usage of SRV records if you provide a URL in the form of

hagi://. By using SRV records, you can list mltiple hosts that Asterisk can attempt to

connect to for purposes of high availability and load balancing. In the following ex-

ample, to find a FastAGI server to connect to, Asterisk will do a DNS lookup for

_agi._tcp.shifteight.org:

exten => l234,l,AGI(hagi://shifteight.org)

Pros o f FastAGIIts more efficient than processbased AGI. Instead of spawning a process per cali,

a FastAGI server can handle many calis.

DNS can be used to achieve high availability and load balancing among FastAGI

servers to further enhance scalability.

Cons o f FastAGI

It is more complex to implement a FastAGI server than to implement a process

based AGI application. However, implementing a TCP server is something that

has been done countless times before, so there are many examples available for

virtually any programming language.

Async AGIAMKontrolled AGI

Async AGI is a newer method of using AGI that was first introduced in Asterisk 1.6.0.

The purpose of async AGI is to allow an application that uses the Asterisk Manager

Interface (AMI) to asynchronously queue up AGI commands to be executed on a chan

nel. This can be especially useful if you are already making extensive use of the AMI

and would like to take advantage of the same application to handle cali control, as

opposed to writing a detailed Asterisk dialplan or developing a separate FastAGI server.

*More information on the Asterisk Manager Interface can be found in

Chapter 20.' l234,i,AGI(async:agi)

AGI Variants | 479

8/11/2019 texto16.pdf

6/31

Additional Information on how to use async AGI over the AMI can be found in the next

section.

Pros o f async AGI

An existing AMI application can be used to control calis using AGI commands.Cons o f async AGI

It is the most complex method of using AGI to implement.

Setting Up /etc/asterisk/manager.conf for Async AGIConfiguration on page 460 discusses the configuration options in manager.confin

detail. To make use of async AGI, an AMI account must have the agi permission for

both read and write. For example, the following user defined in manager.confwould

be able to both execute AGI manager actions and receive AGI manager events:

);Define a user called 'helio', with a password of world'.;Give this user read/write permissions for AGI.

[helio]

secret = world

read = agi

write = agi

AGI Communication Overview

The preceding section discussed the variations of AGI that can be used. This section

goes into more detail about how your custom AGI application communicates with

Asterisk once AGI() has been invoked.

Setting Up an AGI Session

Once AGI() or EAGIQ has been invoked from the Asterisk dialplan, some information

is passed to the AGI application to set up the AGI session. This section discusses what

steps are taken at the beginning of an AGI session for the different variants of AGI.

Process-based AGI/FastAGI

For a processbased AGI application or a connection to a FastAGI server, the variables

listed in Table 211 will be the first pieces of information sent from Asterisk to your

application. Each variable will be on its own line, in the form:

agi_var iab le : va lu


8/11/2019 texto16.pdf

7/31

8/11/2019 texto16.pdf

8/31

8/11/2019 texto16.pdf

9/31

A full list of available AGI commands can be retrieved from the Asterisk consol by

running the command agi show commands. These commands are described in Ta

ble 212. To get more detailed information on a specific AGI command, including

syntax information for any arguments that a command expects, use agi show comm ands

topic . For example, to see the builtin documentation for the ANSWER

AGI command, you would use agi show commands topic ANSWER.

Table 21-2. AGI commands

AGI command

ANSWER

ASVNCAGI BREAK

CHANNELSTATUS

DATABASE DELDATABASE DELTREE

DATABASE GET

DATABASE PUT

EXEC

GET DATA

GET FULLVARIABLE

GET OPTION

GET VARIABLE

HANGUP

NOOP

RECEIVE CHAR

RECEIVE TEXT

RECORD FILE

SAY ALPHA

Description

Answer the ncoming cali.

End an async AGI session and have the channel return to the Asterisk dialplan.

Retrieve the status of the channel. This is used to retrieve the current State of the channel, such as

up (answered), down (hung up), or ringing.

Delete akey/value pairfrom the built-in AstDB.Delete atree of key/value pairs from the built-in AstDB.

Retrieve the valu for akey in the AstDB.

Set the valu for akey in the AstDB.

Execute an Asterisk dialplan application on the channel. This command is very powerful in that

between EXECand GET FULL VARIABLE, you can do anything with the cali that you can do

from the Asterisk dialplan.

Read digits from the caller.

Evaluatean Asteriskdialplanexpression. Youcansendastringthatcontainsvariablesand/ordialplan

functions, and Asterisk will return the result after making the appropriate substitutions. This command is very powerful in that between EXECand GET FULL VARIABLE, you can do anything

with the cali that you can do from the Asterisk dialplan.

Streamasound file while waiting for a digit from the caller. This is similar to the Back

ground() dialplan application.

Retrieve the valu of a channel variable.

Hang up the channel.3

Do nothing. You will get aresult response from this command, just like any other. It can be used as

asimple test of the communication path with Asterisk.

Receive asingle character. This only works for channel types that support it, such as IAX2 using

TEXT framesor SIPusing theMESSAGE method.

Receive atext message. This only works in the same cases as RECEIVE CHAR.

Record the audio from the caller to a file. This is ablocking operation similar to the Record ()

dialplan application. To record acali in the background while you perform other operations, use

EXECMonitororEXEC MixMonitor.

Say a string of characters. You can find an example of this in "Quick Start" on page 475. To get

localized handling of this and the other SAY commands, set the channel language either in the

device configuration file (e.g., sip.conf)or in the dialplan, by setting the CHANNEL(language)

dialplan function.

AGI Communication Overview | 483

8/11/2019 texto16.pdf

10/31

AGI command

SAY DIGITS

SAY NUMBER

SAY PHONETIC

SAY DATE

SAY TIME

SAY DATETIME

SEND IMAGE

SEND TEXT

SET AUTOHANGUP

SET CALLERID

SET CONTEXT

SET EXTENSION

SET MUSIC

SET PRIORITY

SET VARIABLE

STREAM FILE

CONTROL STREAMFILE

TDD MODE

VERBOSE

WAIT FOR DIGIT

SPEECH CREATE

SPEECH SET

SPEECH DESTROY

SPEECHLOAD

GRAMMAR

SPEECH UNLOAD

GRAMMAR

SPEECH ACTIVATE

GRAMMAR

Description

Say a string of digits. For example, 100 would be said as "one zero zero" if the channel's language

is set to Gnglish.

Say a number. For example, 100 would be said as "one hundred" if the channel's language is set toEnglish.

Say a string of characters, but use acommon word for each letter (Alpha, Bravo, Charlie...).

Say agiven date.

Sayagiven time.

Say agiven date and time using a specified format.

Send an image to a channel. IAX2 supports this, but there are no actively developed IAX2 dients

that support it that we know of.

Send text to a channel that supports it. This can be used with SIPand IAX2 channels, at least.

Schedule the channel to be hung up at aspecified point in time in the future.

Set the caller IDame and number on the channel.

Set the current dialplan context on the channel.

Set the current dialplan extensin on the channel.

Start or stop music on hold on the channel.

Set the current dialplan priority on the channel.

Set a channel variable to a given valu.

Streamthe contents of a file to a channel.

Streamthe contents of a file to a channel, but also allow the channel to control the stream. Forexample, the channel can pause, rewind, or fast forward the stream.

Toggle the TDD(Telecommunications Device for the Deaf) mode on the channel.

Send amessage to the verbose logger channel. Verbose messages show up on the Asterisk consol

if the verbose setting is set high enough. Verbose messages will also go to any log file that has been

configured for the verbose logger channel in /etc/asterisk/logger.conf.

Wait for the caller to press adigit.

Initialize speech recognition. This must be done before using other speech AGI commands.b

Set a speech engine setting. The settings that are available are specific to the speech recognition

engine in use.

Destroy resources that were allocated for doing speech recognition. This command should be the

last speech command executed.

Load agrammar.

Unload a grammar.

Actvate agrammar that has been loaded.

484 | Chapter 21: Asterisk Gateway Inter face (AGI)

8/11/2019 texto16.pdf

11/31

Description

Deactivateagrammar.

Play aprompt and perform speech recognition, as well as wait for digits to be pressed.Execute a dialplan subroutine. This will perform in the same way as the GoSub() dialplan appli

cation.

a When the HANGUPAGI command is used, the channel is not immediately hung up. Instead, the channel is marked as needing to be hungup. Your AGI application must exit first before Asterisk will continu and performthe actual hangup process.

b While Asterisk includes acore API for handling speech recognition, it does not come with amodule that provides aspeech recognitionengine. Digiumcurrently provides two commercial options for speech recognition: Lumenvox (http://www.digium.com/en/products/software/lumenvox.php) and Vestec (http://www.digium.com/en/products/software/vestec.php).

AGI command

SPEECHDEACTIVATE

GRAMMAR

SPEECHRECOGNIZEGOSUB


AGI commands are sent to Asterisk on a single line. The line must end with a singlenewline character. Once a command has been sent to Asterisk, no further commands

will be processed until the last command has finished and a response has been sent

back to the AGI application. Here is an example response to an AGI command:

200resulto

**V r -

>? A*

The Asterisk consol allows debugging the Communications with an

AGI application. To enable AGI communication debugging, run the agi

set debug on command. To turn debugging off, use agi set d ebug off.

While this debugging mode is on, all communication to and from an

AGI application will be printed out to the Asterisk consol. An example of this output can be found in Quick Start on page 475.

Async AGI

When youre using async AGI, commands are issued by using the AGI manager action.

To see the builtin documentation for the AGI manager action, run manager show

command AGI at the Asterisk CLI. A demonstration will help clarify how AGI com-

mands are executed using the async AGI method. First, an extensin is created in the

dialplan that runs an async AGI session on a channel:

exten => 7011,l,AGI(agi:async)

The following shows an example manager action execution and the manager events

that are emitted during async AGI processing. After the initial execution of the AGI

manager action, there is an immediate response to indicate that the command has been

queued up for execution. Later, there is a manager event that indicates that the queued

command has been executed. The CommandID header can be used to associate the initial

request with the event that indicates that the command has been executed:

Action: AGI

Channel: SIP/0004F2060EB4-00000013

ActionID: my-action-id

AGI Communication Overview | 485
http://www.digium.com/en/products/http://www.digium.com/en/products/software/vestec.phphttp://www.digium.com/en/products/software/vestec.phphttp://www.digium.com/en/products/

8/11/2019 texto16.pdf

12/31

CommandlD: my-command-id

Command: VERBOSE "Puppies like cotton candy." 1

Response: Success

ActionlO: my-action-id

Message: Added AGI command to queue

Event: AsyncAGI

Privilege: agi,all

SubEvent: Exec

Channel: SIP/0004F2060EB4-00000013

CommandlD: my-command-id

Result: 200%20result%3Dl%0A

The following output is what was seen on the Asterisk consol during this async AGI

session:

-- Executing [7011@phones:l] AGI("SIP/0004F2060EB4-00000013",

"agi:async") in new stackagi:async: Puppies like cotton candy.

== Spawn extensin (phones, 7011, 1) exited non-zero on 'SIP/0004F2060EB4-00000013'

Ending an AG Session

An AGI session ends when your AGI application is ready for it to end. The details about

how this happens depend on whether your application is using processbased AGI,

FastAGI, or async AGI.


Your AGI application may exit or cise its connection at any time. As long as the channel

has not hung up before your application ends, dialplan execution will continu. If

channel hangup occurs while your AGI session is still active, Asterisk will provide no

tification that this has occurred so that your application can adjust its operation as

appropriate.

This is an area where behavior has changed since Asterisk 1.4. In

Asterisk 1.4 and earlier versions, AGI would automatically exit and stop

operation as soon as the channel hung up. It now gives your application

the opportunity to continu running if needed.

If a channel hangs up while your AGI application is still executing, a couple of things

will happen. If an AGI command is in the middle of executing, you may receive a result

code of l. You should not depend on this, though, since not all AGI commands require

channel interaction. If the command being executed does not require channel interac

tion, the result will not reflect the hangup.

The next thing that happens after a channel hangs up is that an explicit notification of

the hangup is sent to your application. For processbased AGI, the signal SIGHUP will


8/11/2019 texto16.pdf

13/31

be sent to the process to notify it of the hangup. For a FastAGI connection, Asterisk

will send a line containing the word HANGUP. If you would like to disable having Asterisk

send the SIGHUP signal to your processbased AGI application or the HANGUP string to

your FastAGI server, you can do so by setting the AGISIGHUP channel variable, as dem

onstrated in the following short example:

); Don't send SIGHUP to an AGI process

; or the "HANGUP" string to a FastAGI server.

xten => 500,1,Set(AGISIGHUP=no)

same => n,AGI(my-agi-application)

At this point, Asterisk automatically adjusts its operation to be in DeadAGI mode. This

just means that an AGI application can run on a channel that has been hung up. The

only AGI commands that may be used at this point are those that do not require channel

interaction. The documentation for the AGI commands built into Asterisk includes anindication of whether or not each command can be used once the channel has been

hung up.

Async AGI

When youre using async AGI, the manager interface provides mechanisms to notify

you about channel hangups. When you would like to end an async AGI session for a

channel, you must execute the ASYNCAGI BREAK command. When the async AGI session

ends, Asterisk will send an AsyncAGI manager event with a SubEvent of End. The fol-

lowing is an example of ending an async AGI session:

Action: AGI

Channel: SIP/0004F2060EB4-000000lb


CommandID: my-command-id

Command: ASYNCAGI BREAK

Response: Success


Message: Added AGI command to queue

Event: AsyncAGI

Privilege: agi,all

SubEvent: EndChannel: SIP/0004F2060EB4-000000lb

At this point, the channel returns to the Asterisk dialplan if it has not yet been hung up.

Development Frameworks

There have been a number of efforts to create frameworks or libraries that make AGI

programming easier. Table 213 lists some of them. If you do not see a library listed

here for your preferred programming language, do a quick search for it and youre likely

to find one, as others do exist.

Development Frameworks | 487

8/11/2019 texto16.pdf

14/31

Table 21-3. AGI development frameworks

Framework Language URL

Adhearsion Ruby http-J/adhearsion.com/

StarPy Python http://starpy.sourceforge.net/

Asterisk-Java Java http://asterisk-java.org/

Asterisk-perl Perl http-J/asterisk.gnuinter.net/

PHPAGI PHP http://phpagi.sourceforge.net/

Conclusin

AGI provides a powerful interface to Asterisk that allows you to implement firstparty

cali control in the programming language of your choice. There are mltiple approaches

that you can take to implementing an AGI application. Some approaches can providebetter performance, but at the cost of more complexity. AGI provides a programming

environment that may make it easier to integrate Asterisk with other systems, or just

provide a more comfortable cali control programming environment for the experienced

programmer.
http://starpy.sourceforge.net/http://asterisk-java.org/http://phpagi.sourceforge.net/http://phpagi.sourceforge.net/http://asterisk-java.org/http://starpy.sourceforge.net/

8/11/2019 texto16.pdf

15/31

__________________________________CHAPTER 20

Asterisk Manager Interface (AMI)

John Malkovich: I have seen a world that

NO man should see!

Craig Schwartz: Really? Beca usefor most people its a

rather enjoyable experience.

Beingjohn Malkovich

The Asterisk Manager Interface (AMI) is a system monitoring and management inter-

face provided by Asterisk. It allows live monitoring of events that occur in the system,

as well enabling you to request that Asterisk perform some action. The actions that are

available are wideranging and include things such as returning status information and

originating new calis. Many interesting applications have been developed on top of

Asterisk that take advantage of the AMI as their primary interface to Asterisk.

Quick Start

This section is for getting your hands dirty with the AMI as quickly as possible. First,

put the following configuration in etc/asterisk/manager.conf:

; Turn on the AMI and ask it to only accept connections from localhost.

[general]

enabled = yeswebenabled = yes

bindaddr = 12 7.O.O.1

; Create an account called "helio", with a password of "world"

[helio]

secret=world

457

8/11/2019 texto16.pdf

16/31

* + %* I This sample configuration is set up to only allow local connections to

theAMI. Ifyouintendon making this interface available overa network,

ti-?,1 it is strongly recommended that you only do so using TLS. The use of

TLS is discussed in more detail later in this chapter.

Once the AM1 configuration is ready, enable the builtin HTTP server by putting the

following contents in /etc/asterisk/http.conf:

y

;Enable the built-in HTTP server, and only listen for connections on localhost.

[general]

enabled = yes

bindaddr = 127.O.O.1

AMI over TCP

There are mltiple ways to connect to the AMI, but a TCP socket is the most common.

We will use telnetto demnstrate AMI connectivity. This example shows these steps:

1. Connect to the AMI over a TCP socket on port 5038.

2. Log in using the Login action.

3. Execute the Ping action.

4. Log off using the Logoff action.

Heres how the AMI responds to those actions:$ telnet localhost 5038

Trying 12 7.O.O.1...

Connected to localhost.

Escape character is

Asterisk Cali Manager/l.l

Action: Login

Userame: helio

Secret: world

Response: Success

Message: Authentication accepted

Action: Ping

Response: Success

Ping: Pong

Timestamp: 1282739190.454046

Action: Logoff

Response: Goodbye

Message: Thanks for all the fish.

Connection closed by foreign host.

458 | Chapter 20: Asterisk Manager Interface (AMI)
http://http.conf/http://http.conf/

8/11/2019 texto16.pdf

17/31

Once you have this working, you have verified that AMI is accepting connections via

a TCP connection.

AMI over HTTP

It is also possible to use the AMI over HTTP. In this section we will perform the same

actions as before, but over HTTP instead of the native TCP interface to the AMI. The

responses will be delivered over HTTP in the same format as the previous example,

since the rawman encoding type is being used. AMIoverHTTP responses can be enco

ded in other formats, such as XML. These responseformatting options are covered in

AMI over HTTP on page 467.

r*

____ I

Accounts used for connecting to the AMI over HTTP are the same ac-

counts configured in/etc/asterisk/manager.conf.

This example demonstrates how to access the AMI over HTTP, log in, execute the

Ping action, and log off:

$ wget "http://localhost:8088/rawman?action=login&username=hello&secret=world" \

> --save-cookies cookies.txt -0 -

--2010-08-31 12:34:23--

Resolving localhost... 127.0.0.1

Connecting to localhost|127.0.0.l|:8088... connected.

HTTP request sent, awaiting response... 200 0K

Length: 55 [text/plain]

Saving to: 'STDOUT'

Response: Success


2010-08-31 12:34:23 (662 KB/s) - written to stdout [55/55]

$ wget "http://localhost:8088/rawman?action=ping" --load-cookies cookies.txt -0 -

--2010-08-31 12:34:23--Resolving localhost... 127.0.0.1

Connecting to localhost|l27.0.0.l|:8088... connected.

HTTP request sent, awaiting response... 200 0K

Length: 63 [text/plain]

Saving to: 'STDOUT'

Response: Success

Ping: Pong

Timestamp: 1283258063.040293

2010-08-31 12:34:23 (775 KB/s) - written to stdout [63/63]

Quick Start | 459
http://localhost:8088/rawman?action=login&username=hello&secret=worldhttp://localhost:8088/rawman?action=pinghttp://localhost:8088/rawman?action=pinghttp://localhost:8088/rawman?action=login&username=hello&secret=world

8/11/2019 texto16.pdf

18/31

$ wget "http://localhost:8088/rawman?action=logoff" load-cookies cookies.txt -0 -

--2010-08-31 12:34:23--

Resolving localhost... 127.0.0.1

Connecting to localhost|127.0.0.l|:8088... connected.HTTP request sent, awaiting response... 200 OK

Length: 56[text/plain]

Saving to: 'STDOUT'

Response: Goodbye

Message: Thanks for all the fish.

2010-08-31 12:34:23 (696KB/s) - written to stdout [56/56]

The HTTP interface to AMI lets you integrate Asterisk cali control into a web Service.

Configuration

The section Quick Start on page 457 showed a very basic set of configuration files to

get you started. However, there are many more options available for the AMI.

manager.conf

The main configuration file for the AMI is /etc/asterisk/manager.conf. The [general]

section contains options (listed in Table 201) that control the overall operation of the

AMI. Any other sections in the manager.conffile will define accounts for logging in and

using the AMI.

Table 20-1. Options in the manager.conf [general] section

Option Value/Example Description

enabled yes Enables the AMI. The default is no.

webenabled yes Allows access to the AMI through the built-in HTTP

server. The default is no.a

port 5038 Sets the port number to listen on for AMI connections.

The default is5038.

bindaddr 127.0.0.1 Sets the address to listen on for AMI connections. The

default is to listen on all addresses(0 .0 .0 .0).How

ever, it is highly recommended to set this to

127.O.O.1.

tlsenable yes Enables listening for AMI connections using TLS. The

default is no. It is highly recommended to only expose

connectivity via TLSoutside of the local machine.b

tlsbindport 5039 Sets the port to listen on for TLSconnections to the

AMI. The default is5039.

460 | Chapter 20: Asterisk Manager Inter face (AMI)
http://localhost:8088/rawman?action=logoffhttp://localhost:8088/rawman?action=logoff

8/11/2019 texto16.pdf

19/31

Option

tlsbindaddr

tlscertfile

tlsprivatekey

tlscipher

Value/Example

O . O . 0 . 0

/var/lib/astersk/keys/astersk.pem

/m/lib/asterisk/keys/private.pem

allowmultiplelogin no

displayconnects yes

timestampevents no

brokeneventsaction no

channelvars

debug

httptimeout

VAR1JVAR2,VAR3[,VAR4[...]]

no

60

Description

Sets the address to listen on for TLS-based AMI con

nections. The default is to listen on all addresses

(o.o.o.o).

Sets the path to the server certifcate for TLS. This is

required if tlsenable is set to yes.

Sets the path to the prvate key for TLS. If this is not

specifted, the t ls c e r t f i le will be checked to see

if it also contains the prvate key.

Specifies a lst of ciphers for OpenSSL to use. Setting

this is optonal. To see alist of available ciphers, run

openssl ciphers -vat the command line.

Allows the same account to make more than one con-

nection at the same time. The default is yes.

Reports connections to the AMI as verbose messages

printed to the Asterisk consol. This is usually useful,

but it can get in the way on a systemthat uses scripts

that make alot of connections to the AMI. The default

is yes.

Adds aUnix epoch-based timestamp to every event

reported to the AMI. The default is no.

Restores previously broken behavior for the Events

AMI action, where aresponse would not be sent in

some circumstances. This option is there for the sake

of backward-com patibil ity for applications that

worked around a bug and should not be used unless

absolutely necessary. The default is no.

Specifies a list of channel variables to inciude with all

manager events that are channel-oriented. The de

fault is to inciude no channel variables.

Enables some additional debugging in the AMI code.

This is primarily there for developers of the Asterisk C

code. The default is no.

Sets the HTTPtimeout, in seconds. This timeout affectsusers of the AMI over HTTP: it sets the Ma x - Age of the

HTTPcookie, sets how long events are cached to allow

retrieval of the events over HTTPusing the WaitE

vent s action, and the amount of time that the HTTP

server keeps asession alive after completing an AMI

action. The default is 60 seconds.

a To access the AMI over HTTP, the built-in HTTPserver must also be configured in/etc/asterisk/http.conf.

b The OpenSSL development package must be installed for Asterisk to be able to use encryption. On Ubuntu, the package is libssl-dev.On

CentOS, the package isopenssl-devel.

Configuration | 461
http://http.conf/http://http.conf/

8/11/2019 texto16.pdf

20/31

8/11/2019 texto16.pdf

21/31

Table 20-3. Available vales for AMI user account read/write options

Permission identi fier read writ e

a l l Shorthand way of specifying that this user

should have access to all available privilege

options.

Grants user all privilege options.

system Allows user to receive general systemInfor

mation, such as notifications of configuration

reloads.

Allows user to perform systemmanagement com

mands such asRestan, Reload,orShutdown.

ca l i Allows user to receive events about channels

on the system.

Allows userto set information on channels.

log Gives user access to logging information.3 read-only

verbose Gives user access to verbose logging

information.b

read-only

agent Gives user access to events regarding the status

of agents from the app_queue and

chan_agent modules.

Enables user to perform actions for managing and

retrieving the status of queues and agents.

user Grants access to user-defined events, as well

as events about Jabber/XMPP users.

Lets user perform the UserEvent manager

action, which provides the ability to request that

Asterisk generate a user-defined event.c

config write-only Allows user to retrieve, update, and reload config

uration files.

command write-only Allows user to execute Asterisk CLI commands over

the AMI.

dtmf Allows user to receive events generated as

DTMF passes through the Asterisk core.d

read-only

reporting Gives user access to call-quality events, such

as jitterbuffer statistics or RTCPreports.

Enables userto execute a range of actions to retrieve

statistics and status information from across the

system.

cdr Grants user access to CDRrecords reported by

the cdr_manager module.

read-only

dialplan Allows user to receive events generated when

variablesareSetornewextensionsarecreated.

read-only

orignate write-only Allows user to execute the Orig inate action,which allows an AMI dient to request that Asterisk

createanewcall.

ag Allows user to receive events generated when

AGI commands are processed.

Enables userto perform actions for managing chan

nels that are running AGI in itsasynchronous mode.

AGI is discussed in more detail in Chapter 21.

cc Allows user to receive events related to Cali

Completion Supplementary Services (CCSS).

read-only

Configuration | 463

8/11/2019 texto16.pdf

22/31

8/11/2019 texto16.pdf

23/31

Option Value/Example Description

tlscipher of available ciphers, runopenssl ciphers-vat the command line.

a The OpenSSL development package must be installed for Asterisk to be able to use encryption. On Ubuntu, the package is libssl-dev.On

CentOS, the package isopenssl-devel.

Protocol Overview

There are two main types of messages on the Asterisk Manager Interface: manager

events and manager actions.

Manager events are oneway messages sent from Asterisk to AMI clients to report

something that has occurred on the system. See Figure 201 for a graphical represen

tation of the transmission of manager events.

AMI Client Asterisk

Manager EventV

/ Manager EventN

Manager Event\

Figure 20-1. Manager events

Manager actions are requests from a client that have associated responses that come

back from Asterisk. That is, a manager action may be a request that Asterisk perform

some action and return the result. For example, there is an AMI action to originate a

new cali. See Figure 202 for a graphical representation of a client sending manager

actions and receiving responses.

Other manager actions are requests for data that Asterisk knows about. For example,

there is a manager action to get a list of all active channels on the system: the details

about each channel are delivered as a manager event. When the list of results is com-

plete, a final message will be sent to indicate that the end has been reached. See Fig-

ure 203 for a graphical representation of a client sending this type of manager action

and receiving a list of responses.

Protocol Overview | 465

8/11/2019 texto16.pdf

24/31

AMI Client Asterisk j

..................i ...'' ' '' ''..... .'i Manager Action ^. ""............ siii

Action Response

:

111

1 Manager Event

i*

i1

' Manager Event

'S

iii Action Response

Figure 20-3. Manager actions that return a list of data

Message Encoding

All AMI messages, including manager events, manager actions, and manager actionresponses, are encoded in the same way. The messages are textbased, with lines ter

minated by a carriage return and a linefeed character. A message is terminated by a

blank line:

Headerl: This is the first header

Header2: This is the second header

Header3: This is the last header of this message


8/11/2019 texto16.pdf

25/31

8/11/2019 texto16.pdf

26/31

This is the method that was used in the quickstart example, as seen in AMI over

HTTP on page 459. The second authentication option is HTTP digest authentica

tion.* The next three sections discuss each of the AMI over HTTP encoding options.

To indicate that HTTP digest authentication should be used, prefix the encoding type

with an a.

Once successfully authenticated, Asterisk will provide a cookie that identifies the au

thenticated session. Here is an example response to the Login action that includes a

session cookie from Asterisk:

$ curl -v "http://localhost:8088/rawman?action=login&username=hello&secret=world"

* Aboutto connect() to localhost port 8088 (#0)

* Trying 127.0.0.1... connected

* Connected to localhost (127.0.0.1) port 8088 (#0)

> GET /rawman ?action=login&username=hello8isecret=wor Ida HTTP/l.l

> User-Agent: curl/7.19.7 (x86_64-pc-linux-gnu) libcurl/7.19.7

OpenSSL/0.9.8k zlib/l.2.3.3 libidn/1.15

> Host: localhost:8088

> Accept: */*

>

< HTTP/l.l 200 0K

< Server: Asterisk/l.8.0-beta4

< Date: Tue, 07 Sep 2010 11:51:28 GMT

< Connection: cise

< Cache-Control: no-cache, no-store

< Content-Length: 55

< Content-type: text/plain

< Cache-Control: no-cache;

< Set-Cookie: mansession_id=''0e929e60"; Version=l; Max-Age=60< Pragma: SuppressEvents

Response: Success


* Closing connection #0

/rawman encoding

The rawman encoding type is what has been used in all the AMI over HTTP examples

in this chapter so far. The responses received from requests using rawman are formatted

in the exact same way that they would be if the requests were sent over a direct TCP

connection to the AMI.

* At the time of writing, there is a problem with HTTP digest authentication that prevents it from working

properly. Issue 18598 (https://issuesMsterisk.org/view.php?id=18598)in the Asterisk project issue tracker has

been opened for this problem. Hopefully it will be fixed by the time you read this.

http://localhost:8088/rawman?action=login&username=hello&secret=worldhttps://issuesmsterisk.org/view.php?id=https://issuesmsterisk.org/view.php?id=http://localhost:8088/rawman?action=login&username=hello&secret=world

8/11/2019 texto16.pdf

27/31

/manager encoding

The manager encoding type provides a response in simple HTML form. This interface

is primarily useful for experimenting with the AMI. Here is an example Login using this

encoding type:

$ curl -v ,,http://localhost:8088/manager?action=login&username=hello&secret=world"

* About to connectQ to localhost port 8088 (#0)

* Trying 12 7.O.O.1... connected


> GET /manager?action=login&username=hello&secret=world HTTP/1.1

> User-Agent: curl/7.19.7 (x86_64-pc-linux-gnu) libcur1/7.19.7

0penSSL/0.9.8k zlib/l.2.3.3 libidn/l.15


> Accept: */*

>

< HTTP/1.1 200 OK


< Date: Tue, 07 Sep 2010 12:19:05 GMT

< Connection: cise



< Content-type: text/html


< Set-Cookie: mansession_id="l39deda7"; Version=l; Max-Age=60

< Pragma: SuppressEvents

Asterisk Manager Interfacec/titlexbody bgcolor="#ffffff">

ctrxtd colspan="2" bgcolor="#flflff"xhl>Manager Tester

* Closing connection #0

8/11/2019 texto16.pdf

28/31

The mxml encoding type provides responses to manager actions encoded in XML. Here

is an example Login using the mxml encoding type:

$ curl -v "http://localhost:8088/mxml?action=login&username=hello&secret=world"

* About to connectQ to localhost port 8088 (#0)

* Trying 127.0.0.1... connected


> GET /mxml?action=login&username=hello&secret=world HTTP/l.l

> User-Agent: curl/7.19.7 (x86_64-pc-linux-gnu) libcurl/7.19-7

0penSSL/O.9.8k zlib/l.2.3.3 libidn/l.15


> Accept: */*

>

< HTTP/l.l 200 0K


< Date: Tue, 07 Sep 2010 12:26:58 GMT< Connection: cise



< Content-type: text/xml


< Set-Cookie: mansession_id="536dl7a4"; Version=l; Max-Age=60

< Pragma: SuppressEvents

Hhttp://localhost:8088/mxml?action=login&username=hello&secret=world" -0 -

/mxml encoding

470 1 Chapter 20: Asterisk Manager Interface (AMI)
http://localhost:8088/mxml?action=login&username=hello&secret=worldhttp://localhost:8088/mxml?action=login&username=hello&secret=worldhttp://localhost:8088/mxml?action=login&username=hello&secret=worldhttp://localhost:8088/mxml?action=login&username=hello&secret=world

8/11/2019 texto16.pdf

29/31

$ wget --load-cookies cookies.txt "http://localhost:8088/mxml?action=waitevent" -O -

Development Frameworks

Many application developers write code that directly interfaces with the AMI. However,

there are a number of existing libraries that aim to make writing AMI applications

easier. Table 205 lists a few that we know are being used successfully. If you search

around for Asterisk libraries in any other popular programming language of your

choice, you are likely to find one that exists.

Table 20-5. AMI development frameworks

Framework Language URL

Adhearsion Ruby http-J/adhearsion.com/

StarPy Python http://starpy.sourceforge.net/

Asterisk-Java Java http-J/asterisk-java.org/

CSTAComputerSupported Telecommunications Applications (CSTA) is a standard for

Computer Telephony Integration (CTI). One of the biggest benefits of CSTA is that it

is used by mltiple manufacturers. Some of what is provided by CSTA can be mapped

to operations available in the AMI. There have been mltiple efforts to provide a CSTA

interface to Asterisk. One of these efforts is the Open CSTA (http://opencsta.org)

project. While none of the authors have experience with this CST A interface to Asterisk,

it is certainly worth considering if you have CSTA experience or an existing CSTA

application you would like to integrate with Asterisk.

Development Frameworks | 471
http://localhost:8088/mxml?action=waiteventhttp://starpy.sourceforge.net/http://opencsta.org/http://opencsta.org/http://starpy.sourceforge.net/http://localhost:8088/mxml?action=waitevent

8/11/2019 texto16.pdf

30/31

Interesting Applications

Many useful applications have been developed that take advantage of the AMI. Here

are a couple of examples.

AsteriskGUI

The AsteriskGUI is an open source PBX administration interface developed by Digium.

It is intended for use on small installations. The AsteriskGUI is written entirely in

HTML and JavaScript and uses the AMI over HTTP for all interaction with Asterisk.

It has been especially popular for use in resource-constrained embedded Asterisk en-

vironments, since it does not require additional software to run on the Asterisk server.

Figure 20-4 shows a page from the AsteriskGUI.

The AsteriskGUI can be obtained from the Digium subversin server:

$ svn co http://svn.digium.c0m/svn/asterisk-gui/branches/2.O

It is also bundled as an option with the AsteriskNOW (http://www.asterisk.org/asteris

knowf)distribution.

Figure 20-4. A ster i skGUI

http://svn.digium.c0m/svn/asterisk-gui/branches/2.Ohttp://www.asterisk.org/asterishttp://www.asterisk.org/asterishttp://svn.digium.c0m/svn/asterisk-gui/branches/2.O

8/11/2019 texto16.pdf

31/31

Flash Operator Panel

Flash Operator Panel is an application that runs in a web browser using Flash. It is

primarily used as an interface to see which extensions are currently ringing or in use.

It also includes the ability to monitor conference room and cali queue status. Some caliactions can be performed as well, such as barging into a cali and transferring calis.

Figure 20-5 shows a screenshot of the Flash Operator Panel interface.

Downloads and more detailed information on Flash Operator Panel can be found at

http://www.asternic.org.

No timeout

Extensin rences

itme 901 Externa 1

Externa 2

9 Florenciof M 3 Pedro Externa 3

Sales Queue14 Rodo

P| Support Queue ^yg^j fnl Externa 5 (

fSAdmin Queue f^D ayM ode

Figure 20-5. Flash O perato r Panel

Conclusin

The Asterisk Manager Interface provides an API for monitoring events from an Asterisksystem, as well as requesting that Asterisk perform a wide range of actions. An HTTP

interface has been provided and a number of frameworks have been developed that

make it easier to develop applications. All of this information, as well as the examples

we looked at at the end of this chapter, should help get you thinking about what new

applications you might be able to build using the Asterisk Manager Interface.
http://www.asternic.org/http://www.asternic.org/

texto16.pdf

Documents

Transcript of texto16.pdf