AstriPedia - New pages [en]

U-Z

2007-09-12T07:20:23Z

Summary: /* WaitForSilence */

; Index U-Z of Asterisk Applications
==UnpauseQueueMember==

'''Synopsis'''

Unpauses a queue member

'''Description'''

UnpauseQueueMember([queuename]|interface[|options]):

Unpauses (resumes calls to) a queue member. This is the counterpart to PauseQueueMember and operates exactly the same way, except it unpauses instead of pausing the given interface. The option string may contain zero or more of the following characters:

'j' -- jump to +101 priority when appropriate.
This application sets the following channel variable upon completion:
UPQMSTATUS The status of the attempt to unpause a queue
member as a text string, one of
UNPAUSED | NOTFOUND
Example: UnpauseQueueMember(|SIP/3000)

==UserEvent==

'''Synopsis'''

Send an arbitrary event to the manager interface

'''Description'''

UserEvent(eventname[|body]):

Sends an arbitrary event to the manager interface, with an optional body representing additional
arguments. The format of the event will be:
Event: UserEvent<specified event name>
Channel: <channel name>
Uniqueid: <call uniqueid>
[body]
If the body is not specified, only Event, Channel, and Uniqueid fields
will be present. Returns 0.

==Verbose==

'''Synopsis'''

Send arbitrary text to verbose output

'''Description'''

Verbose([<level>|]<message>) level must be an integer value. If not specified, defaults to 0.

==VMAuthenticate==

'''Synopsis'''

Authenticate with Voicemail passwords

'''Description'''

VMAuthenticate([mailbox][@context][|options]):

This application behaves the same way as the Authenticate application, but the passwords are taken from
voicemail.conf. If the mailbox is specified, only that mailbox's password will be considered valid. If the mailbox is not specified, the channel variable AUTH_MAILBOX will be set with the authenticated mailbox.
Options: s - Skip playing the initial prompts.

==VoiceMail==

'''Synopsis'''

Leave a Voicemail message

'''Description'''

VoiceMail(mailbox[@context][&mailbox[@context]][...][|options]):

This application allows the calling party to leave a message for the specified list of mailboxes. When multiple mailboxes are specified, the greeting will be taken from the first mailbox specified. Dialplan execution will stop if the specified mailbox does not exist.

The Voicemail application will exit if any of the following DTMF digits are received:
0 - Jump to the 'o' extension in the current dialplan context.
* - Jump to the 'a' extension in the current dialplan context.
This application will set the following channel variable upon completion:
VMSTATUS - This indicates the status of the execution of the VoiceMail
application. The possible values are:
SUCCESS | USEREXIT | FAILED
Options:
b - Play the 'busy' greeting to the calling party.
g(#) - Use the specified amount of gain when recording the voicemail
message. The units are whole-number decibels (dB).
s - Skip the playback of instructions for leaving a message to the
calling party.
u - Play the 'unavailable greeting.
j - Jump to priority n+101 if the mailbox is not found or some other
error occurs.

==VoiceMailMain==

'''Synopsis'''

Check Voicemail messages

'''Description'''

VoiceMailMain([mailbox][@context][|options]):

This application allows the calling party to check voicemail messages. A specific mailbox, and optional
corresponding context, may be specified. If a mailbox is not provided, the calling party will be prompted to enter one. If a context is not specified, the 'default' context will be used.

Options:
p - Consider the mailbox parameter as a prefix to the mailbox that
is entered by the caller.
g(#) - Use the specified amount of gain when recording a voicemail
message. The units are whole-number decibels (dB).
s - Skip checking the passcode for the mailbox.

==Wait==

'''Synopsis'''

Waits for some time

'''Description'''

Wait(seconds):

This application waits for a specified number of seconds. Then, dialplan execution will continue at the next priority. Note that the seconds can be passed with fractions of a second. For example, '1.5' will ask the application to wait for 1.5 seconds.

==WaitExten==

'''Synopsis'''

Waits for an extension to be entered

'''Description'''

WaitExten([seconds][|options]):

This application waits for the user to enter a new extension for a specified number of seconds.
Note that the seconds can be passed with fractions of a second. For example, '1.5' will ask the application to wait for 1.5 seconds.
Options:
m[(x)] - Provide music on hold to the caller while waiting for an extension.
Optionally, specify the class for music on hold within parenthesis.

==WaitForRing==

'''Synopsis'''

Wait for Ring Application

'''Description'''

WaitForRing(timeout) Returns 0 after waiting at least timeout seconds. and only after the next ring has completed. Returns 0 on success or -1 on hangup

==WaitForSilence==

'''Synopsis'''

Waits for a specified amount of silence

'''Description'''

WaitForSilence(x[|y]) Wait for Silence:

Waits for up to 'x' milliseconds of silence, 'y' times or 1 if omitted Set the channel variable WAITSTATUS with to one of these values:SILENCE - if silence of x ms was detectedTIMEOUT - if silence of x ms was not detected.

Examples:
- WaitForSilence(500|2) will wait for 1/2 second of silence, twice
- WaitForSilence(1000) will wait for 1 second of silence, once

==WaitMusicOnHold==

'''Synopsis'''

Wait, playing Music On Hold

'''Description'''

WaitMusicOnHold(delay):

Plays hold music specified number of seconds. Returns 0 when done, or -1 on hangup. If no hold music is available, the delay will still occur with no sound.

==While==

'''Synopsis'''

Start A While Loop

'''Description'''

Usage:

While(<expr>) Start a While Loop. Execution will return to this point when

EndWhile is called until expr is no longer true.

==Zapateller==

'''Synopsis'''

Block telemarketers with SIT

'''Description'''

Zapateller(options):

Generates special information tone to block telemarketers from calling you. 
Options is a pipe-delimited list of options. 
The following options are available: 
'answer' causes the line to be answered before playing the tone, 
'nocallerid' causes Zapateller to only play the tone if there 
is no callerid information available. 
Options should be separated by | characters

==ZapBarge==

'''Synopsis'''

Barge in (monitor) Zap channel

'''Description'''

ZapBarge([channel]):

Barges in on a specified zap channel or prompts if one is not specified. Returns -1 when caller user hangs up and is independent of the state of the channel being monitored.

==ZapRAS==

'''Synopsis'''

Executes Zaptel ISDN RAS application

'''Description'''

ZapRAS(args):

Executes a RAS server using pppd on the given channel. The channel must be a clear channel (i.e. PRI source) and a Zaptel channel to be able to use this function (No modem emulation is included). Your pppd must be patched to be zaptel aware. Arguments should be separated by | characters.

==ZapScan==

'''Synopsis'''

Scan Zap channels to monitor calls

'''Description'''

ZapScan([group]) allows a call center manager to monitor Zap channels in a convenient way. 
Use '#' to select the next channel and use '*' to exit Limit scanning to a channel GROUP by setting the option group argument.

S-T

2007-09-12T07:11:04Z

Summary:

{| align="right"
| __TOC__
|}

; Index S-T of Asterisk Applications
==SayAlpha==

'''Synopsis'''

Say Alpha

'''Description'''

SayAlpha(string):

This application will play the sounds that correspond to the letters of the given string.

==SayCountPL==

'''Synopsis'''

Say the counting word the fits to a number

'''Description'''

Polish grammar has some funny rules for counting words. for example 1 zloty, 2 zlote, 5 zlotych. This application will take the words for 1, 2-4 and 5 and decide based on grammar rules which one to use with the number you pass to it.

Example: saycountpl(zloty,zlote,zlotych,122) will give: zlote

==SayDigits==

'''Synopsis'''

Say Digits

'''Description'''

SayDigits(digits): This application will play the sounds that correspond
to the digits of the given number. This will use the language that is currently
set for the channel. See the LANGUAGE function for more information on setting
the language for the channel.

==SayNumber==

'''Synopsis'''

Say Number

'''Description'''

SayNumber(digits[,gender]): This application will play the sounds that correspond to the given number. Optionally, a gender may be specified. This will use the language that is currently set for the channel. See the LANGUAGE function for more information on setting the language for the channel.

==SayPhonetic==

'''Synopsis'''

Say Phonetic

'''Description'''

SayPhonetic(string): This application will play the sounds from the phonetic alphabet that correspond to the letters in the given string.

==SayUnixTime==

'''Synopsis'''

Says a specified time in a custom format

'''Description'''

SayUnixTime([unixtime][|[timezone][|format]])
unixtime: time, in seconds since Jan 1, 1970. May be negative.
defaults to now.
timezone: timezone, see /usr/share/zoneinfo for a list.
defaults to machine default.
format: a format the time is to be said in. See voicemail.conf.
defaults to "ABdY 'digits/at' IMp"

==SendDTMF==

'''Synopsis'''

Sends arbitrary DTMF digits

'''Description'''

:: SendDTMF(digits[|timeout_ms]): Sends DTMF digits on a channel.
:: Accepted digits: 0-9, *#abcd, w (.5s pause)
:: The application will either pass the assigned digits or terminate if it encounters an error.

==SendImage==

'''Synopsis'''

Send an image file

'''Description'''

SendImage(filename): Sends an image on a channel. If the channel supports image transport but the image send fails, the channel will be hung up. Otherwise, the dialplan continues execution.
The option string may contain the following character:
'j' -- jump to priority n+101 if the channel doesn't support image transport
This application sets the following channel variable upon completion:
SENDIMAGESTATUS The status is the result of the attempt as a text string, one of
OK | NOSUPPORT

==SendText==

'''Synopsis'''

Send a Text Message

'''Description'''

SendText(text[|options]): Sends text to current channel (callee).
Result of transmission will be stored in the SENDTEXTSTATUS

channel variable:
SUCCESS Transmission succeeded
FAILURE Transmission failed
UNSUPPORTED Text transmission not supported by channel

At this moment, text is supposed to be 7 bit ASCII in most channels.
The option string many contain the following character:
'j' -- jump to n+101 priority if the channel doesn't support text transport

==SendURL==

'''Synopsis'''

Send a URL

'''Description'''

SendURL(URL[|option]): Requests client go to URL (IAX2) or sends the
URL to the client (other channels).

Result is returned in the SENDURLSTATUS channel variable:
SUCCESS URL successfully sent to client
FAILURE Failed to send URL
NOLOAD Clien failed to load URL (wait enabled)
UNSUPPORTED Channel does not support URL transport

If the option 'wait' is specified, execution will wait for an acknowledgement that the URL has been loaded before continuing and will return -1 if the peer is unable to load the URL

Old behaviour (deprecated):
If the client does not support Asterisk "html" transport,
and there exists a step with priority n + 101, then execution will
continue at that step.
Otherwise, execution will continue at the next priority level.
SendURL only returns 0 if the URL was sent correctly or if
the channel does not support HTML transport, and -1 otherwise.

==Set==

'''Synopsis'''

Set channel variable(s) or function value(s)

'''Description'''

Set(name1=value1|name2=value2|..[|options])

This function can be used to set the value of channel variables or dialplan functions. It will accept up to 24 name/value pairs. When setting variables, if the variable name is prefixed with _, the variable will be inherited into channels created from the current channel. If the variable name is prefixed with __, the variable will be inherited into channels created from the current channel and all children channels.
Options:
g - Set variable globally instead of on the channel
(applies only to variables, not functions)

==SetAccount==

'''Synopsis'''

Set the CDR Account Code

'''Description'''

SetAccount([account]):

This application will set the channel account code for billing purposes. SetAccount has been deprecated in favor of the Set(CDR(accountcode)=account).

==SetAMAFlags==

'''Synopsis'''

Set the AMA Flags

'''Description'''

SetAMAFlags([flag]): This channel will set the channel's AMA Flags for billing purposes.

==SetCallerID==

'''Synopsis'''

Set CallerID

'''Description'''

SetCallerID(clid[|a]): Set Caller*ID on a call to a new value. Sets ANI as well if a flag is used.

==SetCallerPres==

'''Synopsis'''

Set CallerID Presentation

'''Description'''

SetCallerPres(presentation): Set Caller*ID presentation on a call.

Valid presentations are:
allowed_not_screened : Presentation Allowed, Not Screened
allowed_passed_screen : Presentation Allowed, Passed Screen
allowed_failed_screen : Presentation Allowed, Failed Screen
allowed : Presentation Allowed, Network Number
prohib_not_screened : Presentation Prohibited, Not Screened
prohib_passed_screen : Presentation Prohibited, Passed Screen
prohib_failed_screen : Presentation Prohibited, Failed Screen
prohib : Presentation Prohibited, Network Number
unavailable : Number Unavailable

==SetCDRUserField==

'''Synopsis'''

Set the CDR user field

'''Description'''

SetCDRUserField(value):

Set the CDR 'user field' to value. The Call Data Record (CDR) user field is an extra field you can use for data not stored anywhere else in the record. CDR records can be used for billing or storing other arbitrary data (I.E. telephone survey responses) Also see AppendCDRUserField().

==SetCIDName==

'''Synopsis'''

Set CallerID Name

'''Description'''

SetCIDName(cname[|a]):

Set Caller*ID Name on a call to a new value, while preserving the original Caller*ID number. This is
useful for providing additional information to the called party. SetCIDName has been deprecated in favor of the function CALLERID(name)

==SetCIDNum==

'''Synopsis'''

Set CallerID Number

'''Description'''

SetCIDNum(cnum[|a]):

Set Caller*ID Number on a call to a new value, while preserving the original Caller*ID name. This is
useful for providing additional information to the called party. Sets ANI as well if a flag is used.
SetCIDNum has been deprecated in favor of the function CALLERID(number)

==SetGlobalVar==

'''Synopsis'''

Set a global variable to a given value

'''Description'''

SetGlobalVar(variable=value): This application sets a given global variable to the specified value.

==SetGroup==

'''Synopsis'''

Set the channel's group

'''Description'''

Usage: SetGroup(groupname[@category])

Sets the channel group to the specified value. Equivalent to Set(GROUP=group). Always returns 0.

==SetLanguage==

'''Synopsis'''

Set the channel's preferred language

'''Description'''

SetLanguage(language):

This will set the channel language to the given value. This information is used for the syntax in generation of numbers, and to choose a sound file in the given language, when it is available.
For example, if language is set to 'fr' and the file 'demo-congrats' is requested to be played, if the file 'fr/demo-congrats' exists, then it will play that file. If not, it will play the normal 'demo-congrats'. For some language codes, SetLanguage also changes the syntax of some Asterisk functions, like SayNumber. SetLanguage has been deprecated in favor of Set(LANGUAGE()=language)

==SetMusicOnHold==

'''Synopsis'''

Set default Music On Hold class

'''Description'''

SetMusicOnHold(class):

Sets the default class for music on hold for a given channel. When music on hold is activated, this class will be used to select which music is played.

==SetRDNIS==

'''Synopsis'''

Set RDNIS Number

'''Description'''

SetRDNIS(cnum): Set RDNIS Number on a call to a new value. SetRDNIS has been deprecated in favor of the function CALLERID(rdnis)

==SetTransferCapability==

'''Synopsis'''

Set ISDN Transfer Capability

'''Description'''

SetTransferCapability(transfercapability): Set the ISDN Transfer Capability of a call to a new value.

Valid Transfer Capabilities are:

SPEECH : 0x00 - Speech (default, voice calls)
DIGITAL : 0x08 - Unrestricted digital information (data calls)
RESTRICTED_DIGITAL : 0x09 - Restricted digital information
3K1AUDIO : 0x10 - 3.1kHz Audio (fax calls)
DIGITAL_W_TONES : 0x11 - Unrestricted digital information with tones/announcements
VIDEO : 0x18 - Video:

==SetVar==

'''Synopsis'''

Set channel variable(s)

'''Description'''

SetVar(name1=value1|name2=value2|..[|options]):

This application has been deprecated in favor of using the Set application.

==SIPAddHeader==

'''Synopsis'''

Add a SIP header to the outbound call

'''Description'''

SIPAddHeader(Header: Content) Adds a header to a SIP call placed with DIAL. Remember to user the X-header if you are adding non-standard SIP headers, like "X-Asterisk-Accountcode:". Use this with care. Adding the wrong headers may jeopardize the SIP dialog. Always returns 0

==SIPDtmfMode==

'''Synopsis'''

Change the dtmfmode for a SIP call

'''Description'''

SIPDtmfMode(inband|info|rfc2833): Changes the dtmfmode for a SIP call

==SIPGetHeader==

'''Synopsis'''

Get a SIP header from an incoming call

'''Description'''

SIPGetHeader(var=headername[|options]):

Sets a channel variable to the content of a SIP header
Options:
j - Jump to priority n+101 if the requested header isn't found.
This application sets the following channel variable upon completion:
SIPGETSTATUS - This variable will contain the status of the attempt
FOUND | NOTFOUND
This application has been deprecated in favor of the SIP_HEADER function.

==SMS==

'''Synopsis'''

Communicates with SMS service centres and SMS capable analogue phones

'''Description'''

SMS(name|[a][s]):

SMS handles exchange of SMS data with a call to/from SMS capabale phone or SMS PSTN service center. Can send and/or receive SMS messages. Works to ETSI ES 201 912 compatible with BT SMS PSTN service in UK
Typical usage is to use to handle called from the SMS service centre CLI, or to set up a call using 'outgoing' or manager interface to connect service centre to SMS() name is the name of the queue used in /var/spool/asterisk/sms
Arguments:
a: answer, i.e. send initial FSK packet.
s: act as service centre talking to a phone.
Messages are processed as per text file message queues.
smsq (a separate software) is a command to generate message
queues and send messages.

==SoftHangup==

'''Synopsis'''

Soft Hangup Application

'''Description'''

SoftHangup(Technology/resource|options)

Hangs up the requested channel. If there are no channels to hangup, the application will report it.
- 'options' may contain the following letter:
'a' : hang up all channels on a specified device instead of a single resource

==Sort==

'''Synopsis'''

Sorts a list of keywords and values

'''Description'''

Sort(newvar=key1:val1[,key2:val2[[...],keyN:valN]]):

This application will sort the list provided in ascending order. The result will be stored in the specified variable name. This application has been deprecated in favor of the SORT function.

==StackPop==

'''Synopsis'''

Remove one address from gosub stack

'''Description'''

StackPop() Removes last label on the stack, discarding it.

==StartMusicOnHold==

'''Synopsis'''

Play Music On Hold

'''Description'''

StartMusicOnHold(class):

Starts playing music on hold, uses default music class for channel. Starts playing music specified by class. If omitted, the default music source for the channel will be used. Always returns 0.

==StopMonitor==

'''Synopsis'''

Stop monitoring a channel

'''Description'''

StopMonitor

Stops monitoring a channel. Has no effect if the channel is not monitored

==StopMusicOnHold==

'''Synopsis'''

Stop Playing Music On Hold

'''Description'''

StopMusicOnHold: Stops playing music on hold.

==StopPlayTones==

'''Synopsis'''

Stop playing a tone list

'''Description'''

Stop playing a tone list

==System==

'''Synopsis'''

Execute a system command

'''Description'''

System(command):

Executes a command by using system(). If the command fails, the console should report a fallthrough.

Result of execution is returned in the SYSTEMSTATUS channel variable:
FAILURE Could not execute the specified command
SUCCESS Specified command successfully executed

Old behaviour: If the command itself executes but is in error, and if there exists a priority n + 101, where 'n' is the priority of the current instance, then the channel will be setup to continue at that priority level. Note that this jump functionality has been deprecated and will only occur if the global priority jumping option is enabled in extensions.conf.

==TestClient==

'''Synopsis'''

Execute Interface Test Client

'''Description'''

TestClient(testid):

Executes test client with given testid.

Results stored in var/log/asterisk/testreports/<testid>-client.txt

==TestServer==

'''Synopsis'''

Execute Interface Test Server

'''Description'''

TestServer(): Perform test server function and write call report.

Results stored in /var/log/asterisk/testreports/<testid>-server.txt

==Transfer==

'''Synopsis'''

Transfer caller to remote extension

'''Description'''

Transfer([Tech/]dest[|options]):

Requests the remote caller be transferred to a given destination. If TECH (SIP, IAX2, LOCAL etc) is used, only an incoming call with the same channel technology will be transfered. Note that for SIP, if you transfer before call is setup, a 302 redirect SIP message will be returned to the caller.

The result of the application will be reported in the TRANSFERSTATUS channel variable:
:: SUCCESS    Transfer succeeded
:: FAILURE   Transfer failed
:: UNSUPPORTED   Transfer unsupported by channel driver
The option string many contain the following character:
'j' -- jump to n+101 priority if the channel transfer attempt fails

==TrySystem==

'''Synopsis'''

Try executing a system command

'''Description'''

TrySystem(command):

Executes a command by using system(). on any situation. Result of execution is returned in the SYSTEMSTATUS channel variable:
:: FAILURE    Could not execute the specified command
:: SUCCESS    Specified command successfully executed
:: APPERROR    Specified command successfully executed, but returned error code

Old behaviour:

If the command itself executes but is in error, and if there exists a priority n + 101, where 'n' is the priority of the current instance, then the channel will be setup to continue at that priority level. Otherwise, System will terminate.

==TXTCIDName==

'''Synopsis'''

Lookup caller name from TXT record

'''Description'''

TXTCIDName(<CallerIDNumber>[|options]):

Looks up a Caller Name via DNS and sets the variable 'TXTCIDNAME'. TXTCIDName will either be blank or return the value found in the TXT record in DNS.

The option string may contain the following character:
'j' -- jump to n+101 priority if the lookup fails
This application sets the following channel variable upon completion:
TXTCIDNAMESTATUS The status of the lookup as a text string, one of
SUCCESS | FAILED

P-R

2007-09-12T06:19:05Z

Summary: /* Record */

; Index P-R of Asterisk Applications
==Page==

'''Synopsis'''

Pages phones

'''Description'''

Page(Technology/Resource&Technology2/Resource2[|options])

Places outbound calls to the given technology / resource and dumps them into a conference bridge as muted participants. The original caller is dumped into the conference as a speaker and the room is destroyed when the original caller leaves. Valid options are:
:: d - full duplex audio
:: q - quiet, do not play beep to caller

==Park==

'''Synopsis'''

Park yourself

'''Description'''

Park():

Used to park yourself (typically in combination with a supervised transfer to know the parking space). This application is always registered internally and does not need to be explicitly added into the dialplan, although you should include the 'parkedcalls' context.

==ParkAndAnnounce==

'''Synopsis'''

Park and Announce

'''Description'''

ParkAndAnnounce(announce:template|timeout|dial|[return_context]):

Park a call into the parkinglot and announce the call over the console. announce template: colon separated list of files to announce, the word PARKED will be replaced by a say_digits of the ext the call is parked in timeout: time in seconds before the call returns into the return context. dial: The app_dial style resource to call to make the announcement. Console/dsp calls the console. return_context: the goto style label to jump the call back into after timeout. default=prio+1

==ParkedCall==

'''Synopsis'''

Answer a parked call

'''Description'''

ParkedCall(exten):

Used to connect to a parked call. This application is always registered internally and does not need to be explicitly added into the dialplan, although you should include the 'parkedcalls' context.

==PauseQueueMember==

'''Synopsis'''

Pauses a queue member

'''Description'''

PauseQueueMember([queuename]|interface[|options]):

Pauses (blocks calls for) a queue member. The given interface will be paused in the given queue. This prevents any calls from being sent from the queue to the interface until it is unpaused with UnpauseQueueMember or the manager interface. If no queuename is given, the interface is paused in every queue it is a member of. If the interface is not in the named queue, or if no queue is given and the interface is not in any queue, it will jump to priority n+101, if it exists and the appropriate options are set.
The application will fail if the interface is not found and no extension to jump to exists.
The option string may contain zero or more of the following characters:
:: 'j' -- jump to +101 priority when appropriate.
: This application sets the following channel variable upon completion:
:: PQMSTATUS The status of the attempt to pause a queue member as a
::: text string, one of
:::: PAUSED | NOTFOUND
Example: PauseQueueMember(|SIP/3000)

==Pickup==

'''Synopsis'''

Directed Call Pickup

'''Description'''

Pickup(extension[@context]):

This application can pickup any ringing channel that is calling the specified extension. If no context is specified, the current context will be used.

==Playback==

'''Synopsis'''

Play a file

'''Description'''

Playback(filename[&filename2...][|option]):

Plays back given filenames (do not put extension). Options may also be included following a pipe symbol. The 'skip' option causes the playback of the message to be skipped if the channel is not in the 'up' state (i.e. it hasn't been answered yet). If 'skip' is specified, the application will return immediately should the channel not be off hook. Otherwise, unless 'noanswer' is specified, the channel will be answered before the sound is played. Not all channels support playing messages while still on hook. If 'j' is specified, the application will jump to priority n+101 if present when a file specified to be played does not exist.
This application sets the following channel variable upon completion:
: PLAYBACKSTATUS The status of the playback attempt as a text string, one of
:: SUCCESS | FAILED

==PlayTones==

'''Synopsis'''

Play a tone list

'''Description'''

PlayTones(arg):

Plays a tone list. Execution will continue with the next step immediately, while the tones continue to play. Arg is either the tone name defined in the indications.conf configuration file, or a directly specified list of frequencies and durations. See the sample indications.conf for a description of the specification of a tonelist. Use the StopPlayTones application to stop the tones playing.

==PrivacyManager==

'''Synopsis'''

Require phone number to be entered, if no CallerID sent

'''Description'''

PrivacyManager([maxretries[|minlength[|options]]]):

If no Caller*ID is sent, PrivacyManager answers the channel and asks the caller to enter their phone number. The caller is given 3 attempts to do so.
The application does nothing if Caller*ID was received on the channel.
: Configuration file privacy.conf contains two variables:
:: maxretries default 3 -maximum number of attempts the caller is allowed
::: to input a callerid.
:: minlength default 10 -minimum allowable digits in the input callerid number.
If you don't want to use the config file and have an i/o operation with
every call, you can also specify maxretries and minlength as application
parameters. Doing so supercedes any values set in privacy.conf.
The option string may contain the following character:
: 'j' -- jump to n+101 priority after <maxretries> failed attempts to collect
:: the minlength number of digits.
The application sets the following channel variable upon completion:
PRIVACYMGRSTATUS The status of the privacy manager's attempt to collect
::: a phone number from the user. A text string that is either:
:: SUCCESS | FAILED

==Progress==

'''Synopsis'''

Indicate progress

'''Description'''

Progress():

This application will request that in-band progress information be provided to the calling channel.

==Queue==

'''Synopsis'''

Queue a call for a call queue

'''Description'''

Queue(queuename[|options[|URL][|announceoverride][|timeout]]):

Queues an incoming call in a particular call queue as defined in queues.conf.
This application will return to the dialplan if the queue does not exist, or any of the join options cause the caller to not enter the queue.

The option string may contain zero or more of the following characters:
'd' -- data-quality (modem) call (minimum delay).
'h' -- allow callee to hang up by hitting *.
'H' -- allow caller to hang up by hitting *.
'n' -- no retries on the timeout; will exit this application and
go to the next step.
'r' -- ring instead of playing MOH
't' -- allow the called user transfer the calling user
'T' -- to allow the calling user to transfer the call.
'w' -- allow the called user to write the conversation to disk via Monitor
'W' -- allow the calling user to write the conversation to disk via Monitor
In addition to transferring the call, a call may be parked and then picked
up by another user.
The optional URL will be sent to the called party if the channel supports it.
The timeout will cause the queue to fail out after a specified number of
seconds, checked between each queues.conf 'timeout' and 'retry' cycle.
This application sets the following channel variable upon completion:
QUEUESTATUS The status of the call as a text string, one of
TIMEOUT | FULL | JOINEMPTY | LEAVEEMPTY | JOINUNAVAIL | LEAVEUNAVAIL

==Random==

'''Synopsis'''

Conditionally branches, based upon a probability

'''Description'''

Random([probability]:[context|]extension|]priority)
probability := INTEGER in the range 1 to 100

==Read==

'''Synopsis'''

Read a variable

'''Description'''

Read(variable[|filename][|maxdigits][|option][|attempts][|timeout])

Reads a #-terminated string of digits a certain number of times from the user in to the given variable.
filename -- file to play before reading digits.
maxdigits -- maximum acceptable number of digits. Stops reading after
maxdigits have been entered (without requiring the user to
press the '#' key).
Defaults to 0 - no limit - wait for the user press the '#' key.
Any value below 0 means the same. Max accepted value is 255.
option -- may be 'skip' to return immediately if the line is not up,
or 'noanswer' to read digits even if the line is not up.
attempts -- if greater than 1, that many attempts will be made in the
event no data is entered.
timeout -- if greater than 0, that value will override the default timeout.

Read should disconnect if the function fails or errors out.

==ReadFile==

'''Synopsis'''

ReadFile(varname=file,length)

'''Description'''

ReadFile(varname=file,length)
Varname - Result stored here.
File - The name of the file to read.
Length - Maximum number of characters to capture.

==RealTime==

'''Synopsis'''

Realtime Data Lookup

'''Description'''

Use the RealTime config handler system to read data into channel variables.
RealTime(<family>|<colmatch>|<value>[|<prefix>])
All unique column names will be set as channel variables with optional prefix to the name. e.g. prefix of 'var_' would make the column 'name' become the variable ${var_name}

==RealTimeUpdate==

'''Synopsis'''

Realtime Data Rewrite

'''Description'''

Use the RealTime config handler system to update a value
RealTimeUpdate(<family>|<colmatch>|<value>|<newcol>|<newval>)
The column <newcol> in 'family' matching column <colmatch>=<value> will be updated to <newval>

==Record==

'''Synopsis'''

Record to a file

'''Description'''
Record(filename.format|silence[|maxduration][|options])

Records from the channel into a given filename. If the file exists it will be overwritten.
- 'format' is the format of the file type to be recorded (wav, gsm, etc).
- 'silence' is the number of seconds of silence to allow before returning.
- 'maxduration' is the maximum recording duration in seconds. If missing
or 0 there is no maximum.
- 'options' may contain any of the following letters:
'a' : append to existing recording rather than replacing
'n' : do not answer, but record anyway if line not yet answered
'q' : quiet (do not play a beep tone)
's' : skip recording if the line is not yet answered
't' : use alternate '*' terminator key instead of default '#'
If filename contains '%d', these characters will be replaced with a number incremented by one each time the file is recorded. A channel variable named RECORDED_FILE will also be set, which contains the final filemname.

Use 'show file formats' to see the available formats on your system

User can press '#' to terminate the recording and continue to the next priority.

If the user should hangup during a recording, all data will be lost and the application will teminate.

==RemoveQueueMember==

'''Synopsis'''

Dynamically removes queue members

'''Description'''

RemoveQueueMember(queuename[|interface[|options]]):

Dynamically removes interface to an existing queue If the interface is NOT in the queue and there exists an n+101 priority then it will then jump to this priority. Otherwise it will return an error The option string may contain zero or more of the following characters:
'j' -- jump to +101 priority when appropriate.
This application sets the following channel variable upon completion:
RQMSTATUS The status of the attempt to remove a queue member as a
text string, one of
REMOVED | NOTINQUEUE | NOSUCHQUEUE
Example: RemoveQueueMember(techsupport|SIP/3000)

==ResetCDR==

'''Synopsis'''

Resets the Call Data Record

'''Description'''

ResetCDR([options]):

This application causes the Call Data Record to be reset.
: Options:
:: w -- Store the current CDR record before resetting it.
:: a -- Store any stacked records.
:: v -- Save CDR variables.

==ResponseTimeout==

'''Synopsis'''

Set maximum timeout awaiting response

'''Description'''

ResponseTimeout(seconds):

This will set the maximum amount of time permitted to wait for an extension to dialed (see the WaitExten application), before the timeout occurs. If this timeout is reached, dialplan execution will continue at the 't' extension, if it exists.
ResponseTimeout has been deprecated in favor of Set(TIMEOUT(response)=timeout)

==RetryDial==

'''Synopsis'''

Place a call, retrying on failure allowing optional exit extension.

'''Description'''

RetryDial(announce|sleep|retries|dialargs):

This application will attempt to place a call using the normal Dial application. If no channel can be reached, the 'announce' file will be played. Then, it will wait 'sleep' number of seconds before retying the call. After 'retires' number of attempts, the calling channel will continue at the next priority in the dialplan. If the 'retries' setting is set to 0, this application will retry endlessly. While waiting to retry a call, a 1 digit extension may be dialed. If that extension exists in either the context defined in ${EXITCONTEXT} or the current one, The call will jump to that extension immediately. The 'dialargs' are specified in the same format that arguments are provided to the Dial application.

==Return==

'''Synopsis'''

Return from gosub routine

'''Description'''

Return()
Jumps to the last label on the stack, removing it.

==Ringing==

'''Synopsis'''

Indicate ringing tone

'''Description'''

Ringing():

This application will request that the channel indicate a ringing tone to the user.

M-N

2007-09-12T05:58:42Z

Summary: /* Macro */

; Index M-N of Asterisk Applications
==Macro==

'''Synopsis'''

Macro Implementation

'''Description'''

Macro(macroname|arg1|arg2...):

Executes a macro using the context 'macro-<macroname>', jumping to the 's' extension of that context and executing each step, then returning when the steps end. The calling extension, context, and priority are stored in ${MACRO_EXTEN}, ${MACRO_CONTEXT} and ${MACRO_PRIORITY} respectively.

Arguments become ${ARG1}, ${ARG2}, etc in the macro context.
If you Goto out of the Macro context, the Macro will terminate and control will be returned at the location of the Goto.

If ${MACRO_OFFSET} is set at termination, Macro will attempt to continue at priority MACRO_OFFSET + N + 1 if such a step exists, and N + 1 otherwise.

Extensions: While a macro is being executed, it becomes the current context.
:: This means that if a hangup occurs, for instance, that the macro
:: will be searched for an 'h' extension, NOT the context from which
:: the macro was called. So, make sure to define all appropriate
:: extensions in your macro! (you can use 'catch' in AEL)
WARNING: Because of the way Macro is implemented (it executes the priorities
:: contained within it via sub-engine), and a fixed per-thread
:: memory stack allowance, macros are limited to 7 levels
:: of nesting (macro calling macro calling macro, etc.); It
:: may be possible that stack-intensive applications in deeply nested
:: macros could cause asterisk to crash earlier than this limit.

==MacroExit==

'''Synopsis'''

Exit From Macro

'''Description'''

MacroExit():

Causes the currently running macro to exit as if it had ended normally by running out of priorities to execute. If used outside a macro, will likely cause unexpected behavior.

==MacroIf==

'''Synopsis'''

Conditional Macro Implementation

'''Description'''

MacroIf(<expr>?macroname_a[|arg1][:macroname_b[|arg1]]) Executes macro defined in <macroname_a> if <expr> is true (otherwise <macroname_b> if provided) Arguments and return values as in application macro()

==MailboxExists==

'''Synopsis'''

Check to see if Voicemail mailbox exists

'''Description'''

MailboxExists(mailbox[@context][|options]):

Check to see if the specified mailbox exists. If no voicemail context is specified, the 'default' context will be used. This application will set the following channel variable upon completion:
: VMBOXEXISTSSTATUS - This will contain the status of the execution of the
:: MailboxExists application. Possible values include:
:: SUCCESS | FAILED
Options:
:: j - Jump to priority n+101 if the mailbox is found.

==Math==

'''[Synopsis'''

Performs Mathematical Functions

'''Description'''

Math(returnvar,<number1><op><number 2>

Perform floating point calculation on number 1 to number 2 and store the result in returnvar. Valid ops are:
+,-,/,*,%,<,>,>=,<=,==
and behave as their C equivalents. This application has been deprecated in favor of the MATH function.

==MD5==

'''Synopsis'''

Calculate MD5 checksum

'''Description'''

MD5(<var>=<string>): Calculates a MD5 checksum on <string>. Returns hash value in a channel variable.

==MD5Check==

'''Synopsis'''

Check MD5 checksum

'''Description'''

MD5Check(<md5hash>|<string>[|options]):

Calculates a MD5 checksum on <string> and compares it with the hash. Returns 0 if <md5hash> is correct for <string>. The option string may contain zero or more of the following characters:
:: 'j' -- jump to priority n+101 if the hash and string do not match
This application sets the following channel variable upon completion:
:: CHECKMD5STATUS The status of the MD5 check, one of the following
::: MATCH | NOMATCH

==MeetMe==

'''Synopsis'''

MeetMe conference bridge

'''Description'''

MeetMe([confno][,[options][,pin]]):

Enters the user into a specified MeetMe conference. If the conference number is omitted, the user will be prompted to enter one. User can exit the conference by hangup, or if the 'p' option is specified, by pressing '#'.

Please note: The Zaptel kernel modules and at least one hardware driver (or ztdummy)
:: must be present for conferencing to operate properly. In addition, the chan_zap
:: channel driver must be loaded for the 'i' and 'r' options to operate at all.

The option string may contain zero or more of the following characters:
'a' -- set admin mode
'A' -- set marked mode
'b' -- run AGI script specified in ${MEETME_AGI_BACKGROUND}
Default: conf-background.agi
(Note: This does not work with non-Zap channels in the same conference)
'c' -- announce user(s) count on joining a conference
'd' -- dynamically add conference
'D' -- dynamically add conference, prompting for a PIN
'e' -- select an empty conference
'E' -- select an empty pinless conference
'i' -- announce user join/leave
'm' -- set monitor only mode (Listen only, no talking)
'M' -- enable music on hold when the conference has a single caller
'p' -- allow user to exit the conference by pressing '#'
'P' -- always prompt for the pin even if it is specified
'q' -- quiet mode (don't play enter/leave sounds)
'r' -- Record conference (records as ${MEETME_RECORDINGFILE}
using format ${MEETME_RECORDINGFORMAT}). Default filename is
meetme-conf-rec-${CONFNO}-${UNIQUEID} and the default format is wav.
's' -- Present menu (user or admin) when '*' is received ('send' to menu)
't' -- set talk only mode. (Talk only, no listening)
'T' -- set talker detection (sent to manager interface and meetme list)
'w[(<secs>)]'
-- wait until the marked user enters the conference
'x' -- close the conference when last marked user exits
'X' -- allow user to exit the conference by entering a valid single
digit extension ${MEETME_EXIT_CONTEXT} or the current context
if that variable is not defined.

==MeetMeAdmin==

'''Synopsis'''

MeetMe conference Administration

'''Description'''

MeetMeAdmin(confno,command[,user]): Run admin command for conference
'e' -- Eject last user that joined
'k' -- Kick one user out of conference
'K' -- Kick all users out of conference
'l' -- Unlock conference
'L' -- Lock conference
'm' -- Unmute conference
'M' -- Mute conference
'n' -- Unmute entire conference (except admin)
'N' -- Mute entire conference (except admin)

==MeetMeCount==

'''Synopsis'''

MeetMe participant count

'''Description'''

MeetMeCount(confno[|var]):

Plays back the number of users in the specified MeetMe conference. If var is specified, playback will be skipped and the value will be returned in the variable. Upon app completion, MeetMeCount will hangup the channel, unless priority n+1 exists, in which case priority progress will continue. A ZAPTEL INTERFACE MUST BE INSTALLED FOR CONFERENCING FUNCTIONALITY.

==Milliwatt==

'''Synopsis'''

Generate a Constant 1000Hz tone at 0dbm (mu-law)

'''Description'''

Milliwatt(): Generate a Constant 1000Hz tone at 0dbm (mu-law)

==misdn_check_l2l1==

'''Synopsis'''

misdn_check_l2l1

'''Description'''

misdn_check_l2l1(<port>||g:<groupname>,timeout)Checks if the L2 and L1 are up on either the given <port> or on the ports in the group with <groupname> If the L1/L2 are down, check_l2l1 gets up the L1/L2 and waits for <timeout> seconds that this happens. Otherwise, nothing happens

This application, ensures the L1/L2 state of the Ports in a group it is intended to make the pmp_l1_check option redundant and to fix a buggy switch config from your provider

a sample dialplan would look like:
exten => _X.,1,misdn_check_l2l1(g:out|2)
exten => _X.,n,dial(mISDN/g:out/${EXTEN})

==misdn_facility==

'''Synopsis'''

misdn_facility

'''Description'''

misdn_facility(<FACILITY_TYPE>|<ARG1>|..) Sends the Facility Message FACILITY_TYPE with the given Arguments to the current ISDN Channel Supported Facilities are:
: type=calldeflect args=Nr where to deflect

==misdn_set_opt==

'''Synopsis'''

misdn_set_opt

'''Description'''

misdn_set_opt(:<opt><optarg>:<opt><optarg>..):
Sets mISDN opts. and optargs

The available options are:
d - Send display text on called phone, text is the optparam
n - don't detect dtmf tones on called channel
h - make digital outgoing call
c - make crypted outgoing call, param is keyindex
e - perform echo cancelation on this channel,
takes taps as arguments (32,64,128,256)
s - send Non Inband DTMF as inband
vr - rxgain control
vt - txgain control

==MixMonitor==

'''Synopsis'''

Record a call and mix the audio during the recording

'''Description'''

MixMonitor(<file>.<ext>[|<options>[|<command>]])

Records the audio on the current channel to the specified file. If the filename is an absolute path, uses that path, otherwise creates the file in the configured monitoring directory from asterisk.conf.

Valid options:
a - Append to the file instead of overwriting it.
b - Only save audio to the file while the channel is bridged.
Note: Does not include conferences or sounds played to each bridged
party.
v(<x>) - Adjust the heard volume by a factor of <x> (range -4 to 4)
V(<x>) - Adjust the spoken volume by a factor of <x> (range -4 to 4)
W(<x>) - Adjust the both heard and spoken volumes by a factor of <x>
(range -4 to 4)

<command> will be executed when the recording is over Any strings matching ^{X} will be unescaped to ${X}. All variables will be evaluated at the time MixMonitor is called. The variable MIXMONITOR_FILENAME will contain the filename used to record.

==Monitor==

'''Synopsis'''

Monitor a channel

'''Description'''

Monitor([file_format[:urlbase]|[fname_base]|[options]]):

Used to start monitoring a channel. The channel's input and output voice packets are logged to files until the channel hangs up or monitoring is stopped by the StopMonitor application.
file_format optional, if not set, defaults to "wav"
fname_base if set, changes the filename used to the one specified.
options:
m - when the recording ends mix the two leg files into one and
delete the two leg files. If the variable MONITOR_EXEC is set, the
application referenced in it will be executed instead of
soxmix and the raw leg files will NOT be deleted automatically.
soxmix or MONITOR_EXEC is handed 3 arguments, the two leg files
and a target mixed file name which is the same as the leg file names
only without the in/out designator.
If MONITOR_EXEC_ARGS is set, the contents will be passed on as
additional arguements to MONITOR_EXEC
Both MONITOR_EXEC and the Mix flag can be set from the
administrator interface
b - Don't begin recording unless a call is bridged to another channel

Returns -1 if monitor files can't be opened or if the channel is already monitored, otherwise 0.

==MP3Player==

'''Synopsis'''

Play an MP3 file or stream

'''Description'''

MP3Player(location) Executes mpg123 to play the given location, which typically would be a filename or a URL. User can exit by pressing any key on the dialpad, or by hanging up.

==MusicOnHold==

'''Synopsis'''

Play Music On Hold indefinitely

'''Description'''

MusicOnHold(class):

Plays hold music specified by class. If omitted, the default music source for the channel will be used. Set the default class with the SetMusicOnHold() application. Returns -1 on hangup.
Never returns otherwise.

==NBScat==

'''Synopsis'''

Play an NBS local stream

'''Description'''

NBScat: Executes nbscat to listen to the local NBS stream. User can exit by pressing any key

==NoCDR==

'''Synopsis'''

Tell Asterisk to not maintain a CDR for the current call

'''Description'''

NoCDR(): This application will tell Asterisk not to maintain a CDR for the current call.

==NoOp==

'''Synopsis'''

Do Nothing

'''Description'''

NoOp(): This applicatiion does nothing. However, it is useful for debugging purposes. Any text that is provided as arguments to this application can be viewed at the Asterisk CLI. This method can be used to see the evaluations of variables or functions without having any effect.

G-L

2007-09-12T05:26:29Z

Summary: /* HasNewVoicemail */

; Index G-L of Asterisk Applications
==GetCPEID==

'''Synopsis'''

Get ADSI CPE ID

'''Description'''

GetCPEID: Obtains and displays ADSI CPE ID and other information in order to properly setup zapata.conf for on-hook operations.

==GetGroupCount==

'''Synopsis'''

Get the channel count of a group

'''Description'''

Usage: GetGroupCount([groupname][@category])

Calculates the group count for the specified group, or uses the current channel's group if not specifed (and non-empty). Stores result in GROUPCOUNT. Note: This application has been deprecated, please use the function
GROUP_COUNT.

==GetGroupMatchCount==

'''Synopsis'''

Get the channel count of all groups that match a pattern

'''Description'''

Usage: GetGroupMatchCount(groupmatch[@category])

Calculates the group count for all groups that match the specified pattern. Uses standard regular expression matching (see regex(7)). Stores result in GROUPCOUNT. Always returns 0.
Note: This application has been deprecated, please use the function GROUP_MATCH_COUNT.

==Gosub==

'''Synopsis'''

Jump to label, saving return address

'''Description'''

Gosub([context|]exten|]priority) Jumps to the label specified, saving the return address.

==GosubIf==

'''Synopsis'''

Jump to label, saving return address

'''Description'''

GosubIf(condition?labeliftrue[:labeliffalse])
If the condition is true, then jump to labeliftrue. If false, jumps to labeliffalse, if specified. In either case, a jump saves the return point in the dialplan, to be returned to with a Return.

==GotoIfTime==

'''Synopsis'''

Conditional Goto based on the current time

'''Description'''

GotoIfTime(<times>|<weekdays>|<mdays>|<months>?[context|]exten|]priority):

This application will set the context, extension, and priority in the channel structure if the current time matches the given time specification. Otherwise, nothing is done. Further information on the time specification can be found in examples illustrating how to do time-based context includes in the dialplan. If the target jump location is bogus, Asterisk will respond as outlined in Goto.

==Goto==

'''Synopsis'''

Jump to a particular priority, extension, or context

'''Description'''

Goto([context|]extension|]priority):

This application will set the current context, extension, and priority in the channel structure. After it completes, the pbx engine will continue dialplan execution at the specified location. If no specific extension, or extension and context, are specified, then this application will just set the specified priority of the current extension.

At least a priority is required as an argument, or the goto will return a -1, and the channel and call will be terminated. If the location that is put into the channel information is bogus, and asterisk cannot find that location in the dialplan, then the execution engine will try to find and execute the code in the 'i' (invalid) extension in the current context.

If that does not exist, it will try to execute the 'h' extension. If either or neither the 'h' or 'i' extensions have been defined, the channel is hung up, and the execution of instructions on the channel is terminated.

What this means is that, for example, you specify a context that does not exist, then it will not be possible to find the 'h' or 'i' extensions, and the call will terminate!

==GotoIf==

'''Synopsis'''

Conditional goto

'''Description'''

GotoIf(condition?[labeliftrue]:[labeliffalse]):

This application will set the current context, extension, and priority in the channel structure based on the evaluation of the given condition. After this application completes, the pbx engine will continue dialplan execution at the specified location in the dialplan. The channel will continue at 'labeliftrue' if the condition is true, or 'labeliffalse' if the condition is false. The labels are specified with the same syntax as used within the Goto application. If the label chosen by the condition is omitted, no jump is performed, and the execution passes to the next instruction. If the target location is bogus, and does not exist, the execution engine will try to find and execute the code in the 'i' (invalid) extension in the current context. If that does not exist, it will try to execute the 'h' extension. If either or neither the 'h' or 'i' extensions have been defined, the channel is hung up, and the execution of instructions on the channel is terminated. Remember that this command can set the current context, and if the context specified does not exist, then it will not be able to find any 'h' or 'i' extensions there,
and the channel and call will both be terminated!

==Hangup==

'''Synopsis'''

Hang up the calling channel

'''Description'''

Hangup(): This application will hang up the calling channel.

==HasNewVoicemail==

'''Synopsis'''

Conditionally branches to priority + 101 with the right options set

'''Description'''

HasNewVoicemail(vmbox[/folder][@context][|varname[|options]])

Assumes folder 'INBOX' if folder is not specified. Optionally sets <varname> to the number of messages
in that folder. The option string may contain zero of the following character:
'j' -- jump to priority n+101, if there is new voicemail in folder 'folder' or INBOX
This application sets the following channel variable upon completion:
HASVMSTATUS
The result of the new voicemail check returned as a text string as follows
<# of messages in the folder, 0 for NONE>

==IAX2Provision==

'''Synopsis'''

Provision a calling IAX2 with a given template

'''Description'''

IAX2Provision([template]): Provisions the calling IAX2 (assuming the calling entity is in fact an IAX2) with the given template or default if one is not specified. Returns -1 on error or 0 on success.

==ICES==

'''Synopsis'''

Encode and stream using 'ices'

'''Description'''

ICES(config.xml) Streams to an icecast server using ices (available separately). A configuration file must be supplied for ices (see examples/asterisk-ices.conf).

==ImportVar==

'''Synopsis'''

Import a variable from a channel into a new variable

'''Description'''

ImportVar(newvar=channelname|variable): This application imports a variable from the specified channel (as opposed to the current one) and stores it as a variable in the current channel (the channel that is calling this application). Variables created by this application have the same inheritance properties as those created with the Set application. See the documentation for Set for more information.

==LookupBlacklist==

'''Synopsis'''

Look up Caller*ID name/number from blacklist database

'''Description'''

LookupBlacklist(options): Looks up the Caller*ID number on the active channel in the Asterisk database (family 'blacklist'). The option string may contain the following character:
'j' -- jump to n+101 priority if the number/name is found in the blacklist
This application sets the following channel variable upon completion:
LOOKUPBLSTATUS
The status of the Blacklist lookup as a text string, one of
FOUND | NOTFOUND
Example: exten => 1234,1,LookupBlacklist()

==LookupCIDName==

'''Synopsis'''

Look up CallerID Name from local database

'''Description'''

LookupCIDName: Looks up the Caller*ID number on the active channel in the Asterisk database (family 'cidname') and sets the Caller*ID name. Does nothing if no Caller*ID was received on the channel. This is useful if you do not subscribe to Caller*ID name delivery, or if you want to change the names on some incoming calls.

D-F

2007-09-12T04:46:21Z

Summary: /* ExternalIVR */

; Index D-F of Asterisk Applications
==DateTime==

'''Synopsis'''

Says a specified time in a custom format

'''Description'''

DateTime([unixtime][|[timezone][|format]])
unixtime: time, in seconds since Jan 1, 1970. May be negative.
defaults to now.
timezone: timezone, see /usr/share/zoneinfo for a list.
defaults to machine default.
format: a format the time is to be said in. See voicemail.conf.
defaults to "ABdY 'digits/at' IMp"

==DBdel==

'''Synopsis'''

Delete a key from the database

'''Description'''

DBdel(family/key):

This application will delete a key from the Asterisk database.

==DBdeltree==

'''Synopsis'''

Delete a family or keytree from the database

'''Description'''

DBdeltree(family[/keytree]):

This application will delete a family or keytree from the Asterisk database

==DBget==

'''Synopsis'''

Retrieve a value from the database

'''Description'''

DBget(varname=family/key[|options]):

This application will retrieve a value from the Asterisk database and store it in the given variable.
Options:
j - Jump to priority n+101 if the requested family/key isn't found.
This application sets the following channel variable upon completion:
DBGETSTATUS - This variable will contain the status of the attempt
FOUND | NOTFOUND
This application has been deprecated in favor of the DB function.

==DBput==

'''Synopsis'''

Store a value in the database

'''Description'''

DBput(family/key=value):

This application will store the given value in the specified location in the Asterisk database.
This application has been deprecated in favor of the DB function.

==DeadAGI==

'''Synopsis'''

Executes AGI on a hungup channel

'''Description'''

[E|Dead]AGI(command|args):

Executes an Asterisk Gateway Interface compliant program on a channel. AGI allows Asterisk to launch external programs written in any language to control a telephony channel, play audio, read DTMF digits, etc. by communicating with the AGI protocol on stdin and stdout. 
Returns -1 on hangup (except for DeadAGI) or if application requested hangup, or 0 on non-hangup exit.
Using 'EAGI' provides enhanced AGI, with incoming audio available out of band on file descriptor 3
Use the CLI command 'show agi' to list available agi commands

==Dial==

'''Synopsis'''

Place a call and connect to the current channel

'''Description'''

Dial(Technology/resource[&Tech2/resource2...][|timeout][|options][|URL]):

This application will place calls to one or more specified channels. As soon as one of the requested channels answers, the originating channel will be answered, if it has not already been answered. These two channels will then be active in a bridged call. All other channels that were requested will then
be hung up. Unless there is a timeout specified, the Dial application will wait indefinitely until one of the called channels answers, the user hangs up, or if all of the called channels are busy or unavailable. Dialplan executing will continue if no requested channels can be called, or if the timeout expires.

This application sets the following channel variables upon completion:
DIALEDTIME - This is the time from dialing a channel until when it
is disconnected.
ANSWEREDTIME - This is the amount of time for actual call.
DIALSTATUS - This is the status of the call:
CHANUNAVAIL | CONGESTION | NOANSWER | BUSY | ANSWER | CANCEL
DONTCALL | TORTURE | INVALIDARGS

For the Privacy and Screening Modes, the DIALSTATUS variable will be set to DONTCALL if the called party chooses to send the calling party to the 'Go Away' script. The DIALSTATUS variable will be set to TORTURE if the called party wants to send the caller to the 'torture' script. This application will report normal termination if the originating channel hangs up, or if the call is bridged and either of the parties in the bridge ends the call.

The optional URL will be sent to the called party if the channel supports it.
If the OUTBOUND_GROUP variable is set, all peer channels created by this application will be put into that group (as in Set(GROUP()=...).

If the OUTBOUND_GROUP_ONCE variable is set, all peer channels created by this application will be put into that group (as in Set(GROUP()=...). Unlike OUTBOUND_GROUP,
however, the variable will be unset after use.

Options:
A(x) - Play an announcement to the called party, using 'x' as the file.
C - Reset the CDR for this call.
d - Allow the calling user to dial a 1 digit extension while waiting for
a call to be answered. Exit to that extension if it exists in the
current context, or the context defined in the EXITCONTEXT variable,
if it exists.
D([called][:calling]) - Send the specified DTMF strings *after* the called
party has answered, but before the call gets bridged. The 'called'
DTMF string is sent to the called party, and the 'calling' DTMF
string is sent to the calling party. Both parameters can be used
alone.
f - Force the callerid of the *calling* channel to be set as the
extension associated with the channel using a dialplan 'hint'.
For example, some PSTNs do not allow CallerID to be set to anything
other than the number assigned to the caller.
g - Proceed with dialplan execution at the current extension if the
destination channel hangs up.
G(context^exten^pri) - If the call is answered, transfer the calling party to
the specified priority and the called party to the specified priority+1.
Optionally, an extension, or extension and context may be specified.
Otherwise, the current extension is used. You cannot use any additional
action post answer options in conjunction with this option.
h - Allow the called party to hang up by sending the '*' DTMF digit.
H - Allow the calling party to hang up by hitting the '*' DTMF digit.
j - Jump to priority n+101 if all of the requested channels were busy.
L(x[:y][:z]) - Limit the call to 'x' ms. Play a warning when 'y' ms are
left. Repeat the warning every 'z' ms. The following special
variables can be used with this option:
* LIMIT_PLAYAUDIO_CALLER yes|no (default yes)
Play sounds to the caller.
* LIMIT_PLAYAUDIO_CALLEE yes|no
Play sounds to the callee.
* LIMIT_TIMEOUT_FILE File to play when time is up.
* LIMIT_CONNECT_FILE File to play when call begins.
* LIMIT_WARNING_FILE File to play as warning if 'y' is defined.
The default is to say the time remaining.
m([class]) - Provide hold music to the calling party until a requested
channel answers. A specific MusicOnHold class can be
specified.
M(x[^arg]) - Execute the Macro for the *called* channel before connecting
to the calling channel. Arguments can be specified to the Macro
using '^' as a delimeter. The Macro can set the variable
MACRO_RESULT to specify the following actions after the Macro is
finished executing.
* ABORT Hangup both legs of the call.
* CONGESTION Behave as if line congestion was encountered.
* BUSY Behave as if a busy signal was encountered. This will also
have the application jump to priority n+101 if the
'j' option is set.
* CONTINUE Hangup the called party and allow the calling party
to continue dialplan execution at the next priority.
* GOTO:<context>^<exten>^<priority> - Transfer the call to the
specified priority. Optionally, an extension, or
extension and priority can be specified.
You cannot use any additional action post answer options in conjunction
with this option.
n - This option is a modifier for the screen/privacy mode. It specifies
that no introductions are to be saved in the priv-callerintros
directory.
N - This option is a modifier for the screen/privacy mode. It specifies
that if callerID is present, do not screen the call.
o - Specify that the CallerID that was present on the *calling* channel
be set as the CallerID on the *called* channel. This was the
behavior of Asterisk 1.0 and earlier.
p - This option enables screening mode. This is basically Privacy mode
without memory.
P([x]) - Enable privacy mode. Use 'x' as the family/key in the database if
it is provided. The current extension is used if a database
family/key is not specified.
r - Indicate ringing to the calling party. Pass no audio to the calling
party until the called channel has answered.
S(x) - Hang up the call after 'x' seconds *after* the called party has
answered the call.
t - Allow the called party to transfer the calling party by sending the
DTMF sequence defined in features.conf.
T - Allow the calling party to transfer the called party by sending the
DTMF sequence defined in features.conf.
w - Allow the called party to enable recording of the call by sending
the DTMF sequence defined for one-touch recording in features.conf.
W - Allow the calling party to enable recording of the call by sending
the DTMF sequence defined for one-touch recording in features.conf.

==Dictate==

'''Synopsis'''

Virtual Dictation Machine

'''Description'''

Dictate([<base_dir>])
Start dictation machine using optional base dir for files.

==DigitTimeout==

'''Synopsis'''

Set maximum timeout between digits

'''Description'''

DigitTimeout(seconds): Set the maximum amount of time permitted between digits when the user is typing in an extension. When this timeout expires, after the user has started to type in an extension, the extension will be considered complete, and will be interpreted. Note that if an extension typed in is valid, it will not have to timeout to be tested, so typically at the expiry of this timeout, the extension will be considered invalid (and thus control would be passed to the 'i' extension, or if it doesn't exist the call would be terminated). The default timeout is 5 seconds. DigitTimeout has been deprecated in favor of Set(TIMEOUT(digit)=timeout)

==Directory==

'''Synopsis'''

Provide directory of voicemail extensions

'''Description'''

Directory(vm-context[|dial-context[|options]]):

This application will present the calling channel with a directory of extensions from which they can search by name. The list of names and corresponding extensions is retrieved from the voicemail configuration file, voicemail.conf. This application will immediately exit if one of the following DTMF digits are received and the extension to jump to exists:
0 - Jump to the 'o' extension, if it exists.
* - Jump to the 'a' extension, if it exists.
Parameters:
vm-context - This is the context within voicemail.conf to use for the
Directory.
dial-context - This is the dialplan context to use when looking for an
extension that the user has selected, or when jumping to the
'o' or 'a' extension.
Options:
f - Allow the caller to enter the first name of a user in the directory
instead of using the last name.

==DISA==

'''Synopsis'''

DISA (Direct Inward System Access)

'''Description'''

DISA(<numeric passcode>[|<context>]) or disa(<filename>)

The DISA, Direct Inward System Access, application allows someone from outside the telephone switch (PBX) to obtain an "internal" system dialtone and to place calls from it as if they were placing a call from
within the switch. DISA plays a dialtone. The user enters their numeric passcode, followed by the pound sign (#). If the passcode is correct, the user is then given system dialtone on which a call may be placed. Obviously, this type of access has SERIOUS security implications, and GREAT care must be taken NOT to compromise your security.

There is a possibility of accessing DISA without password. 
Simply exchange your password with "no-password".

Example: exten => s,1,DISA(no-password|local)

Be aware that using this compromises the security of your PBX.

The arguments to this application (in extensions.conf) allow either specification of a single global passcode (that everyone uses), or individual passcodes contained in a file. It also allow specification
of the context on which the user will be dialing. If no context is specified, the DISA application defaults the context to "disa". Presumably a normal system will have a special context set up for DISA use with some or a lot of restrictions.

The file that contains the passcodes (if used) allows specification of either just a passcode (defaulting to the "disa" context, or passcode|context on each line of the file. The file may contain blank lines, or comments starting with "#" or ";".

In addition, the above arguments may have |new-callerid-string appended to them, to specify a new (different) callerid to be used for this call, for
example: numeric-passcode|context|"My Phone" <(234) 123-4567>
or
full-pathname-of-passcode-file|"My Phone" <(234) 123-4567>
Last but not least, |mailbox[@context] may be appended, which will cause a stutter-dialtone (indication "dialrecall") to be used, if the specified mailbox contains any new messages, for example:
numeric-passcode|context||1234 (w/a changing callerid)
Note that in the case of specifying the numeric-passcode, the context must be specified if the callerid is specified also.

If login is successful, the application looks up the dialed number in the specified (or default) context, and executes it if found. If the user enters an invalid extension and extension "i" (invalid) exists in the context, it will be used.

==DumpChan==

'''Synopsis'''

Dump Info About The Calling Channel

'''Description'''

DumpChan([<min_verbose_level>])

Displays information on channel and listing of all channel variables. If min_verbose_level is specified, output is only displayed when the verbose level is currently set to that number or greater.

==DUNDiLookup==

'''Synopsis'''

Look up a number with DUNDi

'''Description'''

DUNDiLookup(number[|context[|options]])

Looks up a given number in the global context specified or in the reserved 'e164' context if not specified. Returns -1 if the channel is hungup during the lookup or 0 otherwise. On completion, the variable ${DUNDTECH} and ${DUNDDEST} will contain the technology and destination of the appropriate technology and destination to access the number. If no answer was found, and the priority n + 101 exists, execution will continue at that location. Note that this will only occur if the global priority jumping option is enabled in extensions.conf. If the 'b' option is specified, the internal DUNDi cache will by bypassed.

==EAGI==

'''Synopsis'''

Executes an EAGI compliant application

'''Description'''

[E|Dead]AGI(command|args):

Executes an Asterisk Gateway Interface compliant program on a channel. AGI allows Asterisk to launch external programs written in any language to control a telephony channel, play audio, read DTMF digits, etc. by communicating with the AGI protocol on stdin and stdout.

Returns -1 on hangup (except for DeadAGI) or if application requested hangup, or 0 on non-hangup exit.
Using 'EAGI' provides enhanced AGI, with incoming audio available out of band on file descriptor 3

Use the CLI command 'show agi' to list available agi commands

==Echo==

'''Synopsis'''

Echo audio read back to the user

'''Description'''

Echo():

Echo audio read from channel back to the channel. User can exit the application by either pressing the '#' key, or hanging up.

==EndWhile==

'''Synopsis'''

End A While Loop

'''Description'''

Usage: EndWhile()
Return to the previous called While

==EnumLookup==

'''Synopsis'''

Lookup number in ENUM

'''Description'''

EnumLookup(exten[|option]):

Looks up an extension via ENUM and sets the variable 'ENUM'. For VoIP URIs this variable will look like 'TECHNOLOGY/URI' with the appropriate technology. Currently, the enumservices SIP, H323, IAX, IAX2 and TEL are recognized.

Returns status in the ENUMSTATUS channel variable:
ERROR Failed to do a lookup
<tech> Technology of the successful lookup: SIP, H323, IAX, IAX2 or TEL
BADURI Got URI Asterisk does not understand.
The option string may contain zero or the following character:
'j' -- jump to +101 priority if the lookup isn't successful.
and jump to +51 priority on a TEL entry.

==Eval==

'''Synopsis'''

Evaluates a string

'''Description'''

Usage: Eval(newvar=somestring)

Normally Asterisk evaluates variables inline. But what if you want to store variable offsets in a database, to be evaluated later? Eval is the answer, by allowing a string to be evaluated twice in the dialplan, the first time as part of the normal dialplan, and the second using Eval.

==Exec==

'''Synopsis'''

Executes internal application

'''Description'''

Usage: Exec(appname(arguments))

Allows an arbitrary application to be invoked even when not hardcoded into the dialplan. To invoke external applications see the application System. Returns whatever value the app returns or a non-zero value if the app cannot be found.

==ExecIf==

'''Synopsis'''

Conditional exec

'''Description'''

Usage: ExecIF (<expr>|<app>|<data>)

If <expr> is true, execute and return the result of <app>(<data>).
If <expr> is true, but <app> is not found, then the application will return a non-zero value.

==ExecIfTime==

'''Synopsis'''

Conditional application execution based on the current time

'''Description'''

ExecIfTime(<times>|<weekdays>|<mdays>|<months>?appname[|appargs]):

This application will execute the specified dialplan application, with optional arguments, if the current time matches the given time specification. Further information on the time speicification can be found in examples illustrating how to do time-based context includes in the dialplan.

==ExternalIVR==

'''Synopsis'''

Interfaces with an external IVR application

'''Description'''

ExternalIVR(command[|arg[|arg...]]):

Forks an process to run the supplied command, and starts a generator on the channel. The generator's play list is controlled by the external application, which can add and clear entries via simple commands issued over its stdout. The external application will receive all DTMF events received on the channel, and notification if the channel is hung up. The application will not be forcibly terminated when the channel is hung up.

See doc/README.externalivr for a protocol specification.

==Festival==

'''Synopsis'''

Say text to the user

'''Description'''

Festival(text[|intkeys]):

Connect to Festival, send the argument, get back the waveform,play it to the user, allowing any given interrupt keys to immediately terminate and return the value, or 'any' to allow any number back (useful in dialplan)

==Flash==

'''Synopsis'''

Flashes a Zap Trunk

'''Description'''

Flash():

Sends a flash on a zap trunk. This is only a hack for people who want to perform transfers and such via AGI and is generally quite useless oths application will only work on Zap trunks.

==ForkCDR==

'''Synopsis'''

Forks the Call Data Record

'''Description'''

ForkCDR([options]):

Causes the Call Data Record to fork an additional cdr record starting from the time of the fork call If the option 'v' is passed all cdr variables will be passed along also.

A-C

2007-09-12T04:23:55Z

Summary: /* AGI */

; Index A-C of Asterisk Applications
==AbsoluteTimeout==

'''Synopsis'''

Set absolute maximum time of call

'''Description'''

AbsoluteTimeout(seconds):

This application will set the absolute maximum amount of time permitted for a call. A setting of 0 disables the timeout. AbsoluteTimeout has been deprecated in favor of Set(TIMEOUT(absolute)=timeout)

==AddQueueMember==

'''Synopsis'''

Dynamically adds queue members

'''Description'''

AddQueueMember(queuename[|interface[|penalty[|options]]]):

Dynamically adds interface to an existing queue. If the interface is already in the queue and there exists an n+101 priority then it will then jump to this priority. Otherwise it will return an error
The option string may contain zero or more of the following characters:
'j' -- jump to +101 priority when appropriate.
This application sets the following channel variable upon completion:
AQMSTATUS The status of the attempt to add a queue member as a text string, one of
ADDED | MEMBERALREADY | NOSUCHQUEUE
Example: AddQueueMember(techsupport|SIP/3000)

==ADSIProg==

'''Synopsis'''

Load Asterisk ADSI Scripts into phone

'''Description'''

ADSIProg(script):

This application programs an ADSI Phone with the given script. If nothing is specified, the default script (asterisk.adsi) is used.

==AgentCallbackLogin==

'''Synopsis'''

Call agent callback login

'''Description'''

AgentCallbackLogin([AgentNo][|[options][|[exten]@context]]):

Asks the agent to login to the system with callback. The agent's callback extension is called (optionally with the specified context). The option string may contain zero or more of the following characters:
's' -- silent login - do not announce the login ok segment agent logged in/off

==AgentLogin==

'''Synopsis'''

Call agent login

'''Description'''

AgentLogin([AgentNo][|options]):

Asks the agent to login to the system. Always returns -1. While logged in, the agent can receive calls and will hear a 'beep' when a new call comes in. The agent can dump the call by pressing the star key. The option string may contain zero or more of the following characters:

's' -- silent login - do not announce the login ok segment after agent logged in/off

==AgentMonitorOutgoing==

'''Synopsis'''

Record agent's outgoing call

'''Description'''

AgentMonitorOutgoing([options]):

Tries to figure out the id of the agent who is placing outgoing call based on comparison of the callerid of the current interface and the global variable placed by the AgentCallbackLogin application. That's why it should be used only with the AgentCallbackLogin app. Uses the monitoring functions in chan_agent instead of Monitor application. That have to be configured in the agents.conf file.

Return value: 
Normally the app returns 0 unless the options are passed. Also if the callerid or the agentid are not specified it'll look for n+101 priority.

Options:
'd' - make the app return -1 if there is an error condition and there is
no extension n+101
'c' - change the CDR so that the source of the call is 'Agent/agent_id'
'n' - don't generate the warnings when there is no callerid or the
agentid is not known.
It's handy if you want to have one context for agent and non-agent calls.

==AGI==

'''Synopsis'''

Executes an AGI compliant application

'''Description'''

[E|Dead]AGI(command|args):

Executes an Asterisk Gateway Interface compliant program on a channel. AGI allows Asterisk to launch external programs written in any language to control a telephony channel, play audio, read DTMF digits, etc. by communicating with the AGI protocol on stdin and stdout. Returns -1 on hangup (except for DeadAGI) or if application requested hangup, or 0 on on-hangup exit. Using 'EAGI' provides enhanced AGI, with incoming audio available out of band on file descriptor 3

Use the CLI command 'show agi' to list available agi commands

answer Answer channel
channel status Returns status of the connected channel
database del Removes database key/value
database deltree Removes database keytree/value
database get Gets database value
database put Adds/updates database value
exec Executes a given Application
get data Prompts for DTMF on a channel
get full variable Evaluates a channel expression
get option Stream file, prompt for DTMF, with timeout
get variable Gets a channel variable
hangup Hangup the current channel
noop Does nothing
receive char Receives one character from channels supporting it
receive text Receives text from channels supporting it
record file Records to a given file
say alpha Says a given character string
say digits Says a given digit string
say number Says a given number
say phonetic Says a given character string with phonetics
say date Says a given date
say time Says a given time
say datetime Says a given time as specfied by the format given
send image Sends images to channels supporting it
send text Sends text to channels supporting it
set autohangup Autohangup channel in some time
set callerid Sets callerid for the current channel
set context Sets channel context
set extension Changes channel extension
set music Enable/Disable Music on hold generator
set priority Set channel dialplan priority
set variable Sets a channel variable
stream file Sends audio file on channel
control stream file Sends audio file on channel and allows the listner to control the stream
tdd mode Toggles TDD mode (for the deaf)
verbose Logs a message to the asterisk verbose log
wait for digit Waits for a digit to be pressed

==AlarmReceiver==

'''Synopsis'''

Provide support for receving alarm reports from a burglar or fire alarm panel

'''Description'''

AlarmReceiver():

Only 1 signalling format is supported at this time: Ademco Contact ID. This application should be called whenever there is an alarm panel calling in to dump its events. The application will handshake with the alarm panel, and receive events, validate them, handshake them, and store them until the panel hangs up. Once the panel hangs up, the application will run the system command specified by the eventcmd setting in alarmreceiver.conf and pipe the events to the standard input of the application. The configuration file also contains settings for DTMF timing, and for the loudness of the acknowledgement tones.

==Answer==

'''Synopsis'''

Answer a channel if ringing

'''Description'''

Answer([delay]):

If the call has not been answered, this application will answer it. Otherwise, it has no effect on the call. If a delay is specified, Asterisk will wait this number of milliseconds before returning to the dialplan after answering the call.

==AppendCDRUserField==

'''Synopsis'''

Append to the CDR user field

'''[Description'''

AppendCDRUserField(value):

Append value to the CDR user field The Call Data Record (CDR) user field is an extra field you can use for data not stored anywhere else in the record. CDR records can be used for billing or storing other arbitrary data (I.E. telephone survey responses) Also see SetCDRUserField().

==Authenticate==

'''Synopsis'''

Authenticate a user

'''Description'''

Authenticate(password[|options]):

This application asks the caller to enter a given password in order to continue dialplan execution. If the password begins with the '/' character, it is interpreted as a file which contains a list of valid passwords, listed 1 password per line in the file. When using a database key, the value associated with the key can be anything. Users have three attempts to authenticate before the channel is hung up. If the passsword is invalid, the 'j' option is specified, and priority n+101 exists, dialplan execution will continnue at this location.
Options:
a - Set the channels' account code to the password that is entered
d - Interpret the given path as database key, not a literal file
j - Support jumping to n+101 if authentication fails
m - Interpret the given path as a file which contains a list of account
codes and password hashes delimited with ':', listed one per line in
the file. When one of the passwords is matched, the channel will have
its account code set to the corresponding account code in the file.
r - Remove the database key upon successful entry (valid with 'd' only)

==BackGround==

'''Synopsis'''

Play a file while awaiting extension

'''Description'''

Background(filename1[&filename2...][|options[|langoverride][|context]]):

This application will play the given list of files while waiting for an extension to be dialed by the calling channel. To continue waiting for digits after this application has finished playing files, the WaitExten application should be used. The 'langoverride' option explicity specifies which language to attempt to use for the requested sound files. If a 'context' is specified, this is the dialplan context that this application will use when exiting to a dialed extension. If one of the requested sound files does not exist, call processing will be terminated.
Options:
s - causes the playback of the message to be skipped
if the channel is not in the 'up' state (i.e. it
hasn't been answered yet.) If this happens, the
application will return immediately.
n - don't answer the channel before playing the files
m - only break if a digit hit matches a one digit
extension in the destination context

==BackgroundDetect==

'''Synopsis'''

Background a file with talk detect

'''Description'''

BackgroundDetect(filename[|sil[|min|[max]]]):

Plays back a given filename, waiting for interruption from a given digit (the digit must
start the beginning of a valid extension, or it will be ignored). During the playback of the file, audio is monitored in the receive direction, and if a period of non-silence which is greater than 'min' ms
yet less than 'max' ms is followed by silence for at least 'sil' ms then the audio playback is aborted and processing jumps to the 'talk' extension if available. If unspecified, sil, min, and max default to 1000, 100, and infinity respectively.

==Busy==

'''Synopsis'''

Indicate the Busy condition

'''Description'''

Busy([timeout]):

This application will indicate the busy condition to the calling channel. If the optional timeout is specified, the calling channel will be hung up after the specified number of seconds. Otherwise, this application will wait until the calling channel hangs up.

==ChangeMonitor==

'''Synopsis'''

Change monitoring filename of a channel

'''Description'''

ChangeMonitor(filename_base)

Changes monitoring filename of a channel. Has no effect if the channel is not monitored The argument is the new filename base to use for monitoring this channel.

==ChanIsAvail==

'''Synopsis'''

Check channel availability

'''Description'''

ChanIsAvail(Technology/resource[&Technology2/resource2...][|options]):

This application will check to see if any of the specified channels are available. 
The following variables will be set by this application:
${AVAILCHAN} - the name of the available channel, if one exists
${AVAILORIGCHAN} - the canonical channel name that was used to create the channel
${AVAILSTATUS} - the status code for the available channel
Options:
s - Consider the channel unavailable if the channel is in use at all
j - Support jumping to priority n+101 if no channel is available

==ChanSpy==

'''Synopsis'''

Listen to the audio of an active channel

'''Description'''

ChanSpy([chanprefix][|options]):

This application is used to listen to the audio from an active Asterisk channel. This includes the audio coming in and out of the channel being spied on. If the 'chanprefix' parameter is specified, only channels beginning with this string will be spied upon. 
While Spying, the following actions may be performed:
- Dialing # cycles the volume level.
- Dialing * will stop spying and look for another channel to spy on.
- Dialing a series of digits followed by # builds a channel name to append
to 'chanprefix'. For example, executing ChanSpy(Agent) and then dialing
the digits '1234#' while spying will begin spying on the channel,
'Agent/1234'.
Options:
b - Only spy on channels involved in a bridged call.
g(grp) - Match only channels where their ${SPYGROUP} variable is set to
'grp'.
q - Don't play a beep when beginning to spy on a channel.
r[(basename)] - Record the session to the monitor spool directory. An
optional base for the filename may be specified. The
default is 'chanspy'.
v([value]) - Adjust the initial volume in the range from -4 to 4. A
negative value refers to a quieter setting.

==CheckGroup==

'''Synopsis'''

Check the channel count of a group against a limit

'''Description'''

Usage: CheckGroup(max[@category][|options])

Checks that the current number of total channels in the current channel's group does not exceed 'max'. If the number does not exceed 'max', we continue to the next step. The option string may contain zero of the following character:
'j' -- jump to n+101 priority if the number does in fact exceed max,
and priority n+101 exists. Execuation then continues at that
step, otherwise -1 is returned.
This application sets the following channel variable upon successful completion:
CHECKGROUPSTATUS The status of the check that the current channel's
group does not exceed 'max'. It's value is one of
OK | OVERMAX

==Congestion==

'''Synopsis'''

Indicate the Congestion condition

'''Description'''

Congestion([timeout]):

This application will indicate the congenstion condition to the calling channel. If the optional timeout is specified, the calling channel will be hung up after the specified number of seconds. Otherwise, this application will wait until the calling channel hangs up.

==ControlPlayback==

'''Synopsis'''

Play a file with fast forward and rewind

'''Description'''

ControlPlayback(file[|skipms[|ff[|rew[|stop[|pause[|restart|options]]]]]]]):

This application will play back the given filename. 
By default, the '*' key can be used to rewind, and the '#' key can be used to fast-forward.
Parameters:
skipms - This is number of milliseconds to skip when rewinding or
fast-forwarding.
ff - Fast-forward when this DTMF digit is received.
rew - Rewind when this DTMF digit is received.
stop - Stop playback when this DTMF digit is received.
pause - Pause playback when this DTMF digit is received.
restart - Restart playback when this DTMF digit is received.
Options:
j - Jump to priority n+101 if the requested file is not found.
This application sets the following channel variable upon completion:
CPLAYBACKSTATUS - This variable contains the status of the attempt as a text
string, one of: SUCCESS | USERSTOPPED | ERROR

==Cut==

'''Synopsis'''

Splits a variable's contents using the specified delimiter

'''Description'''

Cut(newvar=varname,delimiter,fieldspec):

This application will split the contents of a variable based on the given delimeter and store the result in a new variable.
Parameters:
newvar - new variable created from result string
varname - variable you want cut
delimiter - defaults to '-'
fieldspec - number of the field you want (1-based offset)
may also be specified as a range (with -)
or group of ranges and fields (with &)
This application has been deprecated in favor of the CUT function.

Applications

2007-09-12T04:23:27Z

Summary:

==Asterisk Applications==
: Alphabetical Index of Asterisk Applications

{|style="width:100%; border:solid 1px #AAAAAA; background:#f9f9f9; margin:0; padding:.1em; color:#000; white-space:nowrap; color:#000;"
|style="width:20%;"|
*[[A-C|A - C applications]]
|style="width:20%;"|
*[[G-L|G - L applications]]
|style="width:20%;"|
*[[P-R|P - R applications]]
|style="width:20%;"|
*[[U-Z|U - Z applications]]
|-
|style="width:20%;"|
*[[D-F|D - F applications]]
|style="width:20%;"|
*[[M-N|M - N applications]]
|style="width:20%;"|
*[[S-T|S - T applications]]
|}

 

{|style="width:100%; border:solid 1px #AAAAAA; background:#f9f9f9; margin:0; padding:.1em; color:#000; white-space:nowrap; color:#000;"
|+ A - C Application Index
|style="width:20%;"|
*[[A-C|AbsoluteTimeout]]
| Set absolute maximum time of call
|-
|style="width:20%;"|
*[[A-C|AddQueueMember]]
| Dynamically adds queue members
|-
|style="width:20%;"|
*[[A-C|ADSIProg]]
| Load Asterisk ADSI Scripts into phone
|-
|style="width:20%;"|
*[[A-C|AgentCallbackLogin]]
| Call agent callback login
|-
|style="width:20%;"|
*[[A-C|AgentLogin]]
| Call agent login
|-
|style="width:20%;"|
*[[A-C|AgentMonitorOutgoing]]
| Record agent's outgoing call
|-
|style="width:20%;"|
*[[A-C|AGI]]
| Executes an AGI compliant application
|-
|style="width:20%;"|
*[[A-C|AlarmReceiver]]
| Provide support for receving alarm reports from a burglar or fire alarm panel
|-
|style="width:20%;"|
*[[A-C|Answer]]
| Answer a channel if ringing
|-
|style="width:20%;"|
*[[A-C|AppendCDRUserField]]
| Append to the CDR user field
|-
|style="width:20%;"|
*[[A-C|Authenticate]]
| Authenticate a user
|-
|style="width:20%;"|
*[[A-C|BackGround]]
| Play a file while awaiting extension
|-
|style="width:20%;"|
*[[A-C|BackgroundDetect]]
| Background a file with talk detect
|-
|style="width:20%;"|
*[[A-C|Busy]]
| Indicate the Busy condition
|-
|style="width:20%;"|
*[[A-C|ChangeMonitor]]
| Change monitoring filename of a channel
|-
|style="width:20%;"|
*[[A-C|ChanIsAvail]]
| Check channel availability
|-
|style="width:20%;"|
*[[A-C|ChanSpy]]
| Listen to the audio of an active channel
|-
|style="width:20%;"|
*[[A-C|CheckGroup]]
| Check the channel count of a group against a limit
|-
|style="width:20%;"|
*[[A-C|Congestion]]
| Indicate the Congestion condition
|-
|style="width:20%;"|
*[[A-C|ControlPlayback]]
| Play a file with fast forward and rewind
|-
|style="width:20%;"|
*[[A-C|Cut]]
| Splits a variable's contents using the specified delimiter
|}
 

{|style="width:100%; border:solid 1px #AAAAAA; background:#f9f9f9; margin:0; padding:.1em; color:#000; white-space:nowrap; color:#000;"
|+ D - F Application Index
|style="width:20%;"|
*[[D-F|DateTime]]
|Says a specified time in a custom format
|-
|style="width:20%;"|
*[[D-F|DBdel]]
|Delete a key from the database
|-
|style="width:20%;"|
*[[D-F|DBdeltree]]
|Delete a family or keytree from the database
|-
|style="width:20%;"|
*[[D-F|DBget]]
|Retrieve a value from the database
|-
|style="width:20%;"|
*[[D-F|DBput]]
|Store a value in the database
|-
|style="width:20%;"|
*[[D-F|DeadAGI]]
|Executes AGI on a hungup channel
|-
|style="width:20%;"|
*[[D-F|Dial]]
|Place a call and connect to the current channel
|-
|style="width:20%;"|
*[[D-F|Dictate]]
|Virtual Dictation Machine
|-
|style="width:20%;"|
*[[D-F|DigitTimeout]]
|Set maximum timeout between digits
|-
|style="width:20%;"|
*[[D-F|Directory]]
|Provide directory of voicemail extensions
|-
|style="width:20%;"|
*[[D-F|DISA]]
|DISA (Direct Inward System Access)
|-
|style="width:20%;"|
*[[D-F|DumpChan]]
|Dump Info About The Calling Channel
|-
|style="width:20%;"|
*[[D-F|DUNDiLookup]]
|Look up a number with DUNDi
|-
|style="width:20%;"|
*[[D-F|EAGI]]
|Executes an EAGI compliant application
|-
|style="width:20%;"|
*[[D-F|Echo]]
|Echo audio read back to the user
|-
|style="width:20%;"|
*[[D-F|EndWhile]]
|End A While Loop
|-
|style="width:20%;"|
*[[D-F|EnumLookup]]
|Lookup number in ENUM
|-
|style="width:20%;"|
*[[D-F|Eval]]
|Evaluates a string
|-
|style="width:20%;"|
*[[D-F|Exec]]
|Executes internal application
|-
|style="width:20%;"|
*[[D-F|ExecIf]]
|Conditional exec
|-
|style="width:20%;"|
*[[D-F|ExecIfTime]]
|Conditional application execution based on the current time
|-
|style="width:20%;"|
*[[D-F|ExternalIVR]]
|Interfaces with an external IVR application
|-
|style="width:20%;"|
*[[D-F|Festival]]
|Say text to the user
|-
|style="width:20%;"|
*[[D-F|Flash]]
|Flashes a Zap Trunk
|-
|style="width:20%;"|
*[[D-F|ForkCDR]]
|Forks the Call Data Record
|}
 

{|style="width:100%; border:solid 1px #AAAAAA; background:#f9f9f9; margin:0; padding:.1em; color:#000; white-space:nowrap; color:#000;"
|+ G - L Application Index
|style="width:20%;"|
*[[G-L|GetCPEID]]
|Get ADSI CPE ID
|-
|style="width:20%;"|
*[[G-L|GetGroupCount]]
|Get the channel count of a group
|-
|style="width:20%;"|
*[[G-L|GetGroupMatchCount]]
|Get the channel count of all groups that match a pattern
|-
|style="width:20%;"|
*[[G-L|Gosub]]
|Jump to label, saving return address
|-
|style="width:20%;"|
*[[G-L|GosubIf]]
|Jump to label, saving return address
|-
|style="width:20%;"|
*[[G-L|GotoIfTime]]
|Conditional Goto based on the current time
|-
|style="width:20%;"|
*[[G-L|Goto]]
|Jump to a particular priority, extension, or context
|-
|style="width:20%;"|
*[[G-L|GotoIf]]
|Conditional goto
|-
|style="width:20%;"|
*[[G-L|Hangup]]
|Hang up the calling channel
|-
|style="width:20%;"|
*[[G-L|HasNewVoicemail]]
|Conditionally branches to priority + 101 with the right options set
|-
|style="width:20%;"|
*[[G-L|IAX2Provision]]
|Provision a calling IAX2 with a given template
|-
|style="width:20%;"|
*[[G-L|ICES]]
|Encode and stream using 'ices'
|-
|style="width:20%;"|
*[[G-L|ImportVar]]
|Import a variable from a channel into a new variable
|-
|style="width:20%;"|
*[[G-L|LookupBlacklist]]
|Look up Caller*ID name/number from blacklist database
|-
|style="width:20%;"|
*[[G-L|LookupCIDName]]
|Look up CallerID Name from local database
|}
 

{|style="width:100%; border:solid 1px #AAAAAA; background:#f9f9f9; margin:0; padding:.1em; color:#000; white-space:nowrap; color:#000;"
|+ M - N Application Index
|style="width:20%;"|
*[[M-N|Macro]]
|Macro Implementation
|-
|style="width:20%;"|
*[[M-N|MacroExit]]
|Exit From Macro
|-
|style="width:20%;"|
*[[M-N|MacroIf]]
|Conditional Macro Implementation
|-
|style="width:20%;"|
*[[M-N|MailboxExists]]
|Check to see if Voicemail mailbox exists
|-
|style="width:20%;"|
*[[M-N|Math]]
|Performs Mathematical Functions
|-
|style="width:20%;"|
*[[M-N|MD5]]
|Calculate MD5 checksum
|-
|style="width:20%;"|
*[[M-N|MD5Check]]
|Check MD5 checksum
|-
|style="width:20%;"|
*[[M-N|MeetMe]]
|MeetMe conference bridge
|-
|style="width:20%;"|
*[[M-N|MeetMeAdmin]]
|MeetMe conference Administration
|-
|style="width:20%;"|
*[[M-N|MeetMeCount]]
|MeetMe participant count
|-
|style="width:20%;"|
*[[M-N|Milliwatt]]
|Generate a Constant 1000Hz tone at 0dbm (mu-law)
|-
|style="width:20%;"|
*[[M-N|misdn_check_l2l1]]
|misdn_check_l2l1
|-
|style="width:20%;"|
*[[M-N|misdn_facility]]
|misdn_facility
|-
|style="width:20%;"|
*[[M-N|misdn_set_opt]]
|misdn_set_opt
|-
|style="width:20%;"|
*[[M-N|MixMonitor]]
|Record a call and mix the audio during the recording
|-
|style="width:20%;"|
*[[M-N|Monitor]]
|Monitor a channel
|-
|style="width:20%;"|
*[[M-N|MP3Player]]
|Play an MP3 file or stream
|-
|style="width:20%;"|
*[[M-N|MusicOnHold]]
|Play Music On Hold indefinitely
|-
|style="width:20%;"|
*[[M-N|NBScat]]
|Play an NBS local stream
|-
|style="width:20%;"|
*[[M-N|NoCDR]]
|Tell Asterisk to not maintain a CDR for the current call
|-
|style="width:20%;"|
*[[M-N|NoOp]]
|Do Nothing
|}
 

{|style="width:100%; border:solid 1px #AAAAAA; background:#f9f9f9; margin:0; padding:.1em; color:#000; white-space:nowrap; color:#000;"
|+ P - R Application Index
|style="width:20%;"|
*[[P-R|Page]]
|Pages phones
|-
|style="width:20%;"|
*[[P-R|Park]]
|Park yourself
|-
|style="width:20%;"|
*[[P-R|ParkAndAnnounce]]
|Park and Announce
|-
|style="width:20%;"|
*[[P-R|ParkedCall]]
|Answer a parked call
|-
|style="width:20%;"|
*[[P-R|PauseQueueMember]]
|Pauses a queue member
|-
|style="width:20%;"|
*[[P-R|Pickup]]
|Directed Call Pickup
|-
|style="width:20%;"|
*[[P-R|Playback]]
|Play a file
|-
|style="width:20%;"|
*[[P-R|PlayTones]]
|Play a tone list
|-
|style="width:20%;"|
*[[P-R|PrivacyManager]]
|Require phone number to be entered, if no CallerID sent
|-
|style="width:20%;"|
*[[P-R|Progress]]
|Indicate progress
|-
|style="width:20%;"|
*[[P-R|Queue]]
|Queue a call for a call queue
|-
|style="width:20%;"|
*[[P-R|Random]]
|Conditionally branches, based upon a probability
|-
|style="width:20%;"|
*[[P-R|Read]]
|Read a variable
|-
|style="width:20%;"|
*[[P-R|ReadFile]]
|ReadFile(varname=file,length)
|-
|style="width:20%;"|
*[[P-R|RealTime]]
|Realtime Data Lookup
|-
|style="width:20%;"|
*[[P-R|RealTimeUpdate]]
|Realtime Data Rewrite
|-
|style="width:20%;"|
*[[P-R|Record]]
|Record to a file
|-
|style="width:20%;"|
*[[P-R|RemoveQueueMember]]
|Dynamically removes queue members
|-
|style="width:20%;"|
*[[P-R|ResetCDR]]
|Resets the Call Data Record
|-
|style="width:20%;"|
*[[P-R|ResponseTimeout]]
|Set maximum timeout awaiting response
|-
|style="width:20%;"|
*[[P-R|RetryDial]]
|Place a call, retrying on failure allowing optional exit extension.
|-
|style="width:20%;"|
*[[P-R|Return]]
|Return from gosub routine
|-
|style="width:20%;"|
*[[P-R|Ringing]]
|Indicate ringing tone
|}
 

{|style="width:100%; border:solid 1px #AAAAAA; background:#f9f9f9; margin:0; padding:.1em; color:#000; white-space:nowrap; color:#000;"
|+ S - T Application Index
|style="width:20%;"|
*[[S-T|SayAlpha]]
|Say Alpha
|-
|style="width:20%;"|
*[[S-T|SayCountPL]]
|Say the counting word the fits to a number
|-
|style="width:20%;"|
*[[S-T|SayDigits]]
|Say Digits
|-
|style="width:20%;"|
*[[S-T|SayNumber]]
|Say Number
|-
|style="width:20%;"|
*[[S-T|SayPhonetic]]
|Say Phonetic
|-
|style="width:20%;"|
*[[S-T|SayUnixTime]]
|Says a specified time in a custom format
|-
|style="width:20%;"|
*[[S-T|SendDTMF]]
|Sends arbitrary DTMF digits
|-
|style="width:20%;"|
*[[S-T|SendImage]]
|Send an image file
|-
|style="width:20%;"|
*[[S-T|SendText]]
|Send a Text Message
|-
|style="width:20%;"|
*[[S-T|SendURL]]
|Send a URL
|-
|style="width:20%;"|
*[[S-T|Set]]
|Set channel variable(s) or function value(s)
|-
|style="width:20%;"|
*[[S-T|SetAccount]]
|Set the CDR Account Code
|-
|style="width:20%;"|
*[[S-T|SetAMAFlags]]
|Set the AMA Flags
|-
|style="width:20%;"|
*[[S-T|SetCallerID]]
|Set Caller*ID on a call to a new value
|-
|style="width:20%;"|
*[[S-T|SetCallerPres]]
|Set CallerID Presentation
|-
|style="width:20%;"|
*[[S-T|SetCDRUserField]]
|Set the CDR user field
|-
|style="width:20%;"|
*[[S-T|SetCIDName]]
|Set CallerID Name
|-
|style="width:20%;"|
*[[S-T|SetCIDNum]]
|Set CallerID Number
|-
|style="width:20%;"|
*[[S-T|SetGlobalVar]]
|Set a global variable to a given value
|-
|style="width:20%;"|
*[[S-T|SetGroup]]
|Set the channel's group
|-
|style="width:20%;"|
*[[S-T|SetLanguage]]
|Set the channel's preferred language
|-
|style="width:20%;"|
*[[S-T|SetMusicOnHold]]
|Set default Music On Hold class
|-
|style="width:20%;"|
*[[S-T|SetRDNIS]]
|Set RDNIS Number
|-
|style="width:20%;"|
*[[S-T|SetTransferCapability]]
|Set ISDN Transfer Capability
|-
|style="width:20%;"|
*[[S-T|SetVar]]
|Set channel variable(s)
|-
|style="width:20%;"|
*[[S-T|SIPAddHeader]]
|Add a SIP header to the outbound call
|-
|style="width:20%;"|
*[[S-T|SIPDtmfMode]]
|Change the dtmfmode for a SIP call
|-
|style="width:20%;"|
*[[S-T|SIPGetHeader]]
|Get a SIP header from an incoming call
|-
|style="width:20%;"|
*[[S-T|SMS]]
|Communicates with SMS service centres and SMS capable analogue phones
|-
|style="width:20%;"|
*[[S-T|SoftHangup]]
|Soft Hangup Application
|-
|style="width:20%;"|
*[[S-T|Sort]]
|Sorts a list of keywords and values
|-
|style="width:20%;"|
*[[S-T|StackPop]]
|Remove one address from gosub stack
|-
|style="width:20%;"|
*[[S-T|StartMusicOnHold]]
|Play Music On Hold
|-
|style="width:20%;"|
*[[S-T|StopMonitor]]
|Stop monitoring a channel
|-
|style="width:20%;"|
*[[S-T|StopMusicOnHold]]
|Stop Playing Music On Hold
|-
|style="width:20%;"|
*[[S-T|StopPlayTones]]
|Stop playing a tone list
|-
|style="width:20%;"|
*[[S-T|System]]
|Execute a system command
|-
|style="width:20%;"|
*[[S-T|TestClient]]
|Execute Interface Test Client
|-
|style="width:20%;"|
*[[S-T|TestServer]]
|Execute Interface Test Server
|-
|style="width:20%;"|
*[[S-T|Transfer]]
|Transfer caller to remote extension
|-
|style="width:20%;"|
*[[S-T|TrySystem]]
|Try executing a system command
|-
|style="width:20%;"|
*[[S-T|TXTCIDName]]
|Lookup caller name from TXT record
|}
 

{|style="width:100%; border:solid 1px #AAAAAA; background:#f9f9f9; margin:0; padding:.1em; color:#000; white-space:nowrap; color:#000;"
|+ U - Z Application Index
|style="width:20%;"|
*[[U-Z|UnpauseQueueMember]]
|Unpauses a queue member
|-
|style="width:20%;"|
*[[U-Z|UserEvent]]
|Send an arbitrary event to the manager interface
|-
|style="width:20%;"|
*[[U-Z|Verbose]]
|Send arbitrary text to verbose output
|-
|style="width:20%;"|
*[[U-Z|VMAuthenticate]]
|Authenticate with Voicemail passwords
|-
|style="width:20%;"|
*[[U-Z|VoiceMail]]
|Leave a Voicemail message
|-
|style="width:20%;"|
*[[U-Z|VoiceMailMain]]
|Check Voicemail messages
|-
|style="width:20%;"|
*[[U-Z|Wait]]
|Waits for some time
|-
|style="width:20%;"|
*[[U-Z|WaitExten]]
|Waits for an extension to be entered
|-
|style="width:20%;"|
*[[U-Z|WaitForRing]]
|Wait for Ring Application
|-
|style="width:20%;"|
*[[U-Z|WaitForSilence]]
|Waits for a specified amount of silence
|-
|style="width:20%;"|
*[[U-Z|WaitMusicOnHold]]
|Wait, playing Music On Hold
|-
|style="width:20%;"|
*[[U-Z|While]]
|Start A While Loop
|-
|style="width:20%;"|
*[[U-Z|Zapateller]]
|Block telemarketers with SIT
|-
|style="width:20%;"|
*[[U-Z|ZapBarge]]
|Barge in (monitor) Zap channel
|-
|style="width:20%;"|
*[[U-Z|ZapRAS]]
|Executes Zaptel ISDN RAS application
|-
|style="width:20%;"|
*[[U-Z|ZapScan]]
|Scan Zap channels to monitor calls
|}

Troubleshooting Guide

2007-09-10T07:02:09Z

Summary: /* feature digit timeout */

; Asterisk Troubleshooting Guide
== Asterisk dialplan rule order ==
Important to Know!   Working with dialplan it may be useful to know the order of the commands, here a small example.
[My-Context]
1. include => context1
2. include => context2
3. exten => 100,1,...
4. exten => _1XX,1,...
5. exten => _XXX,1,...
6. exten => _X.,1,...
The number in the first column shows the rule order. The following CLI command check how the order for the exten 100 are work
asterisk -rx "show dialplan 100@My-Context"

== Read all Asterisk variables ==
Here is an example to read all variables used by macro-callforwarding

[macro-callforwarding]
exten => s,1,Set(temp=${DB(CFI/${ARG1})})
exten => s,n,GotoIf(${temp}?cf:cf_busy)
exten => s,n(cf),NoOp(CFI CALLFORWARDING CFI/${ARG1} -> ${temp} )
#include extensions_var.conf
exten => s,n,SetCallerID(62915${ARG1})
exten => s,n,Dial(mISDN/g:pstn/${temp})

The file called extensions_var.conf read all used variables

;; list all asterisk variables
;; file = extensions_var.conf
;; include file = extensions_var.conf
;;
;; user to print out: grep V-V full | awk -F"R=" '{print $2}'
;;
exten => s,n,NoOp(V= [${ACCOUNTCODE}] - ACCOUNTCODE )
exten => s,n,NoOp(V-VAR= [${BLINDTRANSFER}] - BLINDTRANSFER )
exten => s,n,NoOp(V-VAR= [${BRIDGEPEER}] - BRIDGEPEER )
exten => s,n,NoOp(V-VAR= [${CALLERANI}] - CALLERANI )
exten => s,n,NoOp(V-VAR= [${CALLERID}] - CALLERID)
exten => s,n,NoOp(V-VAR= [${CALLERIDNAME}] - CALLERIDNAME )
exten => s,n,NoOp(V-VAR= [${CALLERIDNUM}] - CALLERIDNUM )
exten => s,n,NoOp(V-VAR= [${CALLINGANI2}] - CALLINGANI2 )
exten => s,n,NoOp(V-VAR= [${CALLINGPRES}] - CALLINGPRES )
exten => s,n,NoOp(V-VAR= [${CALLINGTNS}] - CALLINGTNS )
exten => s,n,NoOp(V-VAR= [${CALLINGTON}] - CALLINGTON )
exten => s,n,NoOp(V-VAR= [${CHANNEL}] - CHANNEL )
exten => s,n,NoOp(V-VAR= [${CONTEXT}] - CONTEXT )
exten => s,n,NoOp(V-VAR= [${DATETIME}] - DATETIME)
exten => s,n,NoOp(V-VAR= [${DNID}] - DNID )
exten => s,n,NoOp(V-VAR= [${EPOCH}] - EPOCH )
exten => s,n,NoOp(V-VAR= [${EXTEN}] - EXTEN )
exten => s,n,NoOp(V-VAR= [${ENV(VAR)}] - ENV VAR )
exten => s,n,NoOp(V-VAR= [${GOTO_ON_BLINDXFR}] - GOTO_ON_BLINDXFR)
exten => s,n,NoOp(V-VAR= [${HANGUPCAUSE}] - HANGUPCAUSE )
exten => s,n,NoOp(V-VAR= [${HINT}] - HINT )
exten => s,n,NoOp(V-VAR= [${HINTNAME}] - HINTNAME)
exten => s,n,NoOp(V-VAR= [${INVALID_EXTEN}] - INVALID_EXTEN )
exten => s,n,NoOp(V-VAR= [${LANGUAGE}] - LANGUAGE)
exten => s,n,NoOp(V-VAR= [${LEN(VAR)}] - LEN VAR
exten => s,n,NoOp(V-VAR= [${PRIORITY}] - PRIORITY)
exten => s,n,NoOp(V-VAR= [${PRIREDIRECTREASON}] - PRIREDIRECTREASON )
exten => s,n,NoOp(V-VAR= [${RDNIS}] - RDNIS )
exten => s,n,NoOp(V-VAR= [${TIMESTAMP}] - TIMESTAMP )
exten => s,n,NoOp(V-VAR= [${TRANSFER_CONTEXT}] - TRANSFER_CONTEXT )
exten => s,n,NoOp(V-VAR= [${UNIQUEID}] - UNIQUEID)
exten => s,n,NoOp(V-VAR= [${AQMSTATUS}] - AQMSTATUS )
exten => s,n,NoOp(V-VAR= [${AVAILSTATUS}] - AVAILSTATUS )
exten => s,n,NoOp(V-VAR= [${CHECKGROUPSTATUS}] - CHECKGROUPSTATUS )
exten => s,n,NoOp(V-VAR= [${CHECKMD5STATUS}] - CHECKMD5STATUS )
exten => s,n,NoOp(V-VAR= [${CPLAYBACKSTATUS}] - CPLAYBACKSTATUS )
exten => s,n,NoOp(V-VAR= [${DIALSTATUS}] - DIALSTATUS )
exten => s,n,NoOp(V-VAR= [${DBGETSTATUS}] - DBGETSTATUS )
exten => s,n,NoOp(V-VAR= [${ENUMSTATUS}] - ENUMSTATUS )
exten => s,n,NoOp(V-VAR= [${HASVMSTATUS}] - HASVMSTATUS )
exten => s,n,NoOp(V-VAR= [${LOOKUPBLSTATUS}] - LOOKUPBLSTATUS )
exten => s,n,NoOp(V-VAR= [${OSPLOOKUPSTATUS}] - OSPLOOKUPSTATUS )
exten => s,n,NoOp(V-VAR= [${OSPNEXTSTATUS}] - OSPNEXTSTATUS )
exten => s,n,NoOp(V-VAR= [${OSPFINISHSTATUS}] - OSPFINISHSTATUS )
exten => s,n,NoOp(V-VAR= [${PLAYBACKSTATUS}] - PLAYBACKSTATUS )
exten => s,n,NoOp(V-VAR= [${PQMSTATUS}] - PQMSTATUS )
exten => s,n,NoOp(V-VAR= [${PRIVACYMGRSTATUS}] - PRIVACYMGRSTATUS )
exten => s,n,NoOp(V-VAR= [${QUEUESTATUS}] - QUEUESTATUS )
exten => s,n,NoOp(V-VAR= [${RQMSTATUS}] - RQMSTATUS )
exten => s,n,NoOp(V-VAR= [${SENDIMAGESTATUS}] - SENDIMAGESTATUS )
exten => s,n,NoOp(V-VAR= [${SENDTEXTSTATUS}] - SENDTEXTSTATUS )
exten => s,n,NoOp(V-VAR= [${SENDURLSTATUS}] - SENDURLSTATUS )
exten => s,n,NoOp(V-VAR= [${SIPGETSTATUS}] - SIPGETSTATUS )
exten => s,n,NoOp(V-VAR= [${SYSTEMSTATUS}] - SYSTEMSTATUS )
exten => s,n,NoOp(V-VAR= [${TRANSFERSTATUS}] - TRANSFERSTATUS )
exten => s,n,NoOp(V-VAR= [${TXTCIDNAMESTATUS}] - TXTCIDNAMESTATUS )
exten => s,n,NoOp(V-VAR= [${UPQMSTATUS}] - UPQMSTATUS )
exten => s,n,NoOp(V-VAR= [${VMSTATUS}] - VMSTATUS)
exten => s,n,NoOp(V-VAR= [${VMBOXEXISTSSTATUS}] - VMBOXEXISTSSTATUS )
exten => s,n,NoOp(V-VAR= [${WAITSTATUS}] - WAITSTATUS )
exten => s,n,NoOp(V-VAR= [${CURL}] - CURL )
exten => s,n,NoOp(V-VAR= [${ENUM}] - ENUM )
exten => s,n,NoOp(V-VAR= [${EXITCONTEXT}] - EXITCONTEXT )
exten => s,n,NoOp(V-VAR= [${MONITOR}] - MONITOR )
exten => s,n,NoOp(V-VAR= [${MONITOR_EXEC}] - MONITOR_EXEC )
exten => s,n,NoOp(V-VAR= [${MONITOR_EXEC_ARGS}] - MONITOR_EXEC_ARGS )
exten => s,n,NoOp(V-VAR= [${MONITOR_FILENAME}] - MONITOR_FILENAME )
exten => s,n,NoOp(V-VAR= [${QUEUE_PRIO}] - QUEUE_PRIO )
exten => s,n,NoOp(V-VAR= [${QUEUESTATUS}] - QUEUESTATUS )
exten => s,n,NoOp(V-VAR= [${RECORDED_FILE}] - RECORDED_FILE )
exten => s,n,NoOp(V-VAR= [${TALK_DETECTED}] - TALK_DETECTED )
exten => s,n,NoOp(V-VAR= [${TOUCH_MONITOR}] - TOUCH_MONITOR )
exten => s,n,NoOp(V-VAR= [${TOUCH_MONITOR_FORMAT}] - )
exten => s,n,NoOp(V-VAR= [${TXTCIDNAME}] - TXTCIDNAME )
exten => s,n,NoOp(V-VAR= [${VPB_GETDTMF}] - VPB_GETDTMF )
exten => s,n,NoOp(V-VAR= [${MEETME_RECORDINGFILE}] - MEETME_RECORDINGFILE )
exten => s,n,NoOp(V-VAR= [${MEETME_RECORDINGFORMAT}] - MEETME_RECORDINGFORMAT )
exten => s,n,NoOp(V-VAR= [${MEETME_EXIT_CONTEXT}] - MEETME_EXIT_CONTEXT )
exten => s,n,NoOp(V-VAR= [${MEETME_AGI_BACKGROUND}] - MEETME_AGI_BACKGROUND )
exten => s,n,NoOp(V-VAR= [${MEETMESECS}] - MEETMESECS )
exten => s,n,NoOp(V-VAR= [${VM_CATEGORY}] - VM_CATEGORY )
exten => s,n,NoOp(V-VAR= [${VM_NAME}] - VM_NAME )
exten => s,n,NoOp(V-VAR= [${VM_DUR}] - VM_DUR )
exten => s,n,NoOp(V-VAR= [${VM_MSGNUM}] - VM_MSGNUM )
exten => s,n,NoOp(V-VAR= [${VM_CALLERID}] - VM_CALLERID )
exten => s,n,NoOp(V-VAR= [${VM_CIDNAME}] - VM_CIDNAME )
exten => s,n,NoOp(V-VAR= [${VM_CIDNUM}] - VM_CIDNUM )
exten => s,n,NoOp(V-VAR= [${VM_DATE}] - VM_DATE )
exten => s,n,NoOp(V-VAR= [${VM_MESSAGEFILE}] - VM_MESSAGEFILE )
exten => s,n,NoOp(V-VAR= [${AUTH_MAILBOX}] - AUTH_MAILBOX )
exten => s,n,NoOp(V-VAR= [${AUTH_CONTEXT}] - AUTH_CONTEXT )
exten => s,n,NoOp(V-VAR= [${DUNDTECH}] - DUNDTECH)
exten => s,n,NoOp(V-VAR= [${DUNDDEST}] - DUNDDEST)
exten => s,n,NoOp(V-VAR= [${ANI2}] - ANI2 )
exten => s,n,NoOp(V-VAR= [${CALLTYPE}] - CALLTYPE)
exten => s,n,NoOp(V-VAR= [${CALLEDTON}] - CALLEDTON )
exten => s,n,NoOp(V-VAR= [${CALLINGSUBADDR}] - CALLINGSUBADDR )
exten => s,n,NoOp(V-VAR= [${FAXEXTEN}] - FAXEXTEN)
exten => s,n,NoOp(V-VAR= [${PRIREDIRECTREASON}] - PRIREDIRECTREASON )
exten => s,n,NoOp(V-VAR= [${SIPCALLID}] - SIPCALLID )
exten => s,n,NoOp(V-VAR= [${SIPDOMAIN}] - SIPDOMAIN )
exten => s,n,NoOp(V-VAR= [${SIPUSERAGENT}] - SIPUSERAGENT )
exten => s,n,NoOp(V-VAR= [${SIPURI}] - SIPURI )
exten => s,n,NoOp(V-VAR= [${SIP_CODEC}] - SIP_CODEC )
exten => s,n,NoOp(V-VAR= [${SIP_URI_OPTIONS}] - SIP_URI_OPTIONS )
exten => s,n,NoOp(V-VAR= [${AGENTMAXLOGINTRIES}] - AGENTMAXLOGINTRIES )
exten => s,n,NoOp(V-VAR= [${AGENTUPDATECDR}] - AGENTUPDATECDR )
exten => s,n,NoOp(V-VAR= [${AGENTGOODBYE}] - AGENTGOODBYE )
exten => s,n,NoOp(V-VAR= [${AGENTACKCALL}] - AGENTACKCALL )
exten => s,n,NoOp(V-VAR= [${AGENTAUTOLOGOFF}] - AGENTAUTOLOGOFF )
exten => s,n,NoOp(V-VAR= [${AGENTWRAPUPTIME}] - AGENTWRAPUPTIME )
exten => s,n,NoOp(V-VAR= [${AGENTNUMBER}] - AGENTNUMBER )
exten => s,n,NoOp(V-VAR= [${AGENTSTATUS}] - AGENTSTATUS )
exten => s,n,NoOp(V-VAR= [${AGENTEXTEN}] - AGENTEXTEN )
exten => s,n,NoOp(V-VAR= [${DIALEDPEERNAME}] - DIALEDPEERNAME )
exten => s,n,NoOp(V-VAR= [${DIALEDPEERNUMBER}] - DIALEDPEERNUMBER )
exten => s,n,NoOp(V-VAR= [${DIALEDTIME}] - DIALEDTIME )
exten => s,n,NoOp(V-VAR= [${ANSWEREDTIME}] - ANSWEREDTIME )
exten => s,n,NoOp(V-VAR= [${DIALSTATUS}] - DIALSTATUS )
exten => s,n,NoOp(V-VAR= [${DYNAMIC_FEATURES}] - DYNAMIC_FEATURES )
exten => s,n,NoOp(V-VAR= [${LIMIT_PLAYAUDIO_CALLER}] - LIMIT_PLAYAUDIO_CALLER )
exten => s,n,NoOp(V-VAR= [${LIMIT_PLAYAUDIO_CALLEE}] - LIMIT_PLAYAUDIO_CALLEE )
exten => s,n,NoOp(V-VAR= [${LIMIT_WARNING_FILE}] - LIMIT_WARNING_FILE )
exten => s,n,NoOp(V-VAR= [${LIMIT_TIMEOUT_FILE}] - LIMIT_TIMEOUT_FILE )
exten => s,n,NoOp(V-VAR= [${LIMIT_CONNECT_FILE}] - LIMIT_CONNECT_FILE )
exten => s,n,NoOp(V-VAR= [${OUTBOUND_GROUP}] - OUTBOUND_GROUP )
exten => s,n,NoOp(V-VAR= [${AVAILCHAN}] - AVAILCHAN )
exten => s,n,NoOp(V-VAR= [${AVAILORIGCHAN}] - AVAILORIGCHAN )
exten => s,n,NoOp(V-VAR= [${AVAILSTATUS}] - AVAILSTATUS )
exten => s,n,NoOp(V-VAR= [${MACRO_EXTEN}] - MACRO_EXTEN )
exten => s,n,NoOp(V-VAR= [${MACRO_CONTEXT}] - MACRO_CONTEXT )
exten => s,n,NoOp(V-VAR= [${MACRO_PRIORITY}] - MACRO_PRIORITY )
exten => s,n,NoOp(V-VAR= [${MACRO_OFFSET}] - MACRO_OFFSET )
exten => s,n,NoOp(V-VAR= [${OSPHANDLE}] - OSPHANDLE )
exten => s,n,NoOp(V-VAR= [${OSPTECH}] - OSPTECH )
exten => s,n,NoOp(V-VAR= [${OSPDEST}] - OSPDEST )
exten => s,n,NoOp(V-VAR= [${OSPTOKEN}] - OSPTOKEN)
exten => s,n,NoOp(V-VAR= [${OSPRESULTS}] - OSPRESULTS )

==feature digit timeout==
This feature can solve troubles with phone devices by call transfer, using ''featuredigittimeout'' insert into features.conf
[general]

featuredigittimeout => 1000 ; Max time (ms) between digits for

Configuration Guide

2007-09-10T07:01:44Z

Summary:

; Asterisk configuring Guide
still empty, wait to author

Installation Guide

2007-09-10T06:59:43Z

Summary:

; Prerequisite Hardware Minimums

Asterisk can be very processor-intensive, due to its use of the CPU to perform Digital Signal Prosessing (DSP). If you are building a complex, high-usage system, this is extremely important to understand. However, for the purposes of building your first Asterisk PBX, you can use any Intel-compatible (x86) machine, they can by a 300MHz Pentium with 256 memory. Essentially, if you can install and run Fedora Core on it, it should be suitable for your first Asterisk install. If you planing to install a PBX using E1/T1 or BRI Gateway, then better take Debian Linux.

; Comiling Asterisk on Linux
Note. Follow this install order: libpri, zaptel, asterisk

After download and extract the tarball into /usr/src/asterisk

~#cd /usr/src/asterisk

; Installing libpri

~#cd /usr/src/asterisk/libpri
~#make clean
~#make
~#make install

; Installing zaptel

~#cd /usr/src/asterisk/zaptel
~#make clean

Note. If you are using kernel 2.6 enter the following command '#make linux26', before doing '#make install'.

~#make install

; Installing Asterisk

~#cd /usr/src/asterisk/asterisk
~#make clean
~#make

Note: If you want to use a mp3 files for music-on-hold enter the following command '#make mpg123', before ran '#make install'.

~#make install

Note. If this the first installation perform 'make samples' to install sample configuration files.

Current events

2007-09-04T14:32:55Z

Summary:

no events yet :-(

Asterisk HowTo's

2007-09-04T13:57:03Z

Summary: /* Asterisk Ringtone identification */

<div align="right"> --[[User:Don.K|Don.K]] 06:38, 5 September 2007 (CEST)</div>

== Asterisk Voicemail spool ==
If you do not want to store your voicemails on your Asterisk PBX server, you can edit voicemail.conf to delete them. However, using a program called Sendmail, you can make Asterisk email your PBX user the new voicemail, and then the voicemail gets deleted off the server. The following option needs to be ''yes'' in voicemail.conf

<pre>
/etc/asterisk/voicemail.conf

delete=yes ; After notification, the voicemail is deleted from the server. [per-mailbox only]
; This is intended for use with users who wish to receive their voicemail ONLY by email.
</pre>

This script to relieve this /bin/delvm, delete every 5 min. voicemail in the vm-spool queue
(I'm not sure what this script does, other than maybe check voicemailboxes every 5 minutes, and delete periodically. Please edit in English)
#!/bin/bash
#
# build-in use crontab -e */5 * * * * /bin/delvm
# Autor: Don.K at 6th Nov 2006 
# define here your context, mainly is default
cx=default 
vmbox=`asterisk -rx "show voicemail users" | grep $cx | awk '{print $2}'` 
if [ -e /var/spool/asterisk/voicemail/$cx/$vmbox/INBOX/msg0000.wav ]; then
rm /var/spool/asterisk/voicemail/$cx/$vmbox/INBOX/*
else
exit 0
fi

==Call Pickup==
In order to be able to take over a call on another telephone, must be registered than first in the configuration features.conf as a pickup extension.
pickupexten = *8
Now we can implement extension the call pickup are with the option '''callgroup''' and '''pickupgroup''' and the value for the group the calls to take over are in sip.conf for the appropriate telephone registering.
[GXP2000]
type = friend
username = 201
secret = 1234
context = default
dtmfmode = rfc2833
callgroup = 2
pickupgroup = 2
disallow = all
allow=ulaw
allow=alaw
allow=g723.1
allow=g729

==Feature Application==
An Feature Application will most there used where no appropriate button exist on the phone. For instance the Call Transfer on Siemens Gigaset 450C or often other DECT Telephone without Transfer (TRNF) key.
features.conf 
[general] 
#include parking_additional.inc
#include features_general_custom.conf 
featuredigittimeout => 1000 ; Max time (ms) between digits for 
[applicationmap] 
#include features_applicationmap_additional.conf 
[featuremap] 
blindxfer => ## ; Blind Transfer
atxfer => ** ; Attended Xfer
automon => *1 ; One Touch Record

==Re-dialing on Asterisk==
If your telephone does not offer a redial feature, the following example can be used to re-dial the last number by dialing *5. The following example fits into extensions.conf

[default]
include => macro-recall 
exten => _X.,1,Macro(recall,${EXTEN})
exten => *5,1,DBget(toCall=redial/${CALLERID})
exten => *5,2,Macro(recall,${toCall})
exten => *5,102,Hangup() 
[macro-recall]
exten => s,1,DBput(redial/${CALLERID}=${ARG1})
exten => s,1,Dial(SIP/${ARG1},20)
exten => s,2,Goto(s-${DIALSTATUS},1)
exten => s-NOANSWER,1,Voicemail(u${ARG1})
exten => s-BUSY,1,Voicemail(b${ARG1})
exten => _s-.,1,Goto(s-NOANSWER,1)

==Asterisk GSM Soundformat==
Sound files made on Windows are usually wave files. These wave files cannot be read and processed by Asterisk, so we will have to change these wave files into an Asterisk-compatible format, such as GSM. Using a software called ''SOX'', we can do so. The following example shows how to convert foo.wav into foo.gsm using SOX.

sox foo.wav -r 8000 -c1 foo.gsm resample -ql
The converted gsm sound files after copy /var/lib/asterisk/sounds/custom
there are asterisk compatible wave formats
sox wav_file.wav gsm_file.gsm
sox gsm_file.gsm wav_file.wav
sox unnow_wav_file.wav asterisk_wav_file.wav

==Call forwarding==
This implementation allow Call forwarding by using dial *72*nnnnnn#, n is the number where the call to forward
exten => _*72*.,1,Answer()
exten => _*72*.,2,Set(DB(CFI/${CALLERID(NUM)})=${EXTEN:4})
exten => _*72*.,n,Playback(vm-saved)
exten => _*72*.,n,SayDigits(${EXTEN:4})
exten => _*72*.,n,Hangup()
Disallow Call forwarding by using dial #73#
exten => #73#,1,Answer()
exten => #73#,n,DBdel(CFI/${CALLERID(num)})
exten => #73#,n,Playback(call-fwd-cancelled)
exten => #73#,n,Hangup()
This will need the macro insert into the appropriate extension, like extension 200
[200]
exten => 200,1,Macro,callforwarding|${EXTEN}
exten => 200,n,Dial(SIP/202,30,mt)
exten => 200,n,Hangup()
insert ''macro-callforwarding'' into extensions.conf above the default context and below general section
[macro-callforwarding]
exten => s,1,Set(temp=${DB(CFI/${ARG1})})
exten => s,n,GotoIf(${temp}?cfi:nocfi)
exten => s,n(cfi),Dial(SIP/${temp})
exten => s,n(nocfi),NoOp
Note, if your phone may don't understood the pound key (#) like Grandstream, then apply another char for instance (*) or only numbers

==Asterisk Ringtone identification==

An Asterisk macro using ringtone identification. In companies, it makes sense to detect the distinction between an internal and an external call.

That provide the following Macro, which in is entered in the configuration file extensions.conf, on FreePBX this is the file extensions_custom.conf.

In this example with '''SIPAddHeader''', this is here for "global" settings, for all external calls now sounds a different tone, the first command generates an additional 0 (Zero) to add automatically a valid prefix for outgoing dial number while call externally.

[macro-exten_did_prefix] 
exten => s,1,Set(CALLERID(num)=0${CALLERID(num)})
exten => s,1,Set(CALLERID(num)=${CALLERID(num)})
exten => s,n,SIPAddHeader("Alert-Info: <http://127.0.0.1>\;info=alert-external\;x-line-id=0;")

Zapata

2007-09-04T13:39:05Z

Summary:

<pre>
;
; Zapata telephony interface
;
; Configuration file
;
; You need to restart Asterisk to re-configure the Zap channel
; CLI> reload chan_zap.so
; will reload the configuration file,
; but not all configuration options are
; re-configured during a reload.

[trunkgroups]
;
; Trunk groups are used for NFAS or GR-303 connections.
;
; Group: Defines a trunk group.
; trunkgroup => <trunkgroup>,<dchannel>[,<backup1>...]
;
; trunkgroup is the numerical trunk group to create
; dchannel is the zap channel which will have the
; d-channel for the trunk.
; backup1 is an optional list of backup d-channels.
;
;trunkgroup => 1,24,48
;trunkgroup => 1,24
;
; Spanmap: Associates a span with a trunk group
; spanmap => <zapspan>,<trunkgroup>[,<logicalspan>]
;
; zapspan is the zap span number to associate
; trunkgroup is the trunkgroup (specified above) for the mapping
; logicalspan is the logical span number within the trunk group to use.
; if unspecified, no logical span number is used.
;
;spanmap => 1,1,1
;spanmap => 2,1,2
;spanmap => 3,1,3
;spanmap => 4,1,4

[channels]
;
; Default language
;
;language=en
;
; Default context
;
context=default
;
; Switchtype: Only used for PRI.
;
; national: National ISDN 2 (default)
; dms100: Nortel DMS100
; 4ess: AT&T 4ESS
; 5ess: Lucent 5ESS
; euroisdn: EuroISDN
; ni1: Old National ISDN 1
; qsig: Q.SIG
;
switchtype=national
;
; Some switches (AT&T especially) require network specific facility IE
; supported values are currently 'none', 'sdn', 'megacom', 'accunet'
;
;nsf=none
;
; PRI Dialplan: Only RARELY used for PRI.
;
; unknown: Unknown
; private: Private ISDN
; local: Local ISDN
; national: National ISDN
; international: International ISDN
; dynamic: Dynamically selects the appropriate dialplan
;
;pridialplan=national
;
; PRI Local Dialplan: Only RARELY used for PRI (sets the calling number's numbering plan)
;
; unknown: Unknown
; private: Private ISDN
; local: Local ISDN
; national: National ISDN
; international: International ISDN
; dynamic: Dynamically selects the appropriate dialplan
;
;prilocaldialplan=national
;
; PRI callerid prefixes based on the given TON/NPI (dialplan)
; This is especially needed for euroisdn E1-PRIs
;
; sample 1 for Germany
;internationalprefix = 00
;nationalprefix = 0
;localprefix = 0711
;privateprefix = 07115678
;unknownprefix =
;
; sample 2 for Germany
;internationalprefix = +
;nationalprefix = +49
;localprefix = +49711
;privateprefix = +497115678
;unknownprefix =
;
; PRI resetinterval: sets the time in seconds between restart of unused
; channels, defaults to 3600; minimum 60 seconds. Some PBXs don't like
; channel restarts. so set the interval to a very long interval e.g. 100000000
; or 'never' to disable *entirely*.
;
;resetinterval = 3600
;
; Overlap dialing mode (sending overlap digits)
;
;overlapdial=yes
;
; PRI Out of band indications.
; Enable this to report Busy and Congestion on a PRI using out-of-band
; notification. Inband indication, as used by Asterisk doesn't seem to work
; with all telcos.
;
; outofband: Signal Busy/Congestion out of band with RELEASE/DISCONNECT
; inband: Signal Busy/Congestion using in-band tones
;
; priindication = outofband
;
; If you need to override the existing channels selection routine and force all
; PRI channels to be marked as exclusively selected, set this to yes.
; priexclusive = yes
;
; ISDN Timers
; All of the ISDN timers and counters that are used are configurable. Specify
; the timer name, and its value (in ms for timers).
;
; pritimer => t200,1000
; pritimer => t313,4000
;
; To enable transmission of facility-based ISDN supplementary services (such
; as caller name from CPE over facility), enable this option.
; facilityenable = yes
;
;
; Signalling method (default is fxs). Valid values:
; em: E & M
; em_w: E & M Wink
; featd: Feature Group D (The fake, Adtran style, DTMF)
; featdmf: Feature Group D (The real thing, MF (domestic, US))
; featdmf_ta: Feature Group D (The real thing, MF (domestic, US)) through
; a Tandem Access point
; featb: Feature Group B (MF (domestic, US))
; fxs_ls: FXS (Loop Start)
; fxs_gs: FXS (Ground Start)
; fxs_ks: FXS (Kewl Start)
; fxo_ls: FXO (Loop Start)
; fxo_gs: FXO (Ground Start)
; fxo_ks: FXO (Kewl Start)
; pri_cpe: PRI signalling, CPE side
; pri_net: PRI signalling, Network side
; gr303fxoks_net: GR-303 Signalling, FXO Loopstart, Network side
; gr303fxsks_cpe: GR-303 Signalling, FXS Loopstart, CPE side
; sf: SF (Inband Tone) Signalling
; sf_w: SF Wink
; sf_featd: SF Feature Group D (The fake, Adtran style, DTMF)
; sf_featdmf: SF Feature Group D (The real thing, MF (domestic, US))
; sf_featb: SF Feature Group B (MF (domestic, US))
; e911: E911 (MF) style signalling
;
; The following are used for Radio interfaces:
; fxs_rx: Receive audio/COR on an FXS kewlstart interface (FXO at the
; channel bank)
; fxs_tx: Transmit audio/PTT on an FXS loopstart interface (FXO at the
; channel bank)
; fxo_rx: Receive audio/COR on an FXO loopstart interface (FXS at the
; channel bank)
; fxo_tx: Transmit audio/PTT on an FXO groundstart interface (FXS at
; the channel bank)
; em_rx: Receive audio/COR on an E&M interface (1-way)
; em_tx: Transmit audio/PTT on an E&M interface (1-way)
; em_txrx: Receive audio/COR AND Transmit audio/PTT on an E&M interface
; (2-way)
; em_rxtx: Same as em_txrx (for our dyslexic friends)
; sf_rx: Receive audio/COR on an SF interface (1-way)
; sf_tx: Transmit audio/PTT on an SF interface (1-way)
; sf_txrx: Receive audio/COR AND Transmit audio/PTT on an SF interface
; (2-way)
; sf_rxtx: Same as sf_txrx (for our dyslexic friends)
;
signalling=fxo_ls
;
; For Feature Group D Tandem access, to set the default CIC and OZZ use these
; parameters:
;defaultozz=0000
;defaultcic=303
;
; A variety of timing parameters can be specified as well
; Including:
; prewink: Pre-wink time (default 50ms)
; preflash: Pre-flash time (default 50ms)
; wink: Wink time (default 150ms)
; flash: Flash time (default 750ms)
; start: Start time (default 1500ms)
; rxwink: Receiver wink time (default 300ms)
; rxflash: Receiver flashtime (default 1250ms)
; debounce: Debounce timing (default 600ms)
;
rxwink=300 ; Atlas seems to use long (250ms) winks
;
; How long generated tones (DTMF and MF) will be played on the channel
; (in milliseconds)
;toneduration=100
;
; Whether or not to do distinctive ring detection on FXO lines
;
;usedistinctiveringdetection=yes

;
; Whether or not to use caller ID
;
usecallerid=yes
;
; Type of caller ID signalling in use
; bell = bell202 as used in US
; v23 = v23 as used in the UK
; dtmf = DTMF as used in Denmark, Sweden and Netherlands
;
;cidsignalling=bell
;
; What signals the start of caller ID
; ring = a ring signals the start
; polarity = polarity reversal signals the start
;
;cidstart=ring
;
; Whether or not to hide outgoing caller ID (Override with *67 or *82)
;
hidecallerid=no
;
; Whether or not to enable call waiting on internal extensions
; With this set to 'yes', busy extensions will hear the call-waiting
; tone, and can use hook-flash to switch between callers. The Dial()
; app will not return the "BUSY" result for extensions.
;
callwaiting=yes
;
; Whether or not restrict outgoing caller ID (will be sent as ANI only, not
; available for the user)
; Mostly use with FXS ports
;
;restrictcid=no
;
; Whether or not use the caller ID presentation for the outgoing call that the
; calling switch is sending.
;
usecallingpres=yes
;
; Some countries (UK) have ring tones with different ring tones (ring-ring),
; which means the callerid needs to be set later on, and not just after
; the first ring, as per the default.
;
;sendcalleridafter=1
;
;
; Support Caller*ID on Call Waiting
;
callwaitingcallerid=yes
;
; Support three-way calling
;
threewaycalling=yes
;
; Support flash-hook call transfer (requires three way calling)
; Also enables call parking (overrides the 'canpark' parameter)
;
transfer=yes
;
; Allow call parking
; ('canpark=no' is overridden by 'transfer=yes')
;
canpark=yes
;
; Support call forward variable
;
cancallforward=yes
;
; Whether or not to support Call Return (*69)
;
callreturn=yes
;
; Stutter dialtone support: If a mailbox is specified without a voicemail
; context, then when voicemail is received in a mailbox in the default
; voicemail context in voicemail.conf, taking the phone off hook will cause a
; stutter dialtone instead of a normal one.
;
; If a mailbox is specified *with* a voicemail context, the same will result
; if voicemail received in mailbox in the specified voicemail context.
;
; for default voicemail context, the example below is fine:
;
;mailbox=1234
;
; for any other voicemail context, the following will produce the stutter tone:
;
;mailbox=1234@context
;
; Enable echo cancellation
; Use either "yes", "no", or a power of two from 32 to 256 if you wish to
; actually set the number of taps of cancellation.
;
; Note that if any of your Zaptel cards have hardware echo cancellers,
; then this setting only turns them on and off; numeric settings will
; be treated as "yes". There are no special settings required for
; hardware echo cancellers; when present and enabled in their kernel
; modules, they take precedence over the software echo canceller compiled
; into Zaptel automatically.
;
echocancel=yes
;
; Generally, it is not necessary (and in fact undesirable) to echo cancel when
; the circuit path is entirely TDM. You may, however, change this behavior
; by enabling the echo cancel during pure TDM bridging below.
;
echocancelwhenbridged=yes
;
; In some cases, the echo canceller doesn't train quickly enough and there
; is echo at the beginning of the call. Enabling echo training will cause
; asterisk to briefly mute the channel, send an impulse, and use the impulse
; response to pre-train the echo canceller so it can start out with a much
; closer idea of the actual echo. Value may be "yes", "no", or a number of
; milliseconds to delay before training (default = 400)
;
; Note that these parameters do not apply to hardware echo cancellers.
;
;echotraining=yes
;echotraining=800
;
; If you are having trouble with DTMF detection, you can relax the DTMF
; detection parameters. Relaxing them may make the DTMF detector more likely
; to have "talkoff" where DTMF is detected when it shouldn't be.
;
;relaxdtmf=yes
;
; You may also set the default receive and transmit gains (in dB)
;
rxgain=0.0
txgain=0.0
;
; Logical groups can be assigned to allow outgoing rollover. Groups range
; from 0 to 63, and multiple groups can be specified.
;
group=1
;
; Ring groups (a.k.a. call groups) and pickup groups. If a phone is ringing
; and it is a member of a group which is one of your pickup groups, then
; you can answer it by picking up and dialling *8#. For simple offices, just
; make these both the same. Groups range from 0 to 63.
;
callgroup=1
pickupgroup=1

;
; Specify whether the channel should be answered immediately or if the simple
; switch should provide dialtone, read digits, etc.
;
immediate=no
;
; Specify whether flash-hook transfers to 'busy' channels should complete or
; return to the caller performing the transfer (default is yes).
;
;transfertobusy=no
;
; CallerID can be set to "asreceived" or a specific number if you want to
; override it. Note that "asreceived" only applies to trunk interfaces.
;
;callerid=2564286000
;
; AMA flags affects the recording of Call Detail Records. If specified
; it may be 'default', 'omit', 'billing', or 'documentation'.
;
;amaflags=default
;
; Channels may be associated with an account code to ease
; billing
;
;accountcode=lss0101
;
; ADSI (Analog Display Services Interface) can be enabled on a per-channel
; basis if you have (or may have) ADSI compatible CPE equipment
;
;adsi=yes
;
; On trunk interfaces (FXS) and E&M interfaces (E&M, Wink, Feature Group D
; etc, it can be useful to perform busy detection either in an effort to
; detect hangup or for detecting busies. This enables listening for
; the beep-beep busy pattern.
;
;busydetect=yes
;
; If busydetect is enabled, it is also possible to specify how many busy tones
; to wait for before hanging up. The default is 4, but better results can be
; achieved if set to 6 or even 8. Mind that the higher the number, the more
; time that will be needed to hangup a channel, but lowers the probability
; that you will get random hangups.
;
;busycount=4
;
; If busydetect is enabled, it is also possible to specify the cadence of your
; busy signal. In many countries, it is 500msec on, 500msec off. Without
; busypattern specified, we'll accept any regular sound-silence pattern that
; repeats <busycount> times as a busy signal. If you specify busypattern,
; then we'll further check the length of the sound (tone) and silence, which
; will further reduce the chance of a false positive.
;
;busypattern=500,500
;
; NOTE: In the Asterisk Makefile you'll find further options to tweak the busy
; detector. If your country has a busy tone with the same length tone and
; silence (as many countries do), consider defining the
; -DBUSYDETECT_COMPARE_TONE_AND_SILENCE option.
;
; Use a polarity reversal to mark when a outgoing call is answered by the
; remote party.
;
;answeronpolarityswitch=yes
;
; In some countries, a polarity reversal is used to signal the disconnect of a
; phone line. If the hanguponpolarityswitch option is selected, the call will
; be considered "hung up" on a polarity reversal.
;
;hanguponpolarityswitch=yes
;
; On trunk interfaces (FXS) it can be useful to attempt to follow the progress
; of a call through RINGING, BUSY, and ANSWERING. If turned on, call
; progress attempts to determine answer, busy, and ringing on phone lines.
; This feature is HIGHLY EXPERIMENTAL and can easily detect false answers,
; so don't count on it being very accurate.
;
; Few zones are supported at the time of this writing, but may be selected
; with "progzone"
;
; This feature can also easily detect false hangups. The symptoms of this is
; being disconnected in the middle of a call for no reason.
;
;callprogress=yes
;progzone=us
;
; FXO (FXS signalled) devices must have a timeout to determine if there was a
; hangup before the line was answered. This value can be tweaked to shorten
; how long it takes before Zap considers a non-ringing line to have hungup.
;
;ringtimeout=8000
;
; For FXO (FXS signalled) devices, whether to use pulse dial instead of DTMF
;
;pulsedial=yes
;
; For fax detection, uncomment one of the following lines. The default is *OFF*
;
;faxdetect=both
;faxdetect=incoming
;faxdetect=outgoing
;faxdetect=no
;
; Select which class of music to use for music on hold. If not specified
; then the default will be used.
;
;musiconhold=default
;
; PRI channels can have an idle extension and a minunused number. So long as
; at least "minunused" channels are idle, chan_zap will try to call "idledial"
; on them, and then dump them into the PBX in the "idleext" extension (which
; is of the form exten@context). When channels are needed the "idle" calls
; are disconnected (so long as there are at least "minidle" calls still
; running, of course) to make more channels available. The primary use of
; this is to create a dynamic service, where idle channels are bundled through
; multilink PPP, thus more efficiently utilizing combined voice/data services
; than conventional fixed mappings/muxings.
;
;idledial=6999
;idleext=6999@dialout
;minunused=2
;minidle=1
;
; Configure jitter buffers in zapata (each one is 20ms, default is 4)
;
;jitterbuffers=4
;
; You can define your own custom ring cadences here. You can define up to 8
; pairs. If the silence is negative, it indicates where the callerid spill is
; to be placed. Also, if you define any custom cadences, the default cadences
; will be turned off.
;
; Syntax is: cadence=ring,silence[,ring,silence[...]]
;
; These are the default cadences:
;
;cadence=125,125,2000,-4000
;cadence=250,250,500,1000,250,250,500,-4000
;cadence=125,125,125,125,125,-4000
;cadence=1000,500,2500,-5000
;
; Each channel consists of the channel number or range. It inherits the
; parameters that were specified above its declaration.
;
; For GR-303, CRV's are created like channels except they must start with the
; trunk group followed by a colon, e.g.:
;
; crv => 1:1
; crv => 2:1-2,5-8
;
;
;callerid="Green Phone"<(256) 428-6121>
;channel => 1
;callerid="Black Phone"<(256) 428-6122>
;channel => 2
;callerid="CallerID Phone" <(256) 428-6123>
;callerid="CallerID Phone" <(630) 372-1564>
;callerid="CallerID Phone" <(256) 704-4666>
;channel => 3
;callerid="Pac Tel Phone" <(256) 428-6124>
;channel => 4
;callerid="Uniden Dead" <(256) 428-6125>
;channel => 5
;callerid="Cortelco 2500" <(256) 428-6126>
;channel => 6
;callerid="Main TA 750" <(256) 428-6127>
;channel => 44
;
; For example, maybe we have some other channels which start out in a
; different context and use E & M signalling instead.
;
;context=remote
;sigalling=em
;channel => 15
;channel => 16

;signalling=em_w
;
; All those in group 0 I'll use for outgoing calls
;
; Strip most significant digit (9) before sending
;
;stripmsd=1
;callerid=asreceived
;group=0
;signalling=fxs_ls
;channel => 45

;signalling=fxo_ls
;group=1
;callerid="Joe Schmoe" <(256) 428-6131>
;channel => 25
;callerid="Megan May" <(256) 428-6132>
;channel => 26
;callerid="Suzy Queue" <(256) 428-6233>
;channel => 27
;callerid="Larry Moe" <(256) 428-6234>
;channel => 28
;
; Sample PRI (CPE) config: Specify the switchtype, the signalling as either
; pri_cpe or pri_net for CPE or Network termination, and generally you will
; want to create a single "group" for all channels of the PRI.
;
; switchtype = national
; signalling = pri_cpe
; group = 2
; channel => 1-23

;

; Used for distinctive ring support for x100p.
; You can see the dringX patterns is to set any one of the dringXcontext fields
; and they will be printed on the console when an inbound call comes in.
;
;dring1=95,0,0
;dring1context=internal1
;dring2=325,95,0
;dring2context=internal2
; If no pattern is matched here is where we go.
;context=default
;channel => 1
</pre>

Variables

2007-09-04T13:38:20Z

Summary:

; The Asterisk Dialplan Variables

There are two levels of parameter evaluation done in the Asterisk dial plan in extensions.conf.
* The first, and most frequently used, is the substitution of variable references with their values.
* Then there are the evaluations of expressions done in $[ .. ]. This will be discussed below.

Asterisk has user-defined variables and standard variables set by various modules in Asterisk. These standard variables are listed at the end of this document.

==PARAMETER QUOTING==

exten => s,5,BackGround,blabla

The parameter (blabla) can be quoted ("blabla"). In this case, a comma does not terminate the field. However, the double quotes will be passed down to the Background command, in this example.

Also, characters special to variable substitution, expression evaluation, etc (see below), can be quoted. For example, to literally use a $ on the string "$1231", quote it with a preceding \. Special characters that must be quoted to be used, are [ ] $ " \. (to write \ itself, use \\).

These Double quotes and escapes are evaluated at the level of the asterisk config file parser.

Double quotes can also be used inside expressions, as discussed below.

==VARIABLES==

Parameter strings can include variables. Variable names are arbitrary strings. They are stored in the respective channel structure.

To set a variable to a particular value, do:

exten => 1,2,Set(varname=value)

You can substitute the value of a variable everywhere using ${variablename}. For example, to stringwise append $lala to $blabla and store result in $koko, do:

exten => 1,2,Set(koko=${blabla}${lala})

There are two reference modes - reference by value and reference by name. To refer to a variable with its name (as an argument to a function that requires a variable), just write the name. To refer to the variable's value, enclose it inside ${}. For example, Set takes as the first argument (before the =) a variable name, so:

exten => 1,2,Set(koko=lala)
exten => 1,3,Set(${koko}=blabla)

stores to the variable "koko" the value "lala" and to variable "lala" the value "blabla".

In fact, everything contained ${here} is just replaced with the value of the variable "here".

==VARIABLE INHERITANCE==

Variable names which are prefixed by "_" will be inherited to channels that are created in the process of servicing the original channel in which the variable was set. When the inheritance takes place, the
prefix will be removed in the channel inheriting the variable. If the name is prefixed by "__" in the channel, then the variable is inherited and the "__" will remain intact in the new channel.

In the dialplan, all references to these variables refer to the same variable, regardless of having a prefix or not. Note that setting any version of the variable removes any other version of the variable, regardless of prefix.

Example:
<pre>
Set(__FOO=bar) ; Sets an inherited version of "FOO" variable
Set(FOO=bar) ; Removes the inherited version and sets a local
; variable.

However,

NoOp(${__FOO}) is identical to NoOp(${FOO})
</pre>

==SELECTING CHARACTERS FROM VARIABLES==

The format for selecting characters from a variable can be expressed as:

${variable_name[:offset[:length]]}

If you want to select the first N characters from the string assigned to a variable, simply append a colon and the number of characters to skip from the beginning of the string to the variable name.
<pre>
;Remove the first character of extension, save in "number" variable
exten => _9X.,1,Set(number=${EXTEN:1})
</pre>

Assuming we've dialed 918005551234, the value saved to the 'number' variable would be 18005551234. This is useful in situations when we require users to dial a number to access an outside line, but do not wish to pass the first digit.

If you use a negative offset number, Asterisk starts counting from the end of the string and then selects everything after the new position. The following example will save the numbers 1234 to the 'number' variable, still assuming we've dialed 918005551234.
<pre>
;Remove everything before the last four digits of the dialed string
exten => _9X.,1,Set(number=${EXTEN:-4})
</pre>
We can also limit the number of characters from our offset position that we wish to use. This is done by appending a second colon and length value to the variable name. The following example will save the numbers 555 to the 'number' variable.
<pre>
;Only save the middle numbers 555 from the string 918005551234
exten => _9X.,1,Set(number=${EXTEN:5:3})
</pre>
The length value can also be used in conjunction with a negative offset. This may be useful if the length of the string is unknown, but the trailing digits are. The following example will save the numbers 555 to the 'number' variable, even if the string starts with more characters than expected (unlike the previous example).
<pre>
;Save the numbers 555 to the 'number' variable
exten => _9X.,1,Set(number=${EXTEN:-7:3})
</pre>
If a negative length value is entered, it is ignored and Asterisk will match to the end of the string.

==EXPRESSIONS==

Everything contained inside a bracket pair prefixed by a $ (like $[this]) is considered as an expression and it is evaluated. Evaluation works similar to (but is done on a later stage than) variable substitution: the expression (including the square brackets) is replaced by the result of the expression evaluation.

For example, after the sequence:

exten => 1,1,Set(lala=$[1 + 2])
exten => 1,2,Set(koko=$[2 * ${lala}])

the value of variable koko is "6".

and, further:

exten => 1,1,Set,(lala=$[ 1 + 2 ]);

will parse as intended. Extra spaces are ignored.

==SPACES INSIDE VARIABLE VALUES==

If the variable being evaluated contains spaces, there can be problems.

For these cases, double quotes around text that may contain spaces will force the surrounded text to be evaluated as a single token. The double quotes will be counted as part of that lexical token.

As an example:

exten => s,6,GotoIf($[ "${CALLERIDNAME}" : "Privacy Manager" ]?callerid-liar|s|1:s|7)

The variable CALLERIDNAME could evaluate to "DELOREAN MOTORS" (with a space) but the above will evaluate to:

"DELOREAN MOTORS" : "Privacy Manager"

and will evaluate to 0.

The above without double quotes would have evaluated to:

DELOREAN MOTORS : Privacy Manager

and will result in syntax errors, because token DELOREAN is immediately followed by token MOTORS and the expression parser will not know how to evaluate this expression, because it does not match its grammar.

==OPERATORS==

<pre>
Operators are listed below in order of increasing precedence. Operators
with equal precedence are grouped within { } symbols.

expr1 | expr2
Return the evaluation of expr1 if it is neither an empty string
nor zero; otherwise, returns the evaluation of expr2.

expr1 & expr2
Return the evaluation of expr1 if neither expression evaluates to
an empty string or zero; otherwise, returns zero.

expr1 {=, >, >=, <, <=, !=} expr2
Return the results of integer comparison if both arguments are
integers; otherwise, returns the results of string comparison
using the locale-specific collation sequence. The result of each
comparison is 1 if the specified relation is true, or 0 if the
relation is false.

expr1 {+, -} expr2
Return the results of addition or subtraction of integer-valued
arguments.

expr1 {*, /, %} expr2
Return the results of multiplication, integer division, or
remainder of integer-valued arguments.

- expr1
Return the result of subtracting expr1 from 0.
This, the unary minus operator, is right associative, and
has the same precedence as the ! operator.

expr1 : expr2
The `:' operator matches expr1 against expr2, which must be a
regular expression. The regular expression is anchored to the
beginning of the string with an implicit `^'.

If the match succeeds and the pattern contains at least one regu-
lar expression subexpression `$...$', the string correspond-
ing to `\1' is returned; otherwise the matching operator
returns the number of characters matched. If the match fails and
the pattern contains a regular expression subexpression the null
string is returned; otherwise 0.

Normally, the double quotes wrapping a string are left as part
of the string. This is disastrous to the : operator. Therefore,
before the regex match is made, beginning and ending double quote
characters are stripped from both the pattern and the string.

expr1 ? expr2 :: expr3
Traditional Conditional operator. If expr1 is a number
that evaluates to 0 (false), expr3 is result of the this
expression evaluation. Otherwise, expr2 is the result.
If expr1 is a string, and evaluates to an empty string,
or the two characters (""), then expr3 is the
result. Otherwise, expr2 is the result. In Asterisk, all
3 exprs will be "evaluated"; if expr1 is "true", expr2
will be the result of the "evaluation" of this
expression. expr3 will be the result otherwise. This
operator has the lowest precedence.

Parentheses are used for grouping in the usual manner.

Operator precedence is applied as one would expect in any of the C
or C derived languages.

Examples

"One Thousand Five Hundred" : "T[^ ]+"
returns: 0

"8015551212" : "(...)"
returns: 801

"3075551212":"...(...)"
returns: 555

!( "One Thousand Five Hundred" : "T[^ ]+" )
returns: 1 (because the string doesn't start with a word starting
with T, so the match evals to 0, and the ! operator
inverts it to 1 ).

2 + 8 / 2
returns 6. (because of operator precedence; the division is done first, then the addition).

2+8/2
returns 6. Spaces aren't necessary.

(2+8)/2
returns 5, of course.

Of course, all of the above examples use constants, but would work the
same if any of the numeric or string constants were replaced with a
variable reference ${CALLERIDNUM}, for instance.
</pre>

==NUMBERS VS STRINGS==

Tokens consisting only of numbers are converted to 64-bit numbers for most of the operators. This means that overflows can occur when the numbers get above 18 digits. Warnings will appear in the logs in this case.

==CONDITIONALS==

There is one conditional application - the conditional goto :

exten => 1,2,gotoif(condition?label1:label2)

If condition is true go to label1, else go to label2. Labels are interpreted exactly as in the normal goto command.

"condition" is just a string. If the string is empty or "0", the condition is considered to be false, if it's anything else, the condition is true. This is designed to be used together with the expression syntax described above, eg :

exten => 1,2,gotoif($[${CALLERID} = 123456]?2|1:3|1)

Example of use :

exten => s,2,Set(vara=1)
exten => s,3,Set(varb=$[${vara} + 2])
exten => s,4,Set(varc=$[${varb} * 2])
exten => s,5,GotoIf($[${varc} = 6]?99|1:s|6)

==PARSE ERRORS==

Syntax errors are now output with 3 lines.

If the extensions.conf file contains a line like:
<pre>
exten => s,6,GotoIf($[ "${CALLERIDNUM}" = "3071234567" & & "${CALLERIDNAME}" : "Privacy Manager" ]?callerid-liar|s|1:s|7)
</pre>
You may see an error in /var/log/asterisk/messages like this:
<pre>
Jul 15 21:27:49 WARNING[1251240752]: ast_yyerror(): syntax error: parse error, unexpected TOK_AND, expecting TOK_MINUS or TOK_LP or TOKEN; Input:
"3072312154" = "3071234567" & & "Steves Extension" : "Privacy Manager"
^
</pre>

The log line tells you that a syntax error was encountered. It now also tells you (in grand standard bison format) that it hit an "AND" (&) token unexpectedly, and that was hoping for for a MINUS (-), LP
(left parenthesis), or a plain token (a string or number).

The next line shows the evaluated expression, and the line after that, the position of the parser in the expression when it became confused, marked with the "^" character.

==NULL STRINGS==

<pre>
Testing to see if a string is null can be done in one of two different ways:

exten => _XX.,1,GotoIf($["${calledid}" != ""]?3)

exten => _XX.,1,GotoIf($[foo${calledid} != foo]?3)
</pre>

The second example above is the way suggested by the WIKI. It will work as long as there are no spaces in the evaluated value.

The first way should work in all cases, and indeed, might now be the safest way to handle this situation.

==WARNING==

If you need to do complicated things with strings, asterisk expressions is most likely NOT the best way to go about it. AGI scripts are an excellent option to this need, and make available the full power of
whatever language you desire, be it Perl, C, C++, Cobol, RPG, Java, Snobol, PL/I, Scheme, Common Lisp, Shell scripts, Tcl, Forth, Modula, Pascal, APL, assembler, etc.

==INCOMPATIBILITIES==

The asterisk expression parser has undergone some evolution. It is hoped that the changes will be viewed as positive.

The "original" expression parser had a simple, hand-written scanner, and a simple bison grammar. This was upgraded to a more involved bison grammar, and a hand-written scanner upgraded to allow extra spaces, and to generate better error diagnostics. This upgrade required bison 1.85, and part of the user community felt the pain of having to upgrade their bison version.

The next upgrade included new bison and flex input files, and the makefile was upgraded to detect current version of both flex and bison, conditionally compiling and linking the new files if the versions of flex and bison would allow it.

If you have not touched your extensions.conf files in a year or so, the above upgrades may cause you some heartburn in certain circumstances, as several changes have been made, and these will affect asterisk's behavior on legacy extension.conf constructs. The changes have been engineered
to minimize these conflicts, but there are bound to be problems.

The following list gives some (and most likely, not all) of areas of possible concern with "legacy" extension.conf files:
<pre>
1. Tokens separated by space(s).
Previously, tokens were separated by spaces. Thus, ' 1 + 1 ' would evaluate
to the value '2', but '1+1' would evaluate to the string '1+1'. If this
behavior was depended on, then the expression evaluation will break. '1+1'
will now evaluate to '2', and something is not going to work right.
To keep such strings from being evaluated, simply wrap them in double
quotes: ' "1+1" '

2. The colon operator. In versions previous to double quoting, the
colon operator takes the right hand string, and using it as a
regex pattern, looks for it in the left hand string. It is given
an implicit ^ operator at the beginning, meaning the pattern
will match only at the beginning of the left hand string.
If the pattern or the matching string had double quotes around
them, these could get in the way of the pattern match. Now,
the wrapping double quotes are stripped from both the pattern
and the left hand string before applying the pattern. This
was done because it recognized that the new way of
scanning the expression doesn't use spaces to separate tokens,
and the average regex expression is full of operators that
the scanner will recognize as expression operators. Thus, unless
the pattern is wrapped in double quotes, there will be trouble.
For instance, ${VAR1} : (Who|What*)+
may have have worked before, but unless you wrap the pattern
in double quotes now, look out for trouble! This is better:
"${VAR1}" : "(Who|What*)+"
and should work as previous.

3. Variables and Double Quotes
Before these changes, if a variable's value contained one or more double
quotes, it was no reason for concern. It is now!

4. LE, GE, NE operators removed. The code supported these operators,
but they were not documented. The symbolic operators, <=, >=, and !=
should be used instead.

5. Added the unary '-' operator. So you can 3+ -4 and get -1.

6. Added the unary '!' operator, which is a logical complement.
Basically, if the string or number is null, empty, or '0',
a '1' is returned. Otherwise a '0' is returned.

7. Added the '=~' operator, just in case someone is just looking for
match anywhere in the string. The only diff with the ':' is that
match doesn't have to be anchored to the beginning of the string.

8. Added the conditional operator 'expr1 ? true_expr :: false_expr'
First, all 3 exprs are evaluated, and if expr1 is false, the 'false_expr'
is returned as the result. See above for details.

9. Unary operators '-' and '!' were made right associative.
</pre>

==DEBUGGING==

;HINTS FOR $[ ] EXPRESSIONS
----

There are two utilities you can build to help debug the $[ ] in your extensions.conf file.

The first, and most simplistic, is to issue the command:

make testexpr2

in the top level asterisk source directory. This will build a small executable, that is able to take the first command line argument, and run it thru the expression parser. No variable substitutions will be performed. It might be safest to wrap the expression in single quotes...

testexpr2 '2*2+2/2'

is an example.

And, in the utils directory, you can say:

make check_expr

and a small program will be built, that will check the file mentioned in the first command line argument, for any expressions that might be have problems when you move to flex-2.5.31. It was originally designed to help spot possible incompatibilities when moving from the
pre-2.5.31 world to the upgraded version of the lexer. But one more capability has been added to check_expr, that might make it more generally useful. It now does a simple minded evaluation of
all variables, and then passes the $[] exprs to the parser. If there are any parse errors, they will be reported in the log file. You can use check_expr to do a quick sanity check of the expressions in your
extensions.conf file, to see if they pass a crude syntax check.

The "simple-minded" variable substitution replaces ${varname} variable references with '555'. You can override the 555 for variable values, by entering in var=val arguments after the filename on the command line. So...

check_expr /etc/asterisk/extensions.conf CALLERIDNUM=3075551212 DIALSTATUS=TORTURE EXTEN=121

will substitute any ${CALLERIDNUM} variable references with 3075551212, any ${DIALSTATUS} variable references with 'TORTURE', and any ${EXTEN} references with '121'. If there is any fancy stuff going on in the reference, like ${EXTEN:2}, then the override will not work. Everything in the ${...} has to match. So, to substitute #{EXTEN:2} references, you'd best say:

check_expr /etc/asterisk/extensions.conf CALLERIDNUM=3075551212 DIALSTATUS=TORTURE EXTEN:2=121

on stdout, you will see something like:

OK -- $[ "${DIALSTATUS}" = "TORTURE" | "${DIALSTATUS}" = "DONTCALL" ] at line 416

In the expr2_log file that is generated, you will see:

line 416, evaluation of $[ "TORTURE" = "TORTURE" | "TORTURE" = "DONTCALL" ] result: 1

check_expr is a very simplistic algorithm, and it is far from being guaranteed to work in all cases, but it is hoped that it will be useful.

==Asterisk standard channel variables==

There are a number of variables that are defined or read by Asterisk. Here is a list of them. More information is available in each application's help text. All these variables are in UPPER CASE only.

Variables marked with a * are builtin functions and can't be set, only read in the dialplan. Writes to such variables are silently ignored.
<pre>
${ACCOUNTCODE} * Account code (if specified) (Deprecated; use ${CDR(accountcode)})
${BLINDTRANSFER} The name of the channel on the other side of a blind transfer
${BRIDGEPEER} Bridged peer
${CALLERANI} * Caller ANI (PRI channels) (Deprecated; use ${CALLERID(ani)})
${CALLERID} * Caller ID (Deprecated; use ${CALLERID(all)})
${CALLERIDNAME} * Caller ID Name only (Deprecated; use ${CALLERID(name)})
${CALLERIDNUM} * Caller ID Number only (Deprecated; use ${CALLERID(num)})
${CALLINGANI2} * Caller ANI2 (PRI channels)
${CALLINGPRES} * Caller ID presentation for incoming calls (PRI channels)
${CALLINGTNS} * Transit Network Selector (PRI channels)
${CALLINGTON} * Caller Type of Number (PRI channels)
${CHANNEL} * Current channel name
${CONTEXT} * Current context
${DATETIME} * Current date time in the format: DDMMYYYY-HH:MM:SS (Deprecated; use ${STRFTIME(${EPOCH},,%d%m%Y-%H:%M:%S)})
${DB_RESULT} Result value of DB_EXISTS() dial plan function
${DNID} * Dialed Number Identifier (Deprecated; use ${CALLERID(dnid)})
${EPOCH} * Current unix style epoch
${EXTEN} * Current extension
${ENV(VAR)} Environmental variable VAR
${GOTO_ON_BLINDXFR} Transfer to the specified context/extension/priority
after a blind transfer (use ^ characters in place of
| to separate context/extension/priority when setting
this variable from the dialplan)
${HANGUPCAUSE} * Asterisk cause of hangup (inbound/outbound)
${HINT} * Channel hints for this extension
${HINTNAME} * Suggested Caller*ID name for this extension
${INVALID_EXTEN} The invalid called extension (used in the "i" extension)
${LANGUAGE} * Current language (Deprecated; use ${LANGUAGE()})
${LEN(VAR)} * String length of VAR (integer)
${PRIORITY} * Current priority in the dialplan
${PRIREDIRECTREASON} Reason for redirect on PRI, if a call was directed
${RDNIS} * Redirected Dial Number ID Service (Deprecated; use ${CALLERID(rdnis)})
${TIMESTAMP} * Current date time in the format: YYYYMMDD-HHMMSS (Deprecated; use ${STRFTIME(${EPOCH},,%Y%m%d-%H%M%S)})
${TRANSFER_CONTEXT} Context for transferred calls
${UNIQUEID} * Current call unique identifier
</pre>

Application return values
----
In Asterisk 1.2, many applications return the result in a variable instead of, as in Asterisk 1.0, changing the dial plan priority (+101). For the various status values, see each application's help text.
<pre>
${AQMSTATUS} * addqueuemember()
${AVAILSTATUS} * chanisavail()
${CHECKGROUPSTATUS} * checkgroup()
${CHECKMD5STATUS} * checkmd5()
${CPLAYBACKSTATUS} * controlplayback()
${DIALSTATUS} * dial()
${DBGETSTATUS} * dbget()
${ENUMSTATUS} * enumlookup()
${HASVMSTATUS} * hasnewvoicemail()
${LOOKUPBLSTATUS} * lookupblacklist()
${OSPLOOKUPSTATUS} * osplookup()
${OSPNEXTSTATUS} * ospnext()
${OSPFINISHSTATUS} * ospfinish()
${PLAYBACKSTATUS} * playback()
${PQMSTATUS} * pausequeuemember()
${PRIVACYMGRSTATUS} * privacymanager()
${QUEUESTATUS} * queue()
${RQMSTATUS} * removequeuemember()
${SENDIMAGESTATUS} * sendimage()
${SENDTEXTSTATUS} * sendtext()
${SENDURLSTATUS} * sendurl()
${SIPGETSTATUS} * sipgetheader()
${SYSTEMSTATUS} * system()
${TRANSFERSTATUS} * transfer()
${TXTCIDNAMESTATUS} * txtcidname()
${UPQMSTATUS} * unpausequeuemember()
${VMSTATUS} * voicmail()
${VMBOXEXISTSSTATUS} * vmboxexists()
${WAITSTATUS} * waitforsilence()
</pre>

Various application variables
----
<pre>
${CURL} * Resulting page content for curl()
${ENUM} * Result of application EnumLookup
${EXITCONTEXT} Context to exit to in IVR menu (app background())
or in the RetryDial() application
${MONITOR} * Set to "TRUE" if the channel is/has been monitored (app monitor())
${MONITOR_EXEC} Application to execute after monitoring a call
${MONITOR_EXEC_ARGS} Arguments to application
${MONITOR_FILENAME} File for monitoring (recording) calls in queue
${QUEUE_PRIO} Queue priority
${QUEUESTATUS} Status of the call, one of:
(TIMEOUT | FULL | JOINEMPTY | LEAVEEMPTY | JOINUNAVAIL | LEAVEUNAVAIL)
${RECORDED_FILE} * Recorded file in record()
${TALK_DETECTED} * Result from talkdetect()
${TOUCH_MONITOR} The filename base to use with Touch Monitor (auto record)
${TOUCH_MONITOR_FORMAT} The audio format to use with Touch Monitor (auto record)
${TXTCIDNAME} * Result of application TXTCIDName
${VPB_GETDTMF} chan_vpb
</pre>

The MeetMe Conference Bridge uses the following variables:
----
<pre>
${MEETME_RECORDINGFILE} Name of file for recording a conference with
the "r" option
${MEETME_RECORDINGFORMAT} Format of file to be recorded
${MEETME_EXIT_CONTEXT} Context for exit out of meetme meeting
${MEETME_AGI_BACKGROUND} AGI script for Meetme (zap only)
${MEETMESECS} * Number of seconds a user participated in a MeetMe conference
</pre>

The VoiceMail() application uses the following variables:
----
<pre>
${VM_CATEGORY} Sets voicemail category
${VM_NAME} * Full name in voicemail
${VM_DUR} * Voicemail duration
${VM_MSGNUM} * Number of voicemail message in mailbox
${VM_CALLERID} * Voicemail Caller ID (Person leaving vm)
${VM_CIDNAME} * Voicemail Caller ID Name
${VM_CIDNUM} * Voicemail Caller ID Number
${VM_DATE} * Voicemail Date
${VM_MESSAGEFILE} * Path to message left by caller
</pre>

The VMAuthenticate() application uses the following variables:
----
<pre>
${AUTH_MAILBOX} * Authenticated mailbox
${AUTH_CONTEXT} * Authenticated mailbox context
</pre>

DUNDiLookup() uses the following variables
----
<pre>
${DUNDTECH} * The Technology of the result from a call to DUNDiLookup()
${DUNDDEST} * The Destination of the result from a call to DUNDiLookup()
</pre>

The Zaptel channel sets the following variables:
----
<pre>
${ANI2} * The ANI2 Code provided by the network on the incoming call.
(ie, Code 29 identifies call as a Prison/Inmate Call)
${CALLTYPE} * Type of call (Speech, Digital, etc)
${CALLEDTON} * Type of number for incoming PRI extension
i.e. 0=unknown, 1=international, 2=domestic, 3=net_specific,
4=subscriber, 6=abbreviated, 7=reserved
${CALLINGSUBADDR} * Called PRI Subaddress
${FAXEXTEN} * The extension called before being redirected to "fax"
${PRIREDIRECTREASON} * Reason for redirect, if a call was directed
</pre>

The SIP channel uses the following variables:
----
<pre>
${SIPCALLID} * SIP Call-ID: header verbatim (for logging or CDR matching)
${SIPDOMAIN} * SIP destination domain of an inbound call (if appropriate)
${SIPUSERAGENT} * SIP user agent
${SIPURI} * SIP uri
${SIP_CODEC} Set the SIP codec for a call
${SIP_URI_OPTIONS} * additional options to add to the URI for an outgoing call
</pre>

The Agent channel uses the following variables:
----
<pre>
${AGENTMAXLOGINTRIES} Set the maximum number of failed logins
${AGENTUPDATECDR} Whether to update the CDR record with Agent channel data
${AGENTGOODBYE} Sound file to use for "Good Bye" when agent logs out
${AGENTACKCALL} Whether the agent should acknowledge the incoming call
${AGENTAUTOLOGOFF} Auto logging off for an agent
${AGENTWRAPUPTIME} Setting the time for wrapup between incoming calls
${AGENTNUMBER} * Agent number (username) set at login
${AGENTSTATUS} * Status of login ( fail | on | off )
${AGENTEXTEN} * Extension for logged in agent
</pre>

The Dial() application uses the following variables:
----
<pre>
${DIALEDPEERNAME} * Dialed peer name
${DIALEDPEERNUMBER} * Dialed peer number
${DIALEDTIME} * Time for the call (seconds)
${ANSWEREDTIME} * Time from dial to answer (seconds)
${DIALSTATUS} * Status of the call, one of:
(CHANUNAVAIL | CONGESTION | BUSY | NOANSWER
| ANSWER | CANCEL | DONTCALL | TORTURE)
${DYNAMIC_FEATURES} * The list of features (from the [applicationmap] section of
features.conf) to activate during the call, with feature
names separated by '#' characters
${LIMIT_PLAYAUDIO_CALLER} Soundfile for call limits
${LIMIT_PLAYAUDIO_CALLEE} Soundfile for call limits
${LIMIT_WARNING_FILE} Soundfile for call limits
${LIMIT_TIMEOUT_FILE} Soundfile for call limits
${LIMIT_CONNECT_FILE} Soundfile for call limits
${OUTBOUND_GROUP} Default groups for peer channels (as in SetGroup)
* See "show application dial" for more information
</pre>

The chanisavail() application sets the following variables:
----
<pre>
${AVAILCHAN} * the name of the available channel if one was found
${AVAILORIGCHAN} * the canonical channel name that was used to create the channel
${AVAILSTATUS} * Status of requested channel
</pre>

When using macros in the dialplan, these variables are available
----
<pre>
${MACRO_EXTEN} * The calling extensions
${MACRO_CONTEXT} * The calling context
${MACRO_PRIORITY} * The calling priority
${MACRO_OFFSET} Offset to add to priority at return from macro
</pre>

If you compile with OSP support in the SIP channel, these variables are used:
----
<pre>
${OSPHANDLE} Handle from the OSP Library
${OSPTECH} OSP Technology from Library
${OSPDEST} OSP Destination from Library
${OSPTOKEN} OSP Token to use for call from Library
${OSPRESULTS} Number of OSP results
</pre>

==CDR Variables==

If the channel has a cdr, that cdr record has it's own set of variables which can be accessed just like channel variables. The following builtin variables are available.
<pre>
${CDR(clid)} Caller ID
${CDR(src)} Source
${CDR(dst)} Destination
${CDR(dcontext)} Destination context
${CDR(channel)} Channel name
${CDR(dstchannel)} Destination channel
${CDR(lastapp)} Last app executed
${CDR(lastdata)} Last app's arguments
${CDR(start)} Time the call started.
${CDR(answer)} Time the call was answered.
${CDR(end)} Time the call ended.
${CDR(duration)} Duration of the call.
${CDR(billsec)} Duration of the call once it was answered.
${CDR(disposition)} ANSWERED, NO ANSWER, BUSY
${CDR(amaflags)} DOCUMENTATION, BILL, IGNORE etc
${CDR(accountcode)} The channel's account code.
${CDR(uniqueid)} The channel's unique id.
${CDR(userfield)} The channels uses specified field.
</pre>

In addition, you can set your own extra variables with a traditional Set(CDR(var)=val) to anything you want.

Certain functional variables may be accessed with ${foo(<args>)}. A list of these functional variables may be found by typing "show functions" at the Asterisk CLI.

Voicemail

2007-09-04T13:37:48Z

Summary:

; Synopsis : Leave a Voicemail message

; Description : VoiceMail(mailbox[@context][&mailbox[@context]][...][|options]): This application allows the calling party to leave a message for the specified list of mailboxes. When multiple mailboxes are specified, the greeting will be taken from the first mailbox specified. Dialplan execution will stop if the specified mailbox does not exist. The Voicemail application will exit if any of the following DTMF digits are received:
0 - Jump to the 'o' extension in the current dialplan context.
* - Jump to the 'a' extension in the current dialplan context.
This application will set the following channel variable upon completion:
VMSTATUS - This indicates the status of the execution of the VoiceMail
application. The possible values are:
SUCCESS | USEREXIT | FAILED
Options:
b - Play the 'busy' greeting to the calling party.
g(#) - Use the specified amount of gain when recording the voicemail
message. The units are whole-number decibels (dB).
s - Skip the playback of instructions for leaving a message to the
calling party.
u - Play the 'unavailable' greeting.
j - Jump to priority n+101 if the mailbox is not found or some other

Sample voicemail.conf
<pre>
;
; Voicemail Configuration
;

;
; NOTE: Asterisk has to edit this file to change a user's password. This does
; not currently work with the "#include <file>" directive for Asterisk
; configuration files. Do not use it with this configuration file.
;

[general]
; Default formats for writing Voicemail
;format=g723sf|wav49|wav
format=wav49|gsm|wav
;
; WARNING:
; If you change the list of formats that you record voicemail in
; when you have mailboxes that contain messages, you _MUST_ absolutely
; manually go through those mailboxes and convert/delete/add the
; the message files so that they appear to have been stored using
; your new format list. If you don't do this, very unpleasant
; things may happen to your users while they are retrieving and
; manipulating their voicemail.
;
; In other words: don't change the format list on a production system
; unless you are _VERY_ sure that you know what you are doing and are
; prepared for the consequences.
;
; Who the e-mail notification should appear to come from
serveremail=asterisk
;serveremail=asterisk@linux-support.net
; Should the email contain the voicemail as an attachment
attach=yes
; Maximum number of messages per folder. If not specified, a default value
; (100) is used. Maximum value for this option is 9999.
;maxmsg=100
; Maximum length of a voicemail message in seconds
;maxmessage=180
; Minimum length of a voicemail message in seconds for the message to be kept
; The default is no minimum.
;minmessage=3
; Maximum length of greetings in seconds
;maxgreet=60
; How many milliseconds to skip forward/back when rew/ff in message playback
skipms=3000
; How many seconds of silence before we end the recording
maxsilence=10
; Silence threshold (what we consider silence: the lower, the more sensitive)
silencethreshold=128
; Max number of failed login attempts
maxlogins=3
; If you need to have an external program, i.e. /usr/bin/myapp called when a
; voicemail is left, delivered, or your voicemailbox is checked, uncomment
; this:
;externnotify=/usr/bin/myapp
; If you need to have an external program, i.e. /usr/bin/myapp called when a
; voicemail password is changed, uncomment this:
;externpass=/usr/bin/myapp
; For the directory, you can override the intro file if you want
;directoryintro=dir-intro
; The character set for voicemail messages can be specified here
;charset=ISO-8859-1
; The ADSI feature descriptor number to download to
;adsifdn=0000000F
; The ADSI security lock code
;adsisec=9BDBF7AC
; The ADSI voicemail application version number.
;adsiver=1
; Skip the "[PBX]:" string from the message title
;pbxskip=yes
; Change the From: string
;fromstring=The Asterisk PBX
; Permit finding entries for forward/compose from the directory
;usedirectory=yes
;
; Change the from, body and/or subject, variables:
; VM_NAME, VM_DUR, VM_MSGNUM, VM_MAILBOX, VM_CALLERID, VM_CIDNUM,
; VM_CIDNAME, VM_DATE
;
; Note: The emailbody config row can only be up to 512 characters due to a
; limitation in the Asterisk configuration subsystem.
;emailsubject=[PBX]: New message ${VM_MSGNUM} in mailbox ${VM_MAILBOX}
; The following definition is very close to the default, but the default shows
; just the CIDNAME, if it is not null, otherwise just the CIDNUM, or "an unknown
; caller", if they are both null.
;emailbody=Dear ${VM_NAME}:\n\n\tjust wanted to let you know you were just left a ${VM_DUR} long message (number ${VM_MSGNUM})\nin mailbox ${VM_MAILBOX} from ${VM_CALLERID}, on ${VM_DATE}, so you might\nwant to check it when you get a chance. Thanks!\n\n\t\t\t\t--Asterisk\n
;
; You can also change the Pager From: string, the pager body and/or subject.
; The above defined variables also can be used here
;pagerfromstring=The Asterisk PBX
;pagersubject=New VM
;pagerbody=New ${VM_DUR} long msg in box ${VM_MAILBOX}\nfrom ${VM_CALLERID}, on ${VM_DATE}
;
; Set the date format on outgoing mails. Valid arguments can be found on the
; strftime(3) man page
;
; Default
emaildateformat=%A, %B %d, %Y at %r
; 24h date format
;emaildateformat=%A, %d %B %Y at %H:%M:%S
;
; You can override the default program to send e-mail if you wish, too
;
;mailcmd=/usr/sbin/sendmail -t
;
; Users may be located in different timezones, or may have different
; message announcements for their introductory message when they enter
; the voicemail system. Set the message and the timezone each user
; hears here. Set the user into one of these zones with the tz= attribute
; in the options field of the mailbox. Of course, language substitution
; still applies here so you may have several directory trees that have
; alternate language choices.
;
; Look in /usr/share/zoneinfo/ for names of timezones.
; Look at the manual page for strftime for a quick tutorial on how the
; variable substitution is done on the values below.
;
; Supported values:
; 'filename' filename of a soundfile (single ticks around the filename
; required)
; ${VAR} variable substitution
; A or a Day of week (Saturday, Sunday, ...)
; B or b or h Month name (January, February, ...)
; d or e numeric day of month (first, second, ..., thirty-first)
; Y Year
; I or l Hour, 12 hour clock
; H Hour, 24 hour clock (single digit hours preceded by "oh")
; k Hour, 24 hour clock (single digit hours NOT preceded by "oh")
; M Minute, with 00 pronounced as "o'clock"
; N Minute, with 00 pronounced as "hundred" (US military time)
; P or p AM or PM
; Q "today", "yesterday" or ABdY
; (*note: not standard strftime value)
; q "" (for today), "yesterday", weekday, or ABdY
; (*note: not standard strftime value)
; R 24 hour time, including minute
;
;

;
; Each mailbox is listed in the form <mailbox>=<password>,<name>,<email>,<pager_email>,<options>
; if the e-mail is specified, a message will be sent when a message is
; received, to the given mailbox. If pager is specified, a message will be
; sent there as well. If the password is prefixed by '-', then it is
; considered to be unchangeable.
;
; Advanced options example is extension 4069
; NOTE: All options can be expressed globally in the general section, and
; overridden in the per-mailbox settings, unless listed otherwise.
;
; tz=central ; Timezone from zonemessages above. Irrelevant if envelope=no.
; attach=yes ; Attach the voicemail to the notification email *NOT* the pager email
; saycid=yes ; Say the caller id information before the message. If not described,
; or set to no, it will be in the envelope
; cidinternalcontexts=intern ; Internal Context for Name Playback instead of extension digits when saying caller id.
; sayduration=no ; Turn on/off the duration information before the message. [ON by default]
; saydurationm=2 ; Specify the minimum duration to say. Default is 2 minutes
; dialout=fromvm ; Context to dial out from [option 4 from the advanced menu]
; if not listed, dialing out will not be permitted
sendvoicemail=yes ; Context to Send voicemail from [option 5 from the advanced menu]
; if not listed, sending messages from inside voicemail will not be
; permitted
; searchcontexts=yes ; Current default behavior is to search only the default context
; if one is not specified. The older behavior was to search all contexts.
; This option restores the old behavior [DEFAULT=no]
; callback=fromvm ; Context to call back from
; if not listed, calling the sender back will not be permitted
; review=yes ; Allow sender to review/rerecord their message before saving it [OFF by default
; operator=yes ; Allow sender to hit 0 before/after/during leaving a voicemail to
; reach an operator [OFF by default]
; envelope=no ; Turn on/off envelope playback before message playback. [ON by default]
; This does NOT affect option 3,3 from the advanced options menu
; delete=yes ; After notification, the voicemail is deleted from the server. [per-mailbox only]
; This is intended for use with users who wish to receive their voicemail ONLY by email.
; Note: deletevoicemail is provided as an equivalent option for Realtime configuration.
; nextaftercmd=yes ; Skips to the next message after hitting 7 or 9 to delete/save current message.
; [global option only at this time]
; forcename=yes ; Forces a new user to record their name. A new user is
; determined by the password being the same as
; the mailbox number. The default is "no".
; forcegreetings=no ; This is the same as forcename, except for recording
; greetings. The default is "no".
; hidefromdir=yes ; Hide this mailbox from the directory produced by app_directory
; The default is "no".

[zonemessages]
eastern=America/New_York|'vm-received' Q 'digits/at' IMp
central=America/Chicago|'vm-received' Q 'digits/at' IMp
central24=America/Chicago|'vm-received' q 'digits/at' H N 'hours'
military=Zulu|'vm-received' q 'digits/at' H N 'hours' 'phonetic/z_p'

[default]
; Define maximum number of messages per folder for partcular context.
;maxmsg=50

1234 => 4242,Example Mailbox,root@localhost
;4200 => 9855,Mark Spencer,markster@linux-support.net,mypager@digium.com,attach=no|serveremail=myaddy@digium.com|tz=central|maxmsg=10
;4300 => 3456,Ben Rigas,ben@american-computer.net
;4310 => -5432,Sales,sales@marko.net
;4069 => 6522,Matt Brooks,matt@marko.net,,|tz=central|attach=yes|saycid=yes|dialout=fromvm|callback=fromvm|review=yes|operator=yes|envelope=yes|sayduration=yes|saydurationm=1
;4073 => 1099,Bianca Paige,bianca@biancapaige.com,,delete=1
;4110 => 3443,Rob Flynn,rflynn@blueridge.net

;
; Mailboxes may be organized into multiple contexts for
; voicemail virtualhosting
;

[other]
;The intro can be customized on a per-context basis
;directoryintro=dir-company2
1234 => 5678,Company2 User,root@localhost
</pre>

SMS

2007-09-04T13:37:15Z

Summary:

SMS() is an application to handles calls to/from text message capable phones and message centres using ETSI ES 201 912 protocol 1 FSK messaging over analog calls.

Basically it allows sending and receiving of text messages over the PSTN. It is compatible with BT Text service in the UK and works on ISDN and PSTN lines. It is designed to connect to an ISDN or zap interface directly and uses FSK so would probably not work over any sort of compressed link (like a VoIP call using GSM codec).

Typical applications include:-

1. Connection to a message centre to send text messages - probably initiated via the manager interface or "outgoing" directory
2. Connection to an POTS line with an SMS capable phone to send messages - probably initiated via the manager interface or "outgoing" directory
3. Acceptance of calls from the message centre (based on CLI) and storage of received messages
4. Acceptance of calls from a POTS line with an SMS capable phone and storage of received messages

* Arguments to sms():
<pre>
- First argument is queue name
- Second is options:
a: SMS() is to act as the answering side, and so send the initial FSK frame
s: SMS() is to act as a service centre side rather than as terminal equipment

- If a third argument is specified, then SMS does not handle the call at all,
but takes the third argument as a destination number to send an SMS to
- The forth argument onward is a message to be queued to the number in the
third argument. All this does is create the file in the me-sc directory.
If 's' is set then the number is the source
address and the message placed in the sc-me directory.
</pre>
All text messages are stored in /var/spool/asterisk/sms
A log is recorded in /var/log/asterisk/sms

There are two subdirectories called sc-me.<queuename> holding all messages from service centre to phone, and me-sc.<queuename> holding all messages from phone to service centre.

In each directory are messages in files, one per file, using any filename not starting with a dot.

When connected as a service centre, SMS(s) will send all messages waiting in the sc-me-<queuename> directory, deleting the files as it goes. Any received in this mode are placed in the me-sc-<queuename> directory.

When connected as a client, SMS() will send all messages waiting in the me-sc-<queuename> directory, deleting the files as it goes. Any received in this mode are placed in the sc-me-<queuename> directory.

Message files created by SMS() use a time stamp/reference based filename.

The format of the sms file is lines that have the form of key=value
Keys are :
<pre>
oa Originating Address
Telephone number, national number if just digits
Telephone number starting with + then digits for international
Ignored on sending messages to service centre (CLI used)
da Destination Address
Telephone number, national number if just digits
Telephone number starting with + then digits for international
scts Service Centre Time Stamp
In the format YYYY-MM-DD HH:MM:SS
pid Protocol Identifier (decimal octet value)
dcs Data coding scheme (decimal octet value)
mr Message reference (decimal octet value)
ud The message (see escaping below)
srr 0/1 Status Report Request
rp 0/1 Return Path
vp mins validity period
</pre>
Omitted fields have default values.

Note that there is special format for ud, ud# instead of ud= which is followed by raw hex (2 characters per octet). This is used in output where characters other than 10,13,32-126,128-255 are included in the data. In this case a comment (line starting ;) is added showing the printable characters

When generating files to send to a service centre, only da and ud need be specified. oa is ignored.

When generating files to send to a phone, only oa and ud need be specified. da is ignored.

When receing a message as a service centre, only the destination address is sent, so the originating address is set to the callerid.

EXAMPLES

The following are examples of use within the UK using BT Text SMS/landline service.

This is a context to use with a manager script.

[smsdial]
; create and send a text message, expects number+message and
; connect to 17094009
exten => _X.,1,SMS(${CALLERIDNUM},,${EXTEN},${CALLERIDNAME})
exten => _X.,n,SMS(${CALLERIDNUM})
exten => _X.,n,Hangup

The script sends

action: originate
callerid: message <from>
exten: to
channel: Local/17094009
context: smsdial
priority: 1

You put the message as the name of the caller ID (messy, I know), the
originating number and hence queue name as the number of the caller ID and the
exten as the number to which the sms is to be sent. The context uses SMS to
create the message in the queue and then SMS to communicate iwth 17094009 to
actually send the message.

Note that the 9 on the end of 17094009 is the sub address 9 meaning no sub
address (BT specific). If a different digit is used then that is the sub
address for the sending message source address (appended to the outgoing CLI
by BT).

For incoming calls you can use a context like this :-

[incoming]
exten => _XXXXXX/_8005875290,1,SMS(${EXTEN:3},a)
exten => _XXXXXX/_8005875290,n,System(/usr/lib/asterisk/smsin ${EXTEN:3})
exten => _XXXXXX/_80058752[0-8]0,1,SMS(${EXTEN:3}${CALLERIDNUM:8:1},a)
exten => _XXXXXX/_80058752[0-8]0,n,System(/usr/lib/asterisk/smsin ${EXTEN>:3}${CALLERIDNUM:8:1})
exten => _XXXXXX/_80058752[0-8]0,n,Hangup

In this case the called number we get from BT is 6 digits (XXXXXX) and we are
using the last 3 digits as the queue name.

Priority 1 causes the SMS to be received and processed for the incoming call.
It is from 080058752X0. The two versions handle the queue name as 3 digits (no
sub address) or 4 digits (with sub address). In both cases, after the call a
script (smsin) is run - this is optional, but is useful to actually processed
the received queued SMS. In our case we email them based on the target number.
Priority 3 hangs up.

If using the CAPI drivers they send the right CLI and so the _800... would be
_0800...

SIP

2007-09-04T13:36:41Z

Summary:

; Example sip.conf
<pre>
;
; SIP Configuration example for Asterisk
;
; Syntax for specifying a SIP device in extensions.conf is
; SIP/devicename where devicename is defined in a section below.
;
; You may also use
; SIP/username@domain to call any SIP user on the Internet
; (Don't forget to enable DNS SRV records if you want to use this)
;
; If you define a SIP proxy as a peer below, you may call
; SIP/proxyhostname/user or SIP/user@proxyhostname
; where the proxyhostname is defined in a section below
;
; Useful CLI commands to check peers/users:
; sip show peers Show all SIP peers (including friends)
; sip show users Show all SIP users (including friends)
; sip show registry Show status of hosts we register with
;
; sip debug Show all SIP messages
;
; reload chan_sip.so Reload configuration file
; Active SIP peers will not be reconfigured
;

[general]
context=default ; Default context for incoming calls
;allowguest=no ; Allow or reject guest calls (default is yes, this can also be set to 'osp'
; if asterisk was compiled with OSP support.
;realm=mydomain.tld ; Realm for digest authentication
; defaults to "asterisk"
; Realms MUST be globally unique according to RFC 3261
; Set this to your host name or domain name
bindport=5060 ; UDP Port to bind to (SIP standard port is 5060)
; bindport is the local UDP port that Asterisk will listen on
bindaddr=0.0.0.0 ; IP address to bind to (0.0.0.0 binds to all)
srvlookup=yes ; Enable DNS SRV lookups on outbound calls
; Note: Asterisk only uses the first host
; in SRV records
; Disabling DNS SRV lookups disables the
; ability to place SIP calls based on domain
; names to some other SIP users on the Internet

;domain=mydomain.tld ; Set default domain for this host
; If configured, Asterisk will only allow
; INVITE and REFER to non-local domains
; Use "sip show domains" to list local domains
;domain=mydomain.tld,mydomain-incoming
; Add domain and configure incoming context
; for external calls to this domain
;domain=1.2.3.4 ; Add IP address as local domain
; You can have several "domain" settings
;allowexternalinvites=no ; Disable INVITE and REFER to non-local domains
; Default is yes
;autodomain=yes ; Turn this on to have Asterisk add local host
; name and local IP to domain list.
;pedantic=yes ; Enable slow, pedantic checking for Pingtel
; and multiline formatted headers for strict
; SIP compatibility (defaults to "no")
;tos=184 ; Set IP QoS to either a keyword or numeric val
;tos=lowdelay ; lowdelay,throughput,reliability,mincost,none
;maxexpiry=3600 ; Max length of incoming registration we allow
;defaultexpiry=120 ; Default length of incoming/outgoing registration
;notifymimetype=text/plain ; Allow overriding of mime type in MWI NOTIFY
;checkmwi=10 ; Default time between mailbox checks for peers
;vmexten=voicemail ; dialplan extension to reach mailbox sets the
; Message-Account in the MWI notify message
; defaults to "asterisk"
;videosupport=yes ; Turn on support for SIP video
;recordhistory=yes ; Record SIP history by default
; (see sip history / sip no history)

;disallow=all ; First disallow all codecs
;allow=ulaw ; Allow codecs in order of preference
;allow=ilbc ;
;musicclass=default ; Sets the default music on hold class for all SIP calls
; This may also be set for individual users/peers
;language=en ; Default language setting for all users/peers
; This may also be set for individual users/peers
;relaxdtmf=yes ; Relax dtmf handling
;rtptimeout=60 ; Terminate call if 60 seconds of no RTP activity
; when we're not on hold
;rtpholdtimeout=300 ; Terminate call if 300 seconds of no RTP activity
; when we're on hold (must be > rtptimeout)
;trustrpid = no ; If Remote-Party-ID should be trusted
;sendrpid = yes ; If Remote-Party-ID should be sent
;progressinband=never ; If we should generate in-band ringing always
; use 'never' to never use in-band signalling, even in cases
; where some buggy devices might not render it
; Valid values: yes, no, never Default: never
;useragent=Asterisk PBX ; Allows you to change the user agent string
;promiscredir = no ; If yes, allows 302 or REDIR to non-local SIP address
; Note that promiscredir when redirects are made to the
; local system will cause loops since SIP is incapable
; of performing a "hairpin" call.
;usereqphone = no ; If yes, ";user=phone" is added to uri that contains
; a valid phone number
;dtmfmode = rfc2833 ; Set default dtmfmode for sending DTMF. Default: rfc2833
; Other options:
; info : SIP INFO messages
; inband : Inband audio (requires 64 kbit codec -alaw, ulaw)
; auto : Use rfc2833 if offered, inband otherwise

;compactheaders = yes ; send compact sip headers.
;sipdebug = yes ; Turn on SIP debugging by default, from
; the moment the channel loads this configuration
;subscribecontext = default ; Set a specific context for SUBSCRIBE requests
; Useful to limit subscriptions to local extensions
; Settable per peer/user also
;notifyringing = yes ; Notify subscriptions on RINGING state
;alwaysauthreject = yes ; When an incoming INVITE or REGISTER is to be rejected,
; for any reason, always reject with '401 Unauthorized'
; instead of letting the requester know whether there was
; a matching user or peer for their request
;
; If regcontext is specified, Asterisk will dynamically create and destroy a
; NoOp priority 1 extension for a given peer who registers or unregisters with
; us. The actual extension is the 'regexten' parameter of the registering
; peer or its name if 'regexten' is not provided. More than one regexten may
; be supplied if they are separated by '&'. Patterns may be used in regexten.
;
;regcontext=sipregistrations
;
; Asterisk can register as a SIP user agent to a SIP proxy (provider)
; Format for the register statement is:
; register => user[:secret[:authuser]]@host[:port][/extension]
;
; If no extension is given, the 's' extension is used. The extension needs to
; be defined in extensions.conf to be able to accept calls from this SIP proxy
; (provider).
;
; host is either a host name defined in DNS or the name of a section defined
; below.
;
; Examples:
;
;register => 1234:password@mysipprovider.com
;
; This will pass incoming calls to the 's' extension
;
;
;register => 2345:password@sip_proxy/1234
;
; Register 2345 at sip provider 'sip_proxy'. Calls from this provider
; connect to local extension 1234 in extensions.conf, default context,
; unless you configure a [sip_proxy] section below, and configure a
; context.
; Tip 1: Avoid assigning hostname to a sip.conf section like [provider.com]
; Tip 2: Use separate type=peer and type=user sections for SIP providers
; (instead of type=friend) if you have calls in both directions

;registertimeout=20 ; retry registration calls every 20 seconds (default)
;registerattempts=10 ; Number of registration attempts before we give up
; 0 = continue forever, hammering the other server until it
; accepts the registration
; Default is 0 tries, continue forever
;callevents=no ; generate manager events when sip ua performs events (e.g. hold)

;----------------------------------------- NAT SUPPORT ------------------------
; The externip, externhost and localnet settings are used if you use Asterisk
; behind a NAT device to communicate with services on the outside.

;externip = 200.201.202.203 ; Address that we're going to put in outbound SIP messages
; if we're behind a NAT

; The externip and localnet is used
; when registering and communicating with other proxies
; that we're registered with
;externhost=foo.dyndns.net ; Alternatively you can specify an
; external host, and Asterisk will
; perform DNS queries periodically. Not
; recommended for production
; environments! Use externip instead
;externrefresh=10 ; How often to refresh externhost if
; used
; You may add multiple local networks. A reasonable set of defaults
; are:
;localnet=192.168.0.0/255.255.0.0; All RFC 1918 addresses are local networks
;localnet=10.0.0.0/255.0.0.0 ; Also RFC1918
;localnet=172.16.0.0/12 ; Another RFC1918 with CIDR notation
;localnet=169.254.0.0/255.255.0.0 ;Zero conf local network

; The nat= setting is used when Asterisk is on a public IP, communicating with
; devices hidden behind a NAT device (broadband router). If you have one-way
; audio problems, you usually have problems with your NAT configuration or your
; firewall's support of SIP+RTP ports. You configure Asterisk choice of RTP
; ports for incoming audio in rtp.conf
;
;nat=no ; Global NAT settings (Affects all peers and users)
; yes = Always ignore info and assume NAT
; no = Use NAT mode only according to RFC3581 (;rport)
; never = Never attempt NAT mode or RFC3581 support
; route = Assume NAT, don't send rport
; (work around more UNIDEN bugs)

;rtcachefriends=yes ; Cache realtime friends by adding them to the internal list
; just like friends added from the config file only on a
; as-needed basis? (yes|no)

;rtupdate=yes ; Send registry updates to database using realtime? (yes|no)
; If set to yes, when a SIP UA registers successfully, the ip address,
; the origination port, the registration period, and the username of
; the UA will be set to database via realtime. If not present, defaults to 'yes'.

;rtautoclear=yes ; Auto-Expire friends created on the fly on the same schedule
; as if it had just registered? (yes|no|<seconds>)
; If set to yes, when the registration expires, the friend will vanish from
; the configuration until requested again. If set to an integer,
; friends expire within this number of seconds instead of the
; registration interval.

;ignoreregexpire=yes ; Enabling this setting has two functions:
;
; For non-realtime peers, when their registration expires, the information
; will _not_ be removed from memory or the Asterisk database; if you attempt
; to place a call to the peer, the existing information will be used in spite
; of it having expired
;
; For realtime peers, when the peer is retrieved from realtime storage,
; the registration information will be used regardless of whether
; it has expired or not; if it expires while the realtime peer is still in
; memory (due to caching or other reasons), the information will not be
; removed from realtime storage

; Incoming INVITE and REFER messages can be matched against a list of 'allowed'
; domains, each of which can direct the call to a specific context if desired.
; By default, all domains are accepted and sent to the default context or the
; context associated with the user/peer placing the call.
; Domains can be specified using:
; domain=<domain>[,<context>]
; Examples:
; domain=myasterisk.dom
; domain=customer.com,customer-context
;
; In addition, all the 'default' domains associated with a server should be
; added if incoming request filtering is desired.
; autodomain=yes
;
; To disallow requests for domains not serviced by this server:
; allowexternaldomains=no

; fromdomain=mydomain.tld ; When making outbound SIP INVITEs to
; non-peers, use your primary domain "identity"
; for From: headers instead of just your IP
; address. This is to be polite and
; it may be a mandatory requirement for some
; destinations which do not have a prior
; account relationship with your server.

[authentication]
; Global credentials for outbound calls, i.e. when a proxy challenges your
; Asterisk server for authentication. These credentials override
; any credentials in peer/register definition if realm is matched.
;
; This way, Asterisk can authenticate for outbound calls to other
; realms. We match realm on the proxy challenge and pick an set of
; credentials from this list
; Syntax:
; auth = <user>:<secret>@<realm>
; auth = <user>#<md5secret>@<realm>
; Example:
;auth=mark:topsecret@digium.com
;
; You may also add auth= statements to [peer] definitions
; Peer auth= override all other authentication settings if we match on realm

;------------------------------------------------------------------------------
; Users and peers have different settings available. Friends have all settings,
; since a friend is both a peer and a user
;
; User config options: Peer configuration:
; -------------------- -------------------
; context context
; permit permit
; deny deny
; secret secret
; md5secret md5secret
; dtmfmode dtmfmode
; canreinvite canreinvite
; nat nat
; callgroup callgroup
; pickupgroup pickupgroup
; language language
; allow allow
; disallow disallow
; insecure insecure
; trustrpid trustrpid
; progressinband progressinband
; promiscredir promiscredir
; useclientcode useclientcode
; accountcode accountcode
; setvar setvar
; callerid callerid
; amaflags amaflags
; call-limit call-limit
; restrictcid restrictcid
; subscribecontext subscribecontext
; mailbox
; username
; template
; fromdomain
; regexten
; fromuser
; host
; port
; qualify
; defaultip
; rtptimeout
; rtpholdtimeout
; sendrpid
; outboundproxy

;[sip_proxy]
; For incoming calls only. Example: FWD (Free World Dialup)
; We match on IP address of the proxy for incoming calls
; since we can not match on username (caller id)
;type=peer
;context=from-fwd
;host=fwd.pulver.com

;[sip_proxy-out]
;type=peer ; we only want to call out, not be called
;secret=guessit
;username=yourusername ; Authentication user for outbound proxies
;fromuser=yourusername ; Many SIP providers require this!
;fromdomain=provider.sip.domain
;host=box.provider.com
;usereqphone=yes ; This provider requires ";user=phone" on URI
;call-limit=5 ; permit only 5 simultaneous outgoing calls to this peer
;outboundproxy=proxy.provider.domain ; send outbound signaling to this proxy, not directly to the peer
;port=80 ; The port number we want to connect to on the remote side

;------------------------------------------------------------------------------
; Definitions of locally connected SIP phones
;
; type = user a device that authenticates to us by "from" field to place calls
; type = peer a device we place calls to or that calls us and we match by host
; type = friend two configurations (peer+user) in one
;
; For local phones, type=friend works most of the time
;
; If you have one-way audio, you probably have NAT problems.
; If Asterisk is on a public IP, and the phone is inside of a NAT device
; you will need to configure nat option for those phones.
; Also, turn on qualify=yes to keep the nat session open

;[grandstream1]
;type=friend
;context=from-sip ; Where to start in the dialplan when this phone calls
;callerid=John Doe <1234> ; Full caller ID, to override the phones config
;host=192.168.0.23 ; we have a static but private IP address
; No registration allowed
;nat=no ; there is not NAT between phone and Asterisk
;canreinvite=yes ; allow RTP voice traffic to bypass Asterisk
;dtmfmode=info ; either RFC2833 or INFO for the BudgeTone
;call-limit=1 ; permit only 1 outgoing call and 1 incoming call at a time
; from the phone to asterisk
; (1 for the explicit peer, 1 for the explicit user,
; remember that a friend equals 1 peer and 1 user in
; memory)
;mailbox=1234@default ; mailbox 1234 in voicemail context "default"
;disallow=all ; need to disallow=all before we can use allow=
;allow=ulaw ; Note: In user sections the order of codecs
; listed with allow= does NOT matter!
;allow=alaw
;allow=g723.1 ; Asterisk only supports g723.1 pass-thru!
;allow=g729 ; Pass-thru only unless g729 license obtained

;[xlite1]
; Turn off silence suppression in X-Lite ("Transmit Silence"=YES)!
; Note that Xlite sends NAT keep-alive packets, so qualify=yes is not needed
;type=friend
;regexten=1234 ; When they register, create extension 1234
;callerid="Jane Smith" <5678>
;host=dynamic ; This device needs to register
;nat=yes ; X-Lite is behind a NAT router
;canreinvite=no ; Typically set to NO if behind NAT
;disallow=all
;allow=gsm ; GSM consumes far less bandwidth than ulaw
;allow=ulaw
;allow=alaw
;mailbox=1234@default,1233@default ; Subscribe to status of multiple mailboxes

;[snom]
;type=friend ; Friends place calls and receive calls
;context=from-sip ; Context for incoming calls from this user
;secret=blah
;subscribecontext=localextensions ; Only allow SUBSCRIBE for local extensions
;language=de ; Use German prompts for this user
;host=dynamic ; This peer register with us
;dtmfmode=inband ; Choices are inband, rfc2833, or info
;defaultip=192.168.0.59 ; IP used until peer registers
;mailbox=1234@context,2345 ; Mailbox(-es) for message waiting indicator
;vmexten=voicemail ; dialplan extension to reach mailbox
; sets the Message-Account in the MWI notify message
; defaults to global vmexten which defaults to "asterisk"
;restrictcid=yes ; To have the callerid restriced -> sent as ANI
;disallow=all
;allow=ulaw ; dtmfmode=inband only works with ulaw or alaw!

;[polycom]
;type=friend ; Friends place calls and receive calls
;context=from-sip ; Context for incoming calls from this user
;secret=blahpoly
;host=dynamic ; This peer register with us
;dtmfmode=rfc2833 ; Choices are inband, rfc2833, or info
;username=polly ; Username to use in INVITE until peer registers
; Normally you do NOT need to set this parameter
;disallow=all
;allow=ulaw ; dtmfmode=inband only works with ulaw or alaw!
;progressinband=no ; Polycom phones don't work properly with "never"

;[pingtel]
;type=friend
;secret=blah
;host=dynamic
;insecure=port ; Allow matching of peer by IP address without matching port number
;insecure=invite ; Do not require authentication of incoming INVITEs
;insecure=port,invite ; (both)
;qualify=1000 ; Consider it down if it's 1 second to reply
; Helps with NAT session
; qualify=yes uses default value
;
; Call group and Pickup group should be in the range from 0 to 63
;
;callgroup=1,3-4 ; We are in caller groups 1,3,4
;pickupgroup=1,3-5 ; We can do call pick-p for call group 1,3,4,5
;defaultip=192.168.0.60 ; IP address to use if peer has not registered

;[cisco1]
;type=friend
;secret=blah
;qualify=200 ; Qualify peer is no more than 200ms away
;nat=yes ; This phone may be natted
; Send SIP and RTP to the IP address that packet is
; received from instead of trusting SIP headers
;host=dynamic ; This device registers with us
;canreinvite=no ; Asterisk by default tries to redirect the
; RTP media stream (audio) to go directly from
; the caller to the callee. Some devices do not
; support this (especially if one of them is
; behind a NAT).
;defaultip=192.168.0.4 ; IP address to use until registration
;username=goran ; Username to use when calling this device before registration
; Normally you do NOT need to set this parameter
;setvar=CUSTID=5678 ; Channel variable to be set for all calls from this device

</pre>

Queue

2007-09-04T13:36:11Z

Summary:

In order to properly manage ACD queues, it is important to be able to keep track of details of call setups and teardowns in much greater detail than traditional call detail records provide. In order to support this, extensive and detailed tracing of every queued call is stored in the queue log, located (by default) in /var/log/asterisk/queue_log.

These are the events (and associated information) in the queue log:

;ABANDON(position|origposition|waittime)
The caller abandoned their position in the queue. The position is the caller's position in the queue when they hungup, the origposition is the original position the caller was when they first entered the
queue, and the waittime is how long the call had been waiting in the queue at the time of disconnect.

;AGENTDUMP
The agent dumped the caller while listening to the queue announcement.

;AGENTLOGIN(channel)
The agent logged in. The channel is recorded.

;AGENTCALLBACKLOGIN(exten@context)
The callback agent logged in. The login extension and context is recorded.

;AGENTLOGOFF(channel|logintime)
The agent logged off. The channel is recorded, along with the total time
the agent was logged in.

;AGENTCALLBACKLOGOFF(exten@context|logintime|reason)
The callback agent logged off. The last login extension and context is recorded, along with the total time the agent was logged in, and the reason for the logoff if it was not a normal logoff (e.g., Autologoff)

;COMPLETEAGENT(holdtime|calltime|origposition)
The caller was connected to an agent, and the call was terminated normally by the *agent*. The caller's hold time and the length of the call are both recorded. The caller's original position in the queue is recorded in origposition.

;COMPLETECALLER(holdtime|calltime|origposition)
The caller was connected to an agent, and the call was terminated normally by the *caller*. The caller's hold time and the length of the call are both recorded. The caller's original position in the queue is recorded in origposition.

;CONFIGRELOAD
The configuration has been reloaded (e.g. with asterisk -rx reload)

;CONNECT(holdtime)
The caller was connected to an agent. Hold time represents the amount
of time the caller was on hold.

;ENTERQUEUE(url|callerid)
A call has entered the queue. URL (if specified) and Caller*ID are placed
in the log.

;EXITWITHKEY(key|position)
The caller elected to use a menu key to exit the queue. The key and the caller's position in the queue are recorded.

;EXITWITHTIMEOUT(position)
The caller was on hold too long and the timeout expired.

;QUEUESTART
The queueing system has been started for the first time this session.

;SYSCOMPAT
A call was answered by an agent, but the call was dropped because the
channels were not compatible.

;TRANSFER(extension,context)
Caller was transferred to a different extension. Context and extension
are recorded.

ODBC

2007-09-04T13:35:43Z

Summary:

MP3

2007-09-04T13:35:12Z

Summary:

* MP3 Music On Hold
Asterisk supports mp3 playback for music on hold via the mpg123
program, available from www.mpg123.de.

The latest release of mpg123 is mpg123 0.59r.
The latest development release of mpg123 is mpg123 pre0.59s.

Please use mpg123 0.59r. Using mpg123 pre0.59s can/may/will result
in crashes and/or unreliable playback.

Running "make mpg123" in the Asterisk source directory will
download and make the working version.

* MP3 Format driver
A format driver for reading MP3 audio files is available
in the asterisk-addons SVN repository on svn.digium.com

Modules

2007-09-04T13:34:39Z

Summary:

All modules must have at least the following functions:

int load_module():

:: Do what you need to do when you get started. This function returns 0 on success and non-zero on failure (it is not considered loaded if it fails.

int unload_module():

:: The module will soon be unloaded. If any channels are using your features, you should give them a softhangup in an effort to keep the program from crashing. Generally, unload_module is only called when the usecount is 0 or less, but the user can force unloading at their discretion, and thus a module should do its best to comply (although in some cases there may be no way to avoid a crash). This function should return 0 on success and non-zero on failure (i.e. it cannot yet be unloaded).

char *description():

:: Return a description of the module's functionality.

int usecnt():

:: Return the number of channels, etc that are using you.

; Example modules.conf

<pre>
;
; Asterisk configuration file
;
; Module Loader configuration file
;

[modules]
autoload=yes
;
; Any modules that need to be loaded before the Asterisk core has been
; initialized (just after the logger has been initialized) can be loaded
; using 'preload'. This will frequently be needed if you wish to map all
; module configuration files into Realtime storage, since the Realtime
; driver will need to be loaded before the modules using those configuration
; files are initialized.
;
; An example of loading ODBC support would be:
;preload => res_odbc.so
;preload => res_config_odbc.so
;
; If you want, load the GTK console right away.
; Don't load the KDE console since
; it's not as sophisticated right now.
;
noload => pbx_gtkconsole.so
;load => pbx_gtkconsole.so
noload => pbx_kdeconsole.so
;
; Intercom application is obsoleted by
; chan_oss. Don't load it.
;
noload => app_intercom.so
;
; The 'modem' channel driver and its subdrivers are
; obsolete, don't load them.
;
noload => chan_modem.so
noload => chan_modem_aopen.so
noload => chan_modem_bestdata.so
noload => chan_modem_i4l.so
;
load => res_musiconhold.so
;
; Load either OSS or ALSA, not both
; By default, load OSS only (automatically) and do not load ALSA
;
noload => chan_alsa.so
;noload => chan_oss.so
;
; Module names listed in "global" section will have symbols globally
; exported to modules loaded after them.
;
[global]
</pre>

MISDN

2007-09-04T13:34:10Z

Summary:

; This package contains the mISDN Channel Driver for the Asterisk PBX.
It supports every mISDN Hardware and provides an interface for asterisk.

==Features==

* NT and TE mode
* PP and PMP mode
* BRI and PRI (with BNE1 and BN2E1 Cards)
* Hardware Bridging
* DTMF Detection in HW+mISDNdsp (much better than asterisks internal!)
* Display Messages to Phones (which support display msg)
* HOLD/RETRIEVE/TRANSFER on ISDN Phones : )
* Screen/ Not Screen User Number
* Basic EchoCancellation
* Volume Control
* Crypting with mISDNdsp (Blowfish)
* Data (HDLC) callthrough
* Data Calling (with app_ptyfork +pppd)
* Echo cancellation
* CallDeflection
* Some other

==Supported Hardware==

chan_misdn supports any mISDN compatible Hardware, like HFC chip based cards.

==Fast Installation Guide==

It is easy to install mISDN and mISDNuser.
Using the Makefile from channels/misdn.
You just need to type:

cd channels/misdn
make misdn

Then all the necessary files are fetched from isdn4linux.de.

==Pre-Requisites==

To compile and install this driver, you'll need at least one mISDN Driver and the mISDNuser package. Chan_misdn works with both, the current release version and the development (svn trunk) version of Asterisk. mISDNuser and mISDN must be fetched from cvs.isdn4linux.de.

Please Note that mISDN works good for the linux-2.6.x kernels. Some of the mISDN drivers do not compile against the 2.4.x or older kernels, you can patch them, but than you'll get mysterious errors.

Using Kernels > 2.6.9 works perfect.

Ok so far so good, now follow the compilation instructions.

!! Dont forget to create the /dev/mISDN device node.

==Compilation==

The compilation of chan_misdn requires a library which will be generated under channels/misdn/.

To compile this library you just need to go into this directory and type make. Now you can go back to the asterisk source root and type make install again, which now should compile and install chan_misdn.

==Installation==

Chan_misdn is automatically installed by the asterisk installation process.

There is a sample init.d script for loading the mISDN modules (mISDN.sample), 5Asimply copy it to /etc/init.d/ and modify it, there you can enter your cards.

!! Forget to use capi together with chan_misdn.

==Configuration==

First of all you must configure the mISDN drivers. Each driver module has got an options and layermask option, which tells the driver wether to start in TE, NT, PP or PMP mode (there are lots more, please read docs in misdn for that).

After thinking about the above you'll probably want to configure the misdn.conf file which resides in the asterisk config directory (normally /etc/asterisk).

; misdn.conf: [general]
The misdn.conf file contains a "general" Section, and user sections which contain misdn port settings and different Asterisk contexts.

The general section contains especially a variable named context with which the default context is set. There is also the very important debug variable which you can set from the Asterisk cli (command line interface) or in this configuration file, bigger numbers will lead to more debug output. There's also a
tracefile option, which takes a path+filename where debug output is written to.

; misdn.conf: [default] section
The default section is another special section which can contain all the options available int the usr/port sections. the user/port section inherit their parameters from the default section.

; misdn.conf: user/port sections
The user sections have names which are unequal to "general". Those sections contain the ports variable which mean the mISDN Ports. Here you can add multiple ports, comma separated.

Espacially for TE-Mode Ports there is a msns variable. This variable tells the chan_misdn driver to listen for incomming calls with the given msns, you can insert a '*' as single msn, which leads in getting every incoming call (if you want to share on PMP TE S0 with a asterisk and a phone or isdn card you should insert here the msns which you'll like to give the Asterisk). Finally a context variable resides in the user sections, which tells chan_misdn where to send incoming calls to in the Asterisk dial plan (extension.conf).

==Dial and Options String==

The dial string of chan_misdn got more complex, because we added more features, so the generic dial string looks like:
<pre>
mISDN/<port>|g:<group>/<extension>[/<OPTIONSSTRING>]

The Optionsstring looks Like:
:<optchar1><OptParam1>:<optchar2><OptParam2>

the ":" character is the delimiter.

The available Optchars are:
d - Send display text on called phone, text is the optparam
n - don't detect dtmf tones on called channel
h - make digital outgoing call
c - make crypted outgoing call, param is keyindex
e - perform echo cancelation on this channel,
takes taps as arguments (32,64,128,256)
s - send Non Inband DTMF as inband
vr - rxgain control
vt - txgain control
</pre>

chan_misdn registers a new dial plan application "misdn_set_opt" when loaded. This application takes the Optionsstring as argument.

The Syntax is:

misdn_set_opt(<OPTIONSSTRING>)

When you set options in the dialstring, the options are set in the external channel. When you set options with misdn_set_opt, they are set in the current incoming channel. So if you like to use static encryption, the scenario looks as follows:
<pre>
Phone1 --> * Box 1 --> PSTN_TE
PSTN_TE --> * Box 2 --> Phone2
</pre>
The Encryption must be done on the PSTN sides, so the dialplan on the boxes
are:
<pre>
* Box 1:
exten => _${CRYPT_PREFIX}X.,1,Dial(mISDN/g:outbound/:c1)

* Box 2:
exten => ${CRYPT_MSN},1,misdn_set_opt(:c1)
exten => ${CRYPT_MSN},2,dial(${PHONE2})
</pre>

misdn cli commands
----
<pre>
At the Asterisk cli you can try to type in:

misdn <tab> <tab>

Now you should see the misdn cli commands:

- clean
-> pid (cleans a broken call, use with care, leads often
to a segmentation fault)
- send
-> display (sends a Text Message to a Asterisk channel,
this channel must be an misdn channel)
- set
-> debug (sets debug level)
- show
-> config (shows the configuration options)
-> channels (shows the current active misdn channels)
-> channel (shows details about the given misdn channels)
-> stacks (shows the currend ports, there protocols and states)
-> fullstacks (shows the current active and inactive misdn channels)

- restart
-> port (restarts given port (L2 Restart) )

- reload (reloads misdn.conf)
</pre>

You can only use "misdn send display" when an Asterisk channel is created and isdn is in the correct state. "correct state" means that you have established a call to another phone (mustn't be isdn though).

Then you use it like this:

misdn send display mISDN/1/101 "Hello World!"

where 1 is the Port of the Card where the phone is plugged in, and 101 is the msn (callerid) of the Phone to send the text to.

<pre>
mISDN Variables
----

mISDN Exports/Imports a few Variables:

MISDN_ADDRESS_COMPLETE : Is either set to 1 from the Provider, or you
can set it to 1 to force a sending complete.

</pre>

Debugging and sending bug reports
----

If you encounter problems, you should set up the debugging flag, usually debug=1 should be enough. the messages are divided in asterisk and misdn parts. Misdn Debug messages begin with an 'I', asterisk messages begin with an '*', the rest is clear I think.

Please take a trace of the problem and open a report in the Asterisk issue tracker at http://bugs.digium.com in the "channel drivers" project, "chan_misdn" category. Read the bug guidelines to make sure you provide all the information needed.

==Examples==

Here are some examples of how to use chan_misdn in the dialplan (extensions.conf):

[globals]
OUT_PORT=1 ; The physical Port of the Card
OUT_GROUP=ExternE1 ; The Group of Ports defined in misdn.conf
 
[misdnIn]
exten => _X.,1,Dial(mISDN/${OUT_PORT}/${EXTEN})
exten => _0X.,1,Dial(mISDN/g:${OUT_GROUP}/${EXTEN:1})
exten => _1X.,1,Dial(mISDN/g:${OUT_GROUP}/${EXTEN:1}/:dHello)
exten => _1X.,1,Dial(mISDN/g:${OUT_GROUP}/${EXTEN:1}/:dHello Test:n)

In the last line you will notice the last argument (Hello), this is sended
as Display Message to the Phone.

==Known working configurations==

In this section I'll put working configurations for chan_misdn. Beware It seems that between Kernel 2.6.3 and Kernel 2.6.8 there were lots of mISDN Bugs. I use Kernel 2.6.9 now, it works quite ok, Kernel 2.6.10+ has changed the pci_find_subgsys funktion, so hfc_multi from mISDN doesn't compile against it, you can just change pci_find_subsys to pci_get_subsys, this works.

; chan_misdn-0.2.1
: linux-kernel >= 2.6.8 (but at least 2.6)
: asterisk >= v1.2 , also CVS Head
: mISDN/mISDNuser (3.0) from isdn.jolly.de

==Known Problems==

; When I use mISDN->IAX I cannot make Trunk calls

-> You need to use ztdummy as dummy zaptel interface for the iax timing in
trunking mode, simply grab libpri, zaptel and compile them (i think you need
to modify the makefile in zaptel to add ztdummy to the defaultly compiled
modules) then modprobe ztdummy, this resolves the problem.

; I cannot hear any tone after succesfull CONNECT to other end

-> you forgot to load mISDNdsp, which is now needed by chan_misdn for switching
and dtmf tone detection

; I have strange ISDN behavior: sometimes I hear the other end, sometimes
not. Also I get STATUS Events with cause 100, with misdn debugging

-> Please update to newest version of chan_misdn and set the te_choose_channel
option in misdn.conf to yes

==Example misdn.conf==

<pre>
;
; chan_misdn sample config
;

; general section:
;
; for debugging and general setup, things that are not bound to port groups
;

[general]
;
; Sets the Path to the misdn-init.conf (for nt_ptp mode checking)
;
misdn_init=/etc/misdn-init.conf

; set debugging flag:
; 0 - No Debug
; 1 - mISDN Messages and * - Messages, and * - State changes
; 2 - Messages + Message specific Informations (e.g. bearer capability)
; 3 - very Verbose, the above + lots of Driver specific infos
; 4 - even more Verbose than 3
;
; default value: 0
;
debug=0

; set debugging file and flags for mISDNuser (NT-Stack)
;
; flags can be or'ed with the following values:
;
; DBGM_NET 0x00000001
; DBGM_MSG 0x00000002
; DBGM_FSM 0x00000004
; DBGM_TEI 0x00000010
; DBGM_L2 0x00000020
; DBGM_L3 0x00000040
; DBGM_L3DATA 0x00000080
; DBGM_BC 0x00000100
; DBGM_TONE 0x00000200
; DBGM_BCDATA 0x00000400
; DBGM_MAN 0x00001000
; DBGM_APPL 0x00002000
; DBGM_ISDN 0x00004000
; DBGM_SOCK 0x00010000
; DBGM_CONN 0x00020000
; DBGM_CDATA 0x00040000
; DBGM_DDATA 0x00080000
; DBGM_SOUND 0x00100000
; DBGM_SDATA 0x00200000
; DBGM_TOPLEVEL 0x40000000
; DBGM_ALL 0xffffffff
;

ntdebugflags=0
ntdebugfile=/var/log/misdn-nt.log

; the big trace
;
; default value: [not set]
;
;tracefile=/var/log/asterisk/misdn.log

; set to yes if you want mISDN_dsp to bridge the calls in HW
;
; default value: yes
;
bridging=no

; stops dialtone after getting first digit on nt Port
;
; default value: yes
;
stop_tone_after_first_digit=yes

; whether to append overlapdialed Digits to Extension or not
;
; default value: yes
;
append_digits2exten=yes

;;; CRYPTION STUFF

; Whether to look for dynamic crypting attempt
;
; default value: no
;
dynamic_crypt=no

; crypt_prefix, what is used for crypting Protocol
;
; default value: [not set]
;
crypt_prefix=**

; Keys for cryption, you reference them in the dialplan
; later also in dynamic encr.
;
; default value: [not set]
;
crypt_keys=test,muh

; users sections:
;
; name your sections as you which but not "general" !
; the sections are Groups, you can dial out in extensions.conf
; with Dial(mISDN/g:extern/101) where extern is a section name,
; chan_misdn tries every port in this section to find a
; new free channel
;

; The default section is not a group section, it just contains config elements
; which are inherited by group sections.
;

[default]

; define your default context here
;
; default value: default
;
context=misdn

; language
;
; default value: en
;
language=en

;
; sets the musiconhold class
;
musicclass=default

;
; Either if we should produce DTMF Tones ourselves
;
senddtmf=yes

;
; If we should generate Ringing for chan_sip and others
;
far_alerting=no

;
; here you can define which bearers should be allowed
;
allowed_bearers=all

; Prefixes for national and international, those are put before the
; oad if an according dialplan is set by the other end.
;
; default values: nationalprefix : 0
; internationalprefix : 00
;
nationalprefix=0
internationalprefix=00

; set rx/tx gains between -8 and 8 to change the RX/TX Gain
;
; default values: rxgain: 0
; txgain: 0
;
rxgain=0
txgain=0

; some telcos especially in NL seem to need this set to yes, also in
; switzerland this seems to be important
;
; default value: no
;
te_choose_channel=no

;
; This option defines, if chan_misdn should check the L1 on a PMP
; before making a group call on it. The L1 may go down for PMP Ports
; so we might need this.
; But be aware! a broken or plugged off cable might be used for a group call
; as well, since chan_misdn has no chance to distinguish if the L1 is down
; because of a lost Link or because the Provider shut it down...
;
; default: no
;
pmp_l1_check=no

;
; in PMP this option defines which cause should be sent out to
; the 3. caller. chan_misdn does not support callwaiting on TE
; PMP side. This allows to modify the RELEASE_COMPLETE cause
; at least.
;
reject_cause=16

;
; Send Setup_Acknowledge on incoming calls anyway (instead of PROCEEDING),
; this requests additional Infos, so we can waitfordigits
; without much issues. This works only for PTP Ports
;
; default value: no
;
need_more_infos=no

;
; set this to yes if you want to disconnect calls when a timeout occurs
; for example during the overlapdial phase
;
nttimeout=no

; set the method to use for channel selection:
; standard - always choose the first free channel with the lowest number
; round_robin - use the round robin algorithm to select a channel. use this
; if you want to balance your load.
;
; default value: standard
;
method=standard

;
; dialplan means Type Of Number in ISDN Terms (for outgoing calls)
;
; there are different types of the dialplan:
;
; dialplan -> outgoing Number
; localdialplan -> callerid
; cpndialplan -> connected party number
;
; dialplan options:
;
; 0 - unknown
; 1 - International
; 2 - National
; 4 - Subscriber
;
; This setting is used for outgoing calls
;
; default value: 0
;
dialplan=0
localdialplan=0
cpndialplan=0

;
; turn this to no if you don't mind correct handling of Progress Indicators
;
early_bconnect=yes

;
; turn this on if you like to send Tone Indications to a Incoming
; isdn channel on a TE Port. Rarely used, only if the Telco allows
; you to send indications by yourself, normally the Telco sends the
; indications to the remote party.
;
; default: no
;
incoming_early_audio=no

; uncomment the following to get into s extension at extension conf
; there you can use DigitTimeout if you can't or don't want to use
; isdn overlap dial.
; note: This will jump into the s exten for every exten!
;
; default value: no
;
;always_immediate=no

;
; set this to yes if you want to generate your own dialtone
; with always_immediate=yes, else chan_misdn generates the dialtone
;
; default value: no
;
nodialtone=no

; uncomment the following if you want callers which called exactly the
; base number (so no extension is set) jump to the s extension.
; if the user dials something more it jumps to the correct extension
; instead
;
; default value: no
;
;immediate=no

; uncomment the following to have hold and retrieve support
;
; default value: no
;
;hold_allowed=yes

; Pickup and Callgroup
;
; default values: not set = 0
;
;callgroup=1
;pickupgroup=1

;
; these are the exact isdn screening and presentation indicators
; if -1 is given for both values the presentation indicators are used
; from asterisks SetCallerPres application.
; s=0, p=0 -> callerid presented not screened
; s=1, p=1 -> callerid presented but screened (the remote end does not see it!)
;
; default values s=-1, p=-1
presentation=-1
screen=-1

; this enables echocancellation, with the given number of taps
; be aware, move this setting only to outgoing portgroups!
; A value of zero turns echocancellation off.
;
; possible values are: 0,32,64,128,256,yes(=128),no(=0)
;
; default value: no
;
;echocancel=no

;
; chan_misdns jitterbuffer, default 4000
;
jitterbuffer=4000

;
; change this threshold to enable dejitter functionality
;
jitterbuffer_upper_threshold=0

;
; change this to yes, if you want to bridge a mISDN data channel to
; another channel type or to an application.
;
hdlc=no

[intern]
; define your ports, e.g. 1,2 (depends on mISDN-driver loading order)
ports=1,2
; context where to go to when incoming Call on one of the above ports
context=Intern

[internPP]
;
; adding the postfix 'ptp' to a port number is obsolete now, chan_misdn
; parses /etc/misdn-init.conf and sets the ptp mode to the corresponding
; configs. For backwards compatibility you can still set ptp here.
;
ports=3

[first_extern]
; again port defs
ports=4
; again a context for incoming calls
context=Extern1
; msns for te ports, listen on those numbers on the above ports, and
; indicate the incoming calls to asterisk
; here you can give a comma separated list or simply an '*' for
; any msn.
msns=*

; here an example with given msns
[second_extern]
ports=5
context=Extern2
callerid=15
msns=102,144,101,104
</pre>

MeetMe

2007-09-04T13:33:43Z

Summary:

; Configuration file for MeetMe simple conference rooms for Asterisk of course

<pre>
-= Info about application 'MeetMe' =-

[Synopsis]
MeetMe conference bridge

[Description]
MeetMe([confno][,[options][,pin]]): Enters the user into a specified MeetMe conference.
If the conference number is omitted, the user will be prompted to enter
one.
User can exit the conference by hangup, or if the 'p' option is specified, by pressing '#'.

Please note: The Zaptel kernel modules and at least one hardware driver (or ztdummy)
must be present for conferencing to operate properly. In addition, the chan_zap
channel driver must be loaded for the 'i' and 'r' options to operate at all.

The option string may contain zero or more of the following characters:
'a' -- set admin mode
'A' -- set marked mode
'b' -- run AGI script specified in ${MEETME_AGI_BACKGROUND}
Default: conf-background.agi
(Note: This does not work with non-Zap channels in the same conference)
'c' -- announce user(s) count on joining a conference
'd' -- dynamically add conference
'D' -- dynamically add conference, prompting for a PIN
'e' -- select an empty conference
'E' -- select an empty pinless conference
'i' -- announce user join/leave
'm' -- set monitor only mode (Listen only, no talking)
'M' -- enable music on hold when the conference has a single caller
'p' -- allow user to exit the conference by pressing '#'
'P' -- always prompt for the pin even if it is specified
'q' -- quiet mode (don't play enter/leave sounds)
'r' -- Record conference (records as ${MEETME_RECORDINGFILE}
using format ${MEETME_RECORDINGFORMAT}). Default filename is
meetme-conf-rec-${CONFNO}-${UNIQUEID} and the default format is wav.
's' -- Present menu (user or admin) when '*' is received ('send' to menu)
't' -- set talk only mode. (Talk only, no listening)
'T' -- set talker detection (sent to manager interface and meetme list)
'w[(<secs>)]'
-- wait until the marked user enters the conference
'x' -- close the conference when last marked user exits
'X' -- allow user to exit the conference by entering a valid single
digit extension ${MEETME_EXIT_CONTEXT} or the current context
if that variable is not defined.
</pre>

Example: meetme.conf
<pre>
;
; Configuration file for MeetMe simple conference rooms for Asterisk of course.
;
; This configuration file is read every time you call app meetme()

[general]
;audiobuffers=32 ; The number of 20ms audio buffers to be used
; when feeding audio frames from non-Zap channels
; into the conference; larger numbers will allow
; for the conference to 'de-jitter' audio that arrives
; at different timing than the conference's timing
; source, but can also allow for latency in hearing
; the audio from the speaker. Minimum value is 2,
; maximum value is 32.
;
[rooms]
;
; Usage is conf => confno[,pin][,adminpin]
;
; Note that once a participant has called the conference, a change to the pin
; number done in this file will not take effect until there are no more users
; in the conference and it goes away. When it is created again, it will have
; the new pin number.
;
;conf => 1234
;conf => 2345,9938
</pre>

Manager

2007-09-04T13:33:13Z

Summary:

;The Asterisk Manager TCP/IP API - AMI
 
----
The manager is a client/server model over TCP. With the manager interface, you'll be able to control the PBX, originate calls, check mailbox status, monitor channels and queues as well as execute Asterisk commands.

AMI is the standard management interface into your Asterisk server. You configure AMI in manager.conf. By default, AMI is available on TCP port 5038 if you enable it in manager.conf.

AMI receive commands, called "actions". These generate a "response" from Asterisk. Asterisk will also send "Events" containing various information messages about changes within Asterisk. Some actions generate an initial response and data in the form list of events. This format is created to make sure that extensive reports do not block the manager interface fully.

Management users are configured in the configuration file manager.conf and are given permissions for read and write, where write represents their ability to perform this class of "action", and read represents their ability to receive this class of "event".

The Asterisk manager interface in version 1.0.x of Asterisk is not very well standardized. Work is under way to change this to Asterisk 1.2. If you develop AMI applications, treat the headers in Actions, Events and Responses as local to that particular message. There is no cross-message standardization of headers.

If you develop applications, please try to reuse existing manager headers and their interpretation. If you are unsure, discuss on the asterisk-dev mailing list.

==Command Syntax==
----
Management communication consists of tags of the form "header: value", terminated with an empty newline (\r\n) in the style of SMTP, HTTP, and other headers.

The first tag MUST be one of the following:

* Action: An action requested by the CLIENT to the Asterisk SERVER.
::Only one "Action" may be outstanding at any time.
* Response: A response to an action from the Asterisk SERVER to the CLIENT.
* Event: An event reported by the Asterisk SERVER to the CLIENT

==Manager commands==
----
Output from the CLI command 'show manager' command:

* Ping: Ping
* Logoff: Logoff Manager
* Hangup: Hangup Channel
* Status: Status
* Redirect: Redirect
* Originate: Originate Call
* MailboxStatus: Check Mailbox
* Command: Execute Command
* ExtensionState: Check Extension Status
* AbsoluteTimeout: Set Absolute Timeout
* MailboxCount: Check Mailbox Message Count
* Monitor: Monitor a channel
* StopMonitor: Stop monitoring a channel
* ChangeMonitor: Change monitoring filename of a channel
* IAXpeers: List IAX Peers (Defaults to IAX2)
* SIPpeers: List SIP peers
* SIPshowpeer: Show data about one SIP peer
* Queues: Queues
* QueueStatus: Queue Status

This list depends on the version of Asterisk you are using, as well as which modules that are loaded.

==Command Summary==
----

Command: Command
Parameters: Command

Command: ExtensionState
Parameters: Exten, Context, ActionID

Command: Hangup
Parameters: Channel

Command: Logoff
Parameters: None

Command: MailboxCount
Parameters: Mailbox, ActionID

Command: MailboxStatus
Parameters: Mailbox, ActionID

Command: Originate
Parameters: Channel, Exten, Context, Priority, Timeout,
CallerID, Variable, Account, Application, Data, Async

Command: Ping
Parameters: None

Command: Redirect
Parameters: Channel, ExtraChannel, Exten, Context, Priority

Command: Timeout
Parameters: Channel, Timeout

You can always get more information about a manager command
with the "show manager command <command>" CLI command in Asterisk.

==Examples==
----
Login - Log a user into the manager interface.

Action: Login
Username: testuser
Secret: testsecret

Originate - Originate a call from a channel to an extension.

Action: Originate
Channel: sip/12345
Exten: 1234
Context: default

Originate - Originate a call from a channel to an extension without waiting
for call to complete.

Action: Originate
Channel: sip/12345
Exten: 1234
Context: default
Async: yes

Redirect with ExtraChannel:

Attempted goal:
Have a 'robot' program Redirect both ends of an already-connected call to a meetme room using the ExtraChannel feature through the management interface.

Action: Redirect
Channel: Zap/1-1
ExtraChannel: SIP/3064-7e00 (varies)
Exten: 680
Priority: 1

Where 680 is an extension that sends you to a MeetMe room.

There are a number of GUI tools that use the manager interface, please search the mailing list archives and the documentation page on the http://www.asterisk.org web site for more information.

==Some standard AMI headers==
<pre>
Account: -- Account Code (Status)
AccountCode: -- Account Code (cdr_manager)
ACL: <Y | N> -- Does ACL exist for object ?
Action: <action> -- request or notification of a particular action
Address-IP: -- IPaddress
Address-Port: -- IP port number
Agent: <string> -- Agent name
AMAflags: -- AMA flag (cdr_manager, sippeers)
AnswerTime: -- Time of answer (cdr_manager)
Append: <bool> -- CDR userfield Append flag
Application: -- Application to use
Async: -- Whether or not to use fast setup
AuthType: -- Authentication type (for login or challenge) "md5"
BillableSeconds: -- Billable seconds for call (cdr_manager)
CallerID: -- Caller id (name and number in Originate & cdr_manager)
CallerID: -- CallerID number
!Number or "<unknown>" or "unknown" (should change to "<unknown>" in app_queue)
CallerID1: -- Channel 1 CallerID (Link event)
CallerID2: -- Channel 2 CallerID (Link event)
CallerIDName: -- CallerID name
!Name or "<unknown>" or "unknown" (should change to "<unknown>" in app_queue)
Callgroup: -- Call group for peer/user
CallsTaken: <num> -- Queue status variable
Cause: <value> -- Event change cause - "Expired"
Cause: <value> -- Hangupcause (channel.c)
CID-CallingPres: -- Caller ID calling presentation
Channel: <channel> -- Channel specifier
Channel: <dialstring> -- Dialstring in Originate
Channel: <tech/[peer/username]> -- Channel in Registry events (SIP, IAX2)
Channel: <tech> -- Technology (SIP/IAX2 etc) in Registry events
ChannelType: -- Tech: SIP, IAX2, ZAP, MGCP etc
Channel1: -- Link channel 1
Channel2: -- Link channel 2
ChanObjectType: -- "peer", "user"
Codecs: -- Codec list
CodecOrder: -- Codec order, separated with comma ","
Command: -- Cli command to run
Context: -- Context
Count: <num> -- Number of callers in queue
Data: -- Application data
Default-addr-IP: -- IP address to use before registration
Default-Username: -- Username part of URI to use before registration
Destination: -- Destination for call (Dialstring ) (dial, cdr_manager)
DestinationContext: -- Destination context (cdr_manager)
DestinationChannel: -- Destination channel (cdr_manager)
DestUniqueID: -- UniqueID of destination (dial event)
Disposition: -- Call disposition (CDR manager)
Domain: <domain> -- DNS domain
Duration: <secs> -- Duration of call (cdr_manager)
Dynamic: <Y | N> -- Device registration supported?
Endtime: -- End time stamp of call (cdr_manager)
EventList: <flag> -- Flag being "Start", "End", "Cancelled" or "ListObject"
Events: <eventmask> -- Eventmask filter ("on", "off", "system", "call", "log")
Exten: -- Extension (Redirect command)
Extension: -- Extension (Status)
Family: <string> -- ASTdb key family
File: <filename> -- Filename (monitor)
Format: <format> -- Format of sound file (monitor)
From: <time> -- Parking time (ParkedCall event)
Hint: -- Extension hint
Incominglimit: -- SIP Peer incoming limit
Key:
Key: -- ASTdb Database key
LastApplication: -- Last application executed (cdr_manager)
LastCall: <num> -- Last call in queue
LastData: -- Data for last application (cdr_manager)
Link: -- (Status)
ListItems: <number> -- Number of items in Eventlist (Optionally sent in "end" packet)
Location: -- Interface (whatever that is -maybe tech/name in app_queue )
Loginchan: -- Login channel for agent
Logintime: <number> -- Login time for agent
Mailbox: -- VM Mailbox (id@vmcontext) (mailboxstatus, mailboxcount)
MD5SecretExist: <Y | N> -- Whether secret exists in MD5 format
Membership: <string> -- "Dynamic" or "static" member in queue
Message: <text> -- Text message in ACKs, errors (explanation)
Mix: <bool> -- Boolean parameter (monitor)
NewMessages: <count> -- Count of new Mailbox messages (mailboxcount)
Newname:
ObjectName: -- Name of object in list
OldName: -- Something in Rename (channel.c)
OldMessages: <count> -- Count of old mailbox messages (mailboxcount)
Outgoinglimit: -- SIP Peer outgoing limit
Paused: <num> -- Queue member paused status
Peer: <tech/name> -- "channel" specifier :-)
PeerStatus: <tech/name> -- Peer status code "Unregistred", "Registred", "Lagged", "Reachable"
Penalty: <num> -- Queue penalty
Priority: -- Extension priority
Privilege: <privilege> -- AMI authorization class (system, call, log, verbose, command, agent, user)
Pickupgroup: -- Pickup group for peer
Position: <num> -- Position in Queue
Queue: -- Queue name
Reason: -- "Autologoff"
Response: <response> -- response code, like "200 OK" "Success", "Error", "Follows"
Restart: -- "True", "False"
RegExpire: -- SIP registry expire
RegExpiry: -- SIP registry expiry
Reason: -- Originate reason code
Seconds: -- Seconds (Status)
Secret: <password> -- Authentication secret (for login)
SecretExist: <Y | N> -- Whether secret exists
Shutdown: -- "Uncleanly", "Cleanly"
SIP-AuthInsecure:
SIP-FromDomain: -- Peer FromDomain
SIP-FromUser: -- Peer FromUser
SIP-NatSupport:
SIPLastMsg:
Source: -- Source of call (dial event, cdr_manager)
SrcUniqueID: -- UniqueID of source (dial event)
StartTime: -- Start time of call (cdr_manager)
State: -- Channel state
Status: -- Registration status (Registry events SIP)
Status: -- Extension status (Extensionstate)
Status: -- Peer status (if monitored) ** Will change name ** "unknown","lagged", "ok"
Status: <num> -- Queue Status
Status: -- DND status (DNDState)
Time: <sec> -- Roundtrip time (latency)
Timeout: -- Parking timeout time
Timeout: -- Timeout for call setup (Originate)
Timeout: <seconds> -- Timout for call
Uniqueid: -- Channel Unique ID
Uniqueid1: -- Channel 1 Unique ID (Link event)
Uniqueid2: -- Channel 2 Unique ID (Link event)
User: -- Username (SIP registry)
UserField: -- CDR userfield (cdr_manager)
Val: -- Value to set/read in ASTdb
Variable: -- Variable AND value to set (multiple separated with | in Originate)
Variable: <name> -- For channel variables
Value: <value> -- Value to set
VoiceMailbox: -- VM Mailbox in SIPpeers
Waiting: -- Count of mailbox messages (mailboxstatus)

** Please try to re-use existing headers to simplify manager message parsing in clients.
</pre>

==Example manager.conf==
<pre>
;
; AMI - The Asterisk Manager Interface
;
; Third party application call management support and PBX event supervision
;
; This configuration file is read every time someone logs in
;
; Use the "show manager commands" at the CLI to list available manager commands
; and their authorization levels.
;
; "show manager command <command>" will show a help text.
;
; ---------------------------- SECURITY NOTE -------------------------------
; Note that you should not enable the AMI on a public IP address. If needed,
; block this TCP port with iptables (or another FW software) and reach it
; with IPsec, SSH, or SSL vpn tunnel
;
[general]
enabled = no
port = 5038
bindaddr = 0.0.0.0
;displayconnects = yes

;[mark]
;secret = mysecret
;deny=0.0.0.0/0.0.0.0
;permit=209.16.236.73/255.255.255.0
;
; If the device connected via this user accepts input slowly,
; the timeout for writes to it can be increased to keep it
; from being disconnected (value is in milliseconds)
;
; writetimeout = 100
;
; Authorization for various classes
;read = system,call,log,verbose,command,agent,user
;write = system,call,log,verbose,command,agent,user
</pre>

Mathematical

2007-09-04T13:32:42Z

Summary:

Yeah, I thought it was a little insane too..

adds:

Sum, Multiply, Divide, Subtract, Modulus, GT, LT, GTE, LTE, EQ functions to Asterisk

All functions follow the same basic pattern for parameters:

parameter 1 = the math expression
parameter 2 = the type of result

Perform calculation on number 1 to number 2. Valid ops are:
+,-,/,*,%,<,>,>=,<=,==
and behave as their C equivalents.

<type_of_result> - wanted type of result:
f, float - float(default)
i, int - integer,
h, hex - hex,
c, char - char

Each math expression is performed as

Action param1 on param2

eg:

Action = Divide
Param1 = 10
Param2 = 2

Results in

Divide 10 by 2

Example dialplan:

exten => 11099,1,Set(RV=${MATH(1+20)})
exten => 11099,n,NOOP(${RV})
exten => 11099,n,Set(RV=${MATH(10*2)})
exten => 11099,n,NOOP(${RV})
exten => 11099,n,Set(RV=${MATH(10*2)})
exten => 11099,n,NOOP(${RV})
exten => 11099,n,Set(RV=${MATH(10-2)})
exten => 11099,n,NOOP(${RV})
exten => 11099,n,Set(RV=${MATH(2%10)})
exten => 11099,n,NOOP(${RV})
exten => 11099,n,Set(RV=${MATH(10/0)})
exten => 11099,n,NOOP(${RV})
exten => 11099,n,Set(RV=${MATH(10-200)})
exten => 11099,n,NOOP(${RV})
exten => 11099,n,Set(RV=${MATH(1-20)})
exten => 11099,n,NOOP(${RV})
exten => 11099,n,Set(RV=${MATH(1<20)})
exten => 11099,n,NOOP(${RV})
exten => 11099,n,Set(RV=${MATH(1>=20)})
exten => 11099,n,NOOP(${RV})
exten => 11099,n,Set(RV=${MATH(101>20)})
exten => 11099,n,NOOP(${RV})
exten => 11099,n,Set(RV=${MATH(1==20)})
exten => 11099,n,NOOP(${RV})
exten => 11099,n,Set(RV=${MATH(20<=20)})
exten => 11099,n,NOOP(${RV})
exten => 11099,n,Set(RV=${MATH(123%16,int)})
exten => 11099,n,NOOP(${RV})

Logging

2007-09-04T13:32:15Z

Summary:

; Logging Configuration

<pre>
;
; Logging Configuration
;
; In this file, you configure logging to files or to
; the syslog system.
;
; "logger reload" at the CLI will reload configuration
; of the logging system.

[general]
; Customize the display of debug message time stamps
; this example is the ISO 8601 date format (yyyy-mm-dd HH:MM:SS)
; see strftime(3) Linux manual for format specifiers
;dateformat=%F %T
;
; This appends the hostname to the name of the log files.
;appendhostname = yes
;
; This determines whether or not we log queue events to a file
; (defaults to yes).
;queue_log = no
;
; This determines whether or not we log generic events to a file
; (defaults to yes).
;event_log = no
;
;
; For each file, specify what to log.
;
; For console logging, you set options at start of
; Asterisk with -v for verbose and -d for debug
; See 'asterisk -h' for more information.
;
; Directory for log files is configures in asterisk.conf
; option astlogdir
;
[logfiles]
;
; Format is "filename" and then "levels" of debugging to be included:
; debug
; notice
; warning
; error
; verbose
; dtmf
;
; Special filename "console" represents the system console
;
; We highly recommend that you DO NOT turn on debug mode if you are simply
; running a production system. Debug mode turns on a LOT of extra messages,
; most of which you are unlikely to understand without an understanding of
; the underlying code. Do NOT report debug messages as code issues, unless
; you have a specific issue that you are attempting to debug. They are
; messages for just that -- debugging -- and do not rise to the level of
; something that merit your attention as an Asterisk administrator. Debug
; messages are also very verbose and can and do fill up logfiles quickly;
; this is another reason not to have debug mode on a production system unless
; you are in the process of debugging a specific issue.
;
;debug => debug
console => notice,warning,error
;console => notice,warning,error,debug
messages => notice,warning,error
;full => notice,warning,error,debug,verbose

;syslog keyword : This special keyword logs to syslog facility
;
;syslog.local0 => notice,warning,error
;
</pre>

Localchannel

2007-09-04T13:31:48Z

Summary:

chan_local is a pseudo-channel. Use of this channel simply loops calls back into the dialplan in a different context. Useful for recursive routing.

* Syntax:

Local/extension@context[/n]

Adding "/n" at the end of the string will make the Local channel not do a native transfer (the "n" stands for "n"o release) upon the remote end answering the line. This is an esoteric, but important feature if you expect the Local channel to handle calls exactly like a normal channel. If you do not have the "no release" feature set, then as soon as the destination (inside of the Local channel) answers the line, the variables and dial plan will revert back to that of the original call, and the Local channel will become a zombie and be removed from the active channels list. This is desirable in some circumstances, but can result in unexpected dialplan behavior if you are doing fancy things with variables in your call handling.

* Purpose:

The Local channel construct can be used to establish dialing into any part of the dialplan.

Imagine you have a TE410P in your box. You want to do something for which you must use a Dial statement (for instance when dropping files in /var/spool/outgoing) but you do want to be able to use your dialplans least-cost-routes or other intelligent stuff. What you could do before we had chan_local was create a cross-link between two ports of the TE410P and then Dial out one port and in the other. This way you could control where the call was going.

Of course, this was a nasty hack, and to make it more sensible, chan_local was built.

The "Local" channel driver allows you to convert an arbitrary extension into a channel. It is used in a variety of places, including agents, etc.

This also allows us to hop to contexts like a GoSub routine; See examples below.

Examples:

[inbound] ; here falls all incoming calls
exten => s,1,Answer
exten => s,2,Dial(local/200@internal,30,r)
exten => s,3,Playback(sorrynoanswer)
exten => s,4,Hangup
 
[internal] ; here where our phones falls for default
exten => 200,1,Dial(sip/blah)
exten => 200,102,VoiceMail(${EXTEN}@default)
 
exten => 201,1,Dial(zap/1)
exten => 201,102,VoiceMail(${EXTEN}@default)
 
exten => _0.,1,Dial(Zap/g1/${EXTEN:1}) ; outgoing calls with 0+number

Caveats:
If you use chan_local from a call-file and you want to pass channel variables into your context, make sure you append the '/n', because otherwise chan_local will 'optimize' itself out of the call-path, and the variables will get lost. i.e.

Local/00531234567@pbx becomes Local/00531234567@pbx/n

----
2004-01-17

Jitterbuffer

2007-09-04T13:31:17Z

Summary:

The new jitterbuffer, PLC, and the IAX2-integration of the new jitterbuffer have been integrated into Asterisk. The jitterbuffer is generic and work is going on to implement it in SIP/RTP as well.

Also, we ve added a feature called "trunktimestamps", which adds individual timestamps to trunked frames within a trunk frame.

Here's how to use this stuff:
<pre>
1) The new jitterbuffer:
------------------------
You must add "jitterbuffer=yes" to either the [general] part of
iax.conf, or to a peer or a user. (just like the old jitterbuffer).
Also, you can set "maxjitterbuffer=n", which puts a hard-limit on the size of the
jitterbuffer of "n milliseconds". It is not necessary to have the new jitterbuffer
on both sides of a call; it works on the receive side only.

2) PLC:
-------
The new jitterbuffer detects packet loss. PLC is done to try to recreate these
lost packets in the codec decoding stage, as the encoded audio is translated to slinear.
PLC is also used to mask jitterbuffer growth.

This facility is enabled by default in iLBC and speex, as it has no additional cost.
This facility can be enabled in adpcm, alaw, g726, gsm, lpc10, and ulaw by setting
genericplc => true in the [plc] section of codecs.conf.

3) Trunktimestamps:
-------------------
To use this, both sides must be using Asterisk v1.2.
Setting "trunktimestamps=yes" in iax.conf will cause your box to send 16-bit timestamps
for each trunked frame inside of a trunk frame. This will enable you to use jitterbuffer
for an IAX2 trunk, something that was not possible in the old architecture.

The other side must also support this functionality, or else, well, bad things will happen.
If you don't use trunktimestamps, there's lots of ways the jitterbuffer can get confused because
timestamps aren't necessarily sent through the trunk correctly.

4) Communication with Asterisk v1.0.x systems
---------------------------------------------
You can set up communication with v1.0.x systems with the new jitterbuffer, but
you can't use trunks with trunktimestamps in this communication.

If you are connecting to an Asterisk server with earlier versions of the software (1.0.x),
do not enable both jitterbuffer and trunking for the involved peers/users
in order to be able to communicate. Earlier systems will not support trunktimestamps.

You may also compile chan_iax2.c without the new jitterbuffer, enabling the old
backwards compatible architecture. Look in the source code for instructions.

5) Testing and monitoring:
--------------------------
You can test the effectiveness of PLC and the new jitterbuffer's detection of loss by using
the new CLI command "iax2 test losspct <n>". This will simulate n percent packet loss
coming _in_ to chan_iax2. You should find that with PLC and the new JB, 10 percent packet
loss should lead to just a tiny amount of distortion, while without PLC, it would lead to
silent gaps in your audio.

"iax2 show netstats" shows you statistics for each iax2 call you have up.
The columns are "RTT" which is the round-trip time for the last PING, and then a bunch of s
tats for both the local side (what you're receiving), and the remote side (what the other
end is telling us they are seeing). The remote stats may not be complete if the remote
end isn't using the new jitterbuffer.

The stats shown are:
* Jit: The jitter we have measured (milliseconds)
* Del: The maximum delay imposed by the jitterbuffer (milliseconds)
* Lost: The number of packets we've detected as lost.
* %: The percentage of packets we've detected as lost recently.
* Drop: The number of packets we've purposely dropped (to lower latency).
* OOO: The number of packets we've received out-of-order
* Kpkts: The number of packets we've received / 1000.

Reporting problems
==================

There's a couple of things that can make calls sound bad using the jitterbuffer:

1) The JB and PLC can make your calls sound better, but they can't fix everything.
If you lost 10 frames in a row, it can't possibly fix that. It really can't help much
more than one or two consecutive frames.

2) Bad timestamps: If whatever is generating timestamps to be sent to you generates
nonsensical timestamps, it can confuse the jitterbuffer. In particular, discontinuities
in timestamps will really upset it: Things like timestamps sequences which go 0, 20, 40,
60, 80, 34000, 34020, 34040, 34060... It's going to think you've got about 34 seconds
of jitter in this case, etc..
The right solution to this is to find out what's causing the sender to send us such nonsense,
and fix that. But we should also figure out how to make the receiver more robust in
cases like this.

chan_iax2 will actually help fix this a bit if it's more than 3 seconds or so, but at
some point we should try to think of a better way to detect this kind of thing and
resynchronize.

Different clock rates are handled very gracefully though; it will actually deal with a
sender sending 20% faster or slower than you expect just fine.

3) Really strange network delays: If your network "pauses" for like 5 seconds, and then
when it restarts, you are sent some packets that are 5 seconds old, we are going to see
that as a lot of jitter. We already throw away up to the worst 20 frames like this,
though, and the "maxjitterbuffer" parameter should put a limit on what we do in this case.

Reporting possible bugs
-----------------------
If you do find bad behaviors, here's the information that will help to diagnose this:

1) Describe

a) the source of the timestamps and frames: i.e. if they're coming from another chan_iax2 box,
a bridged RTP-based channel, an IAX2 softphone, etc..

b) The network between, in brief (i.e. the internet, a local lan, etc).

c) What is the problem you're seeing.

2) Take a look and see what iax2 show netstats is saying about the call, and if it makes sense.

3) a tcpdump of the frames, (or, tethereal output from), so we can see the timestamps and delivery
times of the frames you're receiving. You can make such a tcpdump with:

tcpdump -s 2048 -w /tmp/example.dump udp and port 4569 [and host <other-end>]

Report bugs in the Asterisk bugtracker, http://bugs.digium.com.
Please read the bug guidelines before you post a bug.
</pre>
Have fun!

-SteveK

IAX

2007-09-04T13:30:21Z

Summary:

==INTRODUCTION==
----

This document is intended as an introduction to the Inter-Asterisk eXchange (or simply IAX) protocol. It provides both a theoretical background and practical information on its use.

==WHY IAX==
----
The first question most people are thinking at this point is "Why do you need another VoIP protocol? Why didn't you just use SIP or H.323?"

Well, the answer is a fairly complicated one, but in a nutshell it's like this... Asterisk is intended as a very flexible and powerful communications tool. As such, the primary feature we need from a VoIP
protocol is the ability to meet our own goals with Asterisk, and one with enough flexibility that we could use it as a kind of laboratory for inventing and implementing new concepts in the field. Neither H.323 or SIP fit the roles we needed, so we developed our own protocol, which, while not standards based, provides a number of advantages over both SIP and H.323, some of which are:

* Interoperability with NAT/PAT/Masquerade firewalls
::IAX seamlessly interoperates through all sorts of NAT and PAT
::and other firewalls, including the ability to place and receive calls, and transfer calls to other stations.

* High performance, low overhead protocol
::When running on low-bandwidth connections, or when running
::large numbers of calls, optimized bandwidth utilization is imperative. IAX uses only 4 bytes of overhead

* Internationalization support
::IAX transmits language information, so that remote PBX
::content can be delivered in the native language of the calling party.

* Remote dialplan polling
::IAX allows a PBX or IP phone to poll the availability of a
::number from a remote server. This allows PBX dialplans to be centralized.

* Flexible authentication
::IAX supports cleartext, md5, and RSA authentication,
::providing flexible security models for outgoing calls and registration services.

* Multimedia protocol
::IAX supports the transmission of voice, video, images, text,
::HTML, DTMF, and URL's. Voice menus can be presented in both audibly and visually.

* Call statistic gathering
::IAX gathers statistics about network performance (including
::latency and jitter, as well as providing end-to-end latency measurement.

* Call parameter communication
::Caller*ID, requested extension, requested context, etc are all communicated through the call.

* Single socket design
::IAX's single socket design allows up to 32768 calls to be multiplexed.

While we value the importance of standards based (i.e. SIP) call handling,
hopefully this will provide a reasonable explanation of why we developed
IAX rather than starting with SIP.

==CONFIG FILE CONVENTIONS==
----
<pre>
Lines beginning with '>' represent lines which might appear in an actual
configuration file. The '>' is used to help separate them from the
descriptive text and should not actually be included in the file itself.

Lines within []'s by themselves represent section labels within the
configuration file. like this:

> [mysection]

Options are set using the "=" sign, for example

> myoption = value

Sometimes an option will have a number of discrete values which it can
take. In that case, in the documentation, the options will be listed
within square brackets (the "[" and "]" ones) separated by the pipe symbol
("|"). For example:

> myoption = [value1|value2|value3]

means the option "myoption" can be assigned a value of "value1", "value2",
or "value3".

Objects, or pseudo-objects are instantiated using the "=>" construct. For
example:

> myobject => parameter

creates an object called "myobject" with some parameter whose definition
would be specific to that object. Note that the config file parser
considers "=>" and "=" to be equivalent and their use is purely to make
configuration files more readable and easier to "humanly parse".

The comment character in Asterisk configuration files is the semicolon
";". The reason it is not "#" is because the "#" symbol can be used as
parts of extensions and it didn't seem like a good idea to have to escape
it.

==IAX CONFIGURATION IN ASTERISK==
-----------------------------

Like everything else in Asterisk, IAX's configuration lies in
/etc/asterisk -- specifically /etc/asterisk/iax.conf

The IAX configuration file is a collection of sections, each of which
(with the exception of the "general" section) represents an entity within
the IAX scope.

------------

The first section is typically the "general" section. In this area,
a number of parameters which affect the entire system are configured.
Specifically, the default codecs, port and address, jitter behavior, TOS
bits, and registrations.

The first line of the "general" section is always:

> [general]

Following the first line are a number of other possibilities:

> bindport = <portnum>

This sets the port that IAX will bind to. The default IAX version 1
port number is 5036. For IAX version 2, that is now the default in
Asterisk, the default port is 4569.
It is recommended that this value not be altered in general.

> bindaddr = <ipaddr>

This allows you to bind IAX to a specific local IP address instead of
binding to all addresses. This could be used to enhance security if, for
example, you only wanted IAX to be available to users on your LAN.

> bandwidth = [low|medium|high]

The bandwidth selection initializes the codec selection to appropriate
values for given bandwidths. The "high" selection enables all codecs and
is recommended only for 10Mbps or higher connections. The "medium"
bandwidth eliminates signed linear, Mu-law and A-law codecs, leaving only
the codecs which are 32kbps and smaller (with MP3 as a special case). It
can be used with broadband connections if desired. "low" eliminates ADPCM
and MP3 formats, leaving only the G.723.1, GSM, and LPC10.

> allow = [gsm|lpc10|g723.1|adpcm|ulaw|alaw|mp3|slinear|all]
> disallow = [gsm|lpc10|g723.1|adpcm|ulaw|alaw|mp3|slinear|all]

The "allow" and "disallow" allow you to fine tune the codec selection
beyond the initial bandwidth selection on a codec-by-codec basis.

The recommended configuration is to select "low" bandwidth and then
disallow the LPC10 codec just because it doesn't sound very good.

> jitterbuffer = [yes|no]
> dropcount = <dropamount>
> maxjitterbuffer = <max>
> maxexcessbuffer = <max>

These parameters control the operation of the jitter buffer. The
jitterbuffer should always be enabled unless you expect all your
connections to be over a LAN.
* drop count is the maximum number of voice packets to allow to drop
(out of 100). Useful values are 3-10.
* maxjitterbuffer is the maximum amount of jitter buffer to permit to be
used.
* maxexcessbuffer is the maximum amount of excess jitter buffer
that is permitted before the jitter buffer is slowly shrunk to eliminate
latency.
* minexcessbuffer is the minimum amout of excess jitter buffer

> accountcode = <code>
> amaflags = [default|omit|billing|documentation]

These parameters affect call detail record generation. The first sets the
account code for records received with IAX. The account code can be
overridden on a per-user basis for incoming calls (see below). The
amaflags controls how the record is labeled ("omit" causes no record to be
written. "billing" and "documentation" label the records as billing or
documentation records respectively, and "default" selects the system
default.

> tos = [lowdelay|throughput|reliability|mincost|none]

IAX can optionally set the TOS (Type of Service) bits to specified values
to help improve performance in routing. The recommended value is
"lowdelay", which many routers (including any Linux routers with 2.4
kernels that have not been altered with ip tables) will give priority to
these packets, improving voice quality.

> register => <name>[:<secret>]@<host>[:port]

Any number of registry entries may be instantiated in the general
section. Registration allows Asterisk to notify a remote Asterisk server
(with a fixed address) what our current address is. In order for
registration to work, the remote Asterisk server will need to have a
dynamic peer entry with the same name (and secret if provided).

The name is a required field, and is the remote peer name that we wish to
identify ourselves as. A secret may be provided as well. The secret is
generally a shared password between the local server and the remote
server. However, if the secret is in square brackets ([]'s) then it is
interpreted as the name of a RSA key to use. In that case, the local Asterisk
server must have the *private* key (/var/lib/asterisk/keys/<name>.key) and
the remote server will have to have the corresponding public key.

The "host" is a required field and is the hostname or IP address of the
remote Asterisk server. The port specification is optional and is by
default 4569 for iax2 if not specified.

> notransfer = yes | no

If an IAX phone calls another IAX phone by using a Asterisk server,
Asterisk will transfer the call to go peer to peer. If you do not
want this, turn on notransfer with a "yes". This is also settable
for peers and users.

-------------

The following sections, after "general" define either users, peers or
friends. A "user" is someone who connects to us. A "peer" is someone
that we connect to. A "friend" is simply shorthand for creating a "user"
and "peer" with identical parameters (i.e. someone who can contact us and
who we contact).

> [identifier]

The section begins with the identifier in square brackets. The identifier
should be an alphanumeric string.

> type = [user|peer|friend]

This line tells Asterisk how to interpret this entity. Users are things
that connect to us, while peers are phones we connect to, and a friend is
shorthand for creating a user and a peer with identical information

----------------
User fields:

> context = <context>

One or more context lines may be specified in a user, thus giving the user
access to place calls in the given contexts. Contexts are used by
Asterisk to divide dialing plans into logical units each with the ability
to have numbers interpreted differently, have their own security model,
auxiliary switch handling, and include other contexts. Most users are
given access to the default context. Trusted users could be given access
to the local context for example.

> permit = <ipaddr>/<netmask>
> deny = <ipaddr>/<netmask>

Permit and deny rules may be applied to users, allowing them to connect
from certain IP addresses and not others. The permit and deny rules are
interpreted in sequence and all are evaluated on a given IP address, with
the final result being the decision. For example:

> permit = 0.0.0.0/0.0.0.0
> deny = 192.168.0.0/255.255.255.0

would deny anyone in 192.168.0.0 with a netmask of 24 bits (class C),
whereas:

> deny = 192.168.0.0/24
> permit = 0.0.0.0/0

would not deny anyone since the final rule would permit anyone, thus
overriding the denial.

If no permit/deny rules are listed, it is assumed that someone may connect
from anywhere.

> callerid = <callerid>

You may override the Caller*ID information passed by a user to you (if
they choose to send it) in order that it always be accurate from the
perspective of your server.

> auth = [md5|plaintext|rsa]

You may select which authentication methods are permitted to be used by
the user to authenticate to us. Multiple methods may be specified,
separated by commas. If md5 or plaintext authentication is selected, a
secret must be provided. If RSA authentication is specified, then one or
more key names must be specified with "inkeys"

If no secret is specified and no authentication method is specified, then
no authentication will be required.

> secret = <secret>

The "secret" line specifies the shared secret for md5 and plaintext
authentication methods. It is never suggested to use plaintext except in
some cases for debugging.

> inkeys = key1[:key2...]

The "inkeys" line specifies which keys we can use to authenticate the
remote peer. If the peer's challenge passes with any of the given keys,
then we accept its authentication. The key files live in
/var/lib/asterisk/keys/<name>.pub and are *public keys*. Public keys are
not typically DES3 encrypted and thus do not usually need initialization.

---------------
Peer configuration

> allow = [gsm|lpc10|g723.1|adpcm|ulaw|alaw|mp3|slinear|all]
> disallow = [gsm|lpc10|g723.1|adpcm|ulaw|alaw|mp3|slinear|all]

The "allow" and "disallow" may be used to enable or disable specific codec
support on a per-peer basis.

> host = [<ipaddr>|dynamic]

The host line specifies the hostname or IP address of the remote host, or
may be the word "dynamic" signifying that the host will register with us
(see register => in the general section above).

> defaultip = <ipaddr>

If the host uses dynamic registration, Asterisk may still be given a
default IP address to use when dynamic registration has not been performed
or has timed out.

> peercontext = <context>

Specifies the context name to be passed to the peer for it to use when routing
the call through its dial plan. This entry will be used only if a context
is not included in the IAX2 channel name passed to the Dial command.

> qualify = [yes | no | <value>]

Qualify turns on checking of availability of the remote peer. If the
peer becomes unavailable, no calls are placed to the peer until
it is reachable again. This is also helpful in certain NAT situations.

> jitterbuffer = [yes | no]

Turns on or off the jitterbuffer for this peer

> mailbox = <mailbox>[@mailboxcontext]

Specifies a mailbox to check for voicemail notification.

> permit = <ipaddr>/<netmask>
> deny = <ipaddr>/<netmask>

Permit and deny rules may be applied to users, allowing them to connect
from certain IP addresses and not others. The permit and deny rules are
interpreted in sequence and all are evaluated on a given IP address, with
the final result being the decision. See the user section above
for examples.

----------------------------------------------------------------------
For more examples of a configuration, please see the iax.conf.sample in
your the /configs directory of you source code distribution
</pre>

----
Usage:

The format for the dialing string on Asterisk is: '''IAX/[user@]peer[:exten[@context]]'''
 
(Note, []'s denote optional fields).

The peer is either an IP address or a peer as specified in the /etc/asterisk/iax.conf file. Exten is an optional requested extension (otherwise "s" will be used), and "context" is an optional context to request. The user is an optional username specified in the peer's iax.conf. If the user is not specified, the peer will select one.
 
Protocol and rationale:
----
IAX is a simple, low overhead and low bandwidth VoIP protocol designed to allow multiple Asterisk PBX's to communicate with one another without the overhead of more complex protocols like H.323. Payload is sent with a header overhead of only 4 octets. Control functions (and one payload packet per minute or so) is sent with a more complex header of 12 octets.

IAX is slightly stateful.

IAX contains two kinds of packets: The full header packet type, which contains much information about the frame, in addition to its contents, and the mini header type, which is used only for non-reliable voice packet delivery.

All packets are immediately transmitted. Packets are received, but not delivered to the actual channels until a given time quantum has passed, in order to try to eliminate jitter.

All full header packets must be ackd (except, obviously for the ACK packets themselves and not so obviously for hangup packets). The "timestamp" field of ack packets is not the normal offset, but rather a quote of the timestamp as included with the original packet that you're acking, and likewise the seqno field is the seqno of the packet you're acking, not your own seqno, and you do not increment your own sequence number. ACKing is based on the sequence number.

See iax.h for a description of the frame formats.

IAX internal frames use the AST_FRAME_IAX type. The subclass of these frames is the IAX control number, as seen in iax.h. The first frame sent must be an AST_FRAME_IAX with the control AST_IAX_CONTROL_NEW.

The AST_IAX_CONTROL_NEW establishes a new connection.

The first frame sent MUST be an AST_CONTROL_NEW to start a connection.

IAX connnections may require authentication using either simple plaintext passwords or an md5 challenge/response pair.

==Example iax.conf==
----
<pre>
; Inter-Asterisk eXchange driver definition
;
; This configuration is re-read at reload
; or with the CLI command
; reload chan_iax2.so
;
; General settings, like port number to bind to, and
; an option address (the default is to bind to all
; local addresses).
;
[general]
;bindport=4569 ; bindport and bindaddr may be specified
; ; NOTE: bindport must be specified BEFORE bindaddr
; ; or may be specified on a specific bindaddr if followed by
; ; colon and port (e.g. bindaddr=192.168.0.1:4569)
;bindaddr=192.168.0.1 ; more than once to bind to multiple
; ; addresses, but the first will be the
; ; default
;
; Set iaxcompat to yes if you plan to use layered switches or
; some other scenario which may cause some delay when doing a
; lookup in the dialplan. It incurs a small performance hit to
; enable it. This option causes Asterisk to spawn a separate thread
; when it receives an IAX DPREQ (Dialplan Request) instead of
; blocking while it waits for a response.
;
;iaxcompat=yes
;
; Disable UDP checksums (if nochecksums is set, then no checkums will
; be calculated/checked on systems supporting this feature)
;
;nochecksums=no
;
;
; For increased security against brute force password attacks
; enable "delayreject" which will delay the sending of authentication
; reject for REGREQ or AUTHREP if there is a password.
;
;delayreject=yes
;
; You may specify a global default AMA flag for iaxtel calls. It must be
; one of 'default', 'omit', 'billing', or 'documentation'. These flags
; are used in the generation of call detail records.
;
;amaflags=default
;
; You may specify a default account for Call Detail Records in addition
; to specifying on a per-user basis
;
;accountcode=lss0101
;
; You may specify a global default language for users.
; Can be specified also on a per-user basis
; If omitted, will fallback to english
;
;language=en
;
; Specify bandwidth of low, medium, or high to control which codecs are used
; in general.
;
bandwidth=low
;
; You can also fine tune codecs here using "allow" and "disallow" clauses
; with specific codecs. Use "all" to represent all formats.
;
;allow=all ; same as bandwidth=high
;disallow=g723.1 ; Hm... Proprietary, don't use it...
disallow=lpc10 ; Icky sound quality... Mr. Roboto.
;allow=gsm ; Always allow GSM, it's cool :)
;

; You can adjust several parameters relating to the jitter buffer.
; The jitter buffer's function is to compensate for varying
; network delay.
;
; There are presently two jitterbuffer implementations available for Asterisk
; and chan_iax2; the classic and the new, channel/application independent
; implementation. These are controlled at compile-time. The new jitterbuffer
; additionally has support for PLC which greatly improves quality as the
; jitterbuffer adapts size, and in compensating for lost packets.
;
; All the jitter buffer settings except dropcount are in milliseconds.
; The jitter buffer works for INCOMING audio - the outbound audio
; will be dejittered by the jitter buffer at the other end.
;
; jitterbuffer=yes|no: global default as to whether you want
; the jitter buffer at all.
;
; forcejitterbuffer=yes|no: in the ideal world, when we bridge VoIP channels
; we don't want to do jitterbuffering on the switch, since the endpoints
; can each handle this. However, some endpoints may have poor jitterbuffers
; themselves, so this option will force * to always jitterbuffer, even in this
; case.
; [This option presently applies only to the new jitterbuffer implementation]
;
; dropcount: the jitter buffer is sized such that no more than "dropcount"
; frames would have been "too late" over the last 2 seconds.
; Set to a small number. "3" represents 1.5% of frames dropped
; [This option is not applicable to, and ignored by the new jitterbuffer implementation]
;
; maxjitterbuffer: a maximum size for the jitter buffer.
; Setting a reasonable maximum here will prevent the call delay
; from rising to silly values in extreme situations; you'll hear
; SOMETHING, even though it will be jittery.
;
; resyncthreshold: when the jitterbuffer notices a significant change in delay
; that continues over a few frames, it will resync, assuming that the change in
; delay was caused by a timestamping mix-up. The threshold for noticing a
; change in delay is measured as twice the measured jitter plus this resync
; threshold.
; Resyncing can be disabled by setting this parameter to -1.
; [This option presently applies only to the new jitterbuffer implementation]
;
; maxjitterinterps: the maximum number of interpolation frames the jitterbuffer
; should return in a row. Since some clients do not send CNG/DTX frames to
; indicate silence, the jitterbuffer will assume silence has begun after
; returning this many interpolations. This prevents interpolating throughout
; a long silence.
; [This option presently applies only to the new jitterbuffer implementation]
;
; maxexcessbuffer: If conditions improve after a period of high jitter,
; the jitter buffer can end up bigger than necessary. If it ends up
; more than "maxexcessbuffer" bigger than needed, Asterisk will start
; gradually decreasing the amount of jitter buffering.
; [This option is not applicable to, and ignored by the new jitterbuffer implementation]
;
; minexcessbuffer: Sets a desired mimimum amount of headroom in
; the jitter buffer. If Asterisk has less headroom than this, then
; it will start gradually increasing the amount of jitter buffering.
; [This option is not applicable to, and ignored by the new jitterbuffer implementation]
;
; jittershrinkrate: when the jitter buffer is being gradually shrunk
; (or enlarged), how many millisecs shall we take off per 20ms frame
; received? Use a small number, or you will be able to hear it
; changing. An example: if you set this to 2, then the jitter buffer
; size will change by 100 millisecs per second.
; [This option is not applicable to, and ignored by the new jitterbuffer implementation]

jitterbuffer=no
forcejitterbuffer=no
;dropcount=2
;maxjitterbuffer=1000
;maxjitterinterps=10
;resyncthreshold=1000
;maxexcessbuffer=80
;minexcessbuffer=10
;jittershrinkrate=1

;trunkfreq=20 ; How frequently to send trunk msgs (in ms)

; Should we send timestamps for the individual sub-frames within trunk frames?
; There is a small bandwidth use for these (less than 1kbps/call), but they
; ensure that frame timestamps get sent end-to-end properly. If both ends of
; all your trunks go directly to TDM, _and_ your trunkfreq equals the frame
; length for your codecs, you can probably suppress these. The receiver must
; also support this feature, although they do not also need to have it enabled.
;
; trunktimestamps=yes
;
; Minimum and maximum amounts of time that IAX peers can request as
; a registration expiration interval (in seconds).
; minregexpire = 60
; maxregexpire = 60
;
; We can register with another IAX server to let him know where we are
; in case we have a dynamic IP address for example
;
; Register with tormenta using username marko and password secretpass
;
;register => marko:secretpass@tormenta.linux-support.net
;
; Register joe at remote host with no password
;
;register => joe@remotehost:5656
;
; Register marko at tormenta.linux-support.net using RSA key "torkey"
;
;register => marko:[torkey]@tormenta.linux-support.net
;
; Sample Registration for iaxtel
;
; Visit http://www.iaxtel.com to register with iaxtel. Replace "user"
; and "pass" with your username and password for iaxtel. Incoming
; calls arrive at the "s" extension of "default" context.
;
;register => user:pass@iaxtel.com
;
; Sample Registration for IAX + FWD
;
; To register using IAX with FWD, it must be enabled by visiting the URL
; http://www.fwdnet.net/index.php?section_id=112
;
; Note that you need an extension in you default context which matches
; your free world dialup number. Please replace "FWDNumber" with your
; FWD number and "passwd" with your password.
;
;register => FWDNumber:passwd@iax.fwdnet.net
;
;
; You can disable authentication debugging to reduce the amount of
; debugging traffic.
;
;authdebug=no
;
; Finally, you can set values for your TOS bits to help improve
; performance. Valid values are:
; lowdelay -- Minimize delay
; throughput -- Maximize throughput
; reliability -- Maximize reliability
; mincost -- Minimize cost
; none -- No flags
;
tos=lowdelay
;
; If mailboxdetail is set to "yes", the user receives
; the actual new/old message counts, not just a yes/no
; as to whether they have messages. this can be set on
; a per-peer basis as well
;
;mailboxdetail=yes
;
; If regcontext is specified, Asterisk will dynamically create and destroy
; a NoOp priority 1 extension for a given peer who registers or unregisters
; with us. The actual extension is the 'regexten' parameter of the registering
; peer or its name if 'regexten' is not provided. More than one regexten
; may be supplied if they are separated by '&'. Patterns may be used in
; regexten.
;
;regcontext=iaxregistrations
;
; If we don't get ACK to our NEW within 2000ms, and autokill is set to yes,
; then we cancel the whole thing (that's enough time for one retransmission
; only). This is used to keep things from stalling for a long time for a host
; that is not available, but would be ill advised for bad connections. In
; addition to 'yes' or 'no' you can also specify a number of milliseconds.
; See 'qualify' for individual peers to turn on for just a specific peer.
;
autokill=yes
;
; codecpriority controls the codec negotiation of an inbound IAX call.
; This option is inherited to all user entities. It can also be defined
; in each user entity separately which will override the setting in general.
;
; The valid values are:
;
; caller - Consider the callers preferred order ahead of the host's.
; host - Consider the host's preferred order ahead of the caller's.
; disabled - Disable the consideration of codec preference altogether.
; (this is the original behaviour before preferences were added)
; reqonly - Same as disabled, only do not consider capabilities if
; the requested format is not available the call will only
; be accepted if the requested format is available.
;
; The default value is 'host'
;
;codecpriority=host

;rtcachefriends=yes ; Cache realtime friends by adding them to the internal list
; just like friends added from the config file only on a
; as-needed basis? (yes|no)

;rtupdate=yes ; Send registry updates to database using realtime? (yes|no)
; If set to yes, when a IAX2 peer registers successfully, the ip address,
; the origination port, the registration period, and the username of
; the peer will be set to database via realtime. If not present, defaults to 'yes'.

;rtautoclear=yes ; Auto-Expire friends created on the fly on the same schedule
; as if it had just registered? (yes|no|<seconds>)
; If set to yes, when the registration expires, the friend will vanish from
; the configuration until requested again. If set to an integer,
; friends expire within this number of seconds instead of the
; registration interval.

;rtignoreregexpire=yes ; When reading a peer from Realtime, if the peer's registration
; has expired based on its registration interval, used the stored
; address information regardless. (yes|no)

; Guest sections for unauthenticated connection attempts. Just specify an
; empty secret, or provide no secret section.
;
[guest]
type=user
context=default
callerid="Guest IAX User"

;
; Trust Caller*ID Coming from iaxtel.com
;
[iaxtel]
type=user
context=default
auth=rsa
inkeys=iaxtel

;
; Trust Caller*ID Coming from iax.fwdnet.net
;
[iaxfwd]
type=user
context=default
auth=rsa
inkeys=freeworlddialup

;
; Trust callerid delivered over DUNDi/e164
;
;
;[dundi]
;type=user
;dbsecret=dundi/secret
;context=dundi-e164-local

;
; Further user sections may be added, specifying a context and a secret used
; for connections with that given authentication name. Limited IP based
; access control is allowed by use of "allow" and "deny" keywords. Multiple
; rules are permitted. Multiple permitted contexts may be specified, in
; which case the first will be the default. You can also override caller*ID
; so that when you receive a call you set the Caller*ID to be what you want
; instead of trusting what the remote user provides
;
; There are three authentication methods that are supported: md5, plaintext,
; and rsa. The least secure is "plaintext", which sends passwords cleartext
; across the net. "md5" uses a challenge/response md5 sum arrangement, but
; still requires both ends have plain text access to the secret. "rsa" allows
; unidirectional secret knowledge through public/private keys. If "rsa"
; authentication is used, "inkeys" is a list of acceptable public keys on the
; local system that can be used to authenticate the remote peer, separated by
; the ":" character. "outkey" is a single, private key to use to authenticate
; to the other side. Public keys are named /var/lib/asterisk/keys/<name>.pub
; while private keys are named /var/lib/asterisk/keys/<name>.key. Private
; keys should always be 3DES encrypted.
;
;
; NOTE: All hostnames and IP addresses in this file are for example purposes
; only; you should not expect any of them to actually be available for
; your use.
;
;
;[markster]
;type=user
;context=default
;context=local
;auth=md5,plaintext,rsa
;secret=markpasswd
;setvar=foo=bar
;dbsecret=mysecrets/place ; Secrets can be stored in astdb, too
;notransfer=yes ; Disable IAX native transfer
;jitterbuffer=yes ; Override global setting an enable jitter buffer
; ; for this user
;maxauthreq=10 ; Set maximum number of outstanding AUTHREQs waiting for replies. Any further authentication attempts will be blocked
; ; if this limit is reached until they expire or a reply is received.
;callerid="Mark Spencer" <(256) 428-6275>
;deny=0.0.0.0/0.0.0.0
;accountcode=markster0101
;permit=209.16.236.73/255.255.255.0
;language=en ; Use english as default language
;
; Peers may also be specified, with a secret and
; a remote hostname.
;
[demo]
type=peer
username=asterisk
secret=supersecret
host=216.207.245.47
;sendani=no
;host=asterisk.linux-support.net
;port=5036
;mask=255.255.255.255
;qualify=yes ; Make sure this peer is alive
;qualifysmoothing = yes ; use an average of the last two PONG
; results to reduce falsely detected LAGGED hosts
; Default: Off
;qualifyfreqok = 60000 ; how frequently to ping the peer when
; everything seems to be ok, in milliseconds
;qualifyfreqnotok = 10000 ; how frequently to ping the peer when it's
; either LAGGED or UNAVAILABLE, in milliseconds
;jitterbuffer=no ; Turn off jitter buffer for this peer

;
; Peers can remotely register as well, so that they can be mobile. Default
; IP's can also optionally be given but are not required. Caller*ID can be
; suggested to the other side as well if it is for example a phone instead of
; another PBX.
;

;[dynamichost]
;host=dynamic
;secret=mysecret
;mailbox=1234 ; Notify about mailbox 1234
;inkeys=key1:key2
;peercontext=local ; Default context to request for calls to peer
;defaultip=216.207.245.34
;callerid="Some Host" <(256) 428-6011>
;

;
;[biggateway]
;type=peer
;host=192.168.0.1
;context=*
;secret=myscret
;trunk=yes ; Use IAX2 trunking with this host
;timezone=America/New_York ; Set a timezone for the date/time IE
;

;
; Friends are a short cut for creating a user and
; a peer with the same values.
;
;[marko]
;type=friend
;host=dynamic
;regexten=1234
;secret=moofoo ; Multiple secrets may be specified. For a "user", all
;secret=foomoo ; specified entries will be accepted as valid. For a "peer",
;secret=shazbot ; only the last specified secret will be used.
;context=default
;permit=0.0.0.0/0.0.0.0
</pre>

H.323

2007-09-04T13:29:51Z

Summary:

The Asterisk PBX supports H.323 via two totally separate channel drivers.

You can find more information Asterisk's native H.323 support in /path/to/asterisk/channels/h323/README or you can download a third party driver at http://www.inaccessnetworks.com/projects/asterisk-oh323

Asterisk's native H.323 is supported and maintained by Jeremy McNamara (JerJer in irc). Support for the third party H.323 driver is supplied by in AccessNetworks.

If you have trouble with either driver you should direct your debug and comments to the appropriate party, making sure to be specific in exactly which H.323 driver you are running.

Please, read all supplied documentation before contacting either party for support. Many issues can be quickly resolved by simply following the instructions that are provided.

Features

2007-09-04T13:29:15Z

Summary:

==Example==
; features.conf
----
<pre>
;
; Sample Parking configuration
;

[general]
parkext => 700 ; What extension to dial to park
parkpos => 701-720 ; What extensions to park calls on. These needs to be
; numeric, as Asterisk starts from the start position
; and increments with one for the next parked call.
context => parkedcalls ; Which context parked calls are in
;parkingtime => 45 ; Number of seconds a call can be parked for
; (default is 45 seconds)
;transferdigittimeout => 3 ; Number of seconds to wait between digits when transferring a call
;courtesytone = beep ; Sound file to play to the parked caller
; when someone dials a parked call
;xfersound = beep ; to indicate an attended transfer is complete
;xferfailsound = beeperr ; to indicate a failed transfer
;adsipark = yes ; if you want ADSI parking announcements
;findslot => next ; Continue to the 'next' free parking space.
; Defaults to 'first' available
pickupexten = *8 ; Configure the pickup extension. Default is *8
;featuredigittimeout = 500 ; Max time (ms) between digits for
; feature activation. Default is 500

[featuremap]
;blindxfer => #1 ; Blind transfer
;disconnect => *0 ; Disconnect
;automon => *1 ; One Touch Record
;atxfer => *2 ; Attended transfer

[applicationmap]
; Note that the DYNAMIC_FEATURES channel variable must be set to use the features
; defined here. The value of DYNAMIC_FEATURES should be the names of the features
; to allow the channel to use separated by '#'. For example:
; Set(DYNAMIC_FEATURES=myfeature1#myfeature2#myfeature3)
;
;testfeature => #9,callee,Playback,tt-monkeys ;Play tt-monkeys to
;callee if #9 was pressed

</pre>

Externalivr

2007-09-04T13:28:46Z

Summary:

If you load app_externalivr.so in your Asterisk instance, you will have an ExternalIVR() application available in your dialplan. This application implements a simple protocol for bidirectional communication with an external process, while simultaneous playing audio files to the connected channel (without interruption or blocking).

The arguments to ExternalIVR() consist of the command to execute and any arguments to pass to it, the same as the System() application accepts. The external command will be executed in a child process, with its standard file handles connected to the Asterisk process as follows:

stdin (0) - DTMF and hangup events will be received on this handle
stdout (1) - Playback and hangup commands can be sent on this handle
stderr (2) - Error messages can be sent on this handle

The application will also create an audio generator to play audio to the channel, and will start playing silence. When your application wants to send audio to the channel, it can send a command (see below) to add file(s) to the generator's playlist. The generator will then work its way through the list, playing each file in turn until it either runs out of files to play, the channel is hung up, or a command is received to clear the list and start with a new file. At any time, more files can be added to the list and the generator will play them in sequence.

While the generator is playing audio (or silence), any DTMF events received on the channel will be sent to the child process (see below). Note that this can happen at any time, since the generator, the child process and the channel thread are all executing independently. It is very important that your external application be ready to receive events from Asterisk at all times (without blocking), or you could cause the channel to become non-responsive.

If the child process dies, ExternalIVR() will notice this and hang up the channel immediately (and also send a message to the log).

DTMF (and other) events
-----------------------

All events will be newline-terminated strings.

Events send to the child's stdin will be in the following format:

tag,timestamp[,data]

The tag can be one of the following characters:
<pre>
0-9: DTMF event for keys 0 through 9
A-D: DTMF event for keys A through D
*: DTMF event for key *
#: DTMF event for key #
H: the channel was hung up by the connected party
Z: the previous command was unable to be executed (file does not exist, etc.)
T: the play list was interrupted (see below)
D: a file was dropped from the play list due to interruption (the data element will be the dropped file name)
F: a file has finished playing (the data element will be the file name)
</pre>
The timestamp will be 10 digits long, and will be a decimal
representation of a standard Unix epoch-based timestamp.

Commands
----

All commands must be newline-terminated strings.

The child process can send commands on stdout in the following formats:

S,filename
A,filename
H,message
O,option

The 'S' command checks to see if there is a playable audio file with the specified name, and if so, clear's the generator's playlist and places the file onto the list. Note that the playability check does not take into account transcoding requirements, so it is possible for the file to not be played even though it was found. If the file cannot be found, a 'Z' event (see above) will be sent to the child. If the generator is not currently playing silence, then T and D events will be sent to the child to signal the playlist interruption and notify it of the files that will not be played.

The 'A' command checks to see if there is a playable audio file with the specified name, and if so, adds it to the generator's playlist. The same playability and exception rules apply as for the 'S' command.

The 'H' command stops the generator and hangs up the channel, and logs the supplied message to the Asterisk log.

The 'O' command allows the child to set/clear options in the
ExternalIVR() application. The supported options are:
autoclear/noautoclear:
Automatically interrupt and clear the playlist upon reception
of DTMF input.

Errors
------

Any newline-terminated output generated by the child process on its
stderr handle will be copied into the Asterisk log.

Extensions

2007-09-04T13:28:17Z

Summary: /* Info about application 'Dial' */

The Asterisk dialplan is divided into contexts. A context is simply a group of extensions. For each "line" that should be able to be called, an extension must be added to a context. Then, you configure the calling "line" to have access to this context.

If you change the dialplan, you can use the Asterisk CLI command "extensions reload" to load the new dialplan without disrupting service in your PBX.

Extensions are routed according to priority and may be based on any set of characters (a-z), digits, #, and *. Please note that when matching a pattern, "N", "X", and "Z" are interpreted as classes of digits.

For each extension, several actions may be listed and must be given a unique priority. When each action completes, the call continunes at the next priority (except for some modules which use explicitly GOTO's).

When each action completes, it generally moves to the next priority (except for some modules which use explicitly GOTO's.

Extensions frequently have data they pass to the executing application (most frequently a string). You can see the available dialplan applications by entering the "show applications" command in the CLI.

In this version of Asterisk, dialplan functions are added. These can be used as arguments to any application. For a list of the installed functions in your Asterisk, use the "show functions" command.

==Special extensions==

There are some extensions with important meanings:

s: What to do when an extension context is entered (unless
overridden by the low level channel interface)
This is used in macros, and some special cases.
"s" is not a generic catch-all wildcard extension.
i: What to do if an invalid extension is entered
h: The hangup extension, executed at hangup
t: What to do if nothing is entered in the requisite amount of time.
T: This is the extension that is executed when the 'absolute'
timeout is reached. See "show function TIMEOUT" for more information on setting timeouts.

And finally, the extension context "default" is used when either a) an extension context is deleted while an extension is in use, or b) a specific starting extension handler has not been defined (unless overridden by the low level channel interface).

== Info about application 'Dial' ==
; Synopsis : Place a call and connect to the current channel

; Description : Dial(Technology/resource[&Tech2/resource2...][|timeout][|options][|URL]): This application will place calls to one or more specified channels. As soon as one of the requested channels answers, the originating channel will be answered, if it has not already been answered. These two channels will then be active in a bridged call. All other channels that were requested will then be hung up. Unless there is a timeout specified, the Dial application will wait indefinitely until one of the called channels answers, the user hangs up, or if all of the called channels are busy or unavailable. Dialplan executing will continue if no requested channels can be called, or if the timeout expires.

This application sets the following channel variables upon completion:
DIALEDTIME - This is the time from dialing a channel until when it
is disconnected.
ANSWEREDTIME - This is the amount of time for actual call.
DIALSTATUS - This is the status of the call:
CHANUNAVAIL | CONGESTION | NOANSWER | BUSY | ANSWER | CANCEL
DONTCALL | TORTURE | INVALIDARGS

For the Privacy and Screening Modes, the DIALSTATUS variable will be set to DONTCALL if the called party chooses to send the calling party to the 'Go Away' script. The DIALSTATUS variable will be set to TORTURE if the called party wants to send the caller to the 'torture' script. This application will report normal termination if the originating channel hangs up, or if the call is bridged and either of the parties in the bridge ends the call. The optional URL will be sent to the called party if the channel supports it. If the OUTBOUND_GROUP variable is set, all peer channels created by this application will be put into that group (as in Set(GROUP()=...). If the OUTBOUND_GROUP_ONCE variable is set, all peer channels created by this application will be put into that group (as in Set(GROUP()=...). Unlike OUTBOUND_GROUP, however, the variable will be unset after use.

Options:
A(x) - Play an announcement to the called party, using 'x' as the file.
C - Reset the CDR for this call.
d - Allow the calling user to dial a 1 digit extension while waiting for
a call to be answered. Exit to that extension if it exists in the
current context, or the context defined in the EXITCONTEXT variable,
if it exists.
D([called][:calling]) - Send the specified DTMF strings *after* the called
party has answered, but before the call gets bridged. The 'called'
DTMF string is sent to the called party, and the 'calling' DTMF
string is sent to the calling party. Both parameters can be used
alone.
f - Force the callerid of the *calling* channel to be set as the
extension associated with the channel using a dialplan 'hint'.
For example, some PSTNs do not allow CallerID to be set to anything
other than the number assigned to the caller.
g - Proceed with dialplan execution at the current extension if the
destination channel hangs up.
G(context^exten^pri) - If the call is answered, transfer the calling party to
the specified priority and the called party to the specified priority+1.
Optionally, an extension, or extension and context may be specified.
Otherwise, the current extension is used. You cannot use any additional
action post answer options in conjunction with this option.
h - Allow the called party to hang up by sending the '*' DTMF digit.
H - Allow the calling party to hang up by hitting the '*' DTMF digit.
j - Jump to priority n+101 if all of the requested channels were busy.
L(x[:y][:z]) - Limit the call to 'x' ms. Play a warning when 'y' ms are
left. Repeat the warning every 'z' ms. The following special
variables can be used with this option:
* LIMIT_PLAYAUDIO_CALLER yes|no (default yes)
Play sounds to the caller.
* LIMIT_PLAYAUDIO_CALLEE yes|no
Play sounds to the callee.
* LIMIT_TIMEOUT_FILE File to play when time is up.
* LIMIT_CONNECT_FILE File to play when call begins.
* LIMIT_WARNING_FILE File to play as warning if 'y' is defined.
The default is to say the time remaining.
m([class]) - Provide hold music to the calling party until a requested
channel answers. A specific MusicOnHold class can be
specified.
M(x[^arg]) - Execute the Macro for the *called* channel before connecting
to the calling channel. Arguments can be specified to the Macro
using '^' as a delimeter. The Macro can set the variable
MACRO_RESULT to specify the following actions after the Macro is
finished executing.
* ABORT Hangup both legs of the call.
* CONGESTION Behave as if line congestion was encountered.
* BUSY Behave as if a busy signal was encountered. This will also
have the application jump to priority n+101 if the
'j' option is set.
* CONTINUE Hangup the called party and allow the calling party
to continue dialplan execution at the next priority.
* GOTO:<context>^<exten>^<priority> - Transfer the call to the
specified priority. Optionally, an extension, or
extension and priority can be specified.
You cannot use any additional action post answer options in conjunction
with this option.
n - This option is a modifier for the screen/privacy mode. It specifies
that no introductions are to be saved in the priv-callerintros
directory.
N - This option is a modifier for the screen/privacy mode. It specifies
that if callerID is present, do not screen the call.
o - Specify that the CallerID that was present on the *calling* channel
be set as the CallerID on the *called* channel. This was the
behavior of Asterisk 1.0 and earlier.
p - This option enables screening mode. This is basically Privacy mode
without memory.
P([x]) - Enable privacy mode. Use 'x' as the family/key in the database if
it is provided. The current extension is used if a database
family/key is not specified.
r - Indicate ringing to the calling party. Pass no audio to the calling
party until the called channel has answered.
S(x) - Hang up the call after 'x' seconds *after* the called party has
answered the call.
t - Allow the called party to transfer the calling party by sending the
DTMF sequence defined in features.conf.
T - Allow the calling party to transfer the called party by sending the
DTMF sequence defined in features.conf.
w - Allow the called party to enable recording of the call by sending
the DTMF sequence defined for one-touch recording in features.conf.
W - Allow the calling party to enable recording of the call by sending
the DTMF sequence defined for one-touch recording in features.conf.

sample dial plan. extensions.conf
<pre>
;
; Static extension configuration file, used by
; the pbx_config module. This is where you configure all your
; inbound and outbound calls in Asterisk.
;
; This configuration file is reloaded
; - With the "extensions reload" command in the CLI
; - With the "reload" command (that reloads everything) in the CLI

;
; The "General" category is for certain variables.
;
[general]
;
; If static is set to no, or omitted, then the pbx_config will rewrite
; this file when extensions are modified. Remember that all comments
; made in the file will be lost when that happens.
;
; XXX Not yet implemented XXX
;
static=yes
;
; if static=yes and writeprotect=no, you can save dialplan by
; CLI command 'save dialplan' too
;
writeprotect=no
;
; If autofallthrough is set, then if an extension runs out of
; things to do, it will terminate the call with BUSY, CONGESTION
; or HANGUP depending on Asterisk's best guess (strongly recommended).
;
; If autofallthrough is not set, then if an extension runs out of
; things to do, asterisk will wait for a new extension to be dialed
; (this is the original behavior of Asterisk 1.0 and earlier).
;
autofallthrough=yes
;
; If clearglobalvars is set, global variables will be cleared
; and reparsed on an extensions reload, or Asterisk reload.
;
; If clearglobalvars is not set, then global variables will persist
; through reloads, and even if deleted from the extensions.conf or
; one of its included files, will remain set to the previous value.
;
clearglobalvars=no
;
; If priorityjumping is set to 'yes', then applications that support
; 'jumping' to a different priority based on the result of their operations
; will do so (this is backwards compatible behavior with pre-1.2 releases
; of Asterisk). Individual applications can also be requested to do this
; by passing a 'j' option in their arguments.
;
priorityjumping=no
;
; You can include other config files, use the #include command
; (without the ';'). Note that this is different from the "include" command
; that includes contexts within other contexts. The #include command works
; in all asterisk configuration files.
;#include "filename.conf"

; The "Globals" category contains global variables that can be referenced
; in the dialplan with ${VARIABLE} or ${ENV(VARIABLE)} for Environmental
; variables,
; ${${VARIABLE}} or ${text${VARIABLE}} or any hybrid
;
[globals]
CONSOLE=Console/dsp ; Console interface for demo
;CONSOLE=Zap/1
;CONSOLE=Phone/phone0
IAXINFO=guest ; IAXtel username/password
;IAXINFO=myuser:mypass
TRUNK=Zap/g2 ; Trunk interface
;
; Note the 'g2' in the TRUNK variable above. It specifies which group (defined
; in zapata.conf) to dial, i.e. group 2, and how to choose a channel to use in
; the specified group. The four possible options are:
;
; g: select the lowest-numbered non-busy Zap channel
; (aka. ascending sequential hunt group).
; G: select the highest-numbered non-busy Zap channel
; (aka. descending sequential hunt group).
; r: use a round-robin search, starting at the next highest channel than last
; time (aka. ascending rotary hunt group).
; R: use a round-robin search, starting at the next lowest channel than last
; time (aka. descending rotary hunt group).
;
TRUNKMSD=1 ; MSD digits to strip (usually 1 or 0)
;TRUNK=IAX2/user:pass@provider

;
; Any category other than "General" and "Globals" represent
; extension contexts, which are collections of extensions.
;
; Extension names may be numbers, letters, or combinations
; thereof. If an extension name is prefixed by a '_'
; character, it is interpreted as a pattern rather than a
; literal. In patterns, some characters have special meanings:
;
; X - any digit from 0-9
; Z - any digit from 1-9
; N - any digit from 2-9
; [1235-9] - any digit in the brackets (in this example, 1,2,3,5,6,7,8,9)
; . - wildcard, matches anything remaining (e.g. _9011. matches
; anything starting with 9011 excluding 9011 itself)
; ! - wildcard, causes the matching process to complete as soon as
; it can unambiguously determine that no other matches are possible
;
; For example the extension _NXXXXXX would match normal 7 digit dialings,
; while _1NXXNXXXXXX would represent an area code plus phone number
; preceded by a one.
;
; Each step of an extension is ordered by priority, which must
; always start with 1 to be considered a valid extension. The priority
; "next" or "n" means the previous priority plus one, regardless of whether
; the previous priority was associated with the current extension or not.
; The priority "same" or "s" means the same as the previously specified
; priority, again regardless of whether the previous entry was for the
; same extension. Priorities may be immediately followed by a plus sign
; and another integer to add that amount (most useful with 's' or 'n').
; Priorities may then also have an alias, or label, in
; parenthesis after their name which can be used in goto situations
;
; Contexts contain several lines, one for each step of each
; extension, which can take one of two forms as listed below,
; with the first form being preferred. One may include another
; context in the current one as well, optionally with a
; date and time. Included contexts are included in the order
; they are listed.
;
;[context]
;exten => someexten,priority[+offset][(alias)],application(arg1,arg2,...)
;exten => someexten,priority[+offset][(alias)],application,arg1|arg2...
;
; Timing list for includes is
;
; <time range>|<days of week>|<days of month>|<months>
;
;include => daytime|9:00-17:00|mon-fri|*|*
;
; ignorepat can be used to instruct drivers to not cancel dialtone upon
; receipt of a particular pattern. The most commonly used example is
; of course '9' like this:
;
;ignorepat => 9
;
; so that dialtone remains even after dialing a 9.
;

;
; Sample entries for extensions.conf
;
;
[dundi-e164-canonical]
;
; List canonical entries here
;
;exten => 12564286000,1,Macro(stdexten,6000,IAX2/foo)
;exten => _125642860XX,1,Dial(IAX2/otherbox/${EXTEN:7})

[dundi-e164-customers]
;
; If you are an ITSP or Reseller, list your customers here.
;
;exten => _12564286000,1,Dial(SIP/customer1)
;exten => _12564286001,1,Dial(IAX2/customer2)

[dundi-e164-via-pstn]
;
; If you are freely delivering calls to the PSTN, list them here
;
;exten => _1256428XXXX,1,Dial(Zap/g2/${EXTEN:7}) ; Expose all of 256-428
;exten => _1256325XXXX,1,Dial(Zap/g2/${EXTEN:7}) ; Ditto for 256-325

[dundi-e164-local]
;
; Context to put your dundi IAX2 or SIP user in for
; full access
;
include => dundi-e164-canonical
include => dundi-e164-customers
include => dundi-e164-via-pstn

[dundi-e164-switch]
;
; Just a wrapper for the switch
;
switch => DUNDi/e164

[dundi-e164-lookup]
;
; Locally to lookup, try looking for a local E.164 solution
; then try DUNDi if we don't have one.
;
include => dundi-e164-local
include => dundi-e164-switch
;
; DUNDi can also be implemented as a Macro instead of using
; the Local channel driver.
;
[macro-dundi-e164]
;
; ARG1 is the extension to Dial
;
exten => s,1,Goto(${ARG1},1)
include => dundi-e164-lookup

;
; Here are the entries you need to participate in the IAXTEL
; call routing system. Most IAXTEL numbers begin with 1-700, but
; there are exceptions. For more information, and to sign
; up, please go to www.gnophone.com or www.iaxtel.com
;
[iaxtel700]
exten => _91700XXXXXXX,1,Dial(IAX2/${IAXINFO}@iaxtel.com/${EXTEN:1}@iaxtel)

;
; The SWITCH statement permits a server to share the dialplan with
; another server. Use with care: Reciprocal switch statements are not
; allowed (e.g. both A -> B and B -> A), and the switched server needs
; to be on-line or else dialing can be severly delayed.
;
[iaxprovider]
;switch => IAX2/user:[key]@myserver/mycontext

[trunkint]
;
; International long distance through trunk
;
exten => _9011.,1,Macro(dundi-e164,${EXTEN:4})
exten => _9011.,n,Dial(${TRUNK}/${EXTEN:${TRUNKMSD}})

[trunkld]
;
; Long distance context accessed through trunk
;
exten => _91NXXNXXXXXX,1,Macro(dundi-e164,${EXTEN:1})
exten => _91NXXNXXXXXX,n,Dial(${TRUNK}/${EXTEN:${TRUNKMSD}})

[trunklocal]
;
; Local seven-digit dialing accessed through trunk interface
;
exten => _9NXXXXXX,1,Dial(${TRUNK}/${EXTEN:${TRUNKMSD}})

[trunktollfree]
;
; Long distance context accessed through trunk interface
;
exten => _91800NXXXXXX,1,Dial(${TRUNK}/${EXTEN:${TRUNKMSD}})
exten => _91888NXXXXXX,1,Dial(${TRUNK}/${EXTEN:${TRUNKMSD}})
exten => _91877NXXXXXX,1,Dial(${TRUNK}/${EXTEN:${TRUNKMSD}})
exten => _91866NXXXXXX,1,Dial(${TRUNK}/${EXTEN:${TRUNKMSD}})

[international]
;
; Master context for international long distance
;
ignorepat => 9
include => longdistance
include => trunkint

[longdistance]
;
; Master context for long distance
;
ignorepat => 9
include => local
include => trunkld

[local]
;
; Master context for local, toll-free, and iaxtel calls only
;
ignorepat => 9
include => default
include => parkedcalls
include => trunklocal
include => iaxtel700
include => trunktollfree
include => iaxprovider
;
; You can use an alternative switch type as well, to resolve
; extensions that are not known here, for example with remote
; IAX switching you transparently get access to the remote
; Asterisk PBX
;
; switch => IAX2/user:password@bigserver/local
;
; An "lswitch" is like a switch but is literal, in that
; variable substitution is not performed at load time
; but is passed to the switch directly (presumably to
; be substituted in the switch routine itself)
;
; lswitch => Loopback/12${EXTEN}@othercontext
;
; An "eswitch" is like a switch but the evaluation of
; variable substitution is performed at runtime before
; being passed to the switch routine.
;
; eswitch => IAX2/context@${CURSERVER}

[macro-stdexten];
;
; Standard extension macro:
; ${ARG1} - Extension (we could have used ${MACRO_EXTEN} here as well
; ${ARG2} - Device(s) to ring
;
exten => s,1,Dial(${ARG2},20) ; Ring the interface, 20 seconds maximum
exten => s,2,Goto(s-${DIALSTATUS},1) ; Jump based on status (NOANSWER,BUSY,CHANUNAVAIL,CONGESTION,ANSWER)

exten => s-NOANSWER,1,Voicemail(u${ARG1}) ; If unavailable, send to voicemail w/ unavail announce
exten => s-NOANSWER,2,Goto(default,s,1) ; If they press #, return to start

exten => s-BUSY,1,Voicemail(b${ARG1}) ; If busy, send to voicemail w/ busy announce
exten => s-BUSY,2,Goto(default,s,1) ; If they press #, return to start
exten => _s-.,1,Goto(s-NOANSWER,1) ; Treat anything else as no answer

exten => a,1,VoicemailMain(${ARG1}) ; If they press *, send the user into VoicemailMain

[macro-stdPrivacyexten];
;
; Standard extension macro:
; ${ARG1} - Extension (we could have used ${MACRO_EXTEN} here as well
; ${ARG2} - Device(s) to ring
; ${ARG3} - Optional DONTCALL context name to jump to (assumes the s,1 extension-priority)
; ${ARG4} - Optional TORTURE context name to jump to (assumes the s,1 extension-priority)`
;
exten => s,1,Dial(${ARG2},20|p) ; Ring the interface, 20 seconds maximum, call screening option (or use P for databased call screening)
exten => s,2,Goto(s-${DIALSTATUS},1) ; Jump based on status (NOANSWER,BUSY,CHANUNAVAIL,CONGESTION,ANSWER)

exten => s-NOANSWER,1,Voicemail(u${ARG1}) ; If unavailable, send to voicemail w/ unavail announce
exten => s-NOANSWER,2,Goto(default,s,1) ; If they press #, return to start

exten => s-BUSY,1,Voicemail(b${ARG1}) ; If busy, send to voicemail w/ busy announce
exten => s-BUSY,2,Goto(default,s,1) ; If they press #, return to start

exten => s-DONTCALL,1,Goto(${ARG3},s,1) ; Callee chose to send this call to a polite "Don't call again" script.

exten => s-TORTURE,1,Goto(${ARG4},s,1) ; Callee chose to send this call to a telemarketer torture script.

exten => _s-.,1,Goto(s-NOANSWER,1) ; Treat anything else as no answer

exten => a,1,VoicemailMain(${ARG1}) ; If they press *, send the user into VoicemailMain

[demo]
;
; We start with what to do when a call first comes in.
;
exten => s,1,Wait,1 ; Wait a second, just for fun
exten => s,n,Answer ; Answer the line
exten => s,n,Set(TIMEOUT(digit)=5) ; Set Digit Timeout to 5 seconds
exten => s,n,Set(TIMEOUT(response)=10) ; Set Response Timeout to 10 seconds
exten => s,n(restart),BackGround(demo-congrats) ; Play a congratulatory message
exten => s,n(instruct),BackGround(demo-instruct) ; Play some instructions
exten => s,n,WaitExten ; Wait for an extension to be dialed.

exten => 2,1,BackGround(demo-moreinfo) ; Give some more information.
exten => 2,n,Goto(s,instruct)

exten => 3,1,Set(LANGUAGE()=fr) ; Set language to french
exten => 3,n,Goto(s,restart) ; Start with the congratulations

exten => 1000,1,Goto(default,s,1)
;
; We also create an example user, 1234, who is on the console and has
; voicemail, etc.
;
exten => 1234,1,Playback(transfer,skip) ; "Please hold while..."
; (but skip if channel is not up)
exten => 1234,n,Macro(stdexten,1234,${CONSOLE})

exten => 1235,1,Voicemail(u1234) ; Right to voicemail

exten => 1236,1,Dial(Console/dsp) ; Ring forever
exten => 1236,n,Voicemail(u1234) ; Unless busy

;
; # for when they're done with the demo
;
exten => #,1,Playback(demo-thanks) ; "Thanks for trying the demo"
exten => #,n,Hangup ; Hang them up.

;
; A timeout and "invalid extension rule"
;
exten => t,1,Goto(#,1) ; If they take too long, give up
exten => i,1,Playback(invalid) ; "That's not valid, try again"

;
; Create an extension, 500, for dialing the
; Asterisk demo.
;
exten => 500,1,Playback(demo-abouttotry); Let them know what's going on
exten => 500,n,Dial(IAX2/guest@misery.digium.com/s@default) ; Call the Asterisk demo
exten => 500,n,Playback(demo-nogo) ; Couldn't connect to the demo site
exten => 500,n,Goto(s,6) ; 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
exten => 600,n,Echo ; Do the echo test
exten => 600,n,Playback(demo-echodone) ; Let them know it's over
exten => 600,n,Goto(s,6) ; Start over

;
; Give voicemail at extension 8500
;
exten => 8500,1,VoicemailMain
exten => 8500,n,Goto(s,6)
;
; Here's what a phone entry would look like (IXJ for example)
;
;exten => 1265,1,Dial(Phone/phone0,15)
;exten => 1265,n,Goto(s,5)

;[mainmenu]
;
; Example "main menu" context with submenu
;
;exten => s,1,Answer
;exten => s,n,Background(thanks) ; "Thanks for calling press 1 for sales, 2 for support, ..."
;exten => s,n,WaitExten
;exten => 1,1,Goto(submenu,s,1)
;exten => 2,1,Hangup
;include => default
;
;[submenu]
;exten => s,1,Ringing ; Make them comfortable with 2 seconds of ringback
;exten => s,n,Wait,2
;exten => s,n,Background(submenuopts) ; "Thanks for calling the sales department. Press 1 for steve, 2 for..."
;exten => s,n,WaitExten
;exten => 1,1,Goto(default,steve,1)
;exten => 2,1,Goto(default,mark,2)

[default]
;
; By default we include the demo. In a production system, you
; probably don't want to have the demo there.
;
include => demo

;
; An extension like the one below can be used for FWD, Nikotel, sipgate etc.
; Note that you must have a [sipprovider] section in sip.conf
;
;exten => _41X.,1,Dial(SIP/${EXTEN:2}@sipprovider,,r)

; Real extensions would go here. Generally you want real extensions to be
; 4 or 5 digits long (although there is no such requirement) and start with a
; single digit that is fairly large (like 6 or 7) so that you have plenty of
; room to overlap extensions and menu options without conflict. You can alias
; them with names, too, and use global variables

;exten => 6245,hint,SIP/Grandstream1&SIP/Xlite1,Joe Schmoe ; Channel hints for presence
;exten => 6245,1,Dial(SIP/Grandstream1,20,rt) ; permit transfer
;exten => 6245,n(dial),Dial(${HINT},20,rtT) ; Use hint as listed
;exten => 6245,n,Voicemail(u6245) ; Voicemail (unavailable)
;exten => 6245,s+1,Hangup ; s+1, same as n
;exten => 6245,dial+101,Voicemail(b6245) ; Voicemail (busy)
;exten => 6361,1,Dial(IAX2/JaneDoe,,rm) ; ring without time limit
;exten => 6389,1,Dial(MGCP/aaln/1@192.168.0.14)
;exten => 6394,1,Dial(Local/6275/n) ; this will dial ${MARK}

;exten => 6275,1,Macro(stdexten,6275,${MARK}) ; assuming ${MARK} is something like Zap/2
;exten => mark,1,Goto(6275|1) ; alias mark to 6275
;exten => 6536,1,Macro(stdexten,6236,${WIL}) ; Ditto for wil
;exten => wil,1,Goto(6236|1)
;
; Some other handy things are an extension for checking voicemail via
; voicemailmain
;
;exten => 8500,1,VoicemailMain
;exten => 8500,n,Hangup
;
; Or a conference room (you'll need to edit meetme.conf to enable this room)
;
;exten => 8600,1,Meetme(1234)
;
; Or playing an announcement to the called party, as soon it answers
;
;exten = 8700,1,Dial(${MARK},30,A(/path/to/my/announcemsg))
;
; For more information on applications, just type "show applications" at your
; friendly Asterisk CLI prompt.
;
; 'show application <command>' will show details of how you
; use that particular application in this file, the dial plan.
;
</pre>

Extconfig

2007-09-04T13:21:09Z

Summary:

The Asterisk external configuration engine is the result of work by Anthony Minessale II, Mark Spencer and Constantine Filin.

It is designed to provide a flexible, seamless integration between Asterisk's internal configuration structure and external SQL other other databases (maybe even LDAP one day).

The external configuration engine is the basis for the ARA, the Asterisk Realtime Architecture (see README.realtime for more information).

'''Configuration'''

External configuration is configured in /etc/asterisk/extconfig.conf allowing you to map any configuration file (static mappings) to be pulled from the database, or to map special runtime entries which permit the dynamic creation of objects, entities, peers, etc. without the necessity of a reload.

Generally speaking, the columns in your tables should line up with the fields you would specify in the given entity declaration. If an entry would appear more than once, in the column it should be separated by a semicolon. For example, an entity that looks like:

[foo]
host=dynamic
secret=bar
context=default
context=local

could be stored in a table like this:
<pre>
+------+--------+-------+--------------+----------+-----+-----------+
| name | host | secret| context | ipaddr | port| regseconds|
+------+--------+-------+--------------+----------+-----+-----------+
| foo | dynamic| bar | default;local| 127.0.0.1| 4569| 1096954152|
+------+--------+-------+--------------+----------+-----+-----------+

Note that for use with IAX or SIP, the table will also need the "name",
"ipaddr", "port", "regseconds" columns. If you wanted to be able to
configure the callerid, you could just add a callerid column to the
table, for example.

A SIP table would look more like this:

+------+--------+-------+----------+-----+------------+----------+
| name | host | secret| ipaddr | port| regseconds | username |
+------+--------+-------+----------+-----+------------+----------+
| foo | dynamic| bar | 127.0.0.1| 4569| 1096954152 | 1234 |
+------+--------+-------+----------+-----+------------+----------+

in order to store appropriate parameters required for SIP.

A Voicemail table would look more like this:

+----------+---------+----------+----------+-----------+---------------+
| uniqueid | mailbox | context | password |email | fullname |
+----------+---------+----------+----------+-----------+---------------+
| 1 | 1234 | default | 4242 | a@b.com | Joe Schmoe |
+----------+---------+----------+----------+-----------+---------------+

The uniqueid should be unique to each voicemail user and can be
autoincrement. It need not have any relation to the mailbox or context.

An extension table would look more like this:

+----------+---------+----------+-------+-----------+
| context | exten | priority | app | appdata |
+----------+---------+----------+-------+-----------+
| default | 1234 | 1 | Dial | Zap/1 |
+----------+---------+----------+-------+-----------+

In the dialplan you just use the Realtime switch:

[foo]
switch => Realtime

or:

[bar]
switch => Realtime/bar@extensions
</pre>

==Example extconfig.conf==
<pre>
;
; Static and realtime external configuration
; engine configuration
;
; Please read doc/README.extconfig for basic table
; formatting information.
;
[settings]
;
; Static configuration files:
;
; file.conf => driver,database[,table]
;
; maps a particular configuration file to the given
; database driver, database and table (or uses the
; name of the file as the table if not specified)
;
;uncomment to load queues.conf via the odbc engine.
;
;queues.conf => odbc,asterisk,ast_config
;
; The following files CANNOT be loaded from Realtime storage:
; asterisk.conf
; extconfig.conf (this file)
; logger.conf
;
; Additionally, the following files cannot be loaded from
; Realtime storage unless the storage driver is loaded
; early using 'preload' statements in modules.conf:
; manager.conf
; cdr.conf
; rtp.conf
;
;
; Realtime configuration engine
;
; maps a particular family of realtime
; configuration to a given database driver,
; database and table (or uses the name of
; the family if the table is not specified
;
;example => odbc,asterisk,alttable
;iaxusers => odbc,asterisk
;iaxpeers => odbc,asterisk
;sipusers => odbc,asterisk
;sippeers => odbc,asterisk
;voicemail => odbc,asterisk
;extensions => odbc,asterisk
;queues => odbc,asterisk
;queue_members => odbc,asterisk
</pre>

ENUM

2007-09-04T13:20:39Z

Summary: added enumquery.com lookup page

2005-09-06
jtodd@loligo.com

The ENUMLOOKUP function is more complex than it first may appear, and this guide is to give a general overview and set of examples that may be well-suited for the advanced user to evaluate in their consideration of ENUM or ENUM-like lookup strategies. This document assumes a familiarity with ENUM (RFC3761) or ENUM-like methods, as well as familiarity with NAPTR DNS records (RFC2915, RFC3401-3404).
For an overview of NAPTR records, and the use of NAPTRs in the ENUM global phone-number-to-DNS mapping scheme, please see http://www.voip-info.org/tiki-index.php?page=ENUM for more detail.

A web interface for performing ENUM lookups from any web browser is available at http://enumquery.com/

Using ENUM within Asterisk can be simple or complex, depending on how many failover methods and redundancy procedures you wish to utilize. Implementation of ENUM paths is supposedly defined by the person creating the NAPTR records, but the local administrator may choose to ignore certain NAPTR response methods (URI types) or prefer some over others, which is in contradiction to the RFC. The ENUMLOOKUP method simply provides administrators a method for determining NAPTR results in either the globally unique ENUM (e164.arpa) DNS tree, or in other ENUM-like DNS trees which are not globally unique. The methods to actually create channels ("dial") results given by the ENUMLOOKUP function is then up to the administrator to implement in a way that best suits their environment.

<pre>
Function: ENUMLOOKUP(<number>[,pointer_type[,options[,zone_suffix]]])

Performs an ENUM tree lookup on the specified number, method type,
and (optionally) ordinal offset, and returns one of four different values:

1) post-parsed NAPTR of one method (URI) type
2) count of elements of one method (URI) type
3) count of all method types
4) full URI of method at a particular point in the list of all possible methods

Arguments:

number = telephone number or search string. Only numeric values
within this string are parsed; all other digits are ignored for
search, but are re-written during NAPTR regexp expansion.

service_type = tel, sip, h323, iax2, mailto, ...[any other string],
ALL. Default type is "sip".
Special name of "ALL" will create a list of method types across
all NAPTR records for the search number, and then put the results
in an ordinal list starting with 1. The position <number>
specified will then be returned, starting with 1 as the first
record (lowest value) in the list. The service types are not
hardcoded in Asterisk except for the default (sip) if no other
service type specified; any method type string (IANA-approved or
not) may be used except for the string "ALL".

options = optional specifiers.
c = count. Returns the number of records of this type are returned
(regardless of order or priority.) If "ALL" is the specified
service_type, then a count of all methods will be returned for the
DNS record.
<integer> = The record in priority/order sequence based on the
total count of records passed back by the query. If a service_type
is specified, all entries of that type will be sorted into an
ordinal list starting with 1 (by order first, then priority).
The default of <options> is "1"

zone_suffix = allows customization of the ENUM zone. Default is e164.arpa.

EXAMPLE USES:

Let's use this ENUM list as an example (note that these examples exist
in the DNS, and will hopefully remain in place as example
destinations, but they may change or become invalid over time. The
end result URIs are not guaranteed to actually work, since some of
these hostnames or SIP proxies are imaginary. Of course, the tel:
replies go to directory assistance for New York City and San
Francisco...) Also note that the complex SIP NAPTR at weight 30 will
strip off the leading "+" from the dialed string if it exists. This
is probably a better NAPTR than hard-coding the number into the NAPTR,
and it is included as a more complex regexp example, though other
simpler NAPTRs will work just as well.

0.2.0.1.1.6.5.1.0.3.1.loligo.com. 3600 IN NAPTR 10 100 "u" "E2U+tel" "!^\\+13015611020$!tel:+12125551212!" .
0.2.0.1.1.6.5.1.0.3.1.loligo.com. 3600 IN NAPTR 21 100 "u" "E2U+tel" "!^\\+13015611020$!tel:+14155551212!" .
0.2.0.1.1.6.5.1.0.3.1.loligo.com. 3600 IN NAPTR 25 100 "u" "E2U+sip" "!^\\+13015611020$!sip:2203@sip.fox-den.com!" .
0.2.0.1.1.6.5.1.0.3.1.loligo.com. 3600 IN NAPTR 26 100 "u" "E2U+sip" "!^\\+13015611020$!sip:1234@sip-2.fox-den.com!" .
0.2.0.1.1.6.5.1.0.3.1.loligo.com. 3600 IN NAPTR 30 100 "u" "E2U+sip" "!^\\+*([^\\*]*)!sip:\\1@sip-3.fox-den.com!" .
0.2.0.1.1.6.5.1.0.3.1.loligo.com. 3600 IN NAPTR 55 100 "u" "E2U+mailto" "!^\\+13015611020$!mailto:jtodd@fox-den.com!" .

Example 1: Simplest case, using first SIP return (use all defaults
except for domain name)
exten => 100,1,Set(foo=${ENUMLOOKUP(+13015611020,,,loligo.com)})
returns: ${foo}="2203@sip.fox-den.com"

Example 2: What is the first "tel" pointer type for this number?
(after sorting by order/preference; default of "1" is assumed in
options field)
exten => 100,1,Set(foo=${ENUMLOOKUP(+13015611020,tel,,loligo.com)})
returns: ${foo}="+12125551212"

Example 3: How many "sip" pointer type entries are there for this number?
exten => 100,1,Set(foo=${ENUMLOOKUP(+13015611020,sip,c,loligo.com)})
returns: ${foo}=3

Example 4: For all the "tel" pointer type entries, what is the second
one in the list? (after sorting by preference)
exten => 100,1,Set(foo=${ENUMLOOKUP(+13015611020,tel,2,loligo.com)})
returns: ${foo}="+14155551212"

Example 5: How many NAPTRs (tel, sip, mailto, etc.) are in the list for this number?
exten => 100,1,Set(foo=${ENUMLOOKUP(+13015611020,ALL,c,loligo.com)})
returns: ${foo}=6

Example 6: Give back the second full URI in the sorted list of all NAPTR URIs:
exten => 100,1,Set(foo=${ENUMLOOKUP(+13015611020,ALL,2,loligo.com)})
returns: ${foo}="tel:+14155551212" [note the "tel:" prefix in the string]

Example 7: Look up first SIP entry for the number in the e164.arpa zone (all defaults)
exten => 100,1,Set(foo=${ENUMLOOKUP(+437203001721)})
returns: ${foo}="enum-test@sip.nemox.net" [note: this result is
subject to change as it is "live" DNS and not under my control]

Example 8: Look up the ISN mapping in freenum.org alpha test zone
exten => 100,1,Set(foo=${ENUMLOOKUP(1234*256,,,freenum.org)})
returns: ${foo}="1234@204.91.156.10" [note: this result is subject
to change as it is "live" DNS]

Example 9: Give back the first SIP pointer for a number in the
enum.yoydynelabs.com zone (invalid lookup)
exten => 100,1,Set(foo=${ENUMLOOKUP(1234567890,sip,1,enum.yoyodynelabs.com)})
returns: ${foo}=""

Usage notes and subtle features:

a) The use of "+" in lookups is confusing, and warrants further
explanation. All E.164 numbers ("global phone numbers") by
definition need a leading "+" during ENUM lookup. If you neglect to
add a leading "+", you may discover that numbers that seem to exist
in the DNS aren't getting matched by the system or are returned with
a null string result. This is due to the NAPTR reply requiring a
"+" in the regular expression matching sequence. Older versions of
Asterisk add a "+" from within the code, which may confuse
administrators converting to the new function. Please ensure that
all ENUM (e164.arpa) lookups contain a leading "+" before lookup, so
ensure your lookup includes the leading plus sign. Other DNS trees
may or may not require a leading "+" - check before using those
trees, as it is possible the parsed NAPTRs will not provide correct
results unless you have the correct dialed string. If you get
console messages like "WARNING[24907]: enum.c:222 parse_naptr: NAPTR
Regex match failed." then it is very possible that the returned
NAPTR expects a leading "+" in the search string (or the returned
NAPTR is mis-formed.)

b) If a query is performed of type "c" ("count") and let's say you
get back 5 records and then some seconds later a query is made
against record 5 in the list, it may not be the case that the DNS
resolver has the same answers as it did a second or two ago - maybe
there are only 4 records in the list in the newest query. The
resolver should be the canonical storage location for DNS records,
since that is the intent of ENUM. However, some obscure future
cases may have wildly changing NAPTR records within several seconds.
This is a corner case, and probably only worth noting as a very rare
circumstance. (note: I do not object to Asterisk's dnsmgr method of
locally caching DNS replies, but this method needs to honor the TTL
given by the remote zone master. Currently, the ENUMLOOKUP function
does not use the dnsmgr method of caching local DNS replies.)

c) If you want strict NAPTR value ordering, then it will be
necessary to use the "ALL" method to incrementally step through the
different returned NAPTR pointers. You will need to use string
manipulation to strip off the returned method types, since the
results will look like "sip:12125551212" in the returned value.
This is a non-trivial task, though it is required in order to have
strict RFC compliance and to comply with the desires of the remote
party who is presenting NAPTRs in a particular order for a reason.

d) Default behavior for the function (even in event of an error) is
to move to the next priority, and the result is a null value. Most
ENUM lookups are going to be failures, and it is the responsibility
of the dialplan administrator to manage error conditions within
their dialplan. This is a change from the old app_enumlookup method
and it's arbitrary priority jumping based on result type or failure.

e) Anything other than digits will be ignored in lookup strings.
Example: a search string of "+4372030blah01721" will turn into
1.2.7.1.0.0.3.0.2.7.3.4.e164.arpa. for the lookup. The NAPTR
parsing may cause unexpected results if there are strings inside
your NAPTR lookups.

f) If there exist multiple records with the same weight and order as
a result of your query, the function will RANDOMLY select a single
NAPTR from those equal results.

g) Currently, the function ignores the settings in enum.conf as the
search zone name is now specified within the function, and the H323
driver can be chosen by the user via the dialplan. There were no
other values in this file, and so it becomes deprecated.

h) The function will digest and return NAPTRs which use older
(depricated) style, reversed method strings such as "sip+E2U"
instead of the more modern "E2U+sip"

i) There is no provision for multi-part methods at this time. If
there are multiple NAPTRs with (as an example) a method of
"E2U+voice:sip" and then another NAPTR in the same DNS record with a
method of ""E2U+sip", the system will treat these both as method
"sip" and they will be separate records from the perspective of the
function. Of course, if both records point to the same URI and have
equal priority/weight (as is often the case) then this will cause no
serious difficulty, but it bears mentioning.

j) ISN (ITAD Subscriber Number) usage: If the search number is of
the form ABC*DEF (where ABC and DEF are at least one numeric digit)
then perform an ISN-style lookup where the lookup is manipulated to
C.B.A.DEF.domain.tld (all other settings and options apply.) See
http://www.freenum.org/ for more details on ISN lookups. In the
unlikely event you wish to avoid ISN re-writes, put an "n" as the
first digit of the search string - the "n" will be ignored for the search.

==EXAMPLES==

All examples below except where noted use "e164.arpa" as the
referenced domain, which is the default domain name for ENUMLOOKUP.
All numbers are assumed to not have a leading "+" as dialed by the
inbound channel, so that character is added where necessary during
ENUMLOOKUP function calls.

; example 1
;
; Assumes North American international dialing (011) prefix.
; Look up the first SIP result and send the call there, otherwise
; send the call out a PRI. This is the most simple possible
; ENUM example, but only uses the first SIP reply in the list of
; NAPTR(s).
;
exten => _011.,1,Set(enumresult=${ENUMLOOKUP(+${EXTEN:3})})
exten => _011.,n,Dial(SIP/${enumresult})
exten => _011.,n,Dial(Zap/g1/${EXTEN})
;
; end example 1

; example 2
;
; Assumes North American international dialing (011) prefix.
; Check to see if there are multiple SIP NAPTRs returned by
; the lookup, and dial each in order. If none work (or none
; exist) then send the call out a PRI, group 1.
;
exten => _011.,1,Set(sipcount=${ENUMLOOKUP(${EXTEN:3},sip,c)}|counter=0)
exten => _011.,n,While($["${counter}"<"${sipcount}"])
exten => _011.,n,Set(counter=$[${counter}+1])
exten => _011.,n,Dial(SIP/${ENUMLOOKUP(+${EXTEN:3},sip,${counter})})
exten => _011.,n,EndWhile
exten => _011.,n,Dial(Zap/g1/${EXTEN})
;
; end example 2

; example 3
;
; This example expects an ${EXTEN} that is an e.164 number (like
; 14102241145 or 437203001721)
; Search through e164.arpa and then also search through e164.org
; to see if there are any valid SIP or IAX termination capabilities.
; If none, send call out via Zap channel 1.
;
; Start first with e164.arpa zone...
;
exten => _X.,1,Set(sipcount=${ENUMLOOKUP(+${EXTEN},sip,c)}|counter=0)
exten => _X.,2,GotoIf($["${counter}"<"${sipcount}"]?3:6)
exten => _X.,3,Set(counter=$[${counter}+1])
exten => _X.,4,Dial(SIP/${ENUMLOOKUP(+${EXTEN},sip,${counter})})
exten => _X.,5,GotoIf($["${counter}"<"${sipcount}"]?3:6)
;
exten => _X.,6,Set(iaxcount=${ENUMLOOKUP(+${EXTEN},iax2,c)}|counter=0)
exten => _X.,7,GotoIf($["${counter}"<"${iaxcount}"]?8:11)
exten => _X.,8,Set(counter=$[${counter}+1])
exten => _X.,9,Dial(IAX2/${ENUMLOOKUP(+${EXTEN},iax2,${counter})})
exten => _X.,10,GotoIf($["${counter}"<"${iaxcount}"]?8:11)
;
exten => _X.,11,NoOp("No valid entries in e164.arpa for ${EXTEN} - checking in e164.org")
;
; ...then also try e164.org, and look for SIP and IAX NAPTRs...
;
exten => _X.,12,Set(sipcount=${ENUMLOOKUP(+${EXTEN},sip,c,e164.org)}|counter=0)
exten => _X.,13,GotoIf($["${counter}"<"${sipcount}"]?14:17)
exten => _X.,14,Set(counter=$[${counter}+1])
exten => _X.,15,Dial(SIP/${ENUMLOOKUP(+${EXTEN},sip,${counter},e164.org)})
exten => _X.,16,GotoIf($["${counter}"<"${sipcount}"]?14:17)
;
exten => _X.,17,Set(iaxcount=${ENUMLOOKUP(+${EXTEN},iax2,c,e164.org)}|counter=0)
exten => _X.,18,GotoIf($["${counter}"<"${iaxcount}"]?19:22)
exten => _X.,19,Set(counter=$[${counter}+1])
exten => _X.,20,Dial(IAX2/${ENUMLOOKUP(+${EXTEN},iax2,${counter},e164.org)})
exten => _X.,21,GotoIf($["${counter}"<"${iaxcount}"]?19:22)
;
; ...then send out PRI.
;
exten => _X.,22,NoOp("No valid entries in e164.org for ${EXTEN} - sending out via Zap")
exten => _X.,23,Dial(Zap/g1/${EXTEN})
;
; end example 3
</pre>

==Example enum.conf==
<pre>
;
; ENUM Configuration for resolving phone numbers over DNS
;
; Sample config for Asterisk
; This file is reloaded at "reload enum" in the CLI
;
[general]
;
; The search list for domains may be customized. Domains are searched
; in the order they are listed here.
;
search => e164.arpa
;
; If you'd like to use the E.164.org public ENUM registry in addition
; to the official e164.arpa one, uncomment the following line
;
;search => e164.org
;
; As there are more H323 drivers available you have to select to which
; drive a H323 URI will map. Default is "H323".
;
h323driver => H323
</pre>

DUNDi

2007-09-04T13:20:08Z

Summary:

http://www.dundi.com
Mark Spencer, Digium, Inc.

DUNDi is essentially a trusted, peer-to-peer system for being able to call any phone number from the Internet. DUNDi works by creating a network of nodes called the "DUNDi E.164 Trust Group" which are bound by a common peering agreement known as the General Peering Agreement or GPA. The GPA legally binds the members of the Trust Group to provide good-faith accurate information to the other nodes on the network, and provides standards by which the community can insure the integrity of the information on the nodes themselves. Unlike ENUM or similar systems, DUNDi is explicitly designed to preclude any necessity for a single centralized system which could be a source of fees, regulation, etc.

You can find the PEERING agreement in the doc directory.

Much less dramatically, DUNDi can also be used within a private enterprise to share a dialplan efficiently between multiple nodes, without incuring a risk of a single point of failure. In this way,
administrators can locally add extensions which become immediately available to the other nodes in the system.

For more information visit http://www.dundi.com

==Example dundi.conf==
----
<pre>
;
; DUNDi configuration file
;
; For more information about DUNDi, see http://www.dundi.com
;
;
[general]
;
; The "general" section contains general parameters relating
; to the operation of the dundi client and server.
;
; The first part should be your complete contact information
; should someone else in your peer group need to contact you.
;
;department=Your Department
;organization=Your Company, Inc.
;locality=Your City
;stateprov=ST
;country=US
;email=your@email.com
;phone=+12565551212
;
;
; Specify bind address and port number. Default is
; 4520
;
;bindaddr=0.0.0.0
;port=4520
;
; Our entity identifier (Should generally be the MAC address of the
; machine it's running on. Defaults to the first eth address, but you
; can override it here, as long as you set it to the MAC of *something*
; you own!)
;
;entityid=00:07:E9:3B:76:60
;
; Peers shall cache our query responses for the specified time,
; given in seconds. Default is 3600.
;
;cachetime=3600
;
; This defines the max depth in which to search the DUNDi system.
; Note that the maximum time that we will wait for a response is
; (2000 + 200 * ttl) ms.
;
ttl=32
;
; If we don't get ACK to our DPDISCOVER within 2000ms, and autokill is set
; to yes, then we cancel the whole thing (that's enough time for one
; retransmission only). This is used to keep things from stalling for a long
; time for a host that is not available, but would be ill advised for bad
; connections. In addition to 'yes' or 'no' you can also specify a number
; of milliseconds. See 'qualify' for individual peers to turn on for just
; a specific peer.
;
autokill=yes
;
; pbx_dundi creates a rotating key called "secret", under the family
; 'secretpath'. The default family is dundi (resulting in
; the key being held at dundi/secret).
;
;secretpath=dundi
;
; The 'storehistory' option (also changeable at runtime with
; 'dundi store history' and 'dundi no store history') will
; cause the DUNDi engine to keep track of the last several
; queries and the amount of time each query took to execute
; for the purpose of tracking slow nodes. This option is
; off by default due to performance impacts.
;
;storehistory=yes

[mappings]
;
; The "mappings" section maps DUNDi contexts
; to contexts on the local asterisk system. Remember
; that numbers that are made available under the e164
; DUNDi context are regulated by the DUNDi General Peering
; Agreement (GPA) if you are a member of the DUNDi E.164
; Peering System.
;
; dundi_context => local_context,weight,tech,dest[,options]]
;
; 'dundi_context' is the name of the context being requested
; within the DUNDi request
;
; 'local_context' is the name of the context on the local system
; in which numbers can be looked up for which responses shall be given.
;
; 'weight' is the weight to use for the responses provided from this
; mapping. The number must be >= 0 and < 60000. Since it is totally
; valid to receive multiple responses to a query, responses received
; with a lower weight are tried first. Note that the weight has a
; special meaning in the e164 context - see the GPA for more details.
;
; 'tech' is the technology to use (IAX, SIP, H323)
;
; 'dest' is the destination to supply for reaching that number. The
; following variables can be used in the destination string and will
; be automatically substituted:
; ${NUMBER}: The number being requested
; ${IPADDR}: The IP address to connect to
; ${SECRET}: The current rotating secret key to be used
;
; Further options may include:
;
; nounsolicited: No unsolicited calls of any type permitted via this
; route
; nocomunsolicit: No commercial unsolicited calls permitted via
; this route
; residential: This number is known to be a residence
; commercial: This number is known to be a business
; mobile: This number is known to be a mobile phone
; nocomunsolicit: No commercial unsolicited calls permitted via
; this route
; nopartial: Do not search for partial matches
;
; There *must* exist an entry in mappings for DUNDi to respond
; to any request, although it may be empty.
;
;e164 => dundi-e164-canonical,0,IAX2,dundi:${SECRET}@${IPADDR}/${NUMBER},nounsolicited,nocomunsolicit,nopartial
;e164 => dundi-e164-customers,100,IAX2,dundi:${SECRET}@${IPADDR}/${NUMBER},nounsolicited,nocomunsolicit,nopartial
;e164 => dundi-e164-via-pstn,400,IAX2,dundi:${SECRET}@${IPADDR}/${NUMBER},nounsolicited,nocomunsolicit,nopartial

;digexten => default,0,IAX2,guest@lappy/${NUMBER}
;asdf =>

;
;
; The remaining sections represent the peers
; that we fundamentally trust. The section name
; represents the name and optionally at a specific
; DUNDi context if you want the trust to be established
; for only a specific DUNDi context.
;
; inkey - What key they will be authenticating to us with
;
; outkey - What key we use to authenticate to them
;
; host - What their host is
;
; order - What search order to use. May be 'primary', 'secondary',
; 'tertiary' or 'quartiary'. In large systems, it is beneficial
; to only query one up-stream host in order to maximize caching
; value. Adding one with primary and one with secondary gives you
; redundancy without sacrificing performance.
;
; include - Includes this peer when searching a particular context
; for lookup (set "all" to perform all lookups with that
; host. This is also the context in which peers are permitted
; to precache.
;
; noinclude - Disincludes this peer when searching a particular context
; for lookup (set "all" to perform no lookups with that
; host.
;
; permit - Permits this peer to search a given DUNDi context on
; the local system. Set "all" to permit this host to
; lookup all contexts. This is also a context for which
; we will create/forward PRECACHE commands.
;
; deny - Denies this peer to search a given DUNDi context on
; the local system. Set "all" to deny this host to
; lookup all contexts.
;
; model - inbound, outbound, or symmetric for whether we receive
; requests only, transmit requests only, or do both.
;
; precache - Utilize/Permit precaching with this peer (to pre
; cache means to provide an answer when no request
; was made and is used so that machines with few
; routes can push those routes up a to a higher level).
; outgoing means we send precache routes to this peer,
; incoming means we permit this peer to send us
; precache routes. symmetric means we do both.
;
; Note: You cannot mix symmetric/outbound model with symmetric/inbound
; precache, nor can you mix symmetric/inbound model with symmetric/outbound
; precache.
;
;
; The '*' peer is special and matches an unspecified entity
;

;
; Sample Primary e164 DUNDi peer
;
;[00:50:8B:F3:75:BB]
;model = symmetric
;host = 64.215.96.114
;inkey = digium
;outkey = misery
;include = e164
;permit = e164
;qualify = yes

;
; Sample Secondary e164 DUNDi peer
;
;[00:A0:C9:96:92:84]
;model = symmetric
;host = misery.digium.com
;inkey = misery
;outkey = ourkey
;include = e164
;permit = e164
;qualify = yes
;order = secondary

;
; Sample "push mode" downstream host
;
;[00:0C:76:96:75:28]
;model = inbound
;host = dynamic
;precache = inbound
;inkey = littleguy
;outkey = ourkey
;include = e164 ; In this case used only for precaching
;permit = e164
;qualify = yes

;
; Sample "push mode" upstream host
;
;[00:07:E9:3B:76:60]
;model = outbound
;precache = outbound
;host = 216.207.245.34
;register = yes
;inkey = dhcp34
;permit = all ; In this case used only for precaching
;include = all
;qualify = yes
;outkey=foo

;[*]
;
</pre>

CLI

2007-09-04T13:19:37Z

Summary:

'''Changing the CLI Prompt'''
----
<pre>
The CLI prompt is set with the ASTERISK_PROMPT UNIX environment variable that
you set from the Unix shell before starting Asterisk

You may include the following variables, that will be replaced by
the current value by Asterisk:

%d Date (year-month-date)
%h Full hostname
%H Short hostname
%t Time
%% Percent sign
%# '#' if Asterisk is run in console mode, '>' if running as remote console
%Cn[;n] Change terminal foreground (and optional background) color to specified
A full list of colors may be found in include/asterisk/term.h

On Linux systems, you may also use
%l1 Load average over past minute
%l2 Load average over past 5 minutes
%l3 Load average over past 15 minutes
%l4 Process fraction (processes running / total processes)
%l5 The most recently allocated pid
</pre>
----
04-03-26

Channel

2007-09-04T13:14:26Z

Summary:

; Implementing a Channel

* What is a channel?

A channel is a unit which brings in a call to the Asterisk PBX. A channel could be connected to a real telephone (like the Internet Phone Jack) or to a logical call (like an Internet phone call). Asterisk makes no distinction between "FXO" and "FXS" style channels (that is, it doesn't distinguish between telephone lines and telephones).

Every call is placed or received on a distinct channel. Asterisk uses a channel driver (typically named chan_xxx.so) to support each type of hardware.

* What do I need to create a channel?

In order to support a new piece of hardware you need to write a channel driver. The easiest way to do so is to look at an existing channel driver and model your own code after it.

* What's the general architecture?

Typically, a channel reads a configuration file on startup which tells it something about the hardware it's going to be servicing. Then, it launches a thread which monitors all the idle channels (See the chan_modem or the chan_ixj for an example of this). When a "RING" or equivalent is detected, the monitoring thread should allocate a channel structure and assign all the callbacks to it (see ixj_new, for example), and then call ast_pbx_start on that channel. ast_pbx_start will launch a new thread to
handle the channel as long as the call is up, so once pbx_start has successfully been run, the monitor should no longer monitor that channel. The PBX thread will use the channel, reading, writing, calling, etc., and multiplexing that channel with others using select() on the channel's file descriptor (if your channel doesn't have an associated file descriptor, you'll need to emulate one somehow, perhaps along the lines of what the translator API does with its channel.

When the PBX is finished with the line, it will hang up the line, at which point it the hardware should again be monitored by the monitoring thread.

CDR

2007-09-04T13:14:01Z

Summary:

Asterisk generates Call Detail Records in a database or in a comma separated text file.

* cdr_csv supports comma separated text file storage, this is the default driver
* cdr_manager supports CDR information via the AMI, The Asterisk Manager interface
* cdr_odbc supports UnixODBC databases, see http://www.unixodbc.org for an updated list of supported databases, from MySQL to MsSQL and text files.
* cdr_tds supports FreeTDS databases (Among them MS SQL)
::NOTE. Please read README.tds for information on possible problems with the FreeTDS driver
* cdr_sqlite supports SQlite
* cdr_pgsql supports PostgreSQL

In the asterisk-addons cvs archive, there's a cdr_mysql driver for MySQL.

==Applications==
----
<pre>
* SetAccount Set account code for billing
* SetAMAFlags Sets AMA flags
* NoCDR Make sure no CDR is saved for a specific call
* ResetCDR Reset CDR
* ForkCDR Save current CDR and start a new CDR for this call
* Authenticate Authenticates and sets the account code
* SetCDRUserField Set CDR user field
* AppendCDRUserField Append data to CDR User field
</pre>

For more information, use the "show application" command. You can set default account codes and AMA flags for devices in channel configuration files, like sip.conf, iax.conf etc.

==Fields of the CDR in Asterisk==
----
<pre>
1. accountcode: What account number to use, (string, 20 characters)
2. src: Caller*ID number (string, 80 characters)
3. dst: Destination extension (string, 80 characters)
4. dcontext: Destination context (string, 80 characters)
5. clid: Caller*ID with text (80 characters)
6. channel: Channel used (80 characters)
7. dstchannel: Destination channel if appropriate (80 characters)
8. lastapp: Last application if appropriate (80 characters)
9. lastdata: Last application data (arguments) (80 characters)
10. start: Start of call (date/time)
11. answer: Answer of call (date/time)
12. end: End of call (date/time)
13. duration: Total time in system, in seconds (integer), from dial to hangup
14. billsec: Total time call is up, in seconds (integer), from answer to hangup
15. disposition: What happened to the call: ANSWERED, NO ANSWER, BUSY
16. amaflags: What flags to use: DOCUMENTATION, BILL, IGNORE etc,
specified on a per channel basis like accountcode.
17. user field: A user-defined field, maximum 255 characters

In some cases, uniqueid is appended:

* uniqueid: Unique Channel Identifier (32 characters)
This needs to be enabled in the source code at compile time
</pre>

ONE IMPORTANT NOTE: If you are trying to collect records on IAX to IAX calls you need to be aware that by default, IAX will attempt to transfer calls in this situation (if DTMF is not required). When the transfer is completed the call is dumped from the middle machine and thus the call detail records
will report a short call time. If you want detailed records you must turn off IAX transfer, but unless your servers are very close together, you will definitely get a latency hit from doing so.

==CDR Variables==
----

If the channel has a cdr, that cdr record has its own set of variables which can be accessed just like channel variables. The following builtin variables are available.
<pre>
${CDR(clid)} Caller ID
${CDR(src)} Source
${CDR(dst)} Destination
${CDR(dcontext)} Destination context
${CDR(channel)} Channel name
${CDR(dstchannel)} Destination channel
${CDR(lastapp)} Last app executed
${CDR(lastdata)} Last app's arguments
${CDR(start)} Time the call started.
${CDR(answer)} Time the call was answered.
${CDR(end)} Time the call ended.
${CDR(duration)} Duration of the call.
${CDR(billsec)} Duration of the call once it was answered.
${CDR(disposition)} ANSWERED, NO ANSWER, BUSY
${CDR(amaflags)} DOCUMENTATION, BILL, IGNORE etc
${CDR(accountcode)} The channel's account code.
${CDR(uniqueid)} The channel's unique id.
${CDR(userfield)} The channels uses specified field.
</pre>

In addition, you can set your own extra variables by using Set(CDR(name)=value). These variables can be output into a text-format CDR by using the cdr_custom CDR driver; see the cdr_custom.conf.sample file in the configs directory for an example of how to do this.

==CSV and MySQL==
----
Call data records can be stored in many different databases or even CSV text.
 
MSSQL: Asterisk can currently store CDRs into an MSSQL database in two different ways: cdr_odbc.c or cdr_tds.c
 
Call Data Records can be stored using unixODBC (which requires the FreeTDS package) [cdr_odbc.c] or directly by using just the FreeTDS package [cdr_tds.c] The following provide some examples known to get asterisk working with mssql. NOTE: Only choose one db connector.
 
ODBC [cdr_odbc.c]:
Compile, configure, and install the latest unixODBC package:
tar -zxvf unixODBC-2.2.9.tar.gz &&
cd unixODBC-2.2.9 &&
./configure --sysconfdir=/etc --prefix=/usr --disable-gui &&
make &&
make install

Compile, configure, and install the latest FreeTDS package:
tar -zxvf freetds-0.62.4.tar.gz &&
cd freetds-0.62.4 &&
./configure --prefix=/usr --with-tdsver=7.0 --with-unixodbc=/usr/lib &&
make &&
make install

Compile, or recompile, asterisk so that it will now add support
for cdr_odbc.c
 
make clean &&
make update &&
make &&
make install
 
Setup odbc configuration files. These are working examples from my system. You will need to modify for your setup. You are not required to store usernames or passwords here.

/etc/odbcinst.ini
[FreeTDS]
Description = FreeTDS ODBC driver for MSSQL
Driver = /usr/lib/libtdsodbc.so
Setup = /usr/lib/libtdsS.so
FileUsage = 1
 
/etc/odbc.ini
[MSSQL-asterisk]
description = Asterisk ODBC for MSSQL
driver = FreeTDS
server = 192.168.1.25
port = 1433
database = voipdb
tds_version = 7.0
language = us_english

Only install one database connector. Do not confuse asterisk
by using both ODBC (cdr_odbc.c) and FreeTDS (cdr_tds.c).
This command will erase the contents of cdr_tds.conf

[ -f /etc/asterisk/cdr_tds.conf ] > /etc/asterisk/cdr_tds.conf
 
NOTE: unixODBC requires the freeTDS package, but asterisk does not call freeTDS directly.
 
Setup cdr_odbc configuration files. These are working samples from my system. You will need to modify for your setup. Define your usernames and passwords here, secure file as well.
 
/etc/asterisk/cdr_odbc.conf
[global]
dsn=MSSQL-asterisk
username=voipdbuser
password=voipdbpass
loguniqueid=yes

And finally, create the 'cdr' table in your mssql database.

CREATE TABLE cdr (
[calldate] [datetime] NOT NULL ,
[clid] [varchar] (80) NOT NULL ,
[src] [varchar] (80) NOT NULL ,
[dst] [varchar] (80) NOT NULL ,
[dcontext] [varchar] (80) NOT NULL ,
[channel] [varchar] (80) NOT NULL ,
[dstchannel] [varchar] (80) NOT NULL ,
[lastapp] [varchar] (80) NOT NULL ,
[lastdata] [varchar] (80) NOT NULL ,
[duration] [int] NOT NULL ,
[billsec] [int] NOT NULL ,
[disposition] [varchar] (45) NOT NULL ,
[amaflags] [int] NOT NULL ,
[accountcode] [varchar] (20) NOT NULL ,
[uniqueid] [varchar] (32) NOT NULL ,
[userfield] [varchar] (255) NOT NULL
)

Start asterisk in verbose mode, you should see that asterisk logs a connection to the database and will now record every call to the database when it's complete.
 
TDS [cdr_tds.c]:
Compile, configure, and install the latest FreeTDS package:
tar -zxvf freetds-0.62.4.tar.gz &&
cd freetds-0.62.4 &&
./configure --prefix=/usr --with-tdsver=7.0
make &&
make install
 
Compile, or recompile, asterisk so that it will now add support for cdr_tds.c (Currently only asterisk SVN supports cdr_tds.c)
 
make clean &&
make update &&
make &&
make install
 
Only install one database connector. Do not confuse asterisk by using both ODBC (cdr_odbc.c) and FreeTDS (cdr_tds.c). This command will erase the contents of cdr_odbc.conf
 
[ -f /etc/asterisk/cdr_odbc.conf ] > /etc/asterisk/cdr_odbc.conf
 
Setup cdr_tds configuration files. These are working samples from my system. You will need to modify for your setup. Define your usernames and passwords here, secure file as well.
 
/etc/asterisk/cdr_tds.conf
[global]
hostname=192.168.1.25
port=1433
dbname=voipdb
user=voipdbuser
password=voipdpass
charset=BIG5
 
And finally, create the 'cdr' table in your mssql database.
 
CREATE TABLE cdr (
[accountcode] [varchar] (20) NULL ,
[src] [varchar] (80) NULL ,
[dst] [varchar] (80) NULL ,
[dcontext] [varchar] (80) NULL ,
[clid] [varchar] (80) NULL ,
[channel] [varchar] (80) NULL ,
[dstchannel] [varchar] (80) NULL ,
[lastapp] [varchar] (80) NULL ,
[lastdata] [varchar] (80) NULL ,
[start] [datetime] NULL ,
[answer] [datetime] NULL ,
[end] [datetime] NULL ,
[duration] [int] NULL ,
[billsec] [int] NULL ,
[disposition] [varchar] (20) NULL ,
[amaflags] [varchar] (16) NULL ,
[uniqueid] [varchar] (32) NULL
)

Start asterisk in verbose mode, you should see that asterisk logs a connection to the database and will now record every call to the database when it's complete.
 
MYSQL:
PGSQL:
SQLLITE:
-------------------------------------------------------------------------------
08/02/2004 : Duane Cox <dcox@illicom.net> - added mssql information

Backtraces

2007-09-04T13:13:30Z

Summary:

<pre>
This document is to provide information on how to obtain the
backtraces required on the asterisk bug tracker, available at
http://bugs.digium.com. The information is required by developers to
help fix problem with bugs of any kind. Backtraces provide information
about what was wrong when a program crashed; in our case,
Asterisk. There are two kind of backtraces (aka 'bt'), which are
useful: bt and bt full.

First of all, when you start Asterisk, you MUST start it with option
-g (this tells Asterisk to produce a core file if it crashes).

If you start Asterisk with the safe_asterisk script, it automatically
starts using the option -g.

If you're not sure if Asterisk is running with the -g option, type the
following command in your shell:

debian:/tmp# ps aux | grep asterisk
root 17832 0.0 1.2 2348 788 pts/1 S Aug12 0:00 /bin/sh /usr/sbin/safe_asterisk
root 26686 0.0 2.8 15544 1744 pts/1 S Aug13 0:02 asterisk -vvvg -c
[...]

The interesting information is located in the last column.

Second, your copy of Asterisk must have been built without
optimization or the backtrace will be (nearly) unusable. This can be
done by using 'make dont-optimize' intead of 'make install' to build
and install the Asterisk binary and modules.

After Asterisk crashes, a core file will be "dumped" in your /tmp/
directory. To make sure it's really there, you can just type the
following command in your shell:

debian:/tmp# ls -l /tmp/core.*
-rw------- 1 root root 10592256 Aug 12 19:40 /tmp/core.26252
-rw------- 1 root root 9924608 Aug 12 20:12 /tmp/core.26340
-rw------- 1 root root 10862592 Aug 12 20:14 /tmp/core.26374
-rw------- 1 root root 9105408 Aug 12 20:19 /tmp/core.26426
-rw------- 1 root root 9441280 Aug 12 20:20 /tmp/core.26462
-rw------- 1 root root 8331264 Aug 13 00:32 /tmp/core.26647
debian:/tmp#

Now that we've verified the core file has been written to disk, the
final part is to extract 'bt' from the core file. Core files are
pretty big, don't be scared, it's normal.

*** NOTE: Don't attach core files on the bug tracker, we only need the bt and bt full. ***

For extraction, we use a really nice tool, called gdb. To verify that
you have gdb installed on your system:

debian:/tmp# gdb -v
GNU gdb 6.3-debian
Copyright 2004 Free Software Foundation, Inc.
GDB is free software, covered by the GNU General Public License, and you are
welcome to change it and/or distribute copies of it under certain conditions.
Type "show copying" to see the conditions.
There is absolutely no warranty for GDB. Type "show warranty" for details.
This GDB was configured as "i386-linux".
debian:/tmp#

Which is great, we can continue. If you don't have gdb installed, go install gdb.

Now load the core file in gdb, as follows:

debian:/tmp# gdb -se "asterisk" -c /tmp/core.26252
[...]
(You would see a lot of output here.)
[...]
Reading symbols from /usr/lib/asterisk/modules/app_externalivr.so...done.
Loaded symbols for /usr/lib/asterisk/modules/app_externalivr.so
#0 0x29b45d7e in ?? ()
(gdb)

Now at the gdb prompt, type: bt
You would see output similar to:
(gdb) bt
#0 0x29b45d7e in ?? ()
#1 0x08180bf8 in ?? ()
#2 0xbcdffa58 in ?? ()
#3 0x08180bf8 in ?? ()
#4 0xbcdffa60 in ?? ()
#5 0x08180bf8 in ?? ()
#6 0x180bf894 in ?? ()
#7 0x0bf80008 in ?? ()
#8 0x180b0818 in ?? ()
#9 0x08068008 in ast_stopstream (tmp=0x40758d38) at file.c:180
#10 0x000000a0 in ?? ()
#11 0x000000a0 in ?? ()
#12 0x00000000 in ?? ()
#13 0x407513c3 in confcall_careful_stream (conf=0x8180bf8, filename=0x8181de8 "Zap/pseudo-1324221520") at app_meetme.c:262
#14 0x40751332 in streamconfthread (args=0x8180bf8) at app_meetme.c:1965
#15 0xbcdffbe0 in ?? ()
#16 0x40028e51 in pthread_start_thread () from /lib/libpthread.so.0
#17 0x401ec92a in clone () from /lib/libc.so.6
(gdb)

The bt's output is the information that we need on the bug tracker.

Now do a bt full as follows:
(gdb) bt full
#0 0x29b45d7e in ?? ()
No symbol table info available.
#1 0x08180bf8 in ?? ()
No symbol table info available.
#2 0xbcdffa58 in ?? ()
No symbol table info available.
#3 0x08180bf8 in ?? ()
No symbol table info available.
#4 0xbcdffa60 in ?? ()
No symbol table info available.
#5 0x08180bf8 in ?? ()
No symbol table info available.
#6 0x180bf894 in ?? ()
No symbol table info available.
#7 0x0bf80008 in ?? ()
No symbol table info available.
#8 0x180b0818 in ?? ()
No symbol table info available.
#9 0x08068008 in ast_stopstream (tmp=0x40758d38) at file.c:180
No locals.
#10 0x000000a0 in ?? ()
No symbol table info available.
#11 0x000000a0 in ?? ()
No symbol table info available.
#12 0x00000000 in ?? ()
No symbol table info available.
#13 0x407513c3 in confcall_careful_stream (conf=0x8180bf8, filename=0x8181de8 "Zap/pseudo-1324221520") at app_meetme.c:262
f = (struct ast_frame *) 0x8180bf8
trans = (struct ast_trans_pvt *) 0x0
#14 0x40751332 in streamconfthread (args=0x8180bf8) at app_meetme.c:1965
No locals.
#15 0xbcdffbe0 in ?? ()
No symbol table info available.
#16 0x40028e51 in pthread_start_thread () from /lib/libpthread.so.0
No symbol table info available.
#17 0x401ec92a in clone () from /lib/libc.so.6
No symbol table info available.
(gdb)

We also need gdb's output. That output gives more details compared to
the simple "bt". So we recommend that you use bt full instead of bt.
But, if you could include both, we appreciate that.

The final "extraction" would the to know all traces by all
threads. Even if asterisk runs on the same thread for each calls, it
could have some new threads created.

To make sure we have the correct informations, just do:
(gdb) thread apply all bt

Thread 1 (process 26252):
#0 0x29b45d7e in ?? ()
#1 0x08180bf8 in ?? ()
#2 0xbcdffa58 in ?? ()
#3 0x08180bf8 in ?? ()
#4 0xbcdffa60 in ?? ()
#5 0x08180bf8 in ?? ()
#6 0x180bf894 in ?? ()
#7 0x0bf80008 in ?? ()
#8 0x180b0818 in ?? ()
#9 0x08068008 in ast_stopstream (tmp=0x40758d38) at file.c:180
#10 0x000000a0 in ?? ()
#11 0x000000a0 in ?? ()
#12 0x00000000 in ?? ()
#13 0x407513c3 in confcall_careful_stream (conf=0x8180bf8, filename=0x8181de8 "Zap/pseudo-1324221520") at app_meetme.c:262
#14 0x40751332 in streamconfthread (args=0x8180bf8) at app_meetme.c:1965
#15 0xbcdffbe0 in ?? ()
#16 0x40028e51 in pthread_start_thread () from /lib/libpthread.so.0
#17 0x401ec92a in clone () from /lib/libc.so.6
(gdb)

That output tell us crucial informations for threads.

Now, just create a output.txt and dump your "bt full" (and/or "bt")
AND with "thread apply all bt".

Note: Please ATTACH your output, DO NOT paste it as a note.

And you're ready for upload on bug tracker.

Questions or comments regarding this documentation, feel free to pass
by #asterisk-bugs on FreeNode.
</pre>

Asterisk configuration parser

2007-09-04T13:12:55Z

Summary:

Asterisk Configuration Parser (version 1.1 and later)
----

The Asterisk configuration parser in the 1.1 development version (1.2
stable) and beyond series has been improved in a number of ways. In
addition to the realtime architecture, we now have the ability to create
templates in configuration files, and use these as templates when we
configure phones, voicemail accounts and queues.

These changes are general to the configuration parser, and works in
all configuration files.

==General syntax==
----
Asterisk configuration files are defined as follows:

[section]
label = value
label2 = value

In some files, (e.g. mgcp.conf, zapata.conf and agents.conf), the syntax
is a bit different. In these files the syntax is as follows:

[section]
label1 = value1
label2 = value2
object => name
 
label3 = value3
label2 = value4
object2 => name2

In this syntax, we create objects with the settings defined above the object
creation. Note that settings are inherited from the top, so in the example
above object2 has inherited the setting for "label1" from the first object.

For template configurations, the syntax for defining a section is changed
to
[section](options)
label = value

The options field is used to define templates, refer to templates and hide
templates. Any object can be used as a template.

No whitespace is allowed between the closing "]" and the parenthesis "(".

==Comments==
----
All lines that starts with semi-colon ";" is treated as comments
and is not parsed.

The ";--" is a marker for a multi-line comment. Everything after
that marker will be treated as a comment until the end-marker "--;"
is found. Parsing begins directly after the end-marker.
<pre>
;This is a comment
label = value
;-- This is
a comment --;

;-- Comment --; exten=> 1000,1,dial(SIP/lisa)
</pre>

==Including other files==
----
In all of the configuration files, you may include the content of another
file with the #include statement. The content of the other file will be
included at the row that the #include statement occured.
<pre>
#include myusers.conf
</pre>
You may also include the output of a program with the #exec directive,
if you enable it in asterisk.conf

In asterisk.conf, add the execincludes = yes statement in the options
section:
[options]
execincludes=yes

The exec directive is used like this:
<pre>
#exec /usr/local/bin/myasteriskconfigurator.sh
</pre>

==Adding to an existing section==
----

[section]
label = value
 
[section](+)
label2 = value2

In this case, the plus sign indicates that the second section (with the
same name) is an addition to the first section. The second section can
be in another file (by using the #include statement). If the section
name referred to before the plus is missing, the configuration will fail
to load.

==Defining a template-only section==
----
[section](!)
label = value

The exclamation mark indicates to the config parser that this is a only
a template and should not itself be used by the Asterisk module for
configuration. The section can be inherited by other sections (see
section "Using templates" below) but is not used by itself.

==Using templates==
''(or other configuration sections)''
----
[section](name[,name])
label = value

The name within the parenthesis refers to other sections, either
templates or standard sections. The referred sections are included
before the configuration engine parses the local settings within the
section as though their entire contents (and anything they were
previously based upon) were included in the new section. For example
consider the following:

[foo]
permit=192.168.0.2
host=asdf
deny=192.168.0.1
 
[bar]
permit=192.168.1.2
host=jkl
deny=192.168.1.1
 
[baz](foo,bar)
permit=192.168.3.1
host=bnm

The [baz] section will be processed as though it had been written in the
following way:

[baz]
permit=192.168.0.2
host=asdf
deny=192.168.0.1
permit=192.168.1.2
host=jkl
deny=192.168.1.1
permit=192.168.3.1
host=bnm

==Additional Examples==
----
(in top-level sip.conf)
 
[defaults](!)
type=friend
nat=yes
qualify=on
dtmfmode=rfc2833
disallow=all
allow=alaw
#include accounts/*/sip.conf
(in accounts/customer1/sip.conf)
 
[def-customer1](!,defaults)
secret=this_is_not_secret
context=from-customer1
callerid=Customer 1 <300>
accountcode=0001
 
[phone1](def-customer1)
mailbox=phone1@customer1
 
[phone2](def-customer1)
mailbox=phone2@customer1

This example defines two phones - phone1 and phone2 with settings inherited from "def-customer1". The "def-customer1" is a template that inherits from "defaults", which also is a template.

Asterisk Main

2007-09-04T13:12:24Z

Summary:

; Below is a sample of the main Asterisk configuration file, asterisk.conf.

Note that this file is '''not''' provided in sample form, because the Makefile creates it when needed and does not touch it when it already exists.

<pre>
[directories]
; Make sure these directoriess have the right permissions if not
; running Asterisk as root

; Where the configuration files (except for this one) are located
astetcdir => /etc/asterisk

; Where the Asterisk loadable modules are located
astmoddir => /usr/lib/asterisk/modules

; Where additional 'library' elements (scripts, etc.) are located
astvarlibdir => /var/lib/asterisk

; Where AGI scripts/programs are located
astagidir => /var/lib/asterisk/agi-bin

; Where spool directories are located
; Voicemail, monitor, dictation and other apps will create files here
; and outgoing call files (used with pbx_spool) must be placed here
astspooldir => /var/spool/asterisk

; Where the Asterisk process ID (pid) file should be created
astrundir => /var/run/asterisk

; Where the Asterisk log files should be created
astlogdir => /var/log/asterisk

[options]
;Under "options" you can enter configuration options
;that you also can set with command line options

verbose = 0 ; Verbosity level for logging (-v)
debug = 3 ; Debug: "No" or value (1-4)
nofork=yes | no ; Background execution disabled (-f)
console= yes | no ; Console mode (-c)
highpriority = yes | no ; Execute with high priority (-p)
initcrypto = yes | no ; Initialize crypto at startup (-i)
nocolor = yes | no ; Disable ANSI colors (-n)
dumpcore = yes | no ; Dump core on failure (-g)
quiet = yes | no ; Run quietly (-q)
timestamp = yes | no ; Force timestamping on log entries to console (-T)
runuser = asterisk ; User to run asterisk as (-U) NOTE: will require changes to
; directory and device permisions
rungroup = asterisk ; Group to run asterisk as (-G)

;These options have no command line equivalent
cache_record_files = yes | no ; Cache record() files in another directory until completion
record_cache_dir = <dir>
transcode_via_sln = yes | no ; Build transcode paths via SLINEAR
transmit_silence_during_record = yes | no ; send SLINEAR silence while channel is being recorded
maxload = 1.0 ; The maximum load average we accept calls for
maxcalls = 255 ; The maximum number of concurrent calls you want to allow
execincludes = yes | no ; Allow #exec entries in configuration files
dontwarn = yes | no ; Don't over-inform the Asterisk sysadm, he's a guru

[files]
; Changing the following lines may compromise your security
; Asterisk.ctl is the pipe that is used to connect the remote CLI
; (asterisk -r) to Asterisk. Changing these settings change the
; permissions and ownership of this file.
; The file is created when Asterisk starts, in the "astrundir" above.

;astctlpermissions = 0660
;astctlowner = root
;astctlgroup = asterisk
;astctl = asterisk.ctl
</pre>

AEL

2007-09-04T13:11:43Z

Summary:

Over time, people have been pushing to add features to extensions.conf to make it more like a programming language. AEL is intended to provide an actual programming language that can be used to write an Asterisk dialplan.

Getting Started
----
The AEL parser (pbx_ael.so) is completely separate from the module that parses extensions.conf (pbx_config.so). To use AEL, the only thing that has to be done is the module pbx_ael.so must be loaded by Asterisk. This will be done automatically if using 'autoload=yes' in etc/asterisk/modules.conf.

When the module is loaded, it will look for 'extensions.ael' in /etc/asterisk/. Both extensions.conf and extensions.ael can be used in conjunction with each other if that is what is desired. Some users may want to keep extensions.conf for the features that are configured in the 'general' section of
extensions.conf.

Reloading extensions.ael

To reload extensions.ael, the following command can be issued at the CLI.

*CLI> reload pbx_ael.so

<pre>
Contexts

Contexts in AEL represent a set of extensions in the same way that they do
in extensions.conf.

context default {
};

Extensions

To specify an extension in a context, the following syntax is used. If more
than one application is be called in an extension, they can be listed in order
inside of a block.

context default {
1234 => Playback(tt-monkeys);
8000 => {
NoOp(one);
NoOp(two);
NoOp(three);
};
_5XXX => NoOp(it's a pattern!);
};

Includes

Contexts can be included in other contexts. All included contexts are listed
within a single block.

context default {
includes {
local;
longdistance;
international;
};
};

Dialplan Switches

Switches are listed in their own block within a context.

context default {
switches {
DUNDi/e164;
IAX2/box5;
};
eswitches {
IAX2/context@${CURSERVER};
};
};

Ignorepat

ignorepat can be used to instruct channel drivers to not cancel dialtone upon
receipt of a particular pattern. The most commonly used example is '9'.

context outgoing {
ignorepat => 9;
};

Variables

Variables in Asterisk do not have a type, so to define a variable, it just has
to be specified with a value.

Global variables are set in their own block.

globals {
CONSOLE=Console/dsp;
TRUNK=Zap/g2;
};

Variables can be set within extensions as well.

context foo {
555 => {
x=5;
y=blah;
NoOp(x is ${x} and y is ${y} !);
};
};

Writing to a dialplan function is treated the same as writing to a variable.

context blah {
s => {
CALLERID(name)=ChickenMan;
NoOp(My name is ${CALLERID(name)} !);
};
};

Loops

AEL has implementations of 'for' and 'while' loops.

context loops {
1 => {
for (x=0; ${x} < 3; x=${x} + 1) {
Verbose(x is ${x} !);
};
};
2 => {
y=10;
while (${y} >= 0) {
Verbose(y is ${y} !);
y=${y}-1;
};
};
};

Conditionals

AEL supports if and switch statements. Note that if you have an else
clause, you MUST place braces around the non-else portion of the if
statement.

context conditional {
_8XXX => {
Dial(SIP/${EXTEN});
if (${DIALSTATUS} = "BUSY") {
Voicemail(${EXTEN}|b);
} else
Voicemail(${EXTEN}|u);
};
_777X => {
switch (${EXTEN}) {
case 7771:
NoOp(You called 7771!);
break;
case 7772:
NoOp(You called 7772!);
break;
case 7773:
NoOp(You called 7773!);
// fall through
default:
NoOp(In the default clause!);
};
};
};

goto and labels

This is an example of how to do a goto in AEL.

context gotoexample {
s => {
begin:
NoOp(Infinite Loop! yay!);
Wait(1);
goto begin;
};
};

Macros

A macro is defined in its own block like this. The arguments to the macro are
specified with the name of the macro. They are then reffered to by that same
name. A catch block can be specified to catch special extensions.

macro std-exten( ext , dev ) {
Dial(${dev}/${ext},20);
switch(${DIALSTATUS) {
case BUSY:
Voicemail(b${ext});
break;
default:
Voicemail(u${ext});
};
catch a {
VoiceMailMain(${ext});
return;
};
};

A macro is then called by preceeding the macro name with an ampersand.

context example {
_5XXX => &std-exten(${EXTEN}, "IAX2");
};

Examples

context demo {
s => {
Wait(1);
Answer();
TIMEOUT(digit)=5;
TIMEOUT(response)=10;
restart:
Background(demo-congrats);
instructions:
for (x=0; ${x} < 3; x=${x} + 1) {
Background(demo-instruct);
WaitExten();
};
};
2 => {
Background(demo-moreinfo);
goto s|instructions;
};
3 => {
LANGUAGE()=fr;
goto s|restart;
};
500 => {
Playback(demo-abouttotry);
Dial(IAX2/guest@misery.digium.com);
Playback(demo-nogo);
goto s|instructions;
};
600 => {
Playback(demo-echotest);
Echo();
Playback(demo-echodone);
goto s|instructions;
};
# => {
hangup:
Playback(demo-thanks);
Hangup();
};
t => goto #|hangup;
i => Playback(invalid);
};

</pre>

'''Syntax Note'''

Please note that all opening {'s are on the same line as the keyword. For the time being, that syntax is mandatory. We are looking at ways to allow other syntax in the future for flexibility, but for now, that is the way you must write AEL clauses.

Asterisk Bookshelf

2007-09-04T12:43:20Z

Summary:

[[image:asterisk-logo.gif|left|Asterisk]]
__NOEDITSECTION__
{| align="right"
| __TOC__
|}

; Asterisk Bookshelf : '''Index From Asterisk Main To Zapata'''
 
: The Asterisk Open Source PBX by Mark Spencer and the Asterisk.org developer community.
: Copyright (C) 2001-2005 Digium, Inc. and other copyright holders.

----
==[[Asterisk Main]]==
; Asterisk Main Configuration

==[[Asterisk configuration parser]]==
; The Asterisk configuration parser

==[[AEL]]==
; The Asterisk Extension Language : AEL is intended to provide an actual programming language that can be used to write an Asterisk dialplan

==[[Backtraces]]==
; how to obtain the backtraces required on the asterisk bug tracker

==[[CDR]]==
;Asterisk billing support - Call Detail Records : Call data records can be stored in many different databases or even CSV text

==[[Channel]]==
; Implementing a Channel : A channel unit who brings a call to the Asterisk PBX

==[[CLI]]==
; Changing the CLI Prompt : The CLI prompt is set with the ASTERISK_PROMPT UNIX environment variable that you set from the Unix shell before starting Asterisk

==[[DUNDi]]==
; Distributed Universal Number Directory (tm) : is essentially a trusted, peer-to-peer system for being able to call any phone number from the Internet

==[[ENUM]]==
; consideration of ENUM or ENUM-like lookup strategies

==[[Extconfig]]==
; Asterisk external configuration : The Asterisk external configuration engine is the result of work by Anthony Minessale II, Mark Spencer and Constantine Filin

==[[Extensions]]==
;The Asterisk dialplan : extensions.conf

==[[Externalivr]]==
; Asterisk External IVR Interface : External Interactive Voice Recording

==[[Features]]==
; Asterisk features as well Parking call-pickup and more

==[[H.323]]==
; The Asterisk PBX supports H.323 via two totally separate channel drivers

==[[IAX]]==
; Inter-Asterisk eXchange Protocol

==[[Jitterbuffer]]==
; Jitterbuffer in Asterisk : The LPC jitterbuffer is to implement it in IAX and SIP/RTP

==[[localchannel]]==
; The Local channel : The Local channel construct simply loops calls back used to establish dialing into any part of the dialplan

==[[Logging]]==
; logging to files or to the syslog system

==[[Mathematical]]==
; Mathematical dialplan function

==[[Manager]]==
; The Asterisk Manager TCP/IP API - AMI : The Manager interface is a client/server model over TCP and will be able to control the PBX as well as execute Asterisk commands

==[[MeetMe]]==
; MeetMe simple conference rooms for Asterisk of course

==[[mISDN]]==
; mISDN Channel Driver for Asterisk PBX : Modular ISDN Channel Driver

==[[Modules]]==
; Asterisk module configuration

==[[MP3]]==
; Asterisk MP3 Support

==[[ODBC]]==
; ODBC Voicemail Storage

==[[Queue]]==
; Queue Log Information : In order to properly manage ACD queues

==[[SIP]]==
; SIP Configuration example for Asterisk

==[[SMS]]==
; The SMS application

==[[Voicemail]]==
; Voicemail Configuration

==[[Variables]]==
; Asterisk dial plan variables

==[[Zapata]]==
; Zapata telephony interface : Zaptel configuration