diff options
| author | russell <russell@f38db490-d61c-443f-a65b-d21fe96a405b> | 2007-03-16 01:41:00 +0000 |
|---|---|---|
| committer | russell <russell@f38db490-d61c-443f-a65b-d21fe96a405b> | 2007-03-16 01:41:00 +0000 |
| commit | dbddd24443348c19c79e9d85f40d2aa429d0d885 (patch) | |
| tree | f88f0d9ea78ee8991946a97d9f7bfb720132ec4f /doc | |
| parent | b2830ad62612116f801a7ea10e8584a1bef42af0 (diff) | |
Making these documentation changes in the 1.4 branch upset various people, so
these chanes will only be done in the trunk.
git-svn-id: http://svn.digium.com/svn/asterisk/branches/1.4@58955 f38db490-d61c-443f-a65b-d21fe96a405b
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/00README.1st | 74 | ||||
| -rw-r--r-- | doc/PEERING | 4 | ||||
| -rw-r--r-- | doc/ael.txt (renamed from doc/ael.tex) | 478 | ||||
| -rw-r--r-- | doc/ajam.txt (renamed from doc/ajam.tex) | 38 | ||||
| -rw-r--r-- | doc/app-sms.txt (renamed from doc/app-sms.tex) | 93 | ||||
| -rw-r--r-- | doc/apps.txt | 10 | ||||
| -rw-r--r-- | doc/ast_appdocs.tex | 3312 | ||||
| -rw-r--r-- | doc/asterisk-conf.tex | 130 | ||||
| -rw-r--r-- | doc/asterisk-conf.txt | 83 | ||||
| -rw-r--r-- | doc/asterisk.tex | 134 | ||||
| -rw-r--r-- | doc/billing.tex | 87 | ||||
| -rw-r--r-- | doc/billing.txt | 105 | ||||
| -rw-r--r-- | doc/callingpres.txt | 18 | ||||
| -rw-r--r-- | doc/cdrdriver.tex | 431 | ||||
| -rw-r--r-- | doc/cdrdriver.txt | 215 | ||||
| -rw-r--r-- | doc/chaniax.tex | 84 | ||||
| -rw-r--r-- | doc/chaniax.txt | 369 | ||||
| -rw-r--r-- | doc/channels.txt | 44 | ||||
| -rw-r--r-- | doc/channelvariables.txt (renamed from doc/channelvariables.tex) | 364 | ||||
| -rw-r--r-- | doc/cliprompt.txt (renamed from doc/cliprompt.tex) | 19 | ||||
| -rw-r--r-- | doc/configuration.txt (renamed from doc/configuration.tex) | 72 | ||||
| -rw-r--r-- | doc/cygwin.txt | 9 | ||||
| -rw-r--r-- | doc/dundi.txt (renamed from doc/dundi.tex) | 4 | ||||
| -rw-r--r-- | doc/enum.txt (renamed from doc/enum.tex) | 143 | ||||
| -rw-r--r-- | doc/extconfig.txt | 91 | ||||
| -rw-r--r-- | doc/extensions.txt (renamed from doc/extensions.tex) | 48 | ||||
| -rw-r--r-- | doc/freetds.txt (renamed from doc/freetds.tex) | 8 | ||||
| -rw-r--r-- | doc/h323.txt | 22 | ||||
| -rw-r--r-- | doc/hardware.tex | 100 | ||||
| -rw-r--r-- | doc/hardware.txt | 74 | ||||
| -rw-r--r-- | doc/iax.txt | 67 | ||||
| -rw-r--r-- | doc/ices.txt (renamed from doc/ices.tex) | 9 | ||||
| -rw-r--r-- | doc/imapstorage.txt (renamed from doc/imapstorage.tex) | 114 | ||||
| -rw-r--r-- | doc/ip-tos.txt (renamed from doc/ip-tos.tex) | 34 | ||||
| -rw-r--r-- | doc/jitterbuffer.txt (renamed from doc/jitterbuffer.tex) | 99 | ||||
| -rw-r--r-- | doc/linkedlists.txt | 98 | ||||
| -rw-r--r-- | doc/localchannel.txt (renamed from doc/localchannel.tex) | 30 | ||||
| -rw-r--r-- | doc/manager.txt (renamed from doc/manager.tex) | 107 | ||||
| -rw-r--r-- | doc/math.txt | 69 | ||||
| -rw-r--r-- | doc/misdn.txt (renamed from doc/misdn.tex) | 189 | ||||
| -rw-r--r-- | doc/model.txt | 15 | ||||
| -rw-r--r-- | doc/mp3.txt (renamed from doc/mp3.tex) | 4 | ||||
| -rw-r--r-- | doc/musiconhold-fpm.txt | 8 | ||||
| -rw-r--r-- | doc/mysql.txt | 15 | ||||
| -rw-r--r-- | doc/odbcstorage.txt (renamed from doc/odbcstorage.tex) | 9 | ||||
| -rw-r--r-- | doc/privacy.txt (renamed from doc/privacy.tex) | 82 | ||||
| -rw-r--r-- | doc/queuelog.txt (renamed from doc/queuelog.tex) | 7 | ||||
| -rw-r--r-- | doc/queues-with-callback-members.txt (renamed from doc/queues-with-callback-members.tex) | 91 | ||||
| -rw-r--r-- | doc/radius.txt | 203 | ||||
| -rw-r--r-- | doc/realtime.txt (renamed from doc/realtime.tex) | 74 | ||||
| -rw-r--r-- | doc/security.txt (renamed from doc/security.tex) | 13 | ||||
| -rw-r--r-- | doc/sla.pdf | bin | 0 -> 68499 bytes | |||
| -rw-r--r-- | doc/sla.tex | 16 |
53 files changed, 2732 insertions, 5284 deletions
diff --git a/doc/00README.1st b/doc/00README.1st new file mode 100644 index 000000000..c006d56a8 --- /dev/null +++ b/doc/00README.1st @@ -0,0 +1,74 @@ +Files in the /doc directory: +---------------------------- +In addition to these files, there is a lot of documentation of various +configuration options in the sample configuration files, in the /configs +directory of your source code + +Start here +---------- +security.txt IMPORTANT INFORMATION ABOUT ASTERISK SECURITY +hardware.txt Hardware supported by Asterisk + +Configuration +------------- +configuration.txt Features in the configuration parser +extensions.txt Basics about the dialplan +extconfig.txt How to use databases for configuration of Asterisk (ARA) +ip-tos.txt About the IP Type Of Service settings +realtime.txt The Asterisk Realtime Architecture - database support +freetds.txt Information about the FreeTDS support +ael.txt Information about the Asterisk Extension Language + +Misc +---- +PEERING The General Peering Agreement for Dundi +ajam.txt About the HTTP-based manager interface +app_sms.txt How to configure the SMS application +asterisk.conf.txt Documentation of various options in asterisk.conf +callingpres.txt Settings for Caller ID presentation +billing.txt Call Data Record information +cliprompt.txt How to change the Asterisk CLI prompt +dundi.txt Dundi - a discovery protocol +enum.txt Enum support in Asterisk +ices.txt Integrating ICEcast streaming in Asterisk +jitterbuffer.txt About the IAX2 jitterbuffer implementation +math.txt About the math() application +mp3.txt About MP3 support in Asterisk +musiconhold-fpm.txt Free Music On Hold music +mysql.txt About MYSQL support in Asterisk +odbcstorage.txt Voicemail storage of messages in UnixODBC +privacy.txt Privacy enhancements in Asterisk +queuelog.txt Agent and queue logging +channelvariables.txt Channel variables +cdrdrivers.txt About CDR storage in various databases (needs update) +asterisk-mib.txt SNMP mib for Asterisk (net-snmp) +digium-mib.txt SNMP mib for Asterisk (net-snmp) + +Channel drivers +--------------- +misdn.txt The mISDN channel driver for ISDN BRI cards +h323.txt How to compile and configure the H.323 channel +chaniax.txt About the IAX2 protocol support in Asterisk +localchannel.txt The local channel is a "gosub" in the dialplan + +Portability +----------- +cygwin.txt Compiling Asterisk on CygWin platforms (Windows) + +For developers +-------------- +See http://www.asterisk.org/developers for more information + +manager.txt About the AMI - Asterisk Manager Interface + for third party call control and PBX management +backtrace.txt How to produce a backtrace when Asterisk crashes +CODING-GUIDELINES Guidelines for developers +channels.txt What is a channel? +externalivr.txt Documentation of the protocol used in externalivr() +linkedlists.txt How to develop linked lists in Asterisk (old) +iax.txt About the IAX protocol +apps.txt About application development +model.txt About the call model in Asterisk (old) +modules.txt How Asterisk modules work +datastores.txt About channel data stores +speechrec.txt The Generic Speech Recognition API diff --git a/doc/PEERING b/doc/PEERING index ba05ffb9c..c1f0b3831 100644 --- a/doc/PEERING +++ b/doc/PEERING @@ -1,5 +1,3 @@ -\begin{verbatim} - DIGIUM GENERAL PEERING AGREEMENT (TM) Version 1.0.0, September 2004 Copyright (C) 2004 Digium, Inc. @@ -499,5 +497,3 @@ member of the Peering System and be able to make Routes available in accordance with this GPA. DUNDi, IAX, Asterisk and GPA are trademarks of Digium, Inc. - -\end{verbatim} diff --git a/doc/ael.tex b/doc/ael.txt index d675190cc..f72f2805b 100644 --- a/doc/ael.tex +++ b/doc/ael.txt @@ -1,4 +1,5 @@ -\section{Introduction} +The Asterisk Extension Language - v 2 +===================================== AEL is a specialized language intended purely for describing Asterisk dial plans. @@ -12,22 +13,21 @@ functionality. AEL is really the merger of 4 different 'languages', or syntaxes: -\begin{itemize} - \item The first and most obvious is the AEL syntax itself. A BNF is + * The first and most obvious is the AEL syntax itself. A BNF is provided near the end of this document. - \item The second syntax is the Expression Syntax, which is normally + * The second syntax is the Expression Syntax, which is normally handled by Asterisk extension engine, as expressions enclosed in - \$[...]. The right hand side of assignments are wrapped in \$[ ... ] + $[...]. The right hand side of assignments are wrapped in $[ ... ] by AEL, and so are the if and while expressions, among others. - \item The third syntax is the Variable Reference Syntax, the stuff - enclosed in \${..} curly braces. It's a bit more involved than just + * The third syntax is the Variable Reference Syntax, the stuff + enclosed in ${..} curly braces. It's a bit more involved than just putting a variable name in there. You can include one of dozens of 'functions', and their arguments, and there are even some string manipulation notation in there. - \item The last syntax that underlies AEL, and is not used + * The last syntax that underlies AEL, and is not used directly in AEL, is the Extension Language Syntax. The extension language is what you see in extensions.conf, and AEL compiles the higher level AEL language into extensions and @@ -36,13 +36,14 @@ AEL is really the merger of 4 different 'languages', or syntaxes: commands, of which one application call per step, or priority can be made. You can think of this as a "macro assembler" language, that AEL will compile into. -\end{itemize} + Any programmer of AEL should be familiar with it's syntax, of course, as well as the Expression syntax, and the Variable syntax. - -\section{Asterisk in a Nutshell} +************************** +* Asterisk in a Nutshell * +************************** Asterisk acts as a server. Devices involved in telephony, like Zapata cards, or Voip phones, all indicate some context that should be @@ -51,7 +52,8 @@ zapata.conf, etc. They all help describe a device, and they all specify a context to activate when somebody picks up a phone, or a call comes in from the phone company, or a voip phone, etc. -\subsection{Contexts} +Contexts +-------- Contexts are a grouping of extensions. @@ -59,7 +61,8 @@ Contexts can also include other contexts. Think of it as a sort of merge operation at runtime, whereby the included context's extensions are added to the contexts making the inclusion. -\subsection{Extensions and priorities} +Extensions and priorities +------------------------- A Context contains zero or more Extensions. There are several predefined extensions. The "s" extension is the "start" extension, and @@ -91,7 +94,8 @@ The extensions can also contain "goto" or "jump" commands to skip to extensions in other contexts. Conditionals provide the ability to react to different stimuli, and there you have it. -\subsection{Macros} +Macros +------ Think of a macro as a combination of a context with one nameless extension, and a subroutine. It has arguments like a subroutine @@ -100,7 +104,8 @@ individual statements there are executed until it ends. At this point, execution returns to the next statement after the macro call. Macros can call other macros. And they work just like function calls. -\subsection{Applications} +Applications +------------ Application calls, like "Dial()", or "Hangup()", or "Answer()", are available for users to use to accomplish the work of the @@ -112,11 +117,14 @@ services. Hopefully, the above objects will allow you do anything you need to in the Asterisk environment! -\section{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 +******************* +* 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/. extensions.conf and @@ -125,7 +133,9 @@ 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 +------------------------------ +- Reloading extensions.ael - +------------------------------ To reload extensions.ael, the following command can be issued at the CLI: @@ -133,7 +143,10 @@ CLI: *CLI> ael reload -\section{Debugging} + +************* +* Debugging * +************* Right at this moment, the following commands are available, but do nothing: @@ -161,7 +174,9 @@ facilities to debug your file: 3. the standalone executable, "aelparse" built in the utils/ dir in the source. -\section{About "aelparse"} +***************************** +* About "aelparse" * +***************************** You can use the "aelparse" program to check your extensions.ael file before feeding it to asterisk. Wouldn't it be nice to eliminate @@ -173,24 +188,20 @@ spot in your PATH. aelparse has two optional arguments: -\begin{itemize} - \item -d - \begin{itemize} - \item Override the normal location of the config file dir, (usually +-d - Override the normal location of the config file dir, (usually /etc/asterisk), and use the current directory instead as the config file dir. Aelparse will then expect to find the file "./extensions.ael" in the current directory, and any included files in the current directory as well. - \end{itemize} - \item -n - \begin{itemize} - \item don't show all the function calls to set priorities and contexts + +-n - don't show all the function calls to set priorities and contexts within asterisk. It will just show the errors and warnings from the parsing and semantic checking phases. - \end{itemize} -\end{itemize} -\section{General Notes about Syntax} + +****************************** +* General Notes about Syntax * +****************************** Note that the syntax and style are now a little more free-form. The opening '{' (curly-braces) do not have to be on the same line as the @@ -200,13 +211,10 @@ be included on a single line. Whatever you think is best! You can just as easily say, -\begin{verbatim} if(${x}=1) { NoOp(hello!); goto s|3; } else { NoOp(Goodbye!); goto s|12; } -\end{verbatim} as you can say: -\begin{verbatim} if(${x}=1) { NoOp(hello!); @@ -217,11 +225,9 @@ else NoOp(Goodbye!); goto s|12; } -\end{verbatim} or: -\begin{verbatim} if(${x}=1) { NoOp(hello!); goto s|3; @@ -229,19 +235,33 @@ if(${x}=1) { NoOp(Goodbye!); goto s|12; } -\end{verbatim} or: -\begin{verbatim} if (${x}=1) { NoOp(hello!); goto s|3; } else { NoOp(Goodbye!); goto s|12; } -\end{verbatim} -\section{Keywords} +or even: + +if +(${x}=1) +{ +NoOp(hello!); +goto s|3; +} +else +{ +NoOp(Goodbye!); +goto s|12; +} + + +************ +* Keywords * +************ The AEL keywords are case-sensitive. If an application name and a keyword overlap, there is probably good reason, and you should @@ -251,38 +271,41 @@ capitalized letter somewhere in its name. In the Asterisk extension language, application names are NOT case-sensitive. The following are keywords in the AEL language: -\begin{itemize} - \item abstract - \item context - \item macro - \item globals - \item ignorepat - \item switch - \item if - \item ifTime - \item else - \item random - \item goto - \item jump - \item return - \item break - \item continue - \item regexten - \item hint - \item for - \item while - \item case - \item pattern - \item default NOTE: the "default" keyword can be used as a context name, + + * abstract + * context + * macro + * globals + * ignorepat + * switch + * if + * ifTime + * else + * random + * goto + * jump + * return + * break + * continue + * regexten + * hint + * for + * while + * case + * pattern + * default NOTE: the "default" keyword can be used as a context name, for those who would like to do so. - \item catch - \item switches - \item eswitches - \item includes -\end{itemize} + * catch + * switches + * eswitches + * includes + -\section{Procedural Interface and Internals} + + +Procedural Interface and Internals +================================== AEL first parses the extensions.ael file into a memory structure representing the file. The entire file is represented by a tree of "pval" structures linked together. @@ -300,19 +323,25 @@ asterisk dialplan. The modularity of the design offers several opportunities for developers to simplify apps to generate dialplan data. -\subsection{AEL version 2 BNF} + +========================= + AEL version 2 BNF +========================= + + (hopefully, something close to bnf). First, some basic objects -\begin{verbatim} ------------------------ + <word> a lexical token consisting of characters matching this pattern: [-a-zA-Z0-9"_/.\<\>\*\+!$#\[\]][-a-zA-Z0-9"_/.!\*\+\<\>\{\}$#\[\]]* <word3-list> a concatenation of up to 3 <word>s. <collected-word> all characters encountered until the character that follows the <collected-word> in the grammar. + ------------------------- <file> :== <objects> @@ -488,27 +517,29 @@ First, some basic objects <includes> :== 'includes' '{' <includeslist> '}' | 'includes' '{' '}' -\end{verbatim} +************************** +* AEL Example USAGE ***** +************************** -\section{AEL Example USAGE} - -\subsection{Comments} +Comments +======== Comments begin with // and end with the end of the line. Comments are removed by the lexical scanner, and will not be recognized in places where it is busy gathering expressions to wrap in -\$[] , or inside application call argument lists. The safest place to put +$[] , or inside application call argument lists. The safest place to put comments is after terminating semicolons, or on otherwise empty lines. -\subsection{Context} +Context +======= Contexts in AEL represent a set of extensions in the same way that they do in extensions.conf. -\begin{verbatim} + context default { } @@ -520,20 +551,21 @@ only be included by another context, and not "stand on its own". The current effect of this keyword is to prevent "goto " statements from being checked. -\begin{verbatim} + abstract context longdist { - _1NXXNXXXXXX => NoOp(generic long distance dialing actions in the US); + _1NXXNXXXXXX => NoOp(generic long distance dialing actions in the US); } -\end{verbatim} -\subsection{Extensions} + +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. -\begin{verbatim} + context default { 1234 => Playback(tt-monkeys); 8000 => { @@ -543,7 +575,7 @@ context default { }; _5XXX => NoOp(it's a pattern!); } -\end{verbatim} + Two optional items have been added to the AEL syntax, that allow the specification of hints, and a keyword, regexten, that will force the @@ -552,38 +584,36 @@ numbering of priorities to start at 2. The ability to make extensions match by CID is preserved in AEL; just use '/' and the CID number in the specification. See below. -\begin{verbatim} + context default { regexten _5XXX => NoOp(it's a pattern!); } -\end{verbatim} -\begin{verbatim} + + context default { hint(Sip/1) _5XXX => NoOp(it's a pattern!); } -\end{verbatim} -\begin{verbatim} + + context default { regexten hint(Sip/1) _5XXX => NoOp(it's a pattern!); } -\end{verbatim} + The regexten must come before the hint if they are both present. CID matching is done as with the extensions.conf file. Follow the extension name/number with a slash (/) and the number to match against the Caller ID: -\begin{verbatim} context zoombo { 819/7079953345 => { NoOp(hello, 3345); } } -\end{verbatim} In the above, the 819/7079953345 extension will only be matched if the CallerID is 7079953345, and the dialed number is 819. Hopefully you have @@ -591,12 +621,13 @@ another 819 extension defined for all those who wish 819, that are not so lucky as to have 7079953345 as their CallerID! -\subsection{Includes} +Includes +======== Contexts can be included in other contexts. All included contexts are listed within a single block. -\begin{verbatim} + context default { includes { local; @@ -604,13 +635,13 @@ context default { international; } } -\end{verbatim} + Time-limited inclusions can be specified, as in extensions.conf format, with the fields described in the wiki page Asterisk cmd GotoIfTime. -\begin{verbatim} + context default { includes { local; @@ -618,19 +649,20 @@ context default { international; } } -\end{verbatim} -\subsection{\#include} -You can include other files with the \#include "filepath" construct. +#include +======== + +You can include other files with the #include "filepath" construct. + -\begin{verbatim} #include "/etc/asterisk/testfor.ael" -\end{verbatim} -An interesting property of the \#include, is that you can use it almost + +An interesting property of the #include, is that you can use it almost anywhere in the .ael file. It is possible to include the contents of -a file in a macro, context, or even extension. The \#include does not +a file in a macro, context, or even extension. The #include does not have to occur at the beginning of a line. Included files can include other files, up to 50 levels deep. If the path provided in quotes is a relative path, the parser looks in the config file directory for the @@ -638,13 +670,14 @@ file (usually /etc/asterisk). -\subsection{Dialplan Switches} +Dialplan Switches +================= Switches are listed in their own block within a context. For clues as to what these are used for, see Asterisk - dual servers, and Asterisk config extensions.conf. -\begin{verbatim} + context default { switches { DUNDi/e164; @@ -654,40 +687,43 @@ context default { IAX2/context@${CURSERVER}; } } -\end{verbatim} -\subsection{Ignorepat} + +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'. -\begin{verbatim} + context outgoing { ignorepat => 9; } -\end{verbatim} -\subsection{Variables} + + +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. -\begin{verbatim} + globals { CONSOLE=Console/dsp; TRUNK=Zap/g2; } -\end{verbatim} + Variables can be set within extensions as well. -\begin{verbatim} + context foo { 555 => { x=5; @@ -696,35 +732,36 @@ context foo { NoOp(x is ${x} and y is ${y} !); } } -\end{verbatim} -NOTE: AEL wraps the right hand side of an assignment with \$[ ] to allow + +NOTE: AEL wraps the right hand side of an assignment with $[ ] to allow expressions to be used If this is unwanted, you can protect the right hand side from being wrapped by using the Set() application. Read the README.variables about the requirements and behavior -of \$[ ] expressions. +of $[ ] expressions. -NOTE: These things are wrapped up in a \$[ ] expression: The while() test; +NOTE: These things are wrapped up in a $[ ] expression: The while() test; the if() test; the middle expression in the for( x; y; z) statement -(the y expression); Assignments - the right hand side, so a = b -> Set(a=\$[b]) +(the y expression); Assignments - the right hand side, so a = b -> Set(a=$[b]) Writing to a dialplan function is treated the same as writing to a variable. -\begin{verbatim} + context blah { s => { CALLERID(name)=ChickenMan; NoOp(My name is ${CALLERID(name)} !); } } -\end{verbatim} -\subsection{Loops} + +Loops +===== AEL has implementations of 'for' and 'while' loops. -\begin{verbatim} + context loops { 1 => { for (x=0; ${x} < 3; x=${x} + 1) { @@ -739,15 +776,16 @@ context loops { } } } -\end{verbatim} -NOTE: The conditional expression (the "\${y} >= 0" above) is wrapped in - \$[ ] so it can be evaluated. NOTE: The for loop test expression - (the "\${x} < 3" above) is wrapped in \$[ ] so it can be evaluated. +NOTE: The conditional expression (the "${y} >= 0" above) is wrapped in + $[ ] so it can be evaluated. NOTE: The for loop test expression + (the "${x} < 3" above) is wrapped in $[ ] so it can be evaluated. -\subsection{Conditionals} + +Conditionals +============ AEL supports if and switch statements, like AEL, but adds ifTime, and random. Unlike the original AEL, though, you do NOT need to put curly @@ -755,7 +793,7 @@ braces around a single statement in the "true" branch of an if(), the random(), or an ifTime() statement. The if(), ifTime(), and random() statements allow optional else clause. -\begin{verbatim} + context conditional { _8XXX => { Dial(SIP/${EXTEN}); @@ -809,14 +847,14 @@ context conditional { } } } -\end{verbatim} + NOTE: The conditional expression in if() statements (the - "\${DIALSTATUS}" = "BUSY" above) is wrapped by the compiler in - \$[] for evaluation. + "${DIALSTATUS}" = "BUSY" above) is wrapped by the compiler in + $[] for evaluation. -NOTE: Neither the switch nor case values are wrapped in \$[ ]; they can - be constants, or \${var} type references only. +NOTE: Neither the switch nor case values are wrapped in $[ ]; they can + be constants, or ${var} type references only. NOTE: AEL generates each case as a separate extension. case clauses with no terminating 'break', or 'goto', have a goto inserted, to @@ -828,7 +866,7 @@ NOTE: AEL introduces the ifTime keyword/statement, which works just Asterisk cmd GotoIfTime NOTE: The pattern statement makes sure the new extension that is - created has an '\_' preceding it to make sure asterisk recognizes + created has an '_' preceding it to make sure asterisk recognizes the extension name as a pattern. NOTE: Every character enclosed by the switch expression's parenthesis @@ -840,7 +878,9 @@ NOTE: NEW: Previous to version 0.13, the random statement used the the RAND() function instead, in the GotoIf application. -\subsection{Break, Continue, and Return} +Break, Continue, and Return +=========================== + Three keywords, break, continue, and return, are included in the syntax to provide flow of control to loops, and switches. @@ -858,11 +898,12 @@ context, or macro, and can be used anywhere. -\subsection{goto, jump, and labels} +goto, jump, and labels +====================== This is an example of how to do a goto in AEL. -\begin{verbatim} + context gotoexample { s => { begin: @@ -884,7 +925,6 @@ context gotoexample2 { goto gotoexample|s|begin; // go to label in different context } } -\end{verbatim} You can use the special label of "1" in the goto and jump statements. It means the "first" statement in the extension. I would @@ -898,7 +938,7 @@ extension[,priority][@context] If priority is absent, it defaults to "1". If context is not present, it is assumed to be the same as that which contains the "jump". -\begin{verbatim} + context gotoexample { s => { begin: @@ -920,7 +960,6 @@ context gotoexample2 { jump s@gotoexample; // go to label in different context } } -\end{verbatim} NOTE: goto labels follow the same requirements as the Goto() application, except the last value has to be a label. If the @@ -941,14 +980,15 @@ NOTE: A NEW addition to AEL: you can now use ',' instead of '|' to -\subsection{Macros} +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 referred to by that same name. A catch block can be specified to catch special extensions. -\begin{verbatim} + macro std-exten( ext , dev ) { Dial(${dev}/${ext},20); switch(${DIALSTATUS) { @@ -964,25 +1004,26 @@ macro std-exten( ext , dev ) { return; } } -\end{verbatim} + A macro is then called by preceding the macro name with an ampersand. Empty arguments can be passed simply with nothing between comments(0.11). -\begin{verbatim} + context example { _5XXX => &std-exten(${EXTEN}, "IAX2"); _6XXX => &std-exten(, "IAX2"); _7XXX => &std-exten(${EXTEN},); _8XXX => &std-exten(,); } -\end{verbatim} -\section{Examples} -\begin{verbatim} +Examples +======== + + context demo { s => { Wait(1); @@ -1026,121 +1067,117 @@ hangup: t => goto #|hangup; i => Playback(invalid); } -\end{verbatim} -\section{Semantic Checks} +Semantic Checks +=============== AEL, after parsing, but before compiling, traverses the dialplan tree, and makes several checks: -\begin{itemize} - \item Macro calls to non-existent macros. - \item Macro calls to contexts. - \item Macro calls with argument count not matching the definition. - \item application call to macro. (missing the '\&') - \item application calls to "GotoIf", "GotoIfTime", "while", + * Macro calls to non-existent macros. + * Macro calls to contexts. + * Macro calls with argument count not matching the definition. + * application call to macro. (missing the '&') + * application calls to "GotoIf", "GotoIfTime", "while", "endwhile", "Random", and "execIf", will generate a message to consider converting the call to AEL goto, while, etc. constructs. - \item goto a label in an empty extension. - \item goto a non-existent label, either a within-extension, + * goto a label in an empty extension. + * goto a non-existent label, either a within-extension, within-context, or in a different context, or in any included contexts. Will even check "sister" context references. - \item All the checks done on the time values in the dial plan, are + * All the checks done on the time values in the dial plan, are done on the time values in the ifTime() and includes times: o the time range has to have two times separated by a dash; o the times have to be in range of 0 to 24 hours. o The weekdays have to match the internal list, if they are provided; o the day of the month, if provided, must be in range of 1 to 31; o the month name or names have to match those in the internal list. - \item (0.5) If an expression is wrapped in \$[ ... ], and the compiler + * (0.5) If an expression is wrapped in $[ ... ], and the compiler will wrap it again, a warning is issued. - \item (0.5) If an expression had operators (you know, - +,-,*,/,%,!,etc), but no \${ } variables, a warning is + * (0.5) If an expression had operators (you know, + +,-,*,/,%,!,etc), but no ${ } variables, a warning is issued. Maybe someone forgot to wrap a variable name? - \item (0.12) check for duplicate context names. - \item (0.12) check for abstract contexts that are not included by any context. - \item (0.13) Issue a warning if a label is a numeric value. -\end{itemize} + * (0.12) check for duplicate context names. + * (0.12) check for abstract contexts that are not included by any context. + * (0.13) Issue a warning if a label is a numeric value. There are a subset of checks that have been removed until the proposed AAL (Asterisk Argument Language) is developed and incorporated into Asterisk. These checks will be: -\begin{itemize} - \item (if the application argument analyzer is working: the presence + * (if the application argument analyzer is working: the presence of the 'j' option is reported as error. - \item if options are specified, that are not available in an + * if options are specified, that are not available in an application. - \item if you specify too many arguments to an application. - \item a required argument is not present in an application call. - \item Switch-case using "known" variables that applications set, that + * if you specify too many arguments to an application. + * a required argument is not present in an application call. + * Switch-case using "known" variables that applications set, that does not cover all the possible values. (a "default" case will solve this problem. Each "unhandled" value is listed. - \item a Switch construct is used, which is uses a known variable, and + * a Switch construct is used, which is uses a known variable, and the application that would set that variable is not called in the same extension. This is a warning only... - \item Calls to applications not in the "applist" database (installed + * Calls to applications not in the "applist" database (installed in /var/lib/asterisk/applist" on most systems). - \item In an assignment statement, if the assignment is to a function, + * In an assignment statement, if the assignment is to a function, the function name used is checked to see if it one of the currently known functions. A warning is issued if it is not. -\end{itemize} + Differences with the original version of AEL ============================================ -\begin{enumerate} - \item The \$[...] expressions have been enhanced to include the ==, ||, - and \&\& operators. These operators are exactly equivalent to the - =, |, and \& operators, respectively. Why? So the C, Java, C++ + 1. The $[...] expressions have been enhanced to include the ==, ||, + and && operators. These operators are exactly equivalent to the + =, |, and & operators, respectively. Why? So the C, Java, C++ hackers feel at home here. - \item It is more free-form. The newline character means very little, + 2. It is more free-form. The newline character means very little, and is pulled out of the white-space only for line numbers in error messages. - \item It generates more error messages -- by this I mean that any + 3. It generates more error messages -- by this I mean that any difference between the input and the grammar are reported, by file, line number, and column. - \item It checks the contents of \$[ ] expressions (or what will end up - being \$[ ] expressions!) for syntax errors. It also does + 4. It checks the contents of $[ ] expressions (or what will end up + being $[ ] expressions!) for syntax errors. It also does matching paren/bracket counts. - \item It runs several semantic checks after the parsing is over, but + 5. It runs several semantic checks after the parsing is over, but before the compiling begins, see the list above. - \item It handles \#include "filepath" directives. -- ALMOST + 6. It handles #include "filepath" directives. -- ALMOST anywhere, in fact. You could easily include a file in a context, in an extension, or at the root level. Files can be included in files that are included in files, down to 50 levels of hierarchy... - \item Local Goto's inside Switch statements automatically have the + 7. Local Goto's inside Switch statements automatically have the extension of the location of the switch statement appended to them. - \item A pretty printer function is available within pbx\_ael.so. - \item In the utils directory, two standalone programs are supplied for + 8. A pretty printer function is available within pbx_ael.so. + 9. In the utils directory, two standalone programs are supplied for debugging AEL files. One is called "aelparse", and it reads in the /etc/asterisk/extensions.ael file, and shows the results of syntax and semantic checking on stdout, and also shows the results of compilation to stdout. The other is "aelparse1", which uses the original ael compiler to do the same work, reading in "/etc/asterisk/extensions.ael", using the original - 'pbx\_ael.so' instead. - \item AEL supports the "jump" statement, and the "pattern" statement + 'pbx_ael.so' instead. + 10. AEL supports the "jump" statement, and the "pattern" statement in switch constructs. Hopefully these will be documented in the AEL README. - \item Added the "return" keyword, which will jump to the end of an + 11. Added the "return" keyword, which will jump to the end of an extension/Macro. - \item Added the ifTime (<time range>|<days of week>|<days of + 12. Added the ifTime (<time range>|<days of week>|<days of month>|<months> ) {} [else {}] construct, which executes much like an if () statement, but the decision is based on the current time, and the time spec provided in the ifTime. See the example above. (Note: all the other time-dependent Applications can be used via ifTime) - \item Added the optional time spec to the contexts in the includes + 13. Added the optional time spec to the contexts in the includes construct. See examples above. - \item You don't have to wrap a single "true" statement in curly + 14. You don't have to wrap a single "true" statement in curly braces, as in the original AEL. An "else" is attached to the closest if. As usual, be careful about nested if statements! When in doubt, use curlies! - \item Added the syntax [regexten] [hint(channel)] to precede an + 15. Added the syntax [regexten] [hint(channel)] to precede an extension declaration. See examples above, under "Extension". The regexten keyword will cause the priorities in the extension to begin with 2 instead of 1. The hint keyword @@ -1148,49 +1185,51 @@ Differences with the original version of AEL the hint priority. They are both optional, of course, but the order is fixed at the moment-- the regexten must come before the hint, if they are both present. - \item Empty case/default/pattern statements will "fall thru" as + 16. Empty case/default/pattern statements will "fall thru" as expected. (0.6) - \item A trailing label in an extension, will automatically have a + 17. A trailing label in an extension, will automatically have a NoOp() added, to make sure the label exists in the extension on Asterisk. (0.6) - \item (0.9) the semicolon is no longer required after a closing brace! - (i.e. "];" ===> "\}". You can have them there if you like, but + 18. (0.9) the semicolon is no longer required after a closing brace! + (i.e. "];" ===> "}". You can have them there if you like, but they are not necessary. Someday they may be rejected as a syntax error, maybe. - \item (0.9) the // comments are not recognized and removed in the + 19. (0.9) the // comments are not recognized and removed in the spots where expressions are gathered, nor in application call arguments. You may have to move a comment if you get errors in existing files. - \item (0.10) the random statement has been added. Syntax: random ( + 20. (0.10) the random statement has been added. Syntax: random ( <expr> ) <lucky-statement> [ else <unlucky-statement> ]. The probability of the lucky-statement getting executed is <expr>, which should evaluate to an integer between 0 and 100. If the <lucky-statement> isn't so lucky this time around, then the <unlucky-statement> gets executed, if it is present. -\end{enumerate} -\section{Hints and Bugs} - The safest way to check for a null strings is to say \$[ "\${x}" = +Hints and Bugs +============== + + * The safest way to check for a null strings is to say $[ "${x}" = "" ] The old way would do as shell scripts often do, and append - something on both sides, like this: \$[ \${x}foo = foo ]. The + something on both sides, like this: $[ ${x}foo = foo ]. The trouble with the old way, is that, if x contains any spaces, then problems occur, usually syntax errors. It is better practice and safer wrap all such tests with double quotes! Also, there are now some functions that can be used in a variable reference, ISNULL(), and LEN(), that can be used to test for an empty string: - \${ISNULL(\${x})} or \$[ \${LEN(\${x}) = 0 ]. + ${ISNULL(${x})} or $[ ${LEN(${x}) = 0 ]. - Assignment vs. Set(). Keep in mind that setting a variable to + * Assignment vs. Set(). Keep in mind that setting a variable to value can be done two different ways. If you choose say 'x=y;', keep in mind that AEL will wrap the right-hand-side with - \$[]. So, when compiled into extension language format, the end - result will be 'Set(x=\$[y])'. If you don't want this effect, + $[]. So, when compiled into extension language format, the end + result will be 'Set(x=$[y])'. If you don't want this effect, then say "Set(x=y);" instead. -\section{The Full Power of AEL} +The Full Power of AEL +============================== A newcomer to Asterisk will look at the above constructs and descriptions, and ask, "Where's the string manipulation functions?", @@ -1200,23 +1239,22 @@ etc. The answer is that the rich capabilities of Asterisk are made available through AEL, via: -\begin{itemize} - \item Applications: See Asterisk - documentation of application + * Applications: See Asterisk - documentation of application commands - \item Functions: Functions were implemented inside \${ .. } variable + * Functions: Functions were implemented inside ${ .. } variable references, and supply many useful capabilities. - \item Expressions: An expression evaluation engine handles items - wrapped inside \$[...]. This includes some string manipulation + * Expressions: An expression evaluation engine handles items + wrapped inside $[...]. This includes some string manipulation facilities, arithmetic expressions, etc. - \item Application Gateway Interface: Asterisk can fork external + * Application Gateway Interface: Asterisk can fork external processes that communicate via pipe. AGI applications can be written in any language. Very powerful applications can be added this way. - \item Variables: Channels of communication have variables associated + * Variables: Channels of communication have variables associated with them, and asterisk provides some global variables. These can be manipulated and/or consulted by the above mechanisms. -\end{itemize} + diff --git a/doc/ajam.tex b/doc/ajam.txt index b5e184931..d3babd0c2 100644 --- a/doc/ajam.tex +++ b/doc/ajam.txt @@ -1,38 +1,37 @@ -\section{Asynchronous Javascript Asterisk Manger (AJAM)} +Asynchronous Javascript Asterisk Manger (AJAM) +============================================== AJAM is a new technology which allows web browsers or other HTTP enabled applications and web pages to directly access the Asterisk Manger Interface (AMI) via HTTP. Setting up your server to process AJAM involves a few steps: -\subsection{Setup the Asterisk HTTP server} +Setup the Asterisk HTTP server +------------------------------ -\begin{enumerate} -\item Uncomment the line "enabled=yes" in /etc/asterisk/http.conf to enable +1) Uncomment the line "enabled=yes" in /etc/asterisk/http.conf to enable Asterisk's builtin micro HTTP server. -\item If you want Asterisk to actually deliver simple HTML pages, CSS, +2) If you want Asterisk to actually deliver simple HTML pages, CSS, javascript, etc. you should uncomment "enablestatic=yes" -\item Adjust your "bindaddr" and "bindport" settings as appropriate for +3) Adjust your "bindaddr" and "bindport" settings as appropriate for your desired accessibility -\item Adjust your "prefix" if appropriate, which must be the beginning of +4) Adjust your "prefix" if appropriate, which must be the beginning of any URI on the server to match. The default is "asterisk" and the rest of these instructions assume that value. -\end{enumerate} -\subsection{Allow Manager Access via HTTP} +Allow Manager Access via HTTP +----------------------------- -\begin{enumerate} -\item Make sure you have both "enabled = yes" and "webenabled = yes" setup +1) Make sure you have both "enabled = yes" and "webenabled = yes" setup in /etc/asterisk/manager.conf -\item You may also use "httptimeout" to set a default timeout for HTTP +2) You may also use "httptimeout" to set a default timeout for HTTP connections. -\item Make sure you have a manager username/secret -\end{enumerate} +3) Make sure you have a manager username/secret Once those configurations are complete you can reload or restart Asterisk and you should be able to point your web browser to specific @@ -41,7 +40,7 @@ list can be found by typing "show http" at the Asterisk CLI. examples: -http://localhost:8088/asterisk/manager?action=login\&username=foo\&secret=bar +http://localhost:8088/asterisk/manager?action=login&username=foo&secret=bar This logs you into the manager interface's "HTML" view. Once you're logged in, Asterisk stores a cookie on your browser (valid for the @@ -71,7 +70,8 @@ manager HTML interfaces. Note that for the demo, there is no need for *any* external web server. -\subsection{Integration with other web servers} +Integration with other web servers +---------------------------------- Asterisk's micro HTTP server is *not* designed to replace a general purpose web server and it is intentionally created to provide only the @@ -83,3 +83,9 @@ will likely need to use a more traditional web server like Apache and link in your Asterisk micro HTTP server with something like this: ProxyPass /asterisk http://localhost:8088/asterisk + +This is a fairly new technology so I'd love to hear if it's useful for +you! + +Mark + diff --git a/doc/app-sms.tex b/doc/app-sms.txt index b588761d8..308376e46 100644 --- a/doc/app-sms.tex +++ b/doc/app-sms.txt @@ -1,4 +1,5 @@ -\section{Introduction} + + * Application SMS The SMS module for Asterisk was developed by Adrian Kennard, and is an implementation of the ETSI specification for landline SMS, ETSI ES 201 @@ -8,7 +9,7 @@ locations such as the US, and use of SMS capable phones such as the Magic Messenger. SMS works using analogue or ISDN lines. -\section{Background} +Background Short Message Service (SMS), or texting is very popular between mobile phones. A message can be sent between two phones, and normally @@ -16,13 +17,11 @@ can be encoded in a text message such as ring tones, and small graphic, etc. Text messaging is being used for voting and competitions, and also SPAM... - Sending a message involves the mobile phone contacting a message centre (SMSC) and passing the message to it. The message centre then contacts the destination mobile to deliver the message. The SMSC is responsible for storing the message and trying to send it until the destination mobile is available, or a timeout. - Landline SMS works in basically the same way. You would normally have a suitable text capable landline phone, or a separate texting box such as a Magic Messenger on your phone line. This sends a message to a @@ -35,58 +34,48 @@ before the first ring, so no phones in the house would ring when a message arrives. -\section{Typical use with Asterisk} +Typical use with Asterisk Sending messages from an Asterisk box can be used for a variety of reasons, including notification from any monitoring systems, email subject lines, etc. - Receiving messages to an Asterisk box is typically used just to email the messages to someone appropriate - we email and texts that are received to our direct numbers to the appropriate person. Received messages could also be used to control applications, manage competitions, votes, post items to IRC, anything. - Using a terminal such as a magic messenger, an Asterisk box could ask as a message centre sending messages to the terminal, which will beep and pop up the message (and remember 100 or so messages in its memory). -\section{Terminology} +Terminology -\begin{itemize} - \item SMS - + SMS Short Message Service i.e. text messages - - \item SMSC - + SMSC Short Message Service Centre The system responsible for storing and forwarding messages - - \item MO - + MO Mobile Originated A message on its way from a mobile or landline device to the SMSC - - \item MT - + MT Mobile Terminated A message on its way from the SMSC to the mobile or landline device - - \item RX - + RX Receive A message coming in to the Asterisk box - - \item TX - + TX Transmit A message going out of the Asterisk box -\end{itemize} -\section{Sub address} +Sub address When sending a message to a landline, you simply send to the landline number. In the UK, all of the mobile operators (bar one) understand sending messages to landlines and pass the messages to the BTText system for delivery to the landline. - The specification for landline SMS allows for the possibility of more than one device on a single landline. These can be configured with Sub addresses which are a single digit. To send a message to a specific @@ -96,22 +85,29 @@ When the call comes in, part of the calling line ID is the sub address, so that only one device on the line answers the call and receives the message. - Sub addresses also work for outgoing messages. Part of the number called by the device to send a message is its sub address. Sending from the default sub address (9 in the UK) means the message is delivered with the sender being the normal landline number. Sending from any other sub address makes the sender the landline number with an extra digit on the end. - Using Asterisk, you can make use of the sub addresses for sending and receiving messages. Using DDI (DID, i.e. multiple numbers on the line on ISDN) you can also make use of many different numbers for SMS. -\section{extensions.conf} +Build / installation + + app_sms.c is included in the Asterisk source apps directory and is + included in the object list (app_sms.so) in apps/Makefile. + smsq.c is a stand alone helper application which is used to send SMSs + from the command line. It uses the popt library. A line for your make + file is:- +smsq: smsq.c + cc -O -o smsq smsq.c -lpopt + +extensions.conf The following contexts are recommended. -\begin{verbatim} ; Mobile Terminated, RX. This is used when an incoming call from the SMS arrive s, with the queue (called number and sub address) in ${EXTEN} ; Running an app after receipt of the text allows the app to find all messages @@ -156,15 +152,13 @@ exten = _X./_080058752[0-8]0,1,Goto(smsmtrx,${EXTEN}-${CALLERIDNUM:9:1},1) handling a call from a sip phone is:- exten = 17094009,1,Goto(smsmorx,${CALLERIDNUM},1) exten = _1709400[0-8],1,Goto(smsmorx,${CALLERIDNUM}-{EXTEN:7:1},1) -\end{verbatim} -\section{Using smsq} +Using smsq smsq is a simple helper application designed to make it easy to send messages from a command line. it is intended to run on the Asterisk box and have direct access to the queue directories for SMS and for Asterisk. - In its simplest form you can send an SMS by a command such as smsq 0123456789 This is a test to 0123456789 This would create a queue file for a mobile originated TX message in @@ -173,17 +167,15 @@ exten = _1709400[0-8],1,Goto(smsmorx,${CALLERIDNUM}-{EXTEN:7:1},1) directory to initiate a call to 17094009 (the default message centre in smsq) attached to application SMS with argument of the queue name (0). - Normally smsq will queue a message ready to send, and will then create a file in the Asterisk outgoing directory causing Asterisk to actually connect to the message centre or device and actually send the pending message(s). - Using --process, smsq can however be used on received queues to run a command for each file (matching the queue if specified) with various environment variables set based on the message (see below); smsq options:- -\begin{verbatim} + --help Show help text --usage @@ -318,7 +310,6 @@ exten = _1709400[0-8],1,Goto(smsmorx,${CALLERIDNUM}-{EXTEN:7:1},1) * If no user data is specified, then no message is sent. However, unless --no-dial is specified, smsq checks for pending messages and generates an outgoing anyway -\end{verbatim} Note that when smsq attempts to make a file in /var/spool/asterisk/outgoing, it checks if there is already a call @@ -334,7 +325,6 @@ exten = _1709400[0-8],1,Goto(smsmorx,${CALLERIDNUM}-{EXTEN:7:1},1) centre or device for the same queue. This is because it is generally more efficient to make one call and send all of the messages one after the other. - smsq can be used with no arguments, or with a queue name only, and it will check for any pending messages and cause an outgoing if there are any. It only sets up one outgoing call at a time based on the first @@ -345,7 +335,6 @@ exten = _1709400[0-8],1,Goto(smsmorx,${CALLERIDNUM}-{EXTEN:7:1},1) selected. Note that smsq does only check motx or mttx depending on the options selected, so it would need to be called twice as a general check. - UTF-8 is used to parse command line arguments for user data, and is the default when reading a file. If an invalid UTF-8 sequence is found, it is treated as UCS-1 data (i.e, as is). @@ -355,7 +344,7 @@ exten = _1709400[0-8],1,Goto(smsmorx,${CALLERIDNUM}-{EXTEN:7:1},1) run with a number of environment variables set as follows. Note that these are unset if not needed and not just taken from the calling environment. This allows simple processing of incoming messages -\begin{verbatim} + $queue Set if a queue specified $?srr @@ -380,15 +369,13 @@ exten = _1709400[0-8],1,Goto(smsmorx,${CALLERIDNUM}-{EXTEN:7:1},1) other Other fields set using their field name, e.g. mr, pid, dcs, etc. udh is a hex byte string -\end{verbatim} -\section{File formats} +File formats By default all queues are held in a director /var/spool/asterisk/sms. Within this directory are sub directories mtrx, mttx, morx, motx which hold the received messages and the messages ready to send. Also, /var/log/asterisk/sms is a log file of all messages handled. - The file name in each queue directory starts with the queue parameter to SMS which is normally the CLI used for an outgoing message or the called number on an incoming message, and may have -X (X being sub @@ -400,12 +387,11 @@ exten = _1709400[0-8],1,Goto(smsmorx,${CALLERIDNUM}-{EXTEN:7:1},1) Files in these queues are in the form of a simple text file where each line starts with a keyword and an = and then data. udh and ud have options for hex encoding, see below. - UTF-8. The user data (ud) field is treated as being UTF-8 encoded unless the DCS is specified indicating 8 bit format. If 8 bit format is specified then the user data is sent as is. The keywords are as follows:- -\begin{verbatim} + oa Originating address The phone number from which the message came Present on mobile terminated messages and is the CLI for morx messages @@ -430,7 +416,7 @@ exten = _1709400[0-8],1,Goto(smsmorx,${CALLERIDNUM}-{EXTEN:7:1},1) Present on mobile originated messages, added by default if absent srr 0 or 1 for status report request - Does not work in UK yet, not implemented in app\_sms yet + Does not work in UK yet, not implemented in app_sms yet rp 0 or 1 return path See GSM specs for details @@ -445,40 +431,34 @@ exten = _1709400[0-8],1,Goto(smsmorx,${CALLERIDNUM}-{EXTEN:7:1},1) header must be in the ud field ud User data, may be text, or hex, see below -\end{verbatim} - udh is specified as as udh\# followed by hex (2 hex digits per byte). + udh is specified as as udh# followed by hex (2 hex digits per byte). If present, then the user data header indicator bit is set, and the length plus the user data header is added to the start of the user data, with padding if necessary (to septet boundary in 7 bit format). User data can hold an USC character codes U+0000 to U+FFFF. Any other characters are coded as U+FEFF - ud can be specified as ud= followed by UTF-8 encoded text if it contains no control characters, i.e. only (U+0020 to U+FFFF). Any invalid UTF-8 sequences are treated as is (U+0080-U+00FF). - - ud can also be specified as ud\# followed by hex (2 hex digits per + ud can also be specified as ud# followed by hex (2 hex digits per byte) containing characters U+0000 to U+00FF only. - - ud can also be specified as ud\#\# followed by hex (4 hex digits per + ud can also be specified as ud## followed by hex (4 hex digits per byte) containing UCS-2 characters. - - When written by app\_sms (e.g. incoming messages), the file is written + When written by app_sms (e.g. incoming messages), the file is written with ud= if it can be (no control characters). If it cannot, the a comment line ;ud= is used to show the user data for human readability - and ud\# or ud\#\# is used. + and ud# or ud## is used. -\section{Delivery reports} +Delivery reports The SMS specification allows for delivery reports. These are requested using the srr bit. However, as these do not work in the UK yet they are not fully implemented in this application. If anyone has a telco that does implement these, please let me know. BT in the UK have a non - standard way to do this by starting the message with *0\#, and so this + standard way to do this by starting the message with *0#, and so this application may have a UK specific bodge in the near future to handle these. -\begin{verbatim} The main changes that are proposed for delivery report handling are :- * New queues for sent messages, one file for each destination address and message reference. @@ -488,4 +468,3 @@ exten = _1709400[0-8],1,Goto(smsmorx,${CALLERIDNUM}-{EXTEN:7:1},1) the outgoing message - the received message file would then have fields for the original outgoing message and user reference allowing applications to handle confirmations better. -\end{verbatim} diff --git a/doc/apps.txt b/doc/apps.txt new file mode 100644 index 000000000..c9696a1a5 --- /dev/null +++ b/doc/apps.txt @@ -0,0 +1,10 @@ +Asterisk applications register themselves with ast_application_register. +They should have a short, unique name, and an exec function which takes +as its arguments a channel and some data that might be useful for callback +stuff. Remember to keep track of how many and which channels are using +your application so that should the module need to be unloaded +(particularly force unloaded), you will be able to ast_softhangup all the +channels. An application should *never* call ast_hangup on the channel +that it is running on (although it could conceivably hang up other +channels that it allocates). See app_playback.c as an example of a simple +application. diff --git a/doc/ast_appdocs.tex b/doc/ast_appdocs.tex deleted file mode 100644 index ee2692658..000000000 --- a/doc/ast_appdocs.tex +++ /dev/null @@ -1,3312 +0,0 @@ -% This file is automatically generated. Any manual edits will be lost. -\section{AddQueueMember} -\subsection{Synopsis} -\begin{verbatim} -Dynamically adds queue members -\end{verbatim} -\subsection{Description} -\begin{verbatim} - AddQueueMember(queuename[|interface[|penalty[|options[|membername]]]]): -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) - -\end{verbatim} - - -\section{ADSIProg} -\subsection{Synopsis} -\begin{verbatim} -Load Asterisk ADSI Scripts into phone -\end{verbatim} -\subsection{Description} -\begin{verbatim} - ADSIProg(script): This application programs an ADSI Phone with the given -script. If nothing is specified, the default script (asterisk.adsi) is used. - -\end{verbatim} - - -\section{AgentCallbackLogin} -\subsection{Synopsis} -\begin{verbatim} -Call agent callback login -\end{verbatim} -\subsection{Description} -\begin{verbatim} - 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 - -\end{verbatim} - - -\section{AgentLogin} -\subsection{Synopsis} -\begin{verbatim} -Call agent login -\end{verbatim} -\subsection{Description} -\begin{verbatim} - 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 - -\end{verbatim} - - -\section{AgentMonitorOutgoing} -\subsection{Synopsis} -\begin{verbatim} -Record agent's outgoing call -\end{verbatim} -\subsection{Description} -\begin{verbatim} - 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. - -\end{verbatim} - - -\section{AGI} -\subsection{Synopsis} -\begin{verbatim} -Executes an AGI compliant application -\end{verbatim} -\subsection{Description} -\begin{verbatim} - [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. - This channel will stop dialplan execution on hangup inside of this -application, except when using DeadAGI. Otherwise, dialplan execution -will continue normally. - A locally executed AGI script will receive SIGHUP on hangup from the channel -except when using DeadAGI. This can be disabled by setting the AGISIGHUP channel -variable to "no" before executing the AGI application. - Using 'EAGI' provides enhanced AGI, with incoming audio available out of band -on file descriptor 3 - - Use the CLI command 'agi show' to list available agi commands - This application sets the following channel variable upon completion: - AGISTATUS The status of the attempt to the run the AGI script - text string, one of SUCCESS | FAILED | HANGUP - -\end{verbatim} - - -\section{AlarmReceiver} -\subsection{Synopsis} -\begin{verbatim} -Provide support for receiving alarm reports from a burglar or fire alarm panel -\end{verbatim} -\subsection{Description} -\begin{verbatim} - 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. - -\end{verbatim} - - -\section{AMD} -\subsection{Synopsis} -\begin{verbatim} -Attempts to detect answering machines -\end{verbatim} -\subsection{Description} -\begin{verbatim} - AMD([initialSilence][|greeting][|afterGreetingSilence][|totalAnalysisTime] - [|minimumWordLength][|betweenWordsSilence][|maximumNumberOfWords] - [|silenceThreshold]) - This application attempts to detect answering machines at the beginning - of outbound calls. Simply call this application after the call - has been answered (outbound only, of course). - When loaded, AMD reads amd.conf and uses the parameters specified as - default values. Those default values get overwritten when calling AMD - with parameters. -- 'initialSilence' is the maximum silence duration before the greeting. If - exceeded then MACHINE. -- 'greeting' is the maximum length of a greeting. If exceeded then MACHINE. -- 'afterGreetingSilence' is the silence after detecting a greeting. - If exceeded then HUMAN. -- 'totalAnalysisTime' is the maximum time allowed for the algorithm to decide - on a HUMAN or MACHINE. -- 'minimumWordLength'is the minimum duration of Voice to considered as a word. -- 'betweenWordsSilence' is the minimum duration of silence after a word to - consider the audio that follows as a new word. -- 'maximumNumberOfWords'is the maximum number of words in the greeting. - If exceeded then MACHINE. -- 'silenceThreshold' is the silence threshold. -This application sets the following channel variable upon completion: - AMDSTATUS - This is the status of the answering machine detection. - Possible values are: - MACHINE | HUMAN | NOTSURE | HANGUP - AMDCAUSE - Indicates the cause that led to the conclusion. - Possible values are: - TOOLONG-<%d total_time> - INITIALSILENCE-<%d silenceDuration>-<%d initialSilence> - HUMAN-<%d silenceDuration>-<%d afterGreetingSilence> - MAXWORDS-<%d wordsCount>-<%d maximumNumberOfWords> - LONGGREETING-<%d voiceDuration>-<%d greeting> - -\end{verbatim} - - -\section{Answer} -\subsection{Synopsis} -\begin{verbatim} -Answer a channel if ringing -\end{verbatim} -\subsection{Description} -\begin{verbatim} - 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. - -\end{verbatim} - - -\section{AppendCDRUserField} -\subsection{Synopsis} -\begin{verbatim} -Append to the CDR user field -\end{verbatim} -\subsection{Description} -\begin{verbatim} -[Synopsis] -AppendCDRUserField(value) - -[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(). - -This application is deprecated in favor of Set(CDR(userfield)=...) - -\end{verbatim} - - -\section{Authenticate} -\subsection{Synopsis} -\begin{verbatim} -Authenticate a user -\end{verbatim} -\subsection{Description} -\begin{verbatim} - Authenticate(password[|options[|maxdigits]]): 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) - 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. - -\end{verbatim} - - -\section{BackGround} -\subsection{Synopsis} -\begin{verbatim} -Play an audio file while waiting for digits of an extension to go to. -\end{verbatim} -\subsection{Description} -\begin{verbatim} - 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 explicitly 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. - -\end{verbatim} - - -\section{BackgroundDetect} -\subsection{Synopsis} -\begin{verbatim} -Background a file with talk detect -\end{verbatim} -\subsection{Description} -\begin{verbatim} - 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. - -\end{verbatim} - - -\section{Busy} -\subsection{Synopsis} -\begin{verbatim} -Indicate the Busy condition -\end{verbatim} -\subsection{Description} -\begin{verbatim} - 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. - -\end{verbatim} - - -\section{ChangeMonitor} -\subsection{Synopsis} -\begin{verbatim} -Change monitoring filename of a channel -\end{verbatim} -\subsection{Description} -\begin{verbatim} -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. - -\end{verbatim} - - -\section{ChanIsAvail} -\subsection{Synopsis} -\begin{verbatim} -Check channel availability -\end{verbatim} -\subsection{Description} -\begin{verbatim} - 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 - -\end{verbatim} - - -\section{ChannelRedirect} -\subsection{Synopsis} -\begin{verbatim} -Redirects given channel to a dialplan target. -\end{verbatim} -\subsection{Description} -\begin{verbatim} -ChannelRedirect(channel|[[context|]extension|]priority): - Sends the specified channel to the specified extension priority - -\end{verbatim} - - -\section{ChanSpy} -\subsection{Synopsis} -\begin{verbatim} -Listen to a channel, and optionally whisper into it -\end{verbatim} -\subsection{Description} -\begin{verbatim} - ChanSpy([chanprefix][|options]): This application is used to listen to the -audio from an 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 - contain 'grp' in an optional : delimited list. - q - Don't play a beep when beginning to spy on a channel, or speak the - selected channel name. - 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. - w - Enable 'whisper' mode, so the spying channel can talk to - the spied-on channel. - W - Enable 'private whisper' mode, so the spying channel can - talk to the spied-on channel but cannot listen to that - channel. - -\end{verbatim} - - -\section{Congestion} -\subsection{Synopsis} -\begin{verbatim} -Indicate the Congestion condition -\end{verbatim} -\subsection{Description} -\begin{verbatim} - Congestion([timeout]): This application will indicate the congestion -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. - -\end{verbatim} - - -\section{ContinueWhile} -\subsection{Synopsis} -\begin{verbatim} -Restart a While loop -\end{verbatim} -\subsection{Description} -\begin{verbatim} -Usage: ContinueWhile() -Returns to the top of the while loop and re-evaluates the conditional. - -\end{verbatim} - - -\section{ControlPlayback} -\subsection{Synopsis} -\begin{verbatim} -Play a file with fast forward and rewind -\end{verbatim} -\subsection{Description} -\begin{verbatim} - 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 - -\end{verbatim} - - -\section{DateTime} -\subsection{Synopsis} -\begin{verbatim} -Says a specified time in a custom format -\end{verbatim} -\subsection{Description} -\begin{verbatim} -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" - -\end{verbatim} - - -\section{DBdel} -\subsection{Synopsis} -\begin{verbatim} -Delete a key from the database -\end{verbatim} -\subsection{Description} -\begin{verbatim} - DBdel(family/key): This application will delete a key from the Asterisk -database. - This application has been DEPRECATED in favor of the DB_DELETE function. - -\end{verbatim} - - -\section{DBdeltree} -\subsection{Synopsis} -\begin{verbatim} -Delete a family or keytree from the database -\end{verbatim} -\subsection{Description} -\begin{verbatim} - DBdeltree(family[/keytree]): This application will delete a family or keytree -from the Asterisk database - -\end{verbatim} - - -\section{DeadAGI} -\subsection{Synopsis} -\begin{verbatim} -Executes AGI on a hungup channel -\end{verbatim} -\subsection{Description} -\begin{verbatim} - [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. - This channel will stop dialplan execution on hangup inside of this -application, except when using DeadAGI. Otherwise, dialplan execution -will continue normally. - A locally executed AGI script will receive SIGHUP on hangup from the channel -except when using DeadAGI. This can be disabled by setting the AGISIGHUP channel -variable to "no" before executing the AGI application. - Using 'EAGI' provides enhanced AGI, with incoming audio available out of band -on file descriptor 3 - - Use the CLI command 'agi show' to list available agi commands - This application sets the following channel variable upon completion: - AGISTATUS The status of the attempt to the run the AGI script - text string, one of SUCCESS | FAILED | HANGUP - -\end{verbatim} - - -\section{Dial} -\subsection{Synopsis} -\begin{verbatim} -Place a call and connect to the current channel -\end{verbatim} -\subsection{Description} -\begin{verbatim} - 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()=...). - - 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. - i - Asterisk will ignore any forwarding requests it may receive on this - dial attempt. - 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. Also, pbx services are not run on the peer (called) channel, - so you will not be able to set timeouts via the TIMEOUT() function in this macro. - 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. - O([x]) - "Operator Services" mode (Zaptel channel to Zaptel channel - only, if specified on non-Zaptel interface, it will be ignored). - When the destination answers (presumably an operator services - station), the originator no longer has control of their line. - They may hang up, but the switch will not release their line - until the destination party hangs up (the operator). Specified - without an arg, or with 1 as an arg, the originator hanging up - will cause the phone to ring back immediately. With a 2 specified, - when the "operator" flashes the trunk, it will ring their phone - back. - 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. - k - Allow the called party to enable parking of the call by sending - the DTMF sequence defined for call parking in features.conf. - K - Allow the calling party to enable parking of the call by sending - the DTMF sequence defined for call parking in features.conf. - -\end{verbatim} - - -\section{Dictate} -\subsection{Synopsis} -\begin{verbatim} -Virtual Dictation Machine -\end{verbatim} -\subsection{Description} -\begin{verbatim} - Dictate([<base_dir>[|<filename>]]) -Start dictation machine using optional base dir for files. - -\end{verbatim} - - -\section{Directory} -\subsection{Synopsis} -\begin{verbatim} -Provide directory of voicemail extensions -\end{verbatim} -\subsection{Description} -\begin{verbatim} - 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: - e - In addition to the name, also read the extension number to the - caller before presenting dialing options. - f - Allow the caller to enter the first name of a user in the directory - instead of using the last name. - -\end{verbatim} - - -\section{DISA} -\subsection{Synopsis} -\begin{verbatim} -DISA (Direct Inward System Access) -\end{verbatim} -\subsection{Description} -\begin{verbatim} -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 allows 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. Also, if you set the 5th argument -to 'NOANSWER', the DISA application will not answer initially. - -\end{verbatim} - - -\section{DumpChan} -\subsection{Synopsis} -\begin{verbatim} -Dump Info About The Calling Channel -\end{verbatim} -\subsection{Description} -\begin{verbatim} - 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. - -\end{verbatim} - - -\section{EAGI} -\subsection{Synopsis} -\begin{verbatim} -Executes an EAGI compliant application -\end{verbatim} -\subsection{Description} -\begin{verbatim} - [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. - This channel will stop dialplan execution on hangup inside of this -application, except when using DeadAGI. Otherwise, dialplan execution -will continue normally. - A locally executed AGI script will receive SIGHUP on hangup from the channel -except when using DeadAGI. This can be disabled by setting the AGISIGHUP channel -variable to "no" before executing the AGI application. - Using 'EAGI' provides enhanced AGI, with incoming audio available out of band -on file descriptor 3 - - Use the CLI command 'agi show' to list available agi commands - This application sets the following channel variable upon completion: - AGISTATUS The status of the attempt to the run the AGI script - text string, one of SUCCESS | FAILED | HANGUP - -\end{verbatim} - - -\section{Echo} -\subsection{Synopsis} -\begin{verbatim} -Echo audio, video, or DTMF back to the calling party -\end{verbatim} -\subsection{Description} -\begin{verbatim} - Echo(): This application will echo any audio, video, or DTMF frames read from -the calling channel back to itself. If the DTMF digit '#' is received, the -application will exit. - -\end{verbatim} - - -\section{EndWhile} -\subsection{Synopsis} -\begin{verbatim} -End a while loop -\end{verbatim} -\subsection{Description} -\begin{verbatim} -Usage: EndWhile() -Return to the previous called While - -\end{verbatim} - - -\section{Exec} -\subsection{Synopsis} -\begin{verbatim} -Executes dialplan application -\end{verbatim} -\subsection{Description} -\begin{verbatim} -Usage: Exec(appname(arguments)) - Allows an arbitrary application to be invoked even when not -hardcoded into the dialplan. If the underlying application -terminates the dialplan, or if the application cannot be found, -Exec will terminate the dialplan. - To invoke external applications, see the application System. - If you would like to catch any error instead, see TryExec. - -\end{verbatim} - - -\section{ExecIf} -\subsection{Synopsis} -\begin{verbatim} -Executes dialplan application, conditionally -\end{verbatim} -\subsection{Description} -\begin{verbatim} -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. - -\end{verbatim} - - -\section{ExecIfTime} -\subsection{Synopsis} -\begin{verbatim} -Conditional application execution based on the current time -\end{verbatim} -\subsection{Description} -\begin{verbatim} - 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. - -\end{verbatim} - - -\section{ExitWhile} -\subsection{Synopsis} -\begin{verbatim} -End a While loop -\end{verbatim} -\subsection{Description} -\begin{verbatim} -Usage: ExitWhile() -Exits a While loop, whether or not the conditional has been satisfied. - -\end{verbatim} - - -\section{ExtenSpy} -\subsection{Synopsis} -\begin{verbatim} -Listen to a channel, and optionally whisper into it -\end{verbatim} -\subsection{Description} -\begin{verbatim} - ExtenSpy(exten[@context][|options]): This application is used to listen to the -audio from an Asterisk channel. This includes the audio coming in and -out of the channel being spied on. Only channels created by outgoing calls for the -specified extension will be selected for spying. If the optional context is not -supplied, the current channel's context will be used. - 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. - Options: - b - Only spy on channels involved in a bridged call. - g(grp) - Match only channels where their ${SPYGROUP} variable is set to - contain 'grp' in an optional : delimited list. - q - Don't play a beep when beginning to spy on a channel, or speak the - selected channel name. - 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. - w - Enable 'whisper' mode, so the spying channel can talk to - the spied-on channel. - W - Enable 'private whisper' mode, so the spying channel can - talk to the spied-on channel but cannot listen to that - channel. - -\end{verbatim} - - -\section{ExternalIVR} -\subsection{Synopsis} -\begin{verbatim} -Interfaces with an external IVR application -\end{verbatim} -\subsection{Description} -\begin{verbatim} - 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/externalivr.txt for a protocol specification. - -\end{verbatim} - - -\section{Festival} -\subsection{Synopsis} -\begin{verbatim} -Say text to the user -\end{verbatim} -\subsection{Description} -\begin{verbatim} - 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) - -\end{verbatim} - - -\section{Flash} -\subsection{Synopsis} -\begin{verbatim} -Flashes a Zap Trunk -\end{verbatim} -\subsection{Description} -\begin{verbatim} - 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. - -\end{verbatim} - - -\section{FollowMe} -\subsection{Synopsis} -\begin{verbatim} -Find-Me/Follow-Me application -\end{verbatim} -\subsection{Description} -\begin{verbatim} - FollowMe(followmeid|options): -This application performs Find-Me/Follow-Me functionality for the caller -as defined in the profile matching the <followmeid> parameter in -followme.conf. If the specified <followmeid> profile doesn't exist in -followme.conf, execution will be returned to the dialplan and call -execution will continue at the next priority. - - Options: - s - Playback the incoming status message prior to starting the follow-me step(s) - a - Record the caller's name so it can be announced to the callee on each step - n - Playback the unreachable status message if we've run out of steps to reach the - or the callee has elected not to be reachable. -Returns -1 on hangup - -\end{verbatim} - - -\section{ForkCDR} -\subsection{Synopsis} -\begin{verbatim} -Forks the Call Data Record -\end{verbatim} -\subsection{Description} -\begin{verbatim} - 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. - -\end{verbatim} - - -\section{GetCPEID} -\subsection{Synopsis} -\begin{verbatim} -Get ADSI CPE ID -\end{verbatim} -\subsection{Description} -\begin{verbatim} - GetCPEID: Obtains and displays ADSI CPE ID and other information in order -to properly setup zapata.conf for on-hook operations. - -\end{verbatim} - - -\section{Gosub} -\subsection{Synopsis} -\begin{verbatim} -Jump to label, saving return address -\end{verbatim} -\subsection{Description} -\begin{verbatim} -Gosub([[context|]exten|]priority) - Jumps to the label specified, saving the return address. - -\end{verbatim} - - -\section{GosubIf} -\subsection{Synopsis} -\begin{verbatim} -Conditionally jump to label, saving return address -\end{verbatim} -\subsection{Description} -\begin{verbatim} -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. - -\end{verbatim} - - -\section{Goto} -\subsection{Synopsis} -\begin{verbatim} -Jump to a particular priority, extension, or context -\end{verbatim} -\subsection{Description} -\begin{verbatim} - 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! - -\end{verbatim} - - -\section{GotoIf} -\subsection{Synopsis} -\begin{verbatim} -Conditional goto -\end{verbatim} -\subsection{Description} -\begin{verbatim} - 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! - -\end{verbatim} - - -\section{GotoIfTime} -\subsection{Synopsis} -\begin{verbatim} -Conditional Goto based on the current time -\end{verbatim} -\subsection{Description} -\begin{verbatim} - 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, the same actions would be taken as for Goto. - -\end{verbatim} - - -\section{Hangup} -\subsection{Synopsis} -\begin{verbatim} -Hang up the calling channel -\end{verbatim} -\subsection{Description} -\begin{verbatim} - Hangup([causecode]): This application will hang up the calling channel. -If a causecode is given the channel's hangup cause will be set to the given -value. - -\end{verbatim} - - -\section{HasNewVoicemail} -\subsection{Synopsis} -\begin{verbatim} -Conditionally branches to priority + 101 with the right options set -\end{verbatim} -\subsection{Description} -\begin{verbatim} -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> - -This application has been deprecated in favor of the VMCOUNT() function - -\end{verbatim} - - -\section{HasVoicemail} -\subsection{Synopsis} -\begin{verbatim} -Conditionally branches to priority + 101 with the right options set -\end{verbatim} -\subsection{Description} -\begin{verbatim} -HasVoicemail(vmbox[/folder][@context][|varname[|options]]) - Optionally sets <varname> to the number of messages in that folder. Assumes folder of INBOX if not specified. - The option string may contain zero or the following character: - 'j' -- jump to priority n+101, if there is voicemail in the folder indicated. - This application sets the following channel variable upon completion: - HASVMSTATUS The result of the voicemail check returned as a text string as follows - <# of messages in the folder, 0 for NONE> - -This application has been deprecated in favor of the VMCOUNT() function - -\end{verbatim} - - -\section{IAX2Provision} -\subsection{Synopsis} -\begin{verbatim} -Provision a calling IAXy with a given template -\end{verbatim} -\subsection{Description} -\begin{verbatim} - IAX2Provision([template]): Provisions the calling IAXy (assuming -the calling entity is in fact an IAXy) with the given template or -default if one is not specified. Returns -1 on error or 0 on success. - -\end{verbatim} - - -\section{ICES} -\subsection{Synopsis} -\begin{verbatim} -Encode and stream using 'ices' -\end{verbatim} -\subsection{Description} -\begin{verbatim} - 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). - -\end{verbatim} - - -\section{ImportVar} -\subsection{Synopsis} -\begin{verbatim} -Import a variable from a channel into a new variable -\end{verbatim} -\subsection{Description} -\begin{verbatim} - 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. - -\end{verbatim} - - -\section{IVRDemo} -\subsection{Synopsis} -\begin{verbatim} -IVR Demo Application -\end{verbatim} -\subsection{Description} -\begin{verbatim} - This is a skeleton application that shows you the basic structure to create your -own asterisk applications and demonstrates the IVR demo. - -\end{verbatim} - - -\section{JabberSend} -\subsection{Synopsis} -\begin{verbatim} -JabberSend(jabber,screenname,message) -\end{verbatim} -\subsection{Description} -\begin{verbatim} -JabberSend(Jabber,ScreenName,Message) - Jabber - Client or transport Asterisk uses to connect to Jabber - ScreenName - User Name to message. - Message - Message to be sent to the buddy - -\end{verbatim} - - -\section{JabberStatus} -\subsection{Synopsis} -\begin{verbatim} -JabberStatus(Jabber,ScreenName,Variable) -\end{verbatim} -\subsection{Description} -\begin{verbatim} -JabberStatus(Jabber,ScreenName,Variable) - Jabber - Client or transport Asterisk uses to connect to Jabber - ScreenName - User Name to retrieve status from. - Variable - Variable to store presence in will be 1-6. - In order, Online, Chatty, Away, XAway, DND, Offline - If not in roster variable will = 7 - -\end{verbatim} - - -\section{Log} -\subsection{Synopsis} -\begin{verbatim} -Send arbitrary text to a selected log level -\end{verbatim} -\subsection{Description} -\begin{verbatim} -Log(<level>|<message>) - level must be one of ERROR, WARNING, NOTICE, DEBUG, VERBOSE, DTMF - -\end{verbatim} - - -\section{LookupBlacklist} -\subsection{Synopsis} -\begin{verbatim} -Look up Caller*ID name/number from blacklist database -\end{verbatim} -\subsection{Description} -\begin{verbatim} - 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() - -This application is deprecated and may be removed from a future release. -Please use the dialplan function BLACKLIST() instead. - -\end{verbatim} - - -\section{LookupCIDName} -\subsection{Synopsis} -\begin{verbatim} -Look up CallerID Name from local database -\end{verbatim} -\subsection{Description} -\begin{verbatim} - 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. - -LookupCIDName is deprecated. Please use ${DB(cidname/${CALLERID(num)})} -instead. - -\end{verbatim} - - -\section{Macro} -\subsection{Synopsis} -\begin{verbatim} -Macro Implementation -\end{verbatim} -\subsection{Description} -\begin{verbatim} - 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. -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. - -\end{verbatim} - - -\section{MacroExclusive} -\subsection{Synopsis} -\begin{verbatim} -Exclusive Macro Implementation -\end{verbatim} -\subsection{Description} -\begin{verbatim} - MacroExclusive(macroname|arg1|arg2...): -Executes macro defined in the context 'macro-macroname' -Only one call at a time may run the macro. -(we'll wait if another call is busy executing in the Macro) -Arguments and return values as in application Macro() - -\end{verbatim} - - -\section{MacroExit} -\subsection{Synopsis} -\begin{verbatim} -Exit From Macro -\end{verbatim} -\subsection{Description} -\begin{verbatim} - 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. - -\end{verbatim} - - -\section{MacroIf} -\subsection{Synopsis} -\begin{verbatim} -Conditional Macro Implementation -\end{verbatim} -\subsection{Description} -\begin{verbatim} - 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() - -\end{verbatim} - - -\section{MailboxExists} -\subsection{Synopsis} -\begin{verbatim} -Check to see if Voicemail mailbox exists -\end{verbatim} -\subsection{Description} -\begin{verbatim} - 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. - -\end{verbatim} - - -\section{MeetMe} -\subsection{Synopsis} -\begin{verbatim} -MeetMe conference bridge -\end{verbatim} -\subsection{Description} -\begin{verbatim} - 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 - 'F' -- Pass DTMF through the conference. DTMF used to activate any - conference features will not be passed through. - 'i' -- announce user join/leave with review - 'I' -- announce user join/leave without review - 'l' -- set listen only mode (Listen only, no talking) - 'm' -- set initially muted - 'M' -- enable music on hold when the conference has a single caller - 'o' -- set talker optimization - treats talkers who aren't speaking as - being muted, meaning (a) No encode is done on transmission and - (b) Received audio that is not registered as talking is omitted - causing no buildup in background noise - '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. - '1' -- do not play message when first person enters - -\end{verbatim} - - -\section{MeetMeAdmin} -\subsection{Synopsis} -\begin{verbatim} -MeetMe conference Administration -\end{verbatim} -\subsection{Description} -\begin{verbatim} - 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 one user - 'M' -- Mute one user - 'n' -- Unmute all users in the conference - 'N' -- Mute all non-admin users in the conference - 'r' -- Reset one user's volume settings - 'R' -- Reset all users volume settings - 's' -- Lower entire conference speaking volume - 'S' -- Raise entire conference speaking volume - 't' -- Lower one user's talk volume - 'T' -- Raise one user's talk volume - 'u' -- Lower one user's listen volume - 'U' -- Raise one user's listen volume - 'v' -- Lower entire conference listening volume - 'V' -- Raise entire conference listening volume - -\end{verbatim} - - -\section{MeetMeCount} -\subsection{Synopsis} -\begin{verbatim} -MeetMe participant count -\end{verbatim} -\subsection{Description} -\begin{verbatim} - 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. - -\end{verbatim} - - -\section{Milliwatt} -\subsection{Synopsis} -\begin{verbatim} -Generate a Constant 1000Hz tone at 0dbm (mu-law) -\end{verbatim} -\subsection{Description} -\begin{verbatim} -Milliwatt(): Generate a Constant 1000Hz tone at 0dbm (mu-law) - -\end{verbatim} - - -\section{MixMonitor} -\subsection{Synopsis} -\begin{verbatim} -Record a call and mix the audio during the recording -\end{verbatim} -\subsection{Description} -\begin{verbatim} - 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} and -all variables will be evaluated at that time. -The variable MIXMONITOR_FILENAME will contain the filename used to record. - -\end{verbatim} - - -\section{Monitor} -\subsection{Synopsis} -\begin{verbatim} -Monitor a channel -\end{verbatim} -\subsection{Description} -\begin{verbatim} -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. - -\end{verbatim} - - -\section{Morsecode} -\subsection{Synopsis} -\begin{verbatim} -Plays morse code -\end{verbatim} -\subsection{Description} -\begin{verbatim} -Usage: Morsecode(<string>) -Plays the Morse code equivalent of the passed string. If the variable -MORSEDITLEN is set, it will use that value for the length (in ms) of the dit -(defaults to 80). Additionally, if MORSETONE is set, it will use that tone -(in Hz). The tone default is 800. - -\end{verbatim} - - -\section{MP3Player} -\subsection{Synopsis} -\begin{verbatim} -Play an MP3 file or stream -\end{verbatim} -\subsection{Description} -\begin{verbatim} - 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. -\end{verbatim} - - -\section{MusicOnHold} -\subsection{Synopsis} -\begin{verbatim} -Play Music On Hold indefinitely -\end{verbatim} -\subsection{Description} -\begin{verbatim} -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. - -\end{verbatim} - - -\section{NBScat} -\subsection{Synopsis} -\begin{verbatim} -Play an NBS local stream -\end{verbatim} -\subsection{Description} -\begin{verbatim} - NBScat: Executes nbscat to listen to the local NBS stream. -User can exit by pressing any key -. -\end{verbatim} - - -\section{NoCDR} -\subsection{Synopsis} -\begin{verbatim} -Tell Asterisk to not maintain a CDR for the current call -\end{verbatim} -\subsection{Description} -\begin{verbatim} - NoCDR(): This application will tell Asterisk not to maintain a CDR for the -current call. - -\end{verbatim} - - -\section{NoOp} -\subsection{Synopsis} -\begin{verbatim} -Do Nothing -\end{verbatim} -\subsection{Description} -\begin{verbatim} - 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. -\end{verbatim} - - -\section{Page} -\subsection{Synopsis} -\begin{verbatim} -Pages phones -\end{verbatim} -\subsection{Description} -\begin{verbatim} -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 - r - record the page into a file (see 'r' for app_meetme) - -\end{verbatim} - - -\section{Park} -\subsection{Synopsis} -\begin{verbatim} -Park yourself -\end{verbatim} -\subsection{Description} -\begin{verbatim} -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 (or the context specified in features.conf). - -If you set the PARKINGEXTEN variable to an extension in your -parking context, park() will park the call on that extension, unless -it already exists. In that case, execution will continue at next -priority. - -\end{verbatim} - - -\section{ParkAndAnnounce} -\subsection{Synopsis} -\begin{verbatim} -Park and Announce -\end{verbatim} -\subsection{Description} -\begin{verbatim} - ParkAndAnnounce(announce:template|timeout|dial|[return_context]): -Park a call into the parkinglot and announce the call to another channel. - -announce template: Colon-separated list of files to announce. The word PARKED - will be replaced by a say_digits of the extension in which - the call is parked. -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 <priority+1>. - -The variable ${PARKEDAT} will contain the parking extension into which the -call was placed. Use with the Local channel to allow the dialplan to make -use of this information. - -\end{verbatim} - - -\section{ParkedCall} -\subsection{Synopsis} -\begin{verbatim} -Answer a parked call -\end{verbatim} -\subsection{Description} -\begin{verbatim} -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. - -\end{verbatim} - - -\section{PauseMonitor} -\subsection{Synopsis} -\begin{verbatim} -Pause monitoring of a channel -\end{verbatim} -\subsection{Description} -\begin{verbatim} -PauseMonitor -Pauses monitoring of a channel until it is re-enabled by a call to UnpauseMonitor. - -\end{verbatim} - - -\section{PauseQueueMember} -\subsection{Synopsis} -\begin{verbatim} -Pauses a queue member -\end{verbatim} -\subsection{Description} -\begin{verbatim} - 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) - -\end{verbatim} - - -\section{Pickup} -\subsection{Synopsis} -\begin{verbatim} -Directed Call Pickup -\end{verbatim} -\subsection{Description} -\begin{verbatim} - Pickup(extension[@context][&extension2@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. If you use the special string "PICKUPMARK" for the context parameter, for example -10@PICKUPMARK, this application tries to find a channel which has defined a channel variable with the same content -as "extension". -\end{verbatim} - - -\section{Playback} -\subsection{Synopsis} -\begin{verbatim} -Play a file -\end{verbatim} -\subsection{Description} -\begin{verbatim} - 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 - -\end{verbatim} - - -\section{PlayTones} -\subsection{Synopsis} -\begin{verbatim} -Play a tone list -\end{verbatim} -\subsection{Description} -\begin{verbatim} -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. - -\end{verbatim} - - -\section{PrivacyManager} -\subsection{Synopsis} -\begin{verbatim} -Require phone number to be entered, if no CallerID sent -\end{verbatim} -\subsection{Description} -\begin{verbatim} - 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 - -\end{verbatim} - - -\section{Progress} -\subsection{Synopsis} -\begin{verbatim} -Indicate progress -\end{verbatim} -\subsection{Description} -\begin{verbatim} - Progress(): This application will request that in-band progress information -be provided to the calling channel. - -\end{verbatim} - - -\section{Queue} -\subsection{Synopsis} -\begin{verbatim} -Queue a call for a call queue -\end{verbatim} -\subsection{Description} -\begin{verbatim} - Queue(queuename[|options[|URL][|announceoverride][|timeout][|AGI]): -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. - 'i' -- ignore call forward requests from queue members and do nothing - when they are requested. - '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 optional AGI parameter will setup an AGI script to be executed on the -calling party's channel once they are connected to a queue member. - 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 - -\end{verbatim} - - -\section{QueueLog} -\subsection{Synopsis} -\begin{verbatim} -Writes to the queue_log -\end{verbatim} -\subsection{Description} -\begin{verbatim} - QueueLog(queuename|uniqueid|agent|event[|additionalinfo]): -Allows you to write your own events into the queue log -Example: QueueLog(101|${UNIQUEID}|${AGENT}|WENTONBREAK|600) - -\end{verbatim} - - -\section{Random} -\subsection{Synopsis} -\begin{verbatim} -Conditionally branches, based upon a probability -\end{verbatim} -\subsection{Description} -\begin{verbatim} -Random([probability]:[[context|]extension|]priority) - probability := INTEGER in the range 1 to 100 -DEPRECATED: Use GotoIf($[${RAND(1,100)} > <number>]?<label>) - -\end{verbatim} - - -\section{Read} -\subsection{Synopsis} -\begin{verbatim} -Read a variable -\end{verbatim} -\subsection{Description} -\begin{verbatim} - 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 or tone with option i - 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 -- options are 's' , 'i', 'n' - 's' to return immediately if the line is not up, - 'i' to play filename as an indication tone from your indications.conf - 'n' 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 -- An integer number of seconds to wait for a digit response. If greater - than 0, that value will override the default timeout. - -Read should disconnect if the function fails or errors out. - -\end{verbatim} - - -\section{ReadFile} -\subsection{Synopsis} -\begin{verbatim} -ReadFile(varname=file,length) -\end{verbatim} -\subsection{Description} -\begin{verbatim} -ReadFile(varname=file,length) - Varname - Result stored here. - File - The name of the file to read. - Length - Maximum number of characters to capture. - -\end{verbatim} - - -\section{RealTime} -\subsection{Synopsis} -\begin{verbatim} -Realtime Data Lookup -\end{verbatim} -\subsection{Description} -\begin{verbatim} -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. For example, a prefix of 'var_' would make the column 'name' -become the variable ${var_name}. REALTIMECOUNT will be set with the number -of values read. - -\end{verbatim} - - -\section{RealTimeUpdate} -\subsection{Synopsis} -\begin{verbatim} -Realtime Data Rewrite -\end{verbatim} -\subsection{Description} -\begin{verbatim} -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>. REALTIMECOUNT will be set with the number of rows -updated or -1 if an error occurs. - -\end{verbatim} - - -\section{Record} -\subsection{Synopsis} -\begin{verbatim} -Record to a file -\end{verbatim} -\subsection{Description} -\begin{verbatim} - 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 (DTMF) instead of default '#' - 'x' : ignore all terminator keys (DTMF) and keep recording until hangup - -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 'core 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. - -\end{verbatim} - - -\section{RemoveQueueMember} -\subsection{Synopsis} -\begin{verbatim} -Dynamically removes queue members -\end{verbatim} -\subsection{Description} -\begin{verbatim} - 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) - -\end{verbatim} - - -\section{ResetCDR} -\subsection{Synopsis} -\begin{verbatim} -Resets the Call Data Record -\end{verbatim} -\subsection{Description} -\begin{verbatim} - 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. - -\end{verbatim} - - -\section{RetryDial} -\subsection{Synopsis} -\begin{verbatim} -Place a call, retrying on failure allowing optional exit extension. -\end{verbatim} -\subsection{Description} -\begin{verbatim} - 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. - -\end{verbatim} - - -\section{Return} -\subsection{Synopsis} -\begin{verbatim} -Return from gosub routine -\end{verbatim} -\subsection{Description} -\begin{verbatim} -Return() - Jumps to the last label on the stack, removing it. - -\end{verbatim} - - -\section{Ringing} -\subsection{Synopsis} -\begin{verbatim} -Indicate ringing tone -\end{verbatim} -\subsection{Description} -\begin{verbatim} - Ringing(): This application will request that the channel indicate a ringing -tone to the user. - -\end{verbatim} - - -\section{Rpt} -\subsection{Synopsis} -\begin{verbatim} -Radio Repeater/Remote Base Control System -\end{verbatim} -\subsection{Description} -\begin{verbatim} - Rpt(nodename[|options]): Radio Remote Link or Remote Base Link Endpoint Process. - - Not specifying an option puts it in normal endpoint mode (where source - IP and nodename are verified). - - Options are as follows: - - X - Normal endpoint mode WITHOUT security check. Only specify - this if you have checked security already (like with an IAX2 - user/password or something). - - Rannounce-string[|timeout[|timeout-destination]] - Amateur Radio - Reverse Autopatch. Caller is put on hold, and announcement (as - specified by the 'announce-string') is played on radio system. - Users of radio system can access autopatch, dial specified - code, and pick up call. Announce-string is list of names of - recordings, or "PARKED" to substitute code for un-parking, - or "NODE" to substitute node number. - - P - Phone Control mode. This allows a regular phone user to have - full control and audio access to the radio system. For the - user to have DTMF control, the 'phone_functions' parameter - must be specified for the node in 'rpt.conf'. An additional - function (cop,6) must be listed so that PTT control is available. - - D - Dumb Phone Control mode. This allows a regular phone user to - have full control and audio access to the radio system. In this - mode, the PTT is activated for the entire length of the call. - For the user to have DTMF control (not generally recomended in - this mode), the 'dphone_functions' parameter must be specified - for the node in 'rpt.conf'. Otherwise no DTMF control will be - available to the phone user. - - -\end{verbatim} - - -\section{SayAlpha} -\subsection{Synopsis} -\begin{verbatim} -Say Alpha -\end{verbatim} -\subsection{Description} -\begin{verbatim} - SayAlpha(string): This application will play the sounds that correspond to -the letters of the given string. - -\end{verbatim} - - -\section{SayDigits} -\subsection{Synopsis} -\begin{verbatim} -Say Digits -\end{verbatim} -\subsection{Description} -\begin{verbatim} - 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. - -\end{verbatim} - - -\section{SayNumber} -\subsection{Synopsis} -\begin{verbatim} -Say Number -\end{verbatim} -\subsection{Description} -\begin{verbatim} - 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. - -\end{verbatim} - - -\section{SayPhonetic} -\subsection{Synopsis} -\begin{verbatim} -Say Phonetic -\end{verbatim} -\subsection{Description} -\begin{verbatim} - SayPhonetic(string): This application will play the sounds from the phonetic -alphabet that correspond to the letters in the given string. - -\end{verbatim} - - -\section{SayUnixTime} -\subsection{Synopsis} -\begin{verbatim} -Says a specified time in a custom format -\end{verbatim} -\subsection{Description} -\begin{verbatim} -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" - -\end{verbatim} - - -\section{SendDTMF} -\subsection{Synopsis} -\begin{verbatim} -Sends arbitrary DTMF digits -\end{verbatim} -\subsection{Description} -\begin{verbatim} - 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. - -\end{verbatim} - - -\section{SendImage} -\subsection{Synopsis} -\begin{verbatim} -Send an image file -\end{verbatim} -\subsection{Description} -\begin{verbatim} - 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 - -\end{verbatim} - - -\section{SendText} -\subsection{Synopsis} -\begin{verbatim} -Send a Text Message -\end{verbatim} -\subsection{Description} -\begin{verbatim} - 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 - -\end{verbatim} - - -\section{SendURL} -\subsection{Synopsis} -\begin{verbatim} -Send a URL -\end{verbatim} -\subsection{Description} -\begin{verbatim} - 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 Client 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 - -If jumping is specified as an option (the 'j' flag), the client does not -support Asterisk "html" transport, and there exists a step with priority -n + 101, then execution will continue at that step. - -SendURL continues normally if the URL was sent correctly or if the channel -does not support HTML transport. Otherwise, the channel is hung up. - -\end{verbatim} - - -\section{Set} -\subsection{Synopsis} -\begin{verbatim} -Set channel variable(s) or function value(s) -\end{verbatim} -\subsection{Description} -\begin{verbatim} - 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) - -The use of Set to set multiple variables at once and the g flag have both -been deprecated. Please use multiple Set calls and the GLOBAL() dialplan -function instead. - -\end{verbatim} - - -\section{SetAMAFlags} -\subsection{Synopsis} -\begin{verbatim} -Set the AMA Flags -\end{verbatim} -\subsection{Description} -\begin{verbatim} - SetAMAFlags([flag]): This application will set the channel's AMA Flags for - billing purposes. - -\end{verbatim} - - -\section{SetCallerID} -\subsection{Synopsis} -\begin{verbatim} -Set CallerID -\end{verbatim} -\subsection{Description} -\begin{verbatim} - SetCallerID(clid[|a]): Set Caller*ID on a call to a new -value. Sets ANI as well if a flag is used. - -This application has been deprecated in favor of Set(CALLERID(all)=...) - -\end{verbatim} - - -\section{SetCallerPres} -\subsection{Synopsis} -\begin{verbatim} -Set CallerID Presentation -\end{verbatim} -\subsection{Description} -\begin{verbatim} - 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 - - -\end{verbatim} - - -\section{SetCDRUserField} -\subsection{Synopsis} -\begin{verbatim} -Set the CDR user field -\end{verbatim} -\subsection{Description} -\begin{verbatim} -[Synopsis] -SetCDRUserField(value) - -[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(). - -This application has been deprecated in favor of Set(CDR(userfield)=...) - -\end{verbatim} - - -\section{SetGlobalVar} -\subsection{Synopsis} -\begin{verbatim} -Set a global variable to a given value -\end{verbatim} -\subsection{Description} -\begin{verbatim} - SetGlobalVar(variable=value): This application sets a given global variable to -the specified value. - -This application has been deprecated in favor of Set(GLOBAL(var)=value) - -\end{verbatim} - - -\section{SetMusicOnHold} -\subsection{Synopsis} -\begin{verbatim} -Set default Music On Hold class -\end{verbatim} -\subsection{Description} -\begin{verbatim} -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. - -\end{verbatim} - - -\section{SetTransferCapability} -\subsection{Synopsis} -\begin{verbatim} -Set ISDN Transfer Capability -\end{verbatim} -\subsection{Description} -\begin{verbatim} - 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 - -This application has been deprecated in favor of Set(CHANNEL(transfercapability)=...) - -\end{verbatim} - - -\section{SIPAddHeader} -\subsection{Synopsis} -\begin{verbatim} -Add a SIP header to the outbound call -\end{verbatim} -\subsection{Description} -\begin{verbatim} - 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 - -\end{verbatim} - - -\section{SIPDtmfMode} -\subsection{Synopsis} -\begin{verbatim} -Change the dtmfmode for a SIP call -\end{verbatim} -\subsection{Description} -\begin{verbatim} -SIPDtmfMode(inband|info|rfc2833): Changes the dtmfmode for a SIP call - -\end{verbatim} - - -\section{SLAStation} -\subsection{Synopsis} -\begin{verbatim} -Shared Line Appearance Station -\end{verbatim} -\subsection{Description} -\begin{verbatim} - SLAStation(station): -This application should be executed by an SLA station. The argument depends -on how the call was initiated. If the phone was just taken off hook, then -the argument "station" should be just the station name. If the call was -initiated by pressing a line key, then the station name should be preceded -by an underscore and the trunk name associated with that line button. -For example: "station1_line1". -\end{verbatim} - - -\section{SLATrunk} -\subsection{Synopsis} -\begin{verbatim} -Shared Line Appearance Trunk -\end{verbatim} -\subsection{Description} -\begin{verbatim} - SLATrunk(trunk): -This application should be executed by an SLA trunk on an inbound call. -The channel calling this application should correspond to the SLA trunk -with the name "trunk" that is being passed as an argument. - -\end{verbatim} - - -\section{SMS} -\subsection{Synopsis} -\begin{verbatim} -Communicates with SMS service centres and SMS capable analogue phones -\end{verbatim} -\subsection{Description} -\begin{verbatim} - 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. - -\end{verbatim} - - -\section{SoftHangup} -\subsection{Synopsis} -\begin{verbatim} -Soft Hangup Application -\end{verbatim} -\subsection{Description} -\begin{verbatim} - 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 - -\end{verbatim} - - -\section{SpeechActivateGrammar} -\subsection{Synopsis} -\begin{verbatim} -Activate a Grammar -\end{verbatim} -\subsection{Description} -\begin{verbatim} -SpeechActivateGrammar(Grammar Name) -This activates the specified grammar to be recognized by the engine. A grammar tells the speech recognition engine what to recognize, -and how to portray it back to you in the dialplan. The grammar name is the only argument to this application. - -\end{verbatim} - - -\section{SpeechBackground} -\subsection{Synopsis} -\begin{verbatim} -Play a sound file and wait for speech to be recognized -\end{verbatim} -\subsection{Description} -\begin{verbatim} -SpeechBackground(Sound File|Timeout) -This application plays a sound file and waits for the person to speak. Once they start speaking playback of the file stops, and silence is heard. -Once they stop talking the processing sound is played to indicate the speech recognition engine is working. -Once results are available the application returns and results (score and text) are available using dialplan functions. -The first text and score are ${SPEECH_TEXT(0)} AND ${SPEECH_SCORE(0)} while the second are ${SPEECH_TEXT(1)} and ${SPEECH_SCORE(1)}. -The first argument is the sound file and the second is the timeout. Note the timeout will only start once the sound file has stopped playing. - -\end{verbatim} - - -\section{SpeechCreate} -\subsection{Synopsis} -\begin{verbatim} -Create a Speech Structure -\end{verbatim} -\subsection{Description} -\begin{verbatim} -SpeechCreate(engine name) -This application creates information to be used by all the other applications. It must be called before doing any speech recognition activities such as activating a grammar. -It takes the engine name to use as the argument, if not specified the default engine will be used. - -\end{verbatim} - - -\section{SpeechDeactivateGrammar} -\subsection{Synopsis} -\begin{verbatim} -Deactivate a Grammar -\end{verbatim} -\subsection{Description} -\begin{verbatim} -SpeechDeactivateGrammar(Grammar Name) -This deactivates the specified grammar so that it is no longer recognized. The only argument is the grammar name to deactivate. - -\end{verbatim} - - -\section{SpeechDestroy} -\subsection{Synopsis} -\begin{verbatim} -End speech recognition -\end{verbatim} -\subsection{Description} -\begin{verbatim} -SpeechDestroy() -This destroys the information used by all the other speech recognition applications. -If you call this application but end up wanting to recognize more speech, you must call SpeechCreate -again before calling any other application. It takes no arguments. - -\end{verbatim} - - -\section{SpeechLoadGrammar} -\subsection{Synopsis} -\begin{verbatim} -Load a Grammar -\end{verbatim} -\subsection{Description} -\begin{verbatim} -SpeechLoadGrammar(Grammar Name|Path) -Load a grammar only on the channel, not globally. -It takes the grammar name as first argument and path as second. - -\end{verbatim} - - -\section{SpeechProcessingSound} -\subsection{Synopsis} -\begin{verbatim} -Change background processing sound -\end{verbatim} -\subsection{Description} -\begin{verbatim} -SpeechProcessingSound(Sound File) -This changes the processing sound that SpeechBackground plays back when the speech recognition engine is processing and working to get results. -It takes the sound file as the only argument. - -\end{verbatim} - - -\section{SpeechStart} -\subsection{Synopsis} -\begin{verbatim} -Start recognizing voice in the audio stream -\end{verbatim} -\subsection{Description} -\begin{verbatim} -SpeechStart() -Tell the speech recognition engine that it should start trying to get results from audio being fed to it. This has no arguments. - -\end{verbatim} - - -\section{SpeechUnloadGrammar} -\subsection{Synopsis} -\begin{verbatim} -Unload a Grammar -\end{verbatim} -\subsection{Description} -\begin{verbatim} -SpeechUnloadGrammar(Grammar Name) -Unload a grammar. It takes the grammar name as the only argument. - -\end{verbatim} - - -\section{StackPop} -\subsection{Synopsis} -\begin{verbatim} -Remove one address from gosub stack -\end{verbatim} -\subsection{Description} -\begin{verbatim} -StackPop() - Removes last label on the stack, discarding it. - -\end{verbatim} - - -\section{StartMusicOnHold} -\subsection{Synopsis} -\begin{verbatim} -Play Music On Hold -\end{verbatim} -\subsection{Description} -\begin{verbatim} -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. - -\end{verbatim} - - -\section{StopMixMonitor} -\subsection{Synopsis} -\begin{verbatim} -Stop recording a call through MixMonitor -\end{verbatim} -\subsection{Description} -\begin{verbatim} - StopMixMonitor() - -Stops the audio recording that was started with a call to MixMonitor() -on the current channel. - -\end{verbatim} - - -\section{StopMonitor} -\subsection{Synopsis} -\begin{verbatim} -Stop monitoring a channel -\end{verbatim} -\subsection{Description} -\begin{verbatim} -StopMonitor -Stops monitoring a channel. Has no effect if the channel is not monitored - -\end{verbatim} - - -\section{StopMusicOnHold} -\subsection{Synopsis} -\begin{verbatim} -Stop Playing Music On Hold -\end{verbatim} -\subsection{Description} -\begin{verbatim} -StopMusicOnHold: Stops playing music on hold. - -\end{verbatim} - - -\section{StopPlayTones} -\subsection{Synopsis} -\begin{verbatim} -Stop playing a tone list -\end{verbatim} -\subsection{Description} -\begin{verbatim} -Stop playing a tone list -\end{verbatim} - - -\section{System} -\subsection{Synopsis} -\begin{verbatim} -Execute a system command -\end{verbatim} -\subsection{Description} -\begin{verbatim} - 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. - -\end{verbatim} - - -\section{TestClient} -\subsection{Synopsis} -\begin{verbatim} -Execute Interface Test Client -\end{verbatim} -\subsection{Description} -\begin{verbatim} -TestClient(testid): Executes test client with given testid. -Results stored in /var/log/asterisk/testreports/<testid>-client.txt -\end{verbatim} - - -\section{TestServer} -\subsection{Synopsis} -\begin{verbatim} -Execute Interface Test Server -\end{verbatim} -\subsection{Description} -\begin{verbatim} -TestServer(): Perform test server function and write call report. -Results stored in /var/log/asterisk/testreports/<testid>-server.txt -\end{verbatim} - - -\section{Transfer} -\subsection{Synopsis} -\begin{verbatim} -Transfer caller to remote extension -\end{verbatim} -\subsection{Description} -\begin{verbatim} - 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 - -\end{verbatim} - - -\section{TryExec} -\subsection{Synopsis} -\begin{verbatim} -Executes dialplan application, always returning -\end{verbatim} -\subsection{Description} -\begin{verbatim} -Usage: TryExec(appname(arguments)) - Allows an arbitrary application to be invoked even when not -hardcoded into the dialplan. To invoke external applications -see the application System. Always returns to the dialplan. -The channel variable TRYSTATUS will be set to: - SUCCESS if the application returned zero - FAILED if the application returned non-zero - NOAPP if the application was not found or was not specified - -\end{verbatim} - - -\section{TrySystem} -\subsection{Synopsis} -\begin{verbatim} -Try executing a system command -\end{verbatim} -\subsection{Description} -\begin{verbatim} - 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. - -\end{verbatim} - - -\section{UnpauseMonitor} -\subsection{Synopsis} -\begin{verbatim} -Unpause monitoring of a channel -\end{verbatim} -\subsection{Description} -\begin{verbatim} -UnpauseMonitor -Unpauses monitoring of a channel on which monitoring had -previously been paused with PauseMonitor. - -\end{verbatim} - - -\section{UnpauseQueueMember} -\subsection{Synopsis} -\begin{verbatim} -Unpauses a queue member -\end{verbatim} -\subsection{Description} -\begin{verbatim} - 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) - -\end{verbatim} - - -\section{UserEvent} -\subsection{Synopsis} -\begin{verbatim} -Send an arbitrary event to the manager interface -\end{verbatim} -\subsection{Description} -\begin{verbatim} - UserEvent(eventname[|body]): Sends an arbitrary event to the manager -interface, with an optional body representing additional arguments. The -body may be specified as a | delimeted list of headers. Each additional -argument will be placed on a new line in the event. The format of the -event will be: - Event: UserEvent - UserEvent: <specified event name> - [body] -If no body is specified, only Event and UserEvent headers will be present. - -\end{verbatim} - - -\section{Verbose} -\subsection{Synopsis} -\begin{verbatim} -Send arbitrary text to verbose output -\end{verbatim} -\subsection{Description} -\begin{verbatim} -Verbose([<level>|]<message>) - level must be an integer value. If not specified, defaults to 0. - -\end{verbatim} - - -\section{VMAuthenticate} -\subsection{Synopsis} -\begin{verbatim} -Authenticate with Voicemail passwords -\end{verbatim} -\subsection{Description} -\begin{verbatim} - 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. - -\end{verbatim} - - -\section{VoiceMail} -\subsection{Synopsis} -\begin{verbatim} -Leave a Voicemail message -\end{verbatim} -\subsection{Description} -\begin{verbatim} - 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. - -\end{verbatim} - - -\section{VoiceMailMain} -\subsection{Synopsis} -\begin{verbatim} -Check Voicemail messages -\end{verbatim} -\subsection{Description} -\begin{verbatim} - 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. - a(#) - Skip folder prompt and go directly to folder specified. - Defaults to INBOX - -\end{verbatim} - - -\section{Wait} -\subsection{Synopsis} -\begin{verbatim} -Waits for some time -\end{verbatim} -\subsection{Description} -\begin{verbatim} - 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. - -\end{verbatim} - - -\section{WaitExten} -\subsection{Synopsis} -\begin{verbatim} -Waits for an extension to be entered -\end{verbatim} -\subsection{Description} -\begin{verbatim} - 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. - -\end{verbatim} - - -\section{WaitForRing} -\subsection{Synopsis} -\begin{verbatim} -Wait for Ring Application -\end{verbatim} -\subsection{Description} -\begin{verbatim} - 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 - -\end{verbatim} - - -\section{WaitForSilence} -\subsection{Synopsis} -\begin{verbatim} -Waits for a specified amount of silence -\end{verbatim} -\subsection{Description} -\begin{verbatim} - WaitForSilence(silencerequired[|iterations][|timeout]) -Wait for Silence: Waits for up to 'silencerequired' -milliseconds of silence, 'iterations' times or once if omitted. -An optional timeout specified the number of seconds to return -after, even if we do not receive the specified amount of silence. -Use 'timeout' with caution, as it may defeat the purpose of this -application, which is to wait indefinitely until silence is detected -on the line. This is particularly useful for reverse-911-type -call broadcast applications where you need to wait for an answering -machine to complete its spiel before playing a message. -The timeout parameter is specified only to avoid an infinite loop in -cases where silence is never achieved. Typically you will want to -include two or more calls to WaitForSilence when dealing with an answering -machine; first waiting for the spiel to finish, then waiting for the beep, etc. - -Examples: - - WaitForSilence(500|2) will wait for 1/2 second of silence, twice - - WaitForSilence(1000) will wait for 1 second of silence, once - - WaitForSilence(300|3|10) will wait for 300ms silence, 3 times, - and returns after 10 sec, even if silence is not detected - -Sets the channel variable WAITSTATUS with to one of these values: -SILENCE - if exited with silence detected -TIMEOUT - if exited without silence detected after timeout - -\end{verbatim} - - -\section{WaitMusicOnHold} -\subsection{Synopsis} -\begin{verbatim} -Wait, playing Music On Hold -\end{verbatim} -\subsection{Description} -\begin{verbatim} -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. - -\end{verbatim} - - -\section{While} -\subsection{Synopsis} -\begin{verbatim} -Start a while loop -\end{verbatim} -\subsection{Description} -\begin{verbatim} -Usage: While(<expr>) -Start a While Loop. Execution will return to this point when -EndWhile is called until expr is no longer true. - -\end{verbatim} - - -\section{Zapateller} -\subsection{Synopsis} -\begin{verbatim} -Block telemarketers with SIT -\end{verbatim} -\subsection{Description} -\begin{verbatim} - 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 - -\end{verbatim} - - -\section{ZapBarge} -\subsection{Synopsis} -\begin{verbatim} -Barge in (monitor) Zap channel -\end{verbatim} -\subsection{Description} -\begin{verbatim} - 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. -\end{verbatim} - - -\section{ZapRAS} -\subsection{Synopsis} -\begin{verbatim} -Executes Zaptel ISDN RAS application -\end{verbatim} -\subsection{Description} -\begin{verbatim} - 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. - -\end{verbatim} - - -\section{ZapScan} -\subsection{Synopsis} -\begin{verbatim} -Scan Zap channels to monitor calls -\end{verbatim} -\subsection{Description} -\begin{verbatim} - 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. - -\end{verbatim} - - -\section{ZapSendKeypadFacility} -\subsection{Synopsis} -\begin{verbatim} -Send digits out of band over a PRI -\end{verbatim} -\subsection{Description} -\begin{verbatim} - ZapSendKeypadFacility(): This application will send the given string of digits in a Keypad Facility - IE over the current channel. - -\end{verbatim} - - diff --git a/doc/asterisk-conf.tex b/doc/asterisk-conf.tex deleted file mode 100644 index 8464ca21d..000000000 --- a/doc/asterisk-conf.tex +++ /dev/null @@ -1,130 +0,0 @@ -\subsubsection{Asterisk Main Configuration File} - -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. - -\begin{verbatim} -[directories] -; Make sure these directories 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 - -; Verbosity level for logging (-v) -verbose = 0 - -; Debug: "No" or value (1-4) -debug = 3 - -; Background execution disabled (-f) -nofork=yes | no - -; Always background, even with -v or -d (-F) -alwaysfork=yes | no - -; Console mode (-c) -console= yes | no - -; Execute with high priority (-p) -highpriority = yes | no - -; Initialize crypto at startup (-i) -initcrypto = yes | no - -; Disable ANSI colors (-n) -nocolor = yes | no - -; Dump core on failure (-g) -dumpcore = yes | no - -; Run quietly (-q) -quiet = yes | no - -; Force timestamping in CLI verbose output (-T) -timestamp = yes | no - -; User to run asterisk as (-U) NOTE: will require changes to -; directory and device permissions -runuser = asterisk - -; Group to run asterisk as (-G) -rungroup = asterisk - -; Enable internal timing support (-I) -internal_timing = yes | no - -; These options have no command line equivalent - -; Cache record() files in another directory until completion -cache_record_files = yes | no -record_cache_dir = <dir> - -; Build transcode paths via SLINEAR -transcode_via_sln = yes | no - -; send SLINEAR silence while channel is being recorded -transmit_silence_during_record = yes | no - -; The maximum load average we accept calls for -maxload = 1.0 - -; The maximum number of concurrent calls you want to allow -maxcalls = 255 - -; Allow #exec entries in configuration files -execincludes = yes | no - -; Don't over-inform the Asterisk sysadm, he's a guru -dontwarn = yes | no - -; System name. Used to prefix CDR uniqueid and to fill \${SYSTEMNAME} -systemname = <a_string> - -; Should language code be last component of sound file name or first? -; when off, sound files are searched as <path>/<lang>/<file> -; when on, sound files are search as <lang>/<path>/<file> -; (only affects relative paths for sound files) -languageprefix = yes | no - - -[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 - -\end{verbatim} diff --git a/doc/asterisk-conf.txt b/doc/asterisk-conf.txt new file mode 100644 index 000000000..9b4fb3e8b --- /dev/null +++ b/doc/asterisk-conf.txt @@ -0,0 +1,83 @@ +Asterisk Main Configuration File +----------------------------------------------------- +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. + +--------------- + +[directories] +; Make sure these directories 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) +alwaysfork=yes | no ; Always background, even with -v or -d (-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 in CLI verbose output (-T) +runuser = asterisk ; User to run asterisk as (-U) NOTE: will require changes to + ; directory and device permissions +rungroup = asterisk ; Group to run asterisk as (-G) +internal_timing = yes | no ; Enable internal timing support (-I) + +;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 +systemname = <a_string> ; System name. Used to prefix CDR uniqueid and to fill ${SYSTEMNAME} +languageprefix = yes | no ; Should language code be last component of sound file name or first? + ; when off, sound files are searched as <path>/<lang>/<file> + ; when on, sound files are search as <lang>/<path>/<file> + ; (only affects relative paths for sound files) + +[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 diff --git a/doc/asterisk.tex b/doc/asterisk.tex deleted file mode 100644 index 86a50ff80..000000000 --- a/doc/asterisk.tex +++ /dev/null @@ -1,134 +0,0 @@ -% To generate a PDF from this, install the "rubber" tool, and the LaTeX -% dependencies for it. Then, run: -% -% rubber asterisk.tex -% -% http://www.pps.jussieu.fr/~beffara/soft/rubber/ - -\documentclass[12pt,a4]{report} -\usepackage{hyperref} - -\author{Asterisk Development Team \\ Asterisk.org} -\title{Asterisk Reference Information \\ Version ASTERISKVERSION} - -\begin{document} -\maketitle - -\tableofcontents - -\chapter{Introduction} - -This document contains various pieces of information that are useful for -reference purposes. - - \section{License Information} - \input{../LICENSE} - \subsection{Hold Music} - Digium has licensed the music included with - the Asterisk distribution From FreePlayMusic - for use and distribution with Asterisk. It - is licensed ONLY for use as hold music within - an Asterisk based PBX. - \section{Security} - \input{security.tex} - \section{Hardware} - \input{hardware.tex} - -\chapter{Configuration} - \section{General Configuration Information} - \subsection{Configuration Parser} - \input{configuration.tex} - \subsection{Asterisk.conf} - \input{asterisk-conf.tex} - \subsection{CLI Prompt} - \input{cliprompt.tex} - \subsection{Extensions} - \input{extensions.tex} - \subsection{IP Type of Service} - \input{ip-tos.tex} - \subsection{MP3 Support} - \input{mp3.tex} - \subsection{ICES} - \input{ices.tex} - \section{Database Support} - \subsection{Realtime Database Configuration} - \input{realtime.tex} - \subsection{FreeTDS} - \input{freetds.tex} - \section{Privacy} - \input{privacy.tex} - -\chapter{Channel Variables} -\input{channelvariables.tex} - -\chapter{AEL, Asterisk Extension Language} -\input{ael.tex} - -\chapter{SLA (Shared Line Appearances)} -\input{sla.tex} - -\chapter{Channel Drivers} - \section{IAX2} - \input{chaniax.tex} - \subsection{IAX2 Jitterbuffer} - \input{jitterbuffer.tex} - \section{mISDN} - \input{misdn.tex} - \section{Local} - \input{localchannel.tex} - -\chapter{Distributed Universal Number Discovery (DUNDi)} - \section{Introduction} - \input{dundi.tex} - \section{Peering Agreement} - \input{PEERING} - -\chapter{ENUM} -\input{enum.tex} - -\chapter{AMI: Asterisk Manager Interface} - \input{manager.tex} - \input{ajam.tex} - -\chapter{CDR: Call Detail Records} -\input{billing.tex} -\input{cdrdriver.tex} - -\chapter{Voicemail} - \section{ODBC Storage} - \input{odbcstorage.tex} - \section{IMAP Storage} - \input{imapstorage.tex} - -\chapter{SMS} -\input{app-sms.tex} - -\chapter{Queues} - \input{queues-with-callback-members.tex} - \section{Queue Logs} - \input{queuelog.tex} - -% Generate this using the "core dumpappdocs" CLI command that is present -% when Asterisk is built with dev-mode enabled. -\chapter{Application Reference} -\input{ast_appdocs.tex} - -% This is a list of files not yet integrated into this document: -% -%Misc -%---- -%asterisk-mib.txt SNMP mib for Asterisk (net-snmp) -%digium-mib.txt SNMP mib for Asterisk (net-snmp) -% -%For developers -%-------------- -%See http://www.asterisk.org/developers for more information -% -%backtrace.txt How to produce a backtrace when Asterisk crashes -%CODING-GUIDELINES Guidelines for developers -%externalivr.txt Documentation of the protocol used in externalivr() -%modules.txt How Asterisk modules work -%datastores.txt About channel data stores -%speechrec.txt The Generic Speech Recognition API - -\enddocument diff --git a/doc/billing.tex b/doc/billing.tex deleted file mode 100644 index e1d3131fa..000000000 --- a/doc/billing.tex +++ /dev/null @@ -1,87 +0,0 @@ -\section{Applications} - -\begin{itemize} - \item SetAccount - Set account code for billing - \item SetAMAFlags - Sets AMA flags - \item NoCDR - Make sure no CDR is saved for a specific call - \item ResetCDR - Reset CDR - \item ForkCDR - Save current CDR and start a new CDR for this call - \item Authenticate - Authenticates and sets the account code - \item SetCDRUserField - Set CDR user field - \item AppendCDRUserField - Append data to CDR User field -\end{itemize} - -For more information, use the "core show application <application>" command. -You can set default account codes and AMA flags for devices in -channel configuration files, like sip.conf, iax.conf etc. - - -\section{Fields of the CDR in Asterisk} - -\begin{itemize} - \item accountcode: What account number to use, (string, 20 characters) - \item src: Caller*ID number (string, 80 characters) - \item dst: Destination extension (string, 80 characters) - \item dcontext: Destination context (string, 80 characters) - \item clid: Caller*ID with text (80 characters) - \item channel: Channel used (80 characters) - \item dstchannel: Destination channel if appropriate (80 characters) - \item lastapp: Last application if appropriate (80 characters) - \item lastdata: Last application data (arguments) (80 characters) - \item start: Start of call (date/time) - \item answer: Answer of call (date/time) - \item end: End of call (date/time) - \item duration: Total time in system, in seconds (integer), from dial to hangup - \item billsec: Total time call is up, in seconds (integer), from answer to hangup - \item disposition: What happened to the call: ANSWERED, NO ANSWER, BUSY - \item amaflags: What flags to use: DOCUMENTATION, BILL, IGNORE etc, - specified on a per channel basis like accountcode. - \item user field: A user-defined field, maximum 255 characters -\end{itemize} - -In some cases, uniqueid is appended: - -\begin{itemize} - \item uniqueid: Unique Channel Identifier (32 characters) - This needs to be enabled in the source code at compile time -\end{itemize} - -NOTE: If you use IAX2 channels for your calls, and allow 'full' transfers -(not media-only transfers), then when the calls is transferred the server -in the middle will no longer be involved in the signaling path, and thus -will not generate accurate CDRs for that call. If you can, use media-only -transfers with IAX2 to avoid this problem, or turn off transfers completely -(although this can result in a media latency increase since the media packets -have to traverse the middle server(s) in the call). - -\section{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. - -\begin{verbatim} -${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. -\end{verbatim} - -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. diff --git a/doc/billing.txt b/doc/billing.txt new file mode 100644 index 000000000..bca6b8fba --- /dev/null +++ b/doc/billing.txt @@ -0,0 +1,105 @@ +Asterisk billing support - Call Detail Records +---------------------------------------------- +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 doc/freetds.txt for information on possible + problems with the FreeTDS driver + * cdr_sqlite supports SQlite + * cdr_pgsql supports PostgreSQL + +In the asterisk-addons subversion repository, there's a cdr_mysql driver for +MySQL. + +Applications +------------ + + * 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 + +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 +----------------------------- + + 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 + + +NOTE: If you use IAX2 channels for your calls, and allow 'full' transfers +(not media-only transfers), then when the calls is transferred the server +in the middle will no longer be involved in the signaling path, and thus +will not generate accurate CDRs for that call. If you can, use media-only +transfers with IAX2 to avoid this problem, or turn off transfers completely +(although this can result in a media latency increase since the media packets +have to traverse the middle server(s) in the call). + +____________________________________ +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. + +${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. + +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. diff --git a/doc/callingpres.txt b/doc/callingpres.txt new file mode 100644 index 000000000..0fa1ff469 --- /dev/null +++ b/doc/callingpres.txt @@ -0,0 +1,18 @@ +Caller ID presentation values +----------------------------- + +In some channels it is possible to set Caller ID presentation for a device. It is +also possible to set the presentation for an active channel in the dial plan +with the setcallerpres() application. + +Valid values 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 diff --git a/doc/cdrdriver.tex b/doc/cdrdriver.tex deleted file mode 100644 index 00c99daea..000000000 --- a/doc/cdrdriver.tex +++ /dev/null @@ -1,431 +0,0 @@ -Call data records can be stored in many different databases or even CSV text. - -\section{MSSQL} - - Asterisk can currently store CDRs into an MSSQL database in - two different ways: cdr\_odbc or cdr\_tds - - Call Data Records can be stored using unixODBC (which requires - the FreeTDS package) [cdr\_odbc] or directly by using just the - FreeTDS package [cdr\_tds] The following provide some - examples known to get asterisk working with mssql. - - NOTE: Only choose one db connector. - -\subsection{ODBC using cdr\_odbc} - Compile, configure, and install the latest unixODBC package: -\begin{verbatim} - tar -zxvf unixODBC-2.2.9.tar.gz && - cd unixODBC-2.2.9 && - ./configure --sysconfdir=/etc --prefix=/usr --disable-gui && - make && - make install -\end{verbatim} - - Compile, configure, and install the latest FreeTDS package: -\begin{verbatim} - 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 -\end{verbatim} - - Compile, or recompile, asterisk so that it will now add support - for cdr\_odbc. -\begin{verbatim} - make clean && ./configure --with-odbc && - make update && - make && - make install -\end{verbatim} - - 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. - -\begin{verbatim} - /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 -\end{verbatim} - - Only install one database connector. Do not confuse asterisk - by using both ODBC (cdr\_odbc) and FreeTDS (cdr\_tds). - This command will erase the contents of cdr\_tds.conf -\begin{verbatim} - [ -f /etc/asterisk/cdr_tds.conf ] > /etc/asterisk/cdr_tds.conf -\end{verbatim} - NOTE: unixODBC requires the freeTDS package, but asterisk does - not call freeTDS directly. - - Now set up 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. -\begin{verbatim} - /etc/asterisk/cdr_odbc.conf - [global] - dsn=MSSQL-asterisk - username=voipdbuser - password=voipdbpass - loguniqueid=yes -\end{verbatim} - And finally, create the 'cdr' table in your mssql database. -\begin{verbatim} - 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 - ) -\end{verbatim} - 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. - -\subsection{TDS, using cdr\_tds} - Compile, configure, and install the latest FreeTDS package: -\begin{verbatim} - tar -zxvf freetds-0.62.4.tar.gz && - cd freetds-0.62.4 && - ./configure --prefix=/usr --with-tdsver=7.0 - make && - make install -\end{verbatim} - Compile, or recompile, asterisk so that it will now add support - for cdr\_tds. -\begin{verbatim} - make clean && ./configure --with-tds && - make update && - make && - make install -\end{verbatim} - Only install one database connector. Do not confuse asterisk - by using both ODBC (cdr\_odbc) and FreeTDS (cdr\_tds). - This command will erase the contents of cdr\_odbc.conf -\begin{verbatim} - [ -f /etc/asterisk/cdr_odbc.conf ] > /etc/asterisk/cdr_odbc.conf -\end{verbatim} - 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. -\begin{verbatim} - /etc/asterisk/cdr_tds.conf - [global] - hostname=192.168.1.25 - port=1433 - dbname=voipdb - user=voipdbuser - password=voipdpass - charset=BIG5 -\end{verbatim} - And finally, create the 'cdr' table in your mssql database. -\begin{verbatim} - 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 - ) -\end{verbatim} - 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. - - -\section{MYSQL} - -Using MySQL for CDR records is supported by using ODBC and the cdr\_odbc module. - -\section{PGSQL} - If you want to go directly to postgresql database, and have the cdr\_pgsql.so - compiled you can use the following sample setup. - On Debian, before compiling asterisk, just install libpqxx-dev. - Other distros will likely have a similiar package. - - Once you have the compile done, - copy the sample cdr\_pgsql.conf file or create your own. - - Here is a sample: -\begin{verbatim} - /etc/asterisk/cdr_pgsql.conf - ; Sample Asterisk config file for CDR logging to PostgresSQL - [global] - hostname=localhost - port=5432 - dbname=asterisk - password=password - user=postgres - table=cdr -\end{verbatim} - Now create a table in postgresql for your cdrs - -\begin{verbatim} - CREATE TABLE cdr ( - calldate time 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 - ); -\end{verbatim} - -\section{SQLLITE} - -SQLite version 2 is supported in cdr\_sqlite. - -\section{RADIUS} - -\subsection{What is needed} - -\begin{itemize} - \item FreeRADIUS server - \item Radiusclient-ng library - \item Asterisk PBX -\end{itemize} - -\begin{verbatim} - +--------------------+ - | Asterisk PBX | - | | - |********************| - | | +---------------+ - | RADIUS client |------->| RADIUS server | - | |<-------| (FreeRADIUS) | - +--------------------+ +---------------+ -\end{verbatim} - - - -\subsection{Steps to follow in order to have RADIUS support} - -\subsubsection{Installation of the Radiusclient library} - Installation: -\begin{verbatim} - Download the sources from: - - http://developer.berlios.de/projects/radiusclient-ng/ - - Untar the source tarball. - root@localhost:/usr/local/src# tar xvfz radiusclient-ng-0.5.2.tar.gz - - Compile and install the library. - root@localhost:/usr/local/src# cd radiusclient-ng-0.5.2 - root@localhost:/usr/local/src/radiusclient-ng-0.5.2# ./configure - root@localhost:/usr/local/src/radiusclient-ng-0.5.2# make - root@localhost:/usr/local/src/radiusclient-ng-0.5.2# make install -\end{verbatim} - -\subsubsection{Configuration of the Radiusclient library} - - By default all the configuration files of the radiusclient library will - be in /usr/local/etc/radiusclient-ng directory. - - File "radiusclient.conf" - Open the file and find lines containing the following: - - authserver localhost - - This is the hostname or IP address of the RADIUS server used for - authentication. You will have to change this unless the server is - running on the same host as your Asterisk PBX. - - acctserver localhost - This is the hostname or IP address of the RADIUS server used for - accounting. You will have to change this unless the server is running - on the same host as your Asterisk PBX. - - File "servers" - - RADIUS protocol uses simple access control mechanism based on shared - secrets that allows RADIUS servers to limit access from RADIUS clients. - - A RADIUS server is configured with a secret string and only RADIUS - clients that have the same secret will be accepted. - - You need to configure a shared secret for each server you have - configured in radiusclient.conf file in the previous step. The shared - secrets are stored in /usr/local/etc/radiusclient-ng/servers file. - - Each line contains hostname of a RADIUS server and shared secret - used in communication with that server. The two values are separated - by white spaces. Configure shared secrets for every RADIUS server you - are going to use. - - File "dictionary" - - Asterisk uses some attributes that are not included in the - dictionary of radiusclient library, therefore it is necessary to add - them. A file called dictionary.digium (kept in the contrib dir) - was created to list all new attributes used by Asterisk. - Add to the end of the main dictionary file - /usr/local/etc/radiusclient-ng/dictionary - the line: -\begin{verbatim} - \$INCLUDE /path/to/dictionary.digium -\end{verbatim} - -\subsubsection{Install FreeRADIUS Server (Version 1.1.1)} - - Download sources tarball from: - - http://freeradius.org/ - - Untar, configure, build, and install the server: - -\begin{verbatim} - root@localhost:/usr/local/src# tar xvfz freeradius-1.1.1.tar.gz - root@localhost:/usr/local/src# cd freeradius-1.1.1 - root@localhost"/usr/local/src/freeradius-1.1.1# ./configure - root@localhost"/usr/local/src/freeradius-1.1.1# make - root@localhost"/usr/local/src/freeradius-1.1.1# make install -\end{verbatim} - - All the configuration files of FreeRADIUS server will be in - /usr/local/etc/raddb directory. - - -\subsubsection{Configuration of the FreeRADIUS Server} - - There are several files that have to be modified to configure the - RADIUS server. These are presented next. - - File "clients.conf" - - File /usr/local/etc/raddb/clients.conf contains description of - RADIUS clients that are allowed to use the server. For each of the - clients you need to specify its hostname or IP address and also a - shared secret. The shared secret must be the same string you configured - in radiusclient library. - - Example: -\begin{verbatim} - client myhost { - secret = mysecret - shortname = foo - } -\end{verbatim} - - This fragment allows access from RADIUS clients on "myhost" if they use - "mysecret" as the shared secret. - The file already contains an entry for localhost (127.0.0.1), so if you - are running the RADIUS server on the same host as your Asterisk server, - then modify the existing entry instead, replacing the default password. - - File "dictionary" - - Note : as of version 1.1.2, the dictionary.digium file ships with FreeRADIUS. - The following procedure brings the dictionary.digium file to previous versions - of FreeRADIUS. - - File /usr/local/etc/raddb/dictionary contains the dictionary of - FreeRADIUS server. You have to add the same dictionary file - (dictionary.digium), which you added to the dictionary of radiusclient-ng - library. You can include it into the main file, adding the following line at the - end of file '/usr/local/etc/raddb/dictionary': - - \$INCLUDE /path/to/dictionary.digium - - That will include the same new attribute definitions that are used - in radiusclient-ng library so the client and server will understand each - other. - - -\subsubsection{Asterisk Accounting Configuration} - - Compilation and installation: - - The module will be compiled as long as the radiusclient-ng - library has been detected on your system. - - By default FreeRADIUS server will log all accounting requests into - /usr/local/var/log/radius/radacct directory in form of plain text files. - The server will create one file for each hostname in the directory. The - following example shows how the log files look like. - - Asterisk now generates Call Detail Records. See /include/asterisk/cdr.h - for all the fields which are recorded. By default, records in comma - separated values will be created in /var/log/asterisk/cdr-csv. - - The configuration file for cdr\_radius.so module is : - - /etc/asterisk/cdr.conf - This is where you can set CDR related parameters as well as the path to - the radiusclient-ng library configuration file. - - -\section{Logged Values} -\begin{verbatim} - "Asterisk-Acc-Code", The account name of detail records - "Asterisk-Src", - "Asterisk-Dst", - "Asterisk-Dst-Ctx", The destination context - "Asterisk-Clid", - "Asterisk-Chan", The channel - "Asterisk-Dst-Chan", (if applicable) - "Asterisk-Last-App", Last application run on the channel - "Asterisk-Last-Data", Argument to the last channel - "Asterisk-Start-Time", - "Asterisk-Answer-Time", - "Asterisk-End-Time", - "Asterisk-Duration", Duration is the whole length that the entire - call lasted. ie. call rx'd to hangup - "end time" minus "start time" - "Asterisk-Bill-Sec", The duration that a call was up after other - end answered which will be <= to duration - "end time" minus "answer time" - "Asterisk-Disposition", ANSWERED, NO ANSWER, BUSY - "Asterisk-AMA-Flags", DOCUMENTATION, BILL, IGNORE etc, specified on - a per channel basis like accountcode. - "Asterisk-Unique-ID", Unique call identifier - "Asterisk-User-Field" User field set via SetCDRUserField -\end{verbatim} diff --git a/doc/cdrdriver.txt b/doc/cdrdriver.txt new file mode 100644 index 000000000..8a7e2e328 --- /dev/null +++ b/doc/cdrdriver.txt @@ -0,0 +1,215 @@ +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 + + 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: + If you want to go directly to postgresql database, and have the cdr_pgsql.so + compiled you can use the following sample setup. + On Debian, before compiling asterisk, just install libpqxx-dev. + Other distros will likely have a similiar package. + + Once you have the compile done, + copy the sample cdr_pgsql.conf file or create your own. + + Here is a sample: + + /etc/asterisk/cdr_pgsql.conf + ; Sample Asterisk config file for CDR logging to PostgresSQL + [global] + hostname=localhost + port=5432 + dbname=asterisk + password=password + user=postgres + table=cdr + + ;Now create a table in postgresql for your cdrs + + ;SQL table where CDRs will be inserted + ;Copy and paste this into your postgresql prompt. + CREATE TABLE cdr ( + calldate time 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 + ); + + +SQLLITE: + + +RADIUS: See doc/radius.txt for more information on cdr_radius diff --git a/doc/chaniax.tex b/doc/chaniax.tex deleted file mode 100644 index 954e068b0..000000000 --- a/doc/chaniax.tex +++ /dev/null @@ -1,84 +0,0 @@ -\subsection{Introduction} - -This section is intended as an introduction to the Inter-Asterisk -eXchange v2 (or simply IAX2) protocol. It provides both a theoretical -background and practical information on its use. - -\subsection{Why IAX2?} - -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: - -\begin{itemize} - \item Interoperability with NAT/PAT/Masquerade firewalls - \begin{itemize} - \item 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. - \end{itemize} - \item High performance, low overhead protocol - \begin{itemize} - \item 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 - \end{itemize} - \item Internationalization support - \begin{itemize} - \item IAX transmits language information, so that remote PBX - content can be delivered in the native language of the - calling party. - \end{itemize} - \item Remote dialplan polling - \begin{itemize} - \item 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. - \end{itemize} - \item Flexible authentication - \begin{itemize} - \item IAX supports cleartext, md5, and RSA authentication, - providing flexible security models for outgoing calls and - registration services. - \end{itemize} - \item Multimedia protocol - \begin{itemize} - \item IAX supports the transmission of voice, video, images, text, - HTML, DTMF, and URL's. Voice menus can be presented in both - audibly and visually. - \end{itemize} - \item Call statistic gathering - \begin{itemize} - \item IAX gathers statistics about network performance (including - latency and jitter, as well as providing end-to-end latency - measurement. - \end{itemize} - \item Call parameter communication - \begin{itemize} - \item Caller*ID, requested extension, requested context, etc are - all communicated through the call. - \end{itemize} - \item Single socket design - \begin{itemize} - \item IAX's single socket design allows up to 32768 calls to be - multiplexed. - \end{itemize} -\end{itemize} - -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. - -\subsection{Configuration} - -For examples of a configuration, please see the iax.conf.sample in -your the /configs directory of you source code distribution. diff --git a/doc/chaniax.txt b/doc/chaniax.txt new file mode 100644 index 000000000..0bac3046f --- /dev/null +++ b/doc/chaniax.txt @@ -0,0 +1,369 @@ +Inter-Asterisk eXchange Protocol +================================ + +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 +----------------------- +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 amount 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 diff --git a/doc/channels.txt b/doc/channels.txt new file mode 100644 index 000000000..b907a92aa --- /dev/null +++ b/doc/channels.txt @@ -0,0 +1,44 @@ +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. + +--------------- +For more information, please consult the Asterisk Developer's Documentation +on http://www.asterisk.org diff --git a/doc/channelvariables.tex b/doc/channelvariables.txt index 8b50d0459..761516fa7 100644 --- a/doc/channelvariables.tex +++ b/doc/channelvariables.txt @@ -1,82 +1,89 @@ -\section{Introduction} +---------------------------- +Asterisk dial plan variables +---------------------------- There are two levels of parameter evaluation done in the Asterisk dial plan in extensions.conf. -\begin{enumerate} -\item The first, and most frequently used, is the substitution of variable +* The first, and most frequently used, is the substitution of variable references with their values. -\item Then there are the evaluations of expressions done in \$[ .. ]. +* Then there are the evaluations of expressions done in $[ .. ]. This will be discussed below. -\end{enumerate} + 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. -\section{Parameter Quoting} -\begin{verbatim} +___________________________ +PARAMETER QUOTING: +--------------------------- + exten => s,5,BackGround,blabla -\end{verbatim} + 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 \\). +(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. -\section{Variables} +___________________________ +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 : -\begin{verbatim} + exten => 1,2,Set(varname=value) -\end{verbatim} -You can substitute the value of a variable everywhere using \${variablename}. -For example, to stringwise append \$lala to \$blabla and store result in \$koko, + +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: -\begin{verbatim} + exten => 1,2,Set(koko=${blabla}${lala}) -\end{verbatim} + 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 +enclose it inside ${}. For example, Set takes as the first argument (before the =) a variable name, so: -\begin{verbatim} + exten => 1,2,Set(koko=lala) exten => 1,3,Set(${koko}=blabla) -\end{verbatim} + 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 +In fact, everything contained ${here} is just replaced with the value of the variable "here". -\section{Variable Inheritance} +____________________ +VARIABLE INHERITANCE +-------------------- -Variable names which are prefixed by "\_" will be inherited to channels +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. +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. -\subsection{Example} -\begin{verbatim} +Example: + Set(__FOO=bar) ; Sets an inherited version of "FOO" variable Set(FOO=bar) ; Removes the inherited version and sets a local ; variable. @@ -84,22 +91,24 @@ Set(FOO=bar) ; Removes the inherited version and sets a local However, NoOp(${__FOO}) is identical to NoOp(${FOO}) -\end{verbatim} -\section{Selecting Characters from Variables} + +___________________________________ +SELECTING CHARACTERS FROM VARIABLES +----------------------------------- The format for selecting characters from a variable can be expressed as: -\begin{verbatim} + ${variable_name[:offset[:length]]} -\end{verbatim} + 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. -\begin{verbatim} + ;Remove the first character of extension, save in "number" variable exten => _9X.,1,Set(number=${EXTEN:1}) -\end{verbatim} + 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 @@ -109,58 +118,60 @@ 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. -\begin{verbatim} + ;Remove everything before the last four digits of the dialed string exten => _9X.,1,Set(number=${EXTEN:-4}) -\end{verbatim} + 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. -\begin{verbatim} + ;Only save the middle numbers 555 from the string 918005551234 exten => _9X.,1,Set(number=${EXTEN:5:3}) -\end{verbatim} + 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). -\begin{verbatim} + ;Save the numbers 555 to the 'number' variable exten => _9X.,1,Set(number=${EXTEN:-7:3}) -\end{verbatim} + If a negative length value is entered, Asterisk will remove that many characters from the end of the string. -\begin{verbatim} + ;Set pin to everything but the trailing #. exten => _XXXX#,1,Set(pin=${EXTEN:0:-1}) -\end{verbatim} -\section{Expressions} +___________________________ +EXPRESSIONS: +--------------------------- -Everything contained inside a bracket pair prefixed by a \$ (like \$[this]) is +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: -\begin{verbatim} +For example, after the sequence: + exten => 1,1,Set(lala=$[1 + 2]) exten => 1,2,Set(koko=$[2 * ${lala}]) -\end{verbatim} + the value of variable koko is "6". and, further: -\begin{verbatim} + exten => 1,1,Set,(lala=$[ 1 + 2 ]); -\end{verbatim} -will parse as intended. Extra spaces are ignored. +will parse as intended. Extra spaces are ignored. -\subsection{Spaces Inside Variables Values} +______________________________ +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 @@ -169,35 +180,29 @@ The double quotes will be counted as part of that lexical token. As an example: -\begin{verbatim} exten => s,6,GotoIf($[ "${CALLERIDNAME}" : "Privacy Manager" ]?callerid-liar|s|1:s|7) -\end{verbatim} The variable CALLERIDNAME could evaluate to "DELOREAN MOTORS" (with a space) but the above will evaluate to: -\begin{verbatim} "DELOREAN MOTORS" : "Privacy Manager" -\end{verbatim} and will evaluate to 0. The above without double quotes would have evaluated to: -\begin{verbatim} DELOREAN MOTORS : Privacy Manager -\end{verbatim} 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. -\subsection{Operators} - +_____________________ +OPERATORS +--------------------- Operators are listed below in order of increasing precedence. Operators with equal precedence are grouped within { } symbols. -\begin{verbatim} expr1 | expr2 Return the evaluation of expr1 if it is neither an empty string nor zero; otherwise, returns the evaluation of expr2. @@ -267,16 +272,14 @@ with equal precedence are grouped within { } symbols. will be the result of the "evaluation" of this expression. expr3 will be the result otherwise. This operator has the lowest precedence. -\end{verbatim} 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. -\subsection{Examples} +Examples -\begin{verbatim} "One Thousand Five Hundred" =~ "(T[^ ]+)" returns: Thousand @@ -310,27 +313,26 @@ or C derived languages. (2+8)/2 returns 5, of course. -\begin{verbatim} 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. +variable reference ${CALLERIDNUM}, for instance. - -\subsection{Numbers Vs. Strings} +__________________________ +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. - -\subsection{Conditionals} +___________________________ +CONDITIONALS +--------------------------- There is one conditional application - the conditional goto : -\begin{verbatim} exten => 1,2,gotoif(condition?label1:label2) -\end{verbatim} If condition is true go to label1, else go to label2. Labels are interpreted exactly as in the normal goto command. @@ -340,52 +342,50 @@ 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 : -\begin{verbatim} exten => 1,2,gotoif($[${CALLERID} = 123456]?2|1:3|1) -\end{verbatim} Example of use : -\begin{verbatim} 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) -\end{verbatim} -\subsection{Parse Errors} +___________________________ +PARSE ERRORS +--------------------------- Syntax errors are now output with 3 lines. If the extensions.conf file contains a line like: -\begin{verbatim} exten => s,6,GotoIf($[ "${CALLERIDNUM}" = "3071234567" & & "${CALLERIDNAME}" : "Privacy Manager" ]?callerid-liar|s|1:s|7) -\end{verbatim} You may see an error in /var/log/asterisk/messages like this: -\begin{verbatim} + 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" ^ -\end{verbatim} 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 +(&) 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. +marked with the "^" character. + +___________________________ +NULL STRINGS +--------------------------- -\subsection{NULL Strings} Testing to see if a string is null can be done in one of two different ways: -\begin{verbatim} + exten => _XX.,1,GotoIf($["${calledid}" != ""]?3) exten => _XX.,1,GotoIf($[foo${calledid} != foo]?3) -\end{verbatim} + 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. @@ -393,7 +393,9 @@ 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. -\subsection{Warning} +___________________________ +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 @@ -402,7 +404,9 @@ 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. -\subsection{Incompatabilities} +---------------------------- +INCOMPATIBILITIES +---------------------------- The asterisk expression parser has undergone some evolution. It is hoped that the changes will be viewed as positive. @@ -428,8 +432,7 @@ 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: -\begin{enumerate} -\item Tokens separated by space(s). +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' @@ -437,10 +440,10 @@ of possible concern with "legacy" extension.conf files: To keep such strings from being evaluated, simply wrap them in double quotes: ' "1+1" ' -\item The colon operator. In versions previous to double quoting, the +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 + 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, @@ -451,40 +454,41 @@ of possible concern with "legacy" extension.conf files: 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*)+ + 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*)+" + "${VAR1}" : "(Who|What*)+" and should work as previous. -\item Variables and Double Quotes +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! -\item LE, GE, NE operators removed. The code supported these operators, +4. LE, GE, NE operators removed. The code supported these operators, but they were not documented. The symbolic operators, <=, >=, and != should be used instead. -\item Added the unary '-' operator. So you can 3+ -4 and get -1. +5. Added the unary '-' operator. So you can 3+ -4 and get -1. -\item Added the unary '!' operator, which is a logical complement. +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. -\item Added the '=~' operator, just in case someone is just looking for +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. -\item Added the conditional operator 'expr1 ? true\_expr :: false\_expr' - First, all 3 exprs are evaluated, and if expr1 is false, the 'false\_expr' +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. -\item Unary operators '-' and '!' were made right associative. -\end{enumerate} +9. Unary operators '-' and '!' were made right associative. -\subsection{Debugging Hints} +-------------------------------------------------------- +DEBUGGING HINTS FOR $[ ] EXPRESSIONS +-------------------------------------------------------- -There are two utilities you can build to help debug the \$[ ] in +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: @@ -503,7 +507,7 @@ is an example. And, in the utils directory, you can say: -make check\_expr +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 @@ -511,43 +515,44 @@ 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 +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 +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 +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 +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 + 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: +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 + 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 + OK -- $[ "${DIALSTATUS}" = "TORTURE" | "${DIALSTATUS}" = "DONTCALL" ] at line 416 -In the expr2\_log file that is generated, you will see: +In the expr2_log file that is generated, you will see: - line 416, evaluation of \$[ "TORTURE" = "TORTURE" | "TORTURE" = "DONTCALL" ] result: 1 + line 416, evaluation of $[ "TORTURE" = "TORTURE" | "TORTURE" = "DONTCALL" ] result: 1 -check\_expr is a very simplistic algorithm, and it is far from being +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. -\section{Asterisk standard channel variables} - +--------------------------------------------------------- +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 @@ -557,7 +562,6 @@ Variables marked with a * are builtin functions and can't be set, only read in the dialplan. Writes to such variables are silently ignored. -\begin{verbatim} ${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 @@ -595,14 +599,13 @@ ${TRANSFER_CONTEXT} Context for transferred calls ${FORWARD_CONTEXT} Context for forwarded calls ${UNIQUEID} * Current call unique identifier ${SYSTEMNAME} * value of the systemname option of asterisk.conf -\end{verbatim} -\subsection{Application return values} +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. -\begin{verbatim} + ${AGISTATUS} * agi() ${AQMSTATUS} * addqueuemember() ${AVAILSTATUS} * chanisavail() @@ -634,10 +637,10 @@ ${UPQMSTATUS} * unpausequeuemember() ${VMSTATUS} * voicmail() ${VMBOXEXISTSSTATUS} * vmboxexists() ${WAITSTATUS} * waitforsilence() -\end{verbatim} -\subsection{Various application variables} -\begin{verbatim} + +Various application variables +----------------------------- ${CURL} * Resulting page content for curl() ${ENUM} * Result of application EnumLookup ${EXITCONTEXT} Context to exit to in IVR menu (app background()) @@ -657,20 +660,18 @@ ${TOUCH_MONITOR_FORMAT} The audio format to use with Touch Monitor (auto record) ${TOUCH_MONITOR_OUTPUT} * Recorded file from Touch Monitor (auto record) ${TXTCIDNAME} * Result of application TXTCIDName ${VPB_GETDTMF} chan_vpb -\end{verbatim} -\subsection{The MeetMe Conference Bridge} -\begin{verbatim} +The MeetMe Conference Bridge uses the following variables: +---------------------------------------------------------- ${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 -\end{verbatim} -\subsection{The VoiceMail() application} -\begin{verbatim} +The VoiceMail() application uses the following variables: +--------------------------------------------------------- ${VM_CATEGORY} Sets voicemail category ${VM_NAME} * Full name in voicemail ${VM_DUR} * Voicemail duration @@ -680,22 +681,19 @@ ${VM_CIDNAME} * Voicemail Caller ID Name ${VM_CIDNUM} * Voicemail Caller ID Number ${VM_DATE} * Voicemail Date ${VM_MESSAGEFILE} * Path to message left by caller -\end{verbatim} -\subsection{The VMAuthenticate() application} -\begin{verbatim} +The VMAuthenticate() application uses the following variables: +--------------------------------------------------------- ${AUTH_MAILBOX} * Authenticated mailbox ${AUTH_CONTEXT} * Authenticated mailbox context -\end{verbatim} -\subsection{DUNDiLookup()} -\begin{verbatim} +DUNDiLookup() uses the following variables +--------------------------------------------------------- ${DUNDTECH} * The Technology of the result from a call to DUNDiLookup() ${DUNDDEST} * The Destination of the result from a call to DUNDiLookup() -\end{verbatim} -\subsection{chan\_zap} -\begin{verbatim} +The Zaptel channel sets the following variables: +--------------------------------------------------------- ${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) @@ -707,10 +705,9 @@ ${FAXEXTEN} * The extension called before being redirected to "fax" ${PRIREDIRECTREASON} * Reason for redirect, if a call was directed ${SMDI_VM_TYPE} * When an call is received with an SMDI message, the 'type' of message 'b' or 'u' -\end{verbatim} -\subsection{chan\_sip} -\begin{verbatim} +The SIP channel uses the following variables: +--------------------------------------------------------- ${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 (deprecated) @@ -719,10 +716,9 @@ ${SIP_CODEC} Set the SIP codec for a call ${SIP_URI_OPTIONS} * additional options to add to the URI for an outgoing call ${RTPAUDIOQOS} RTCP QoS report for the audio of this call ${RTPVIDEOQOS} RTCP QoS report for the video of this call -\end{verbatim} -\subsection{chan\_agent} -\begin{verbatim} +The Agent channel uses the following variables: +--------------------------------------------------------- ${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 @@ -732,11 +728,9 @@ ${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 -\end{verbatim} - -\subsection{The Dial() application} -\begin{verbatim} +The Dial() application uses the following variables: +--------------------------------------------------------- ${DIALEDPEERNAME} * Dialed peer name ${DIALEDPEERNUMBER} * Dialed peer number ${DIALEDTIME} * Time for the call (seconds) @@ -754,38 +748,68 @@ ${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 -\end{verbatim} -\subsection{The chanisavail() application} -\begin{verbatim} +The chanisavail() application sets the following variables: +----------------------------------------------------------- ${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 -\end{verbatim} -\subsection{Dialplan Macros} -\begin{verbatim} +When using macros in the dialplan, these variables are available +--------------------------------------------------------- ${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 -\end{verbatim} -\subsection{The ChanSpy() application} -\begin{verbatim} +The ChanSpy() application uses the following variables: +--------------------------------------------------------- ${SPYGROUP} * A ':' (colon) separated list of group names. (To be set on spied on channel and matched against the g(grp) option) -\end{verbatim} -\subsection{OSP} -\begin{verbatim} +If you compile with OSP support, these variables are used: +--------------------------------------------------------- ${OSPINHANDLE} OSP handle of in_bound call ${OSPINTIMELIMIT} Duration limit for in_bound call ${OSPOUTHANDLE} OSP handle of out_bound call -${OSPTECH} OSP technology -${OSPDEST} OSP destination +${OSPTECH} OSP technology +${OSPDEST} OSP destination ${OSPCALLING} OSP calling number ${OSPOUTTOKEN} OSP token to use for out_bound call ${OSPOUTTIMELIMIT} Duration limit for out_bound call ${OSPRESULTS} Number of remained destinations -\end{verbatim} + +____________________________________ +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. + +${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. + + +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. diff --git a/doc/cliprompt.tex b/doc/cliprompt.txt index 859943120..fbd7dd99f 100644 --- a/doc/cliprompt.tex +++ b/doc/cliprompt.txt @@ -1,12 +1,12 @@ -\subsubsection{Changing the CLI Prompt} +* Changing the CLI Prompt +------------------------- -The CLI prompt is set with the ASTERISK\_PROMPT UNIX environment variable that +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: -\begin{verbatim} %d Date (year-month-date) %s Asterisk system name (from asterisk.conf) %h Full hostname @@ -15,16 +15,15 @@ the current value by Asterisk: %% 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 -\end{verbatim} + A full list of colors may be found in include/asterisk/term.h -A full list of colors may be found in include/asterisk/term.h - -On Linux systems, you may also use: - -\begin{verbatim} +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 -\end{verbatim} + + +----- +04-03-26 diff --git a/doc/configuration.tex b/doc/configuration.txt index a501928bb..43173b1b4 100644 --- a/doc/configuration.tex +++ b/doc/configuration.txt @@ -1,7 +1,8 @@ -\subsubsection{Introduction} +Asterisk Configuration Parser (version 1.1 and later) +----------------------------------------------------- -The Asterisk configuration parser in the 1.2 version -and beyond series has been improved in a number of ways. In +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. @@ -9,19 +10,17 @@ configure phones, voicemail accounts and queues. These changes are general to the configuration parser, and works in all configuration files. -\subsubsection{General syntax} +General syntax +-------------- Asterisk configuration files are defined as follows: -\begin{verbatim} [section] label = value label2 = value -\end{verbatim} 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: -\begin{verbatim} [section] label1 = value1 label2 = value2 @@ -30,26 +29,23 @@ is a bit different. In these files the syntax is as follows: label3 = value3 label2 = value4 object2 => name2 -\end{verbatim} 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: -\begin{verbatim} +to [section](options) label = value -\end{verbatim} 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 "(". -\subsubsection{Comments} - +Comments +-------- All lines that starts with semi-colon ";" is treated as comments and is not parsed. @@ -57,71 +53,62 @@ 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. -\begin{verbatim} ;This is a comment label = value ;-- This is a comment --; ;-- Comment --; exten=> 1000,1,dial(SIP/lisa) -\end{verbatim} -\subsubsection{Including other files} +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 occurred. +file with the #include statement. The content of the other file will be +included at the row that the #include statement occurred. -\begin{verbatim} #include myusers.conf -\end{verbatim} -You may also include the output of a program with the \#exec directive, +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: -\begin{verbatim} [options] execincludes=yes -\end{verbatim} The exec directive is used like this: -\begin{verbatim} #exec /usr/local/bin/myasteriskconfigurator.sh -\end{verbatim} -\subsubsection{Adding to an existing section} -\begin{verbatim} +Adding to an existing section +----------------------------- + [section] label = value [section](+) label2 = value2 -\end{verbatim} - + 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 +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. -\subsubsection{Defining a template-only section} -\begin{verbatim} +Defining a template-only section +-------------------------------- [section](!) label = value -\end{verbatim} 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. -\subsubsection{Using templates (or other configuration sections)} -\begin{verbatim} +Using templates (or other configuration sections) +------------------------------------------------- [section](name[,name]) label = value -\end{verbatim} The name within the parenthesis refers to other sections, either templates or standard sections. The referred sections are included @@ -130,7 +117,6 @@ section as though their entire contents (and anything they were previously based upon) were included in the new section. For example consider the following: -\begin{verbatim} [foo] permit=192.168.0.2 host=asdf @@ -144,12 +130,10 @@ deny=192.168.1.1 [baz](foo,bar) permit=192.168.3.1 host=bnm -\end{verbatim} The [baz] section will be processed as though it had been written in the following way: -\begin{verbatim} [baz] permit=192.168.0.2 host=asdf @@ -159,13 +143,12 @@ host=jkl deny=192.168.1.1 permit=192.168.3.1 host=bnm -\end{verbatim} -\subsubsection{Additional Examples} +Additional Examples: +-------------------- (in top-level sip.conf) -\begin{verbatim} [defaults](!) type=friend nat=yes @@ -175,11 +158,9 @@ disallow=all allow=alaw #include accounts/*/sip.conf -\end{verbatim} (in accounts/customer1/sip.conf) -\begin{verbatim} [def-customer1](!,defaults) secret=this_is_not_secret context=from-customer1 @@ -191,8 +172,9 @@ mailbox=phone1@customer1 [phone2](def-customer1) mailbox=phone2@customer1 -\end{verbatim} 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. + + diff --git a/doc/cygwin.txt b/doc/cygwin.txt new file mode 100644 index 000000000..0273a1d37 --- /dev/null +++ b/doc/cygwin.txt @@ -0,0 +1,9 @@ +Cygwin support is completely experimental and unsupported at this time. The +current state of cygwin support is that it will compile, and start the cli, +but will not yet take calls properly. + +To compile with cygwin, you will need at least a standard base cygwin install plus the following packages: + +minires +minires-devel + diff --git a/doc/dundi.tex b/doc/dundi.txt index 05d042aad..ffcefc7b8 100644 --- a/doc/dundi.tex +++ b/doc/dundi.txt @@ -1,3 +1,5 @@ +Distributed Universal Number Directory (DUNDi) (tm) +=================================================== http://www.dundi.com Mark Spencer, Digium, Inc. @@ -13,6 +15,8 @@ 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 incurring a risk of a single point of failure. In this way, diff --git a/doc/enum.tex b/doc/enum.txt index 699042d18..3d3d03b0c 100644 --- a/doc/enum.tex +++ b/doc/enum.txt @@ -1,4 +1,7 @@ -\section{The ENUMLOOKUP dialplan function} +Enum support in the ENUMLOOKUP dialplan function +------------------------------------------------ +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 @@ -23,33 +26,23 @@ 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. -\begin{verbatim} Function: ENUMLOOKUP(number[|Method-type[|options[|record#[|zone-suffix]]]]) -\end{verbatim} Performs an ENUM tree lookup on the specified number, method type, and ordinal record offset, and returns one of four different values: -\begin{enumerate} - \item post-parsed NAPTR of one method (URI) type - \item count of elements of one method (URI) type - \item count of all method types - \item full URI of method at a particular point in the list of all possible methods -\end{enumerate} - -\subsection{Arguments} - -\begin{itemize} - \item number - \begin{itemize} - \item 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. - \end{itemize} - - \item service\_type - \begin{itemize} - \item tel, sip, h323, iax2, mailto, ...[any other string], + 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 @@ -59,36 +52,24 @@ Function: ENUMLOOKUP(number[|Method-type[|options[|record#[|zone-suffix]]]]) 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". - \end{itemize} - \item options - \begin{itemize} - \item c - \begin{itemize} - \item count. Returns the number of records of this type are returned +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 + service_type, then a count of all methods will be returned for the DNS record. - \end{itemize} - \end{itemize} - \item record\# - \begin{itemize} - \item which record to present if multiple answers are returned +record# = which record to present if multiple answers are returned <integer> = The record in priority/order sequence based on the - total count of records passed back by the query. If a service\_type + 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" - \end{itemize} + +zone_suffix = allows customization of the ENUM zone. Default is e164.arpa. - \item zone\_suffix - \begin{itemize} - \item allows customization of the ENUM zone. Default is e164.arpa. - \end{itemize} -\end{itemize} -\subsection{Examples} +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 @@ -102,85 +83,62 @@ 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. -\begin{verbatim} -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!" . -\end{verbatim} + +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) -\begin{verbatim} exten => 100,1,Set(foo=${ENUMLOOKUP(+13015611020,,,,loligo.com)}) returns: ${foo}="2203@sip.fox-den.com" -\end{verbatim} 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) -\begin{verbatim} exten => 100,1,Set(foo=${ENUMLOOKUP(+13015611020,tel,,,loligo.com)}) returns: ${foo}="+12125551212" -\end{verbatim} Example 3: How many "sip" pointer type entries are there for this number? -\begin{verbatim} exten => 100,1,Set(foo=${ENUMLOOKUP(+13015611020,sip,c,,loligo.com)}) returns: ${foo}=3 -\end{verbatim} Example 4: For all the "tel" pointer type entries, what is the second one in the list? (after sorting by preference) -\begin{verbatim} exten => 100,1,Set(foo=${ENUMLOOKUP(+13015611020,tel,,2,loligo.com)}) returns: ${foo}="+14155551212" -\end{verbatim} Example 5: How many NAPTRs (tel, sip, mailto, etc.) are in the list for this number? -\begin{verbatim} exten => 100,1,Set(foo=${ENUMLOOKUP(+13015611020,ALL,c,,loligo.com)}) returns: ${foo}=6 -\end{verbatim} Example 6: Give back the second full URI in the sorted list of all NAPTR URIs: -\begin{verbatim} exten => 100,1,Set(foo=${ENUMLOOKUP(+13015611020,ALL,,2,loligo.com)}) returns: ${foo}="tel:+14155551212" [note the "tel:" prefix in the string] -\end{verbatim} Example 7: Look up first SIP entry for the number in the e164.arpa zone (all defaults) -\begin{verbatim} 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] -\end{verbatim} + Example 8: Look up the ISN mapping in freenum.org alpha test zone -\begin{verbatim} 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] -\end{verbatim} Example 9: Give back the first SIP pointer for a number in the -\begin{verbatim} enum.yoydynelabs.com zone (invalid lookup) exten => 100,1,Set(foo=${ENUMLOOKUP(1234567890,sip,,1,enum.yoyodynelabs.com)}) returns: ${foo}="" -\end{verbatim} -\subsection{Usage notes and subtle features} -\begin{itemize} - \item The use of "+" in lookups is confusing, and warrants further + +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 @@ -194,12 +152,12 @@ exten => 100,1,Set(foo=${ENUMLOOKUP(1234567890,sip,,1,enum.yoyodynelabs.com)}) 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 + 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.) - \item If a query is performed of type "c" ("count") and let's say you + 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 @@ -213,7 +171,7 @@ exten => 100,1,Set(foo=${ENUMLOOKUP(1234567890,sip,,1,enum.yoyodynelabs.com)}) given by the remote zone master. Currently, the ENUMLOOKUP function does not use the dnsmgr method of caching local DNS replies.) - \item If you want strict NAPTR value ordering, then it will be + 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 @@ -222,33 +180,33 @@ exten => 100,1,Set(foo=${ENUMLOOKUP(1234567890,sip,,1,enum.yoyodynelabs.com)}) strict RFC compliance and to comply with the desires of the remote party who is presenting NAPTRs in a particular order for a reason. - \item Default behavior for the function (even in event of an error) is + 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 + their dialplan. This is a change from the old app_enumlookup method and it's arbitrary priority jumping based on result type or failure. - \item Anything other than digits will be ignored in lookup strings. + 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. - \item If there exist multiple records with the same weight and order as + 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. - \item Currently, the function ignores the settings in enum.conf as the + 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. - \item The function will digest and return NAPTRs which use older + h) The function will digest and return NAPTRs which use older (deprecated) style, reversed method strings such as "sip+E2U" instead of the more modern "E2U+sip" - \item There is no provision for multi-part methods at this time. If + 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 @@ -257,16 +215,16 @@ exten => 100,1,Set(foo=${ENUMLOOKUP(1234567890,sip,,1,enum.yoyodynelabs.com)}) equal priority/weight (as is often the case) then this will cause no serious difficulty, but it bears mentioning. - \item ISN (ITAD Subscriber Number) usage: If the search number is of + 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. -\end{itemize} -\subsection{Some more Examples} + +==EXAMPLES== All examples below except where noted use "e164.arpa" as the referenced domain, which is the default domain name for ENUMLOOKUP. @@ -274,7 +232,6 @@ 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. -\begin{verbatim} ; example 1 ; ; Assumes North American international dialing (011) prefix. @@ -349,5 +306,3 @@ exten => _X.,22,NoOp("No valid entries in e164.org for ${EXTEN} - sending out vi exten => _X.,23,Dial(Zap/g1/${EXTEN}) ; ; end example 3 - -\end{verbatim} diff --git a/doc/extconfig.txt b/doc/extconfig.txt new file mode 100644 index 000000000..0a95997ce --- /dev/null +++ b/doc/extconfig.txt @@ -0,0 +1,91 @@ +Asterisk external configuration +=============================== + +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 doc/realtime.txt 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: + ++------+--------+-------+--------------+----------+-----+-----------+ +| 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. + +In addition to this, if you add a field named "regserver" to the +SIP peers table and have the system name set in asterisk.conf, +Asterisk will store the system name that the user registered on in +the database. This can be used to direct calls to go through the server +that holds the registration (for NAT traversal purposes). + +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 + diff --git a/doc/extensions.tex b/doc/extensions.txt index 28a49f092..90826f15f 100644 --- a/doc/extensions.tex +++ b/doc/extensions.txt @@ -1,4 +1,5 @@ -\subsubsection{The Asterisk dialplan} +The Asterisk dialplan +===================== 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 @@ -10,7 +11,7 @@ If you change the dialplan, you can use the Asterisk CLI command 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 +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 @@ -28,45 +29,28 @@ 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. -\subsubsection{Example dialplan} +* Example dial plan The example dial plan, in the configs/extensions.conf.sample file is installed as extensions.conf if you run "make samples" after installation of Asterisk. This file includes many more instructions and examples than this file, so it's worthwhile to read it. -\subsubsection{Special extensions} +* Special extensions There are some extensions with important meanings: -\begin{itemize} - \item s - \begin{itemize} - \item 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. - \end{itemize} - \item i - \begin{itemize} - \item What to do if an invalid extension is entered - \end{itemize} - \item h - \begin{itemize} - \item The hangup extension, executed at hangup - \end{itemize} - \item t - \begin{itemize} - \item What to do if nothing is entered in the requisite amount - of time. - \end{itemize} - \item T - \begin{itemize} - \item This is the extension that is executed when the 'absolute' - timeout is reached. See "show function TIMEOUT" for more - information on setting timeouts. - \end{itemize} -\end{itemize} + 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 diff --git a/doc/freetds.tex b/doc/freetds.txt index 8dcbec29a..e1c27fba3 100644 --- a/doc/freetds.tex +++ b/doc/freetds.txt @@ -1,10 +1,12 @@ -The cdr\_tds module is NOT compatible with version 0.63 of FreeTDS. +PLEASE NOTE -The cdr\_tds module is known to work with FreeTDS version 0.62.1; +The cdr_tds module is NOT compatible with version 0.63 of FreeTDS. + +The cdr_tds module is known to work with FreeTDS version 0.62.1; it should also work with 0.62.2, 0.62.3 and 0.62.4, which are bug fix releases. -The cdr\_tds module uses the raw "libtds" API of FreeTDS. It appears +The cdr_tds module uses the raw "libtds" API of FreeTDS. It appears that from 0.63 onwards, this is not considered a published API of FreeTDS and is subject to change without notice. diff --git a/doc/h323.txt b/doc/h323.txt new file mode 100644 index 000000000..c7383e7af --- /dev/null +++ b/doc/h323.txt @@ -0,0 +1,22 @@ +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 inAccessNetworks. + +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. + diff --git a/doc/hardware.tex b/doc/hardware.tex deleted file mode 100644 index 3d7cabd82..000000000 --- a/doc/hardware.tex +++ /dev/null @@ -1,100 +0,0 @@ -\subsection{Introduction} - -A PBX is only really useful if you can get calls into it. Of course, you -can use Asterisk with VoIP calls (SIP, H.323, IAX), but you can also talk -to the real PSTN through various cards. - -Supported Hardware is divided into two general groups: Zaptel devices and -non-zaptel devices. The Zaptel compatible hardware supports pseudo-TDM -conferencing and all call features through chan\_zap, whereas non-zaptel -compatible hardware may have different features. - -\subsection{Zaptel compatible hardware} - -\begin{itemize} -\item Digium, Inc. (Primary Developer of Asterisk) - http://www.digium.com - \begin{itemize} - \item Analog Interfaces - \begin{itemize} - \item TDM400P - The TDM400P is a half-length PCI 2.2-compliant card that supports FXS and FXO station interfaces for connecting analog telephones and analog POTS lines through a PC. - \item TDM800P - The TDM800P is a half-length PCI 2.2-compliant, 8 port card using Digium's VoiceBus technology that supports FXS and FXO station interfaces for connecting analog telephones and analog POTS lines through a PC. - \item TDM2400P - The TDM2400P is a full-length PCI 2.2-compliant card for connecting analog telephones and analog POTS lines through a PC. It supports a combination of up to 6 FXS and/or FXO modules for a total of 24 lines. - \end{itemize} - \item Digital Interfaces - \begin{itemize} - \item TE412P - The TE412P offers an on-board DSP-based echo cancellation module. It supports E1, T1, and J1 environments and is selectable on a per-card or per-port basis. - \item TE410P - The TE410P improves performance and scalability through bus mastering architecture. It supports E1, T1, and J1 environments and is selectable on a per-card or per-port basis. - \item TE407P - The TE407P offers an on-board DSP-based echo cancellation module. It supports E1, T1, and J1 environments and is selectable on a per-card or per-port basis. - \item TE405P - The TE405P improves performance and scalability through bus mastering architecture. It supports both E1, T1, J1 environments and is selectable on a per-card or per-port basis. - \item TE212P - The TE212P offers an on-board DSP-based echo cancellation module. It supports E1, T1, and J1 environments and is selectable on a per-card or per-port basis. - \item TE210P - The TE210P improves performance and scalability through bus mastering architecture. It supports E1, T1, and J1 environments and is selectable on a per-card or per-port basis. - \item TE207P - The TE207P offers an on-board DSP-based echo cancellation module. It supports E1, T1, and J1 environments and is selectable on a per-card or per-port basis. - \item TE205P - The TE205P improves performance and scalability through bus mastering architecture. It supports both E1 and T1/J1 environments and is selectable on a per-card or per-port basis. - \item TE120P - The TE120P is a single span, selectable T1, E1, or J1 card and utilizes Digium's VoiceBus™ technology. It supports both voice and data modes. - \item TE110P - The TE110P brings a high-performance, cost-effective, and flexible single span togglable T1, E1, J1 interface to the Digium line-up of telephony interface devices. - \end{itemize} - \end{itemize} -\end{itemize} - -\subsection{Non-zaptel compatible hardware} - -\begin{itemize} - \item QuickNet, Inc. - http://www.quicknet.net - \begin{itemize} - \item Internet PhoneJack - Single FXS interface. Supports Linux telephony - interface. DSP compression built-in. - - \item Internet LineJack - Single FXS or FXO interface. Supports Linux - telephony interface. - \end{itemize} -\end{itemize} - -\subsection{mISDN compatible hardware} - -mISDN homepage: http://www.isdn4linux.de/mISDN/ - -Any adapter with an mISDN driver should be compatible with -chan\_misdn. See the mISDN section for more information. - -\begin{itemize} - \item Digium, Inc. (Primary Developer of Asterisk) - http://www.digium.com - \begin{itemize} - \item B410P - 4 Port BRI card (TE/NT) - \end{itemize} -\end{itemize} - -\begin{itemize} - \item beroNet - http://www.beronet.com - \begin{itemize} - \item BN4S0 - 4 Port BRI card (TE/NT) - - \item BN8S0 - 8 Port BRI card (TE/NT) - - \item Billion Card - Single Port BRI card (TE (/NT with crossed cable) ) - \end{itemize} -\end{itemize} - -\subsection{Miscellaneous other interfaces} - -\begin{itemize} - \item Digium, Inc. (Primary Developer of Asterisk) - \begin{itemize} - \item TC400B - The TC400B is a half-length, low-profile PCI 2.2-compliant card for transforming complex VoIP codecs (G.729) into simple codecs. - \end{itemize} - - \item ALSA - http://www.alsa-project.org - \begin{itemize} - \item Any ALSA compatible full-duplex sound card - \end{itemize} - - \item OSS - http://www.opensound.com - \begin{itemize} - \item Any OSS compatible full-duplex sound card - \end{itemize} -\end{itemize} diff --git a/doc/hardware.txt b/doc/hardware.txt new file mode 100644 index 000000000..01f8f7f06 --- /dev/null +++ b/doc/hardware.txt @@ -0,0 +1,74 @@ +A PBX is only really useful if you can get calls into it. Of course, you +can use Asterisk with VoIP calls (SIP, H.323, IAX), but you can also talk +to the real PSTN through various cards. + +Supported Hardware is divided into two general groups: Zaptel devices and +non-zaptel devices. The Zaptel compatible hardware supports pseudo-TDM +conferencing and all call features through chan_zap, whereas non-zaptel +compatible hardware may have different features. + +Zaptel compatible hardware +========================== + +-- Digium (Primary author of Asterisk) + http://www.digium.com, http://store.digium.com + + * Wildcard T400P (obsolete) - Quad T1 interface connects to four T1/PRI + interfaces. Supports RBS and PRI voice and PPP, FR, and HDLC data. + + * Wildcard E400P (obsolete)- Quad E1 interface connects to four E1/PRI + (or PRA) interfaces. Supports PRA/PRI, EuroISDN voice and data. + + * Wildcard T100P - Single T1 interface connects to a single T1/PRI + interface. Supports RBS and PRI voice and PPP, FR, and HDLC data. + + * Wildcard E100P - Single E1 interface connects to a single E1/PRI (or PRA) + interface. Supports PRA/PRI, EuroISDN voice and PPP, FR, HDLC data. + + * Wildcard TDM400P - Quad Modular FXS interface connects to standard + analog telephones. + + * Wildcard TE410P - Quad T1/E1 switchable interface. Supports PRI and + RBS signalling, as well as PPP, FR, and HDLC data modes. + +Non-zaptel compatible hardware +============================== + +-- QuickNet, Inc. + http://www.quicknet.net + + * Internet PhoneJack - Single FXS interface. Supports Linux telephony + interface. DSP compression built-in. + + * Internet LineJack - Single FXS or FXO interface. Supports Linux + telephony interface. + +mISDN compatible hardware +========================= +mISDN homepage: http://www.isdn4linux.de/mISDN/ + +Any adapter with an mISDN driver should be compatible with +chan_misdn. See misdn.txt for information. + +-- beroNet + http://www.beronet.com + + * BN4S0 - 4 Port BRI card (TE/NT) + + * BN8S0 - 8 Port BRI card (TE/NT) + + * Billion Card - Single Port BRI card (TE (/NT with crossed cable) ) + + +Miscellaneous other interfaces +============================== + +-- ALSA + http://www.alsa-project.org + + * Any ALSA compatible full-duplex sound card + +-- OSS + http://www.opensound.com + + * Any OSS compatible full-duplex sound card diff --git a/doc/iax.txt b/doc/iax.txt new file mode 100644 index 000000000..9a17c098d --- /dev/null +++ b/doc/iax.txt @@ -0,0 +1,67 @@ +Inter-Asterisk eXchange Protocol +================================ + +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. + +The peer uses a score to determine the best user entry to match against if +one is not specified: + +1. User entry last specified in iax.conf (this is the baseline). +2. User entry with secret specified and ACL specified. +3. User entry with no secret specified and no ACL specified. +4. User entry with no secret specified and ACL specified. +5. User entry matched via username. + +The higher the score the better it is with 5 being an exact match and the maximum +score possible. + +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. + diff --git a/doc/ices.tex b/doc/ices.txt index 77267b506..d75236357 100644 --- a/doc/ices.tex +++ b/doc/ices.txt @@ -1,7 +1,12 @@ +Icecast + Asterisk +================== The advent of icecast into Asterisk allows you to do neat things like have -a caller stream right into an ice-cast stream as well as using chan\_local +a caller stream right into an ice-cast stream as well as using chan_local to place things like conferences, music on hold, etc. into the stream. You'll need to specify a config file for the ices encoder. An example is -included in contrib/asterisk-ices.xml. +included in contrib/asterisk-ices.xml +Anyway hope you like it. + +Mark diff --git a/doc/imapstorage.tex b/doc/imapstorage.txt index 8cae24daa..1e5484b3e 100644 --- a/doc/imapstorage.tex +++ b/doc/imapstorage.txt @@ -1,27 +1,46 @@ +====================== +IMAP Voicemail Storage +====================== + +03-01-2006 - James Rothenberger <jar@onebiztone.com> + By enabling IMAP Storage, Asterisk will use native IMAP as the storage mechanism for voicemail messages instead of using the standard file structure. Tighter integration of Asterisk voicemail and IMAP email services allows additional voicemail functionality, including: -\begin{itemize} - \item Listening to a voicemail on the phone will set its state to "read" in + - Listening to a voicemail on the phone will set its state to "read" in a user's mailbox automatically. - \item Deleting a voicemail on the phone will delete it from the user's + - Deleting a voicemail on the phone will delete it from the user's mailbox automatically. - \item Accessing a voicemail recording email message will turn off the message + - Accessing a voicemail recording email message will turn off the message waiting indicator (MWI) on the user's phone. - \item Deleting a voicemail recording email will also turn off the message + - Deleting a voicemail recording email will also turn off the message waiting indicator, and delete the message from the voicemail system. -\end{itemize} -\subsection{Installation Notes} +===================== +Contents of this file +===================== + + - Installation Notes + - Separate vs. Shared Email Accounts + - IMAP Server Implementations + - Quota Support + - Application Notes + - Known Issues -\subsubsection{University of Washington IMAP C-Client} +================== +Installation Notes +================== + +-------------------------------------- +University of Washington IMAP C-Client +-------------------------------------- You will need a source distribution of University of Washington's IMAP c-client (http://www.washington.edu/imap/). Asterisk supports both the -2004 and 2006 versions of c-client, however mail\_expunge\_full is enabled +2004 and 2006 versions of c-client, however mail_expunge_full is enabled in the 2006 version. Note that Asterisk only uses the 'client' portion of the UW IMAP toolkit, @@ -37,23 +56,23 @@ is outside the scope of this document. Building the c-client library is fairly straightforward; for example, on a Debian system there are two possibilities: -\begin{verbatim} 1) if you will not be using SSL to connect to the IMAP server: $ make slx SSLTYPE=none 2) if you will be using SSL to connect to the IMAP server: $ make slx EXTRACFLAGS="-I/usr/include/openssl" -\end{verbatim} Once this completes you can proceed with the Asterisk build; there is no need to run 'make install'. -\subsubsection{Compiling Asterisk} +------------------ +Compiling Asterisk +------------------ Configure with ./configure --with-imap=/usr/src/imap or where ever you built thfe UWashington IMAP Toolkit. When you run 'make menuselect', choose 'Voicemail Build Options' and the -IMAP\_STORAGE option should be available for selection. +IMAP_STORAGE option should be available for selection. Note that the --with-imap option will NOT search your system for an installed copy of the IMAP Toolkit c-client library; the Asterisk @@ -64,18 +83,17 @@ distribution. After selecting it, use the 'x' key to exit menuselect and save your changes, and the build/install Asterisk normally. -\subsection{Modify voicemail.conf} - +--------------------- +Modify voicemail.conf +--------------------- The following directives have been added to voicemail.conf: -\begin{verbatim} imapserver=<name or IP address of IMAP mail server> imapport=<IMAP port, defaults to 143> imapflags=<IMAP flags, "novalidate-cert" for example> expungeonhangup=<yes or no> authuser=<username> authpassword=<password> -\end{verbatim} The "expungeonhangup" flag is used to determine if the voicemail system should expunge all messages marked for deletion when the user hangs up the phone. @@ -83,25 +101,24 @@ expunge all messages marked for deletion when the user hangs up the phone. Each mailbox definition should also have imapuser=<imap username>. For example: -\begin{verbatim} 4123=>4123,James Rothenberger,jar@onebiztone.com,,attach=yes|imapuser=jar -\end{verbatim} The directives "authuser" and "authpassword" are not needed when using Kerberos. They are defined to allow Asterisk to authenticate as a single user that has access to all mailboxes as an alternative to Kerberos. - -\subsection{IMAP Folders} - +-------------- +IMAP Folders +-------------- Besides INBOX, users should create "Old", "Work", "Family" and "Friends" IMAP folders at the same level of hierarchy as the INBOX. These will be used as alternate folders for storing voicemail messages to mimic the behavior of the current (file-based) voicemail system. -\subsection{Separate vs. Shared Email Accounts} - +================================== +Separate vs. Shared Email Accounts +================================== As administrator you will have to decide if you want to send the voicemail messages to a separate IMAP account or use each user's existing IMAP mailbox for voicemail storage. The IMAP storage mechanism will work either way. @@ -115,42 +132,46 @@ system, not just the VOICEMAIL messages marked for deletion. By implementing separate IMAP mailboxes for voicemail and email, voicemail expunges will not remove regular email flagged for deletion. - -\subsection{IMAP Server Implementations} - +=========================== +IMAP Server Implementations +=========================== There are various IMAP server implementations, each supports a potentially different set of features. - -\subsubsection{UW IMAP-2005 or earlier} - +----------------------- +UW IMAP-2005 or earlier +----------------------- UIDPLUS is currently NOT supported on these versions of UW-IMAP. Please note -that without UID\_EXPUNGE, Asterisk voicemail will expunge ALL messages marked +that without UID_EXPUNGE, Asterisk voicemail will expunge ALL messages marked for deletion when a user exits the voicemail system (hangs up the phone). -\subsubsection{UW IMAP-2006 Development Branch} - -This version supports UIDPLUS, which allows UID\_EXPUNGE capabilities. This +------------------------------- +UW IMAP-2006 Development Branch +------------------------------- +This version supports UIDPLUS, which allows UID_EXPUNGE capabilities. This feature allow the system to expunge ONLY pertinent messages, instead of the default behavior, which is to expunge ALL messages marked for deletion when EXPUNGE is called. The IMAP storage mechanism is this version of Asterisk -will check if the UID\_EXPUNGE feature is supported by the server, and use it +will check if the UID_EXPUNGE feature is supported by the server, and use it if possible. -\subsubsection{Cyrus IMAP} - +---------- +Cyrus IMAP +---------- Cyrus IMAP server v2.3.3 has been tested using a hierarchy delimiter of '/'. -\subsection{Quota Support} - +============= +Quota Support +============= If the IMAP server supports quotas, Asterisk will check the quota when accessing voicemail. Currently only a warning is given to the user that their quota is exceeded. -\subsection{Application Notes} - +================= +Application Notes +================= Since the primary storage mechanism is IMAP, all message information that was previously stored in an associated text file, AND the recording itself, is now stored in a single email message. This means that the .gsm recording @@ -158,7 +179,6 @@ will ALWAYS be attached to the message (along with the user's preference of recording format if different - ie. .WAV). The voicemail message information is stored in the email message headers. These headers include: -\begin{verbatim} X-Asterisk-VM-Message-Num X-Asterisk-VM-Server-Name X-Asterisk-VM-Context @@ -171,4 +191,12 @@ X-Asterisk-VM-Duration X-Asterisk-VM-Category X-Asterisk-VM-Orig-date X-Asterisk-VM-Orig-time -\end{verbatim} + +================= +Known Issues +================= + + - Forward With Comment advanced option is not currently supported. + This feature will be added in the near future. + - Message Waiting Indicator blinks off and back on when a message arrives. + This should be fixed soon. diff --git a/doc/ip-tos.tex b/doc/ip-tos.txt index aa753b55e..36febd99a 100644 --- a/doc/ip-tos.tex +++ b/doc/ip-tos.txt @@ -1,25 +1,26 @@ -\subsubsection{Introduction} +IP Type of Service settings for VoIP channels +--------------------------------------------- Asterisk can set the Type of Service (TOS) byte on outgoing IP packets for various protocols. The TOS byte is used by the network to provide some level of Quality of Service (QoS) even if the network is congested with other traffic. -\subsubsection{SIP} - +* SIP +----- In sip.conf, there are three parameters that control the TOS settings: -"tos\_sip", "tos\_audio", and "tos\_video". tos\_sip controls what TOS SIP call -signalling packets are set to. tos\_audio controls what TOS RTP audio -packets are set to. tos\_video controls what TOS RTP video packets are +"tos_sip", "tos_audio", and "tos_video". tos_sip controls what TOS SIP call +signalling packets are set to. tos_audio controls what TOS RTP audio +packets are set to. tos_video controls what TOS RTP video packets are set to. - There is a "tos" parameter that is supported for backwards compatibility. The tos parameter should be avoided in sip.conf because it sets all three tos settings in sip.conf to the same value. -\subsubsection{IAX2} +* IAX2 +------ In iax.conf, there is a "tos" parameter that sets the global default TOS -for IAX packets generated by chan\_iax2. Since IAX connections combine +for IAX packets generated by chan_iax2. Since IAX connections combine signalling, audio, and video into one UDP stream, it is not possible to set the TOS separately for the different types of traffic. @@ -41,23 +42,22 @@ deprecated because they set the IP TOS using the outdated "IP precedence" model as defined in RFC 791 and RFC 1349. They still work in this version of Asterisk, but will be removed in future releases. -\begin{verbatim} =========================================== Configuration Parameter Recommended File Setting ------------------------------------------- -sip.conf tos\_sip cs3 -sip.conf tos\_audio ef -sip.conf tos\_video af41 +sip.conf tos_sip cs3 +sip.conf tos_audio ef +sip.conf tos_video af41 ------------------------------------------- iax.conf tos ef ------------------------------------------- iaxprov.conf tos ef =========================================== -\end{verbatim} -\subsubsection{Reference} +* REFERENCE +----------- RFC 2474 - "Definition of the Differentiated Services Field (DS field) in the IPv4 and IPv6 Headers", Nichols, K., et al, December 1998. @@ -70,12 +70,12 @@ To get the most out of setting the TOS on packets generated by Asterisk, you will need to ensure that your network handles packets with a TOS properly. For Cisco devices, see the previously mentioned "Enterprise QoS Solution Reference Network Design Guide". For Linux -systems see the "Linux Advanced Routing \& Traffic Control HOWTO" at +systems see the "Linux Advanced Routing & Traffic Control HOWTO" at <http://www.lartc.org/>. For more information on Quality of Service for VoIP networks see the "Enterprise QoS Solution Reference Network Design Guide" version 3.3 from Cisco at: -<http://www.cisco.com/application/pdf/en/us/guest/netsol/ns432/c649/ccmigration\_09186a008049b062.pdf> +<http://www.cisco.com/application/pdf/en/us/guest/netsol/ns432/c649/ccmigration_09186a008049b062.pdf> diff --git a/doc/jitterbuffer.tex b/doc/jitterbuffer.txt index 5122f1286..e5cd81ce0 100644 --- a/doc/jitterbuffer.tex +++ b/doc/jitterbuffer.txt @@ -1,13 +1,28 @@ -\subsubsection{The new jitterbuffer} +The new Jitterbuffer in Asterisk +-------------------------------- +Steve Kann + + +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: + +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. -\subsubsection{PLC} - +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. @@ -16,9 +31,9 @@ This facility is enabled by default in iLBC and speex, as it has no additional c This facility can be enabled in adpcm, alaw, g726, gsm, lpc10, and ulaw by setting genericplc => true in the [plc] section of codecs.conf. -\subsubsection{Trunktimestamps} - -To use this, both sides must be using Asterisk v1.2 or later. +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. @@ -27,8 +42,8 @@ The other side must also support this functionality, or else, well, bad things w 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. -\subsubsection{Communication with Asterisk v1.0.x systems} - +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. @@ -36,15 +51,15 @@ If you are connecting to an Asterisk server with earlier versions of the softwar 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 +You may also compile chan_iax2.c without the new jitterbuffer, enabling the old backwards compatible architecture. Look in the source code for instructions. -\subsubsection{Testing and monitoring} - +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 +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. @@ -55,26 +70,24 @@ end is telling us they are seeing). The remote stats may not be complete if the end isn't using the new jitterbuffer. The stats shown are: -\begin{itemize} -\item Jit: The jitter we have measured (milliseconds) -\item Del: The maximum delay imposed by the jitterbuffer (milliseconds) -\item Lost: The number of packets we've detected as lost. -\item \%: The percentage of packets we've detected as lost recently. -\item Drop: The number of packets we've purposely dropped (to lower latency). -\item OOO: The number of packets we've received out-of-order -\item Kpkts: The number of packets we've received / 1000. -\end{itemize} - -\subsubsection{Reporting problems} +* 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: -\begin{enumerate} -\item The JB and PLC can make your calls sound better, but they can't fix everything. +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. -\item Bad timestamps: If whatever is generating timestamps to be sent to you generates +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 @@ -83,16 +96,42 @@ The right solution to this is to find out what's causing the sender to send us s 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 +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. +sender sending 20% faster or slower than you expect just fine. -\item Really strange network delays: If your network "pauses" for like 5 seconds, and then +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. -\end{enumerate} +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. + +Have fun! + +-SteveK diff --git a/doc/linkedlists.txt b/doc/linkedlists.txt new file mode 100644 index 000000000..340933548 --- /dev/null +++ b/doc/linkedlists.txt @@ -0,0 +1,98 @@ +As of 2004-12-23, this documentation is no longer maintained. The doxygen documentation +generated from linkedlists.h should be referred to in its place, as it is more complete +and better maintained. + +2nd version, implemented as macros. + + include <asterisk/linkedlists.h> + +AST_LIST_ENTRY declares pointers inside the object structure : + + struct ast_var_t { + char *name; + char *value; + AST_LIST_ENTRY(ast_var_t) listpointers; + }; + +AST_LIST_HEAD declares a head structure, which is initialized +to AST_LIST_HEAD_NULL : + + AST_LIST_HEAD(head, ast_var_t) head + +Next, we declare a pointer to this structure : + + struct headtype *headp = head; + +AST_LIST_INIT initializes the head pointer to a null value + + AST_LIST_INIT(headp); + +AST_LIST_INSERT_HEAD inserts an element to the head of the list : + + struct ast_var_t *node; + + node=malloc(sizeof(struct ast_var_t)); + (...we fill data in struct....) + data->name=malloc(100); + strcpy(data->name,"lalalalaa"); + etc etc + + (then we insert the node in the head of the list :) + + AST_LIST_INSERT_HEAD(headp,node,listpointers); + +AST_LIST_INSERT_HEAD_AFTER inserts an element after another : + + struct ast_var_t *node1; + ... + AST_LIST_INSERT_AFTER(node,node1,listpointers); + +AST_LIST_REMOVE removes an arbitrary element from the head: + + AST_LIST_REMOVE(headp,node1,ast_var_t,listpointers); + +AST_LIST_REMOVE_HEAD removes the entry at the head of the list and +returns a pointer to the removed entry: + + AST_LIST_REMOVE_HEAD(headp,node,listpointers); + +AST_LIST_FIRST returns a pointer to the first element of the list; + + struct ast_var_t *firstnode; + firstnode=AST_LIST_FIRST(headp); + +AST_LIST_NEXT returns a pointer to the next element : + + struct ast_var_t *nextnode; + nextnode=AST_LIST_NEXT(firstnode,listpointers); + +AST_LIST_TRAVERSE traverses all elements of the list : + + struct ast_var_t *node; + + AST_LIST_TRAVERSE(headp,node,listpointers) { + printf("%s\n",node->name); + } + +AST_LIST_EMPTY evaluates to a true condition if there are no elements on +the list. + +To completely delete a list : + + struct ast_var_t *vardata; + + while (!AST_LIST_EMPTY(headp)) { /* List Deletion. */ + vardata = AST_LIST_REMOVE_HEAD(head, ast_var_t, listpointers); + free(vardata->name); + free(vardata->value); + } + +AST_LIST_LOCK returns true if it can lock the list, AST_LIST_UNLOCK unlocks +the list : + +if (AST_LIST_LOCK(headp)) { + ...do all list operations here... + AST_LIST_UNLOCK(headp); +} else { + ast_log(LOG_WARNING,"List locked bla bla bla\n"); +} diff --git a/doc/localchannel.tex b/doc/localchannel.txt index 76cf44566..f96ea15ec 100644 --- a/doc/localchannel.tex +++ b/doc/localchannel.txt @@ -1,29 +1,29 @@ -\subsection{Introduction} +The Local channel +----------------- -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. +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: -\subsection{Syntax} -\begin{verbatim} Local/extension@context[/n] -\end{verbatim} 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. -\subsection{Purpose} +* 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. +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. +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. -\subsection{Examples} +Examples: +--------- -\begin{verbatim} [inbound] ; here falls all incoming calls exten => s,1,Answer exten => s,2,Dial(local/200@internal,30,r) @@ -38,12 +38,12 @@ 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 -\end{verbatim} -\subsection{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. +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. -\begin{verbatim} Local/00531234567@pbx becomes Local/00531234567@pbx/n -\end{verbatim} + +---------- +2004-01-17 diff --git a/doc/manager.tex b/doc/manager.txt index 4c505ce5e..a0a832c8d 100644 --- a/doc/manager.tex +++ b/doc/manager.txt @@ -1,4 +1,5 @@ -\section{The Asterisk Manager TCP/IP API} +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, @@ -20,7 +21,9 @@ 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". -If you develop AMI applications, treat the headers +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. @@ -28,8 +31,8 @@ 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. -\section{Device status reports} - +Device status reports +--------------------- Manager subscribes to extension status reports from all channels, to be able to generate events when an extension or device changes state. The level of details in these events may depend on the channel @@ -38,30 +41,89 @@ file for more information. (in sip.conf, check the section on subscriptions and call limits) -\section{Command Syntax} - +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 +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: -\begin{itemize} - \item Action: An action requested by the CLIENT to the Asterisk SERVER. Only one "Action" may be outstanding at any time. - \item Response: A response to an action from the Asterisk SERVER to the CLIENT. - \item Event: An event reported by the Asterisk SERVER to the CLIENT -\end{itemize} + * 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 -\section{Manager commands} +Command: ExtensionState +Parameters: Exten, Context, ActionID -To see all of the available manager commands, use the "manager show commands" -CLI command. +Command: Hangup +Parameters: Channel -You can get more information about a manager command -with the "manager show command <command>" CLI command in Asterisk. +Command: Logoff +Parameters: None -\section{Examples} -\begin{verbatim} +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: PlayDTMF +Parameters: Channel, Digit + +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 @@ -97,15 +159,15 @@ Redirect with ExtraChannel: Priority: 1 Where 680 is an extension that sends you to a MeetMe room. -\end{verbatim} 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. -\section{Some standard AMI headers} -\begin{verbatim} +Some standard AMI headers: +-------------------------- + Account: -- Account Code (Status) AccountCode: -- Account Code (cdr_manager) ACL: <Y | N> -- Does ACL exist for object ? @@ -243,7 +305,6 @@ http://www.asterisk.org web site for more information. Value: <value> -- Value to set VoiceMailbox: -- VM Mailbox in SIPpeers Waiting: -- Count of mailbox messages (mailboxstatus) -\end{verbatim} ** Please try to re-use existing headers to simplify manager message parsing in clients. diff --git a/doc/math.txt b/doc/math.txt new file mode 100644 index 000000000..7718f9e44 --- /dev/null +++ b/doc/math.txt @@ -0,0 +1,69 @@ + +Mathematical dialplan function + +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}) diff --git a/doc/misdn.tex b/doc/misdn.txt index 3b1ca17ae..74f9742fb 100644 --- a/doc/misdn.tex +++ b/doc/misdn.txt @@ -1,126 +1,142 @@ -\subsection{Introduction} +mISDN Channel Driver for Asterisk PBX +====================================== + This package contains the mISDN Channel Driver for the Asterisk PBX. It supports every mISDN Hardware and provides an interface for asterisk. -\subsection{Features} - -\begin{itemize} -\item NT and TE mode -\item PP and PMP mode -\item BRI and PRI (with BNE1 and BN2E1 Cards) -\item Hardware Bridging -\item DTMF Detection in HW+mISDNdsp -\item Display Messages on Phones (on those that support display msg) -\item app\_SendText -\item HOLD/RETRIEVE/TRANSFER on ISDN Phones : ) -\item Screen/ Not Screen User Number -\item EchoCancellation -\item Volume Control -\item Crypting with mISDNdsp (Blowfish) -\item Data (HDLC) callthrough -\item Data Calling (with app\_ptyfork +pppd) -\item Echo cancellation -\item CallDeflection -\item Some other -\end{itemize} - -\subsection{Fast Installation Guide} +Features: +--------- + +* NT and TE mode +* PP and PMP mode +* BRI and PRI (with BNE1 and BN2E1 Cards) +* Hardware Bridging +* DTMF Detection in HW+mISDNdsp +* Display Messages on Phones (on those that support display msg) +* app_SendText +* HOLD/RETRIEVE/TRANSFER on ISDN Phones : ) +* Screen/ Not Screen User Number +* 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. + +Overview +-------- + +- Fast Installation Guide +- Pre-Requisites +- Configuration +- Dial and Options String +- misdn cli commands +- mISDN Variables +- Debugging and sending Bugreports +- Examples +- Known Problems +- Changes + + +Fast Installation Guide +----------------------- It is easy to install mISDN and mISDNuser. Just fetch the newest head of the cvs, this can be done by: -\begin{verbatim} cvs -d:pserver:anonymous:readonly@cvs.isdn4linux.de:/i4ldev co mISDN mISDNuser -\end{verbatim} -then compile and install both with: +the compile and install both with: -\begin{verbatim} cd mISDN ; make && make install -\end{verbatim} (you will need at least your kernel headers to compile mISDN). -\begin{verbatim} cd mISDNuser ; make && make install -\end{verbatim} -Now you can compile chan\_misdn, just by making asterisk: +Now you can compile chan_misdn, just by making asterisk: -\begin{verbatim} cd asterisk ; -./configure && make && make install -\end{verbatim} +make && make install That's all! -Follow the instructions in the mISDN Package for how to load the Kernel + +Follow the instructions in the mISDN Package for howto loading the Kernel Modules. -\subsection{Pre-Requisites} +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 +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. You should use Kernels >= 2.6.9 -\subsection{Configuration} +Configuration +------------- First of all you must configure the mISDN drivers, please follow the instructions in the mISDN package to do that, the main config file and config script is: -\begin{verbatim} /etc/init.d/misdn-init and /etc/misdn-init.conf -\end{verbatim} + Now you will want to configure the misdn.conf file which resides in the asterisk config directory (normally /etc/asterisk). -\subsubsection{misdn.conf: [general]} -The misdn.conf file contains a "general" subsection, and user subsections which +- misdn.conf: [general] +The misdn.conf file contains a "general" Section, and user sections which contain misdn port settings and different Asterisk contexts. -In the general subsection you can set options that are not directly port +In the general Section you can set options that are not directly port related. There is for example 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. -\subsubsection{misdn.conf: [default] subsection} +- misdn.conf: [default] section -The default subsection is another special subsection which can contain all the -options available in the user/port subsections. the user/port subsection inherit -their parameters from the default subsection. +The default section is another special section which can contain all the +options available in the user/port sections. the user/port section inherit +their parameters from the default section. -\subsubsection{misdn.conf: user/port subsections} +- misdn.conf: user/port sections -The user subsections have names which are unequal to "general". Those subsections +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 option. This option tells the -chan\_misdn driver to listen for incoming calls with the given msns, you can +chan_misdn driver to listen for incoming 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 subsections, which tells chan\_misdn where to +context variable resides in the user sections, which tells chan_misdn where to send incoming calls to in the Asterisk dial plan (extension.conf). -\subsubsection{Dial and Options String} +Dial and Options String +----------------------- -The dial string of chan\_misdn got more complex, because we added more features, +The dial string of chan_misdn got more complex, because we added more features, so the generic dial string looks like: -\begin{verbatim} mISDN/<port>|g:<group>/<extension>[/<OPTIONSSTRING>] The Optionsstring looks Like: @@ -138,49 +154,44 @@ The available Optchars are: s - send Non Inband DTMF as inband vr - rxgain control vt - txgain control -\end{verbatim} -chan\_misdn registers a new dial plan application "misdn\_set\_opt" when + +chan_misdn registers a new dial plan application "misdn_set_opt" when loaded. This application takes the Optionsstring as argument. The Syntax is: -\begin{verbatim} misdn_set_opt(<OPTIONSSTRING>) -\end{verbatim} + 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 +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: -\begin{verbatim} Phone1 --> * Box 1 --> PSTN_TE PSTN_TE --> * Box 2 --> Phone2 -\end{verbatim} The Encryption must be done on the PSTN sides, so the dialplan on the boxes are: -\begin{verbatim} * 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}) -\end{verbatim} -\subsection{mISDN CLI commands} + + +misdn cli commands +------------------ At the Asterisk cli you can try to type in: -\begin{verbatim} misdn <tab> <tab> -\end{verbatim} Now you should see the misdn cli commands: -\begin{verbatim} - clean -> pid (cleans a broken call, use with care, leads often to a segmentation fault) @@ -200,7 +211,6 @@ Now you should see the misdn cli commands: -> port (restarts given port (L2 Restart) ) - reload (reloads misdn.conf) -\end{verbatim} 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 @@ -213,17 +223,19 @@ 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. -\subsection{mISDN Variables} + +mISDN Variables +--------------- mISDN Exports/Imports a few Variables: -\begin{verbatim} - MISDN_ADDRESS_COMPLETE : Is either set to 1 from the Provider, or you can set it to 1 to force a sending complete. -\end{verbatim} -\subsection{Debugging and sending bug reports} + +Debugging and sending bug reports +--------------------------------- If you encounter problems, you should set up the debugging flag, usually debug=2 should be enough. the messages are divided in asterisk and misdn @@ -232,16 +244,17 @@ 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 +"chan_misdn" category. Read the bug guidelines to make sure you provide all the information needed. -\subsection{Examples} +Examples +-------- -Here are some examples of how to use chan\_misdn in the dialplan +Here are some examples of how to use chan_misdn in the dialplan (extensions.conf): -\begin{verbatim} + [globals] OUT_PORT=1 ; The physical Port of the Card OUT_GROUP=ExternE1 ; The Group of Ports defined in misdn.conf @@ -251,16 +264,28 @@ 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) -\end{verbatim} On the last line, you will notice the last argument (Hello); this is sent as Display Message to the Phone. -\subsection{Known Problems} +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 default compiled +modules) then modprobe ztdummy, this resolves the problem. + -\begin{verbatim} * I cannot hear any tone after a successful CONNECT to the other end --> you forgot to load mISDNdsp, which is now needed by chan\_misdn for switching +-> you forgot to load mISDNdsp, which is now needed by chan_misdn for switching and dtmf tone detection -\end{verbatim} + + +Changes +------- +in the Changes File + diff --git a/doc/model.txt b/doc/model.txt new file mode 100644 index 000000000..10d2d0e05 --- /dev/null +++ b/doc/model.txt @@ -0,0 +1,15 @@ +Description of call model: + +Incoming Call: + + Channel backend waits for a RING or equivalent on some sort of +interface. Typically this is done in its own thread. When a RING is +detected, the backend should create a channel structure and then call +ast_pbx_start() on that channel, which will create a thread to monitor +that interface. At this point, the PBX and/or applications it launches +will manage the interface, and it need not be monitored by the +aforementioned thread. When the applications are finished, the requisite +hangup function will be called, at which the channel can be considered to +be no longer valid, and the thread that controls it will imminently be +terminated. + diff --git a/doc/mp3.tex b/doc/mp3.txt index b1713fc1d..191bddb6e 100644 --- a/doc/mp3.tex +++ b/doc/mp3.txt @@ -1,5 +1,7 @@ -\subsubsection{MP3 Music On Hold} +* Asterisk MP3 Support +====================== +* MP3 Music On Hold Use of the mpg123 for your music on hold is no longer recommended and is now officially deprecated. You should now use one of the native formats for your music on hold selections. diff --git a/doc/musiconhold-fpm.txt b/doc/musiconhold-fpm.txt new file mode 100644 index 000000000..ad11c4815 --- /dev/null +++ b/doc/musiconhold-fpm.txt @@ -0,0 +1,8 @@ +About Hold Music +================ +Digium has licensed the music included with +the Asterisk distribution From FreePlayMusic +for use and distribution with Asterisk. It +is licensed ONLY for use as hold music within +an Asterisk based PBX. + diff --git a/doc/mysql.txt b/doc/mysql.txt new file mode 100644 index 000000000..27adaa956 --- /dev/null +++ b/doc/mysql.txt @@ -0,0 +1,15 @@ +MYSQL LICENSING UPDATE +====================== +We were recently contacted by MySQL and informed that the MySQL client +libraries are now under GPL license and not LGPL license as before. + +Since Asterisk does allow exceptions to GPL, we are removing MySQL support +from standard Asterisk. We will, where appropriate, make it available via +a separate package which will only be usable when Asterisk is used completely +within GPL (i.e. not in conjunction with G.729, OpenH.323, etc). We +apologize for the confusion. + +You may find this in the new "asterisk-addons" package. + +Mark Spencer +Digium diff --git a/doc/odbcstorage.tex b/doc/odbcstorage.txt index 97d1c94f1..435574b0e 100644 --- a/doc/odbcstorage.tex +++ b/doc/odbcstorage.txt @@ -1,9 +1,11 @@ +ODBC Voicemail Storage +====================== + ODBC Storage allows you to store voicemail messages within a database instead of using a file. This is *not* a full realtime engine and *only* supports ODBC. The table description for the "voicemessages" table is as follows: -\begin{verbatim} +----------------+-------------+------+-----+---------+-------+ | Field | Type | Null | Key | Default | Extra | +----------------+-------------+------+-----+---------+-------+ @@ -18,12 +20,11 @@ table is as follows: | mailboxcontext | varchar(80) | YES | | NULL | | | recording | longblob | YES | | NULL | | +----------------+-------------+------+-----+---------+-------+ -\end{verbatim} -The database name (from /etc/asterisk/res\_odbc.conf) is in the +The database name (from /etc/asterisk/res_odbc.conf) is in the "odbcstorage" variable in the general section of voicemail.conf. You may modify the voicemessages table name by using -odbctable=??? in voicemail.conf. +odbctable=??? in voicemail.conf diff --git a/doc/privacy.tex b/doc/privacy.txt index eed47644d..3a990fa4b 100644 --- a/doc/privacy.tex +++ b/doc/privacy.txt @@ -1,14 +1,26 @@ +Title: Everything About The Privacy Options In The Dial Command That +You Never Wanted To Know, And Even A Little More On Zapateller and +PrivacyManager: + +by Steve Murphy + + So, you want to avoid talking to pesky telemarketers/charity seekers/poll takers/magazine renewers/etc? -\subsection{First of all} +============= +First of all: +============= Try the FTC "Don't call" database, this alone will reduce your telemarketing call volume considerably. (see: https://www.donotcall.gov/default.aspx ) But, this list won't protect from the Charities, previous business relationships, etc. -\subsection{Next, Fight against autodialers!!} + +================================= +Next, Fight against autodialers!! +================================= Zapateller detects if callerid is present, and if not, plays the da-da-da tones that immediately precede messages like, "I'm sorry, @@ -26,7 +38,9 @@ number from their lists. I highly advise Zapateller for those seeking the nirvana of "privacy". -\subsection{Next, Fight against the empty CALLERID!} +======================================= +Next, Fight against the empty CALLERID! +======================================= A considerable percentage of the calls you don't want, come from sites that do not provide CallerID. @@ -53,8 +67,9 @@ the last year. not always be appropriate for all users. Another option might be to use call screening. See below.) - -\subsection{Next, use a WELCOME MENU !} +========================== +Next, use a WELCOME MENU ! +========================== Experience has shown that simply presenting incoming callers with a set of options, no matter how simple, will deter them from calling @@ -64,8 +79,11 @@ hang up rather than make a choice and press a key. This will also immediately foil all autodialers that simply belch a message in your ear and hang up. -\subsubsection{Example usage of Zapateller and PrivacyManager} -\begin{verbatim} + +---------------------------------------------- +Example usage of Zapateller and PrivacyManager: +---------------------------------------------- + [homeline] exten => s,1,Answer exten => s,2,SetVar,repeatcount=0 @@ -78,7 +96,6 @@ exten => s,108,Background(tt-monkeys) exten => s,109,Background(tt-weasels) exten => s,110,Hangup exten => s,5,GotoIf($[ "${CALLERIDNUM}" = "7773334444" & "${CALLERIDNAME}" : "Privacy Manager" ]?callerid-liar|s|1:s|7) -\end{verbatim} I suggest using Zapateller at the beginning of the context, before anything else, on incoming calls.This can be followed by the @@ -98,8 +115,9 @@ usually get thru to my main intro, hang up. I guess they can see it's pointless, or the average telemarketer/charity-seeker is instructed not to enter options when encountering such systems. Don't know. - -\subsection{Next: Torture Them!} +=================== +Next: Torture Them! +=================== I have developed an elaborate script to torture Telemarketers, and entertain friends. (See @@ -127,7 +145,9 @@ so what the heck. but, that's about it. Not a whole lot. But I haven't had to say "NO" or "GO AWAY" to any of these folks for about a year now ...! -\subsection{Using Call Screening} +======================================== + Using Call Screening +======================================= Another option is to use call screening in the Dial command. It has two main privacy modes, one that remembers the CID of the caller, and @@ -137,31 +157,30 @@ have a "memory". Turning on these modes in the dial command results in this sequence of events, when someone calls you at an extension: -\begin{enumerate} -\item The caller calls the Asterisk system, and at some point, selects an +1. The caller calls the Asterisk system, and at some point, selects an option or enters an extension number that would dial your extension. -\item Before ringing your extension, the caller is asked to supply an +2. Before ringing your extension, the caller is asked to supply an introduction. The application asks them: "After the tone, say your name". They are allowed 4 seconds of introduction. -\item After that, they are told "Hang on, we will attempt to connect you +3. After that, they are told "Hang on, we will attempt to connect you to your party. Depending on your dial options, they will hear ringing indications, or get music on hold. I suggest music on hold. -\item Your extension is then dialed. When (and if) you pick up, you are +4. Your extension is then dialed. When (and if) you pick up, you are told that a caller presenting themselves as <their recorded intro is played> is calling, and you have options, like being connected, sending them to voicemail, torture, etc. -\item You make your selection, and the call is handled as you chose. -\end{enumerate} +5. You make your selection, and the call is handled as you chose. + There are some variations, and these will be explained in due course. To use these options, set your Dial to something like: -\begin{verbatim} + exten => 3,3,Dial(Zap/5r3&Zap/6r3|35|tmPA(beep)) or @@ -171,9 +190,9 @@ exten => 3,3,Dial(Zap/5r3&Zap/6r3|35|tmP(something)A(beep)) or exten => 3,3,Dial(Zap/5r3&Zap/6r3|35|tmpA(beep)) -\end{verbatim} -The 't' allows the dialed party to transfer the call using '\#'. It's + +The 't' allows the dialed party to transfer the call using '#'. It's optional. The 'm' is for music on hold. I suggest it. Otherwise, the calling @@ -197,13 +216,15 @@ helpful. When there is no CallerID, P and p options will always record an intro for the incoming caller. This intro will be stored temporarily in the /var/lib/asterisk/sounds/priv-callerintros dir, under the name -NOCALLERID\_<extension><channelname> and will be erased after the +NOCALLERID_<extension><channelname> and will be erased after the callee decides what to do with the call. Of course, NOCALLERID is not stored in the database. All those with no CALLERID will be considered "Unknown". -\subsection{The 'N' and 'n' options} +======================== + The 'N' and 'n' options +======================== Two other options exist, that act as modifiers to the privacy options 'P' and 'p'. They are 'N' and 'n'. You can enter them as dialing @@ -220,15 +241,15 @@ choice on how to handle the call. Whether the P option or the p option is used, the incoming caller will have to supply their intro every time they call. +======================= +Recorded Introductions +======================= -\subsection{Recorded Introductions} - -\subsubsection{Philosophical Side Note} +[Philosophical Side Note: The 'P' option stores the CALLERID in the database, along with the callee's choice of actions, as a convenience to the CALLEE, whereas introductions are stored and re-used for the convenience of the CALLER.] -\subsubsection{Introductions} Unless instructed to not save introductions (see the 'n' option above), the screening modes will save the recordings of the caller's names in the directory /var/lib/asterisk/sounds/priv-callerintros, if they have @@ -244,9 +265,7 @@ having to supply their name, which shortens their call a bit. Next of all, these intros can be used in voicemail, played over loudspeakers, and perhaps other nifty things. For instance: -\begin{verbatim} exten => s,7,System(/usr/bin/play /var/lib/asterisk/sounds/priv-callerintros/${CALLERIDNUM}.gsm&|0) -\end{verbatim} When a call comes in at the house, the above priority gets executed, and the callers intro is played over the phone systems speakers. This @@ -266,7 +285,6 @@ the home system's extensions.conf. (assume that a Goto(home-introduction|s|1) exists somewhere in your main menu as an option): -\begin{verbatim} [home-introduction] exten => s,1,Background,intro-options ;; Script: To hear your Introduction, dial 1. ;; to record a new introduction, dial 2. @@ -334,10 +352,10 @@ exten => t,1,Goto(s,1) exten => i,1,Background,invalid exten => i,2,Goto(s,1) exten => o,1,Goto(s,1) -\end{verbatim} + In the above, you'd most likely reword the messages to your liking, and maybe do more advanced things with the 'error' conditions (i,o,t priorities), -but I hope it conveys the idea. +but I hope it conveys the idea... diff --git a/doc/queuelog.tex b/doc/queuelog.txt index 79d9ff532..fa8cb48e8 100644 --- a/doc/queuelog.tex +++ b/doc/queuelog.txt @@ -1,8 +1,11 @@ +Queue Log Information +===================== + 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. +queue log, located (by default) in /var/log/asterisk/queue_log. These are the events (and associated information) in the queue log: @@ -90,7 +93,7 @@ Caller was transferred to a different extension. Context and extension are recorded. The caller's hold time and the length of the call are both recorded. PLEASE remember that transfers performed by SIP UA's by way of a reinvite may not always be caught by Asterisk and trigger off this -event. The only way to be 100\% sure that you will get this event when +event. The only way to be 100% sure that you will get this event when a transfer is performed by a queue member is to use the built-in transfer functionality of Asterisk. diff --git a/doc/queues-with-callback-members.tex b/doc/queues-with-callback-members.txt index 24a6d899d..3a2c3e785 100644 --- a/doc/queues-with-callback-members.tex +++ b/doc/queues-with-callback-members.txt @@ -1,5 +1,5 @@ -\section{Introduction} +Setting up Call Queues -- A Tutorial Pardon, but the dialplan in this tutorial will be expressed in AEL, the new Asterisk Extension Language. If you are @@ -8,14 +8,12 @@ degree intuitive. If not, there are documents explaining its syntax and constructs. -\section{Configuring Call Queues} +====== Configuring Call Queues -\subsection{queues.conf} First of all, set up call queues in queue.conf Here is an example: -\begin{verbatim} =========== queues.conf =========== | ; Cool Digium Queues | | [general] | @@ -45,7 +43,6 @@ Here is an example: | joinempty=strict | | leavewhenempty=strict | =================================== -\end{verbatim} In the above, we have defined 3 separate calling queues: sales-general, customerservice, and support-dispatch. @@ -76,17 +73,19 @@ remaining incoming callers will immediately be removed from the queue, and the Queue() call will return, IF the "leavewhenempty" is set to "strict". -\subsection{Routing incoming Calls to Queues} + +===================================== +| Routing incoming Calls to Queues | +===================================== Then in extensions.ael, you can do these things: -\subsubsection{The Main Menu} +================ The Main Menu At Digium, incoming callers are sent to the "mainmenu" context, where they are greeted, and directed to the numbers they choose... -\begin{verbatim} context mainmenu { includes { @@ -133,11 +132,12 @@ context mainmenu { Hangup(); } } -\end{verbatim} -\subsubsection{The Contexts referenced from the queues.conf file} -\begin{verbatim} +============= The Contexts referenced from the queues.conf file + + + context sales { 0 => goto dispatch|s|1; @@ -159,12 +159,11 @@ context sales { Hangup(); } } -\end{verbatim} Please note that there is only one attempt to queue a call in the sales queue. All sales agents that are logged in will be rung. -\begin{verbatim} + context customerservice { 0 => { @@ -196,13 +195,12 @@ context customerservice { Hangup(); } } -\end{verbatim} Note that calls coming into customerservice will first be try to queue -calls to those agents with a QUEUE\_MAX\_PENALTY of 10, and if none are available, +calls to those agents with a QUEUE_MAX_PENALTY of 10, and if none are available, then all agents are rung. -\begin{verbatim} + context dispatch { @@ -226,31 +224,32 @@ context dispatch Hangup(); } } -\end{verbatim} And in the dispatch context, first agents of priority 10 are tried, then 20, and if none are available, all agents are tried. Notice that a common pattern is followed in each of the three queue contexts: -First, you set QUEUE\_MAX\_PENALTY to a value, then you call +First, you set QUEUE_MAX_PENALTY to a value, then you call Queue(<queue-name>,option,... (see the documentation for the Queue application)); In the above, note that the "t" option is specified, and this allows the agent picking up the incoming call the luxury of transferring the call to other parties. -The purpose of specifying the QUEUE\_MAX\_PENALTY is to develop a set of priorities +The purpose of specifying the QUEUE_MAX_PENALTY is to develop a set of priorities amongst agents. By the above usage, agents with lower number priorities will -be given the calls first, and then, if no-one picks up the call, the QUEUE\_MAX\_PENALTY +be given the calls first, and then, if no-one picks up the call, the QUEUE_MAX_PENALTY will be incremented, and the queue tried again. Hopefully, along the line, someone will pick up the call, and the Queue application will end with a hangup. -The final attempt to queue in most of our examples sets the QUEUE\_MAX\_PENALTY +The final attempt to queue in most of our examples sets the QUEUE_MAX_PENALTY to zero, which means to try all available agents. -\subsection{Assigning agents to Queues} +========================================= +| Assigning agents to Queues | +========================================= In this example dialplan, we want to be able to add and remove agents to handle incoming calls, as they feel they are available. As they log in, @@ -258,15 +257,16 @@ they are added to the queue's agent list, and as they log out, they are removed. If no agents are available, the queue command will terminate, and it is the duty of the dialplan to do something appropriate, be it sending the incoming caller to voicemail, or trying the queue again with a higher -QUEUE\_MAX\_PENALTY. +QUEUE_MAX_PENALTY. Because a single agent can make themselves available to more than one queue, the process of joining multiple queues can be handled automatically by the dialplan. -\subsubsection{Agents Log In and Out} -\begin{verbatim} +================= Agents Log In and Out + + context queues-loginout { 6092 => { @@ -284,7 +284,7 @@ context queues-loginout goto queues-manip,O${AGENT_NUMBER},1; } } -\end{verbatim} + In the above contexts, the agents dial 6092 to log into their queues, and they dial 6093 to log out of their queues. The agent is prompted @@ -293,7 +293,7 @@ and then they are transferred to the proper extension in the queues-manip context. The queues-manip context does all the actual work: -\begin{verbatim} + context queues-manip { // Raquel Squelch @@ -324,7 +324,6 @@ context queues-manip { &queue-success(); } } -\end{verbatim} In the above extensions, note that the queue-addremove macro is used to actually add or remove the agent from the applicable queue, @@ -335,7 +334,7 @@ of 20 or 30. In the above example, Raquel will be dialed first in the dispatch queue, if she has logged in. If she is not, then the second call of Queue() with priority of 20 will dial Brittanica if she is present, -otherwise the third call of Queue() with MAX\_PENALTY of 0 will +otherwise the third call of Queue() with MAX_PENALTY of 0 will dial Rock and Saline simultaneously. Also note that Rock will be among the first to be called in the sales-general @@ -346,7 +345,6 @@ which queue incoming calls are coming from. The call to queue-success() gives some feedback to the agent as they log in and out, that the process has completed. -\begin{verbatim} macro queue-success() { if( ${queue-announce-success} > 0 ) @@ -362,11 +360,10 @@ macro queue-success() } } } -\end{verbatim} + The queue-addremove macro is defined in this manner: -\begin{verbatim} macro queue-addremove(queuename,penalty) { switch(${MACRO_EXTEN:0:1}) @@ -393,19 +390,19 @@ macro queue-addremove(queuename,penalty) } } } -\end{verbatim} -Basically, it uses the first character of the MACRO\_EXTEN variable, to determine the +Basically, it uses the first character of the MACRO_EXTEN variable, to determine the proper actions to take. In the above dial plan code, only the cases I or O are used, which correspond to the Login and Logout actions. -\subsection{Controlling The Way Queues Call the Agents} +======================================================= +| Controlling The Way Queues Call the Agents | +======================================================= Notice in the above, that the commands to manipulate agents in queues have "@agents" in their arguments. This is a reference to the agents context: -\begin{verbatim} context agents { // General sales queue @@ -446,9 +443,8 @@ context agents 6170 => &callagent(${ROCK}); 6070 => &callagent(${SALINE}); } -\end{verbatim} -In the above, the variables \${RAQUEL}, etc stand for +In the above, the variables ${RAQUEL}, etc stand for actual devices to ring that person's phone (like Zap/37). @@ -461,7 +457,6 @@ Here is the callagent macro, note that if a person in the queue is called, but does not answer, then they are automatically removed from the queue. -\begin{verbatim} macro callagent(device) { if( ${GROUP_COUNT(${MACRO_EXTEN}@agents)}=0 ) @@ -486,27 +481,25 @@ macro callagent(device) Busy(); } } -\end{verbatim} -In the callagent macro above, the \${MACRO\_EXTEN} will +In the callagent macro above, the ${MACRO_EXTEN} will be 6121, or 6165, etc, which is the extension of the agent. -The use of the GROUP\_COUNT, and OUTBOUND\_GROUP follow this line +The use of the GROUP_COUNT, and OUTBOUND_GROUP follow this line of thinking. Incoming calls can be queued to ring all agents in the current priority. If some of those agents are already talking, they would get bothersome call-waiting tones. To avoid this inconvenience, -when an agent gets a call, the OUTBOUND\_GROUP assigns that +when an agent gets a call, the OUTBOUND_GROUP assigns that conversation to the group specified, for instance 6171@agents. -The \${GROUP\_COUNT()} variable on a subsequent call should return -"1" for that group. If GROUP\_COUNT returns 1, then the busy() +The ${GROUP_COUNT()} variable on a subsequent call should return +"1" for that group. If GROUP_COUNT returns 1, then the busy() is returned without actually trying to dial the agent. -\subsection{Pre Acknowledgement Message} +================ Pre Acknowledgement Message If you would like to have a pre acknowledge message with option to reject the message you can use the following dialplan Macro as a base with the 'M' dial argument. -\begin{verbatim} [macro-screen] exten=>s,1,Wait(.25) exten=>s,2,Read(ACCEPT|screen-callee-options|1) @@ -523,9 +516,9 @@ exten=>s,46,Set(MACRO_RESULT=CONTINUE) exten=>s,50,Playback(after-the-tone) exten=>s,51,Playback(connected) exten=>s,52,Playback(beep) -\end{verbatim} -\subsection{Caveats} +================ Caveats In the above examples, some of the possible error checking has been omitted, to reduce clutter and make the examples clearer. + diff --git a/doc/radius.txt b/doc/radius.txt new file mode 100644 index 000000000..041f072ac --- /dev/null +++ b/doc/radius.txt @@ -0,0 +1,203 @@ +Call Detail Recording to RADIUS Server +====================================== + + +Configuration of Asterisk to send CDRs to (Free)RADIUS servers. + + +A. What is needed : + * FreeRADIUS server + * Radiusclient-ng library + * Asterisk PBX + + + +--------------------+ + | Asterisk PBX | + | | + |********************| + | | +---------------+ + | RADIUS client |------->| RADIUS server | + | |<-------| (FreeRADIUS) | + +--------------------+ +---------------+ + + + + +B. Steps to follow in order to have RADIUS support: + + 1.Radiusclient library + 1.a Installation + + Download the sources from: + + http://developer.berlios.de/projects/radiusclient-ng/ + + Untar the source tarball. + root@localhost:/usr/local/src# tar xvfz radiusclient-ng-0.5.2.tar.gz + + Compile and install the library. + root@localhost:/usr/local/src# cd radiusclient-ng-0.5.2 + root@localhost:/usr/local/src/radiusclient-ng-0.5.2# ./configure + root@localhost:/usr/local/src/radiusclient-ng-0.5.2# make + root@localhost:/usr/local/src/radiusclient-ng-0.5.2# make install + + 1.b Configuration + + By default all the configuration files of the radiusclient library will + be in /usr/local/etc/radiusclient-ng directory. + + File "radiusclient.conf" + Open the file and find lines containing the following: + + authserver localhost + + This is the hostname or IP address of the RADIUS server used for + authentication. You will have to change this unless the server is + running on the same host as your Asterisk PBX. + + acctserver localhost + + This is the hostname or IP address of the RADIUS server used for + accounting. You will have to change this unless the server is running + on the same host as your Asterisk PBX. + + File "servers" + + RADIUS protocol uses simple access control mechanism based on shared + secrets that allows RADIUS servers to limit access from RADIUS clients. + + A RADIUS server is configured with a secret string and only RADIUS + clients that have the same secret will be accepted. + + You need to configure a shared secret for each server you have + configured in radiusclient.conf file in the previous step. The shared + secrets are stored in /usr/local/etc/radiusclient-ng/servers file. + + Each line contains hostname of a RADIUS server and shared secret + used in communication with that server. The two values are separated + by white spaces. Configure shared secrets for every RADIUS server you + are going to use. + + File "dictionary" + + Asterisk uses some attributes that are not included in the + dictionary of radiusclient library, therefore it is necessary to add + them. A file called dictionary.digium (kept in the contrib dir) + was created to list all new attributes used by Asterisk. + Add to the end of the main dictionary file + /usr/local/etc/radiusclient-ng/dictionary + the line: + + $INCLUDE /path/to/dictionary.digium + + 2.FreeRADIUS Server (Version 1.1.1) + 2.a Installation + + Download sources tarball from: + + http://freeradius.org/ + + Untar, configure, build, and install the server: + + root@localhost:/usr/local/src# tar xvfz freeradius-1.1.1.tar.gz + root@localhost:/usr/local/src# cd freeradius-1.1.1 + root@localhost"/usr/local/src/freeradius-1.1.1# ./configure + root@localhost"/usr/local/src/freeradius-1.1.1# make + root@localhost"/usr/local/src/freeradius-1.1.1# make install + + All the configuration files of FreeRADIUS server will be in + /usr/local/etc/raddb directory. + + + 2.b Configuration + + There are several file that have to be modified to configure the + RADIUS server. These are presented next. + + File "clients.conf" + + File /usr/local/etc/raddb/clients.conf contains description of + RADIUS clients that are allowed to use the server. For each of the + clients you need to specify its hostname or IP address and also a + shared secret. The shared secret must be the same string you configured + in radiusclient library. + + Example: + client myhost { + secret = mysecret + shortname = foo + } + + This fragment allows access from RADIUS clients on "myhost" if they use + "mysecret" as the shared secret. + The file already contains an entry for localhost (127.0.0.1), so if you + are running the RADIUS server on the same host as your Asterisk server, + then modify the existing entry instead, replacing the default password. + + File "dictionary" + + Note : as of version 1.1.2, the dictionary.digium file ships with FreeRADIUS. + The following procedure brings the dictionary.digium file to previous versions + of FreeRADIUS. + + File /usr/local/etc/raddb/dictionary contains the dictionary of + FreeRADIUS server. You have to add the same dictionary file + (dictionary.digium), which you added to the dictionary of radiusclient-ng + library. You can include it into the main file, adding the following line at the + end of file '/usr/local/etc/raddb/dictionary': + + $INCLUDE /path/to/dictionary.digium + + That will include the same new attribute definitions that are used + in radiusclient-ng library so the client and server will understand each + other. + + + 3. Asterisk Accounting Configuration + + Compilation and installation: + The module will be compiled as long as the radiusclient-ng + library has been detected on your system. + + By default FreeRADIUS server will log all accounting requests into + /usr/local/var/log/radius/radacct directory in form of plain text files. + The server will create one file for each hostname in the directory. The + following example shows how the log files look like. + + Asterisk now generates Call Detail Records. See /include/asterisk/cdr.h + for all the fields which are recorded. By default, records in comma + separated values will be created in /var/log/asterisk/cdr-csv. + + The configuration file for cdr_radius.so module is : + + /etc/asterisk/cdr.conf + This is where you can set CDR related parameters as well as the path to + the radiusclient-ng library configuration file. + + + 4. Logged Values + + "Asterisk-Acc-Code", The account name of detail records + "Asterisk-Src", + "Asterisk-Dst", + "Asterisk-Dst-Ctx", The destination context + "Asterisk-Clid", + "Asterisk-Chan", The channel + "Asterisk-Dst-Chan", (if applicable) + "Asterisk-Last-App", Last application run on the channel + "Asterisk-Last-Data", Argument to the last channel + "Asterisk-Start-Time", + "Asterisk-Answer-Time", + "Asterisk-End-Time", + "Asterisk-Duration", Duration is the whole length that the entire + call lasted. ie. call rx'd to hangup + "end time" minus "start time" + "Asterisk-Bill-Sec", The duration that a call was up after other + end answered which will be <= to duration + "end time" minus "answer time" + "Asterisk-Disposition", ANSWERED, NO ANSWER, BUSY + "Asterisk-AMA-Flags", DOCUMENTATION, BILL, IGNORE etc, specified on + a per channel basis like accountcode. + "Asterisk-Unique-ID", Unique call identifier + "Asterisk-User-Field" User field set via SetCDRUserField + diff --git a/doc/realtime.tex b/doc/realtime.txt index c08dbc8a5..cc415ab73 100644 --- a/doc/realtime.tex +++ b/doc/realtime.txt @@ -1,4 +1,5 @@ -\subsubsection{Introduction} +The Asterisk Realtime Architecture +---------------------------------- The Asterisk Realtime Architecture is a new set of drivers and functions implemented in Asterisk. @@ -21,19 +22,17 @@ realtime driver will be supported in that function. Currently there are three realtime database drivers: -\begin{itemize} - \item ODBC: Support for UnixODBC, integrated into Asterisk - The UnixODBC subsystem supports many different databases, - please check www.unixodbc.org for more information. - \item MySQL: Found in the asterisk-addons subversion repository on svn.digium.com - \item PostgreSQL: Native support for Postgres, integrated into Asterisk -\end{itemize} - -\subsubsection{Two modes: Static and Realtime} +* ODBC: Support for UnixODBC, integrated into Asterisk + The UnixODBC subsystem supports many different databases, + please check www.unixodbc.org for more information. +* MySQL: Found in the asterisk-addons subversion repository on svn.digium.com +* PostgreSQL: Native support for Postgres, integrated into Asterisk +* Two modes: Static and Realtime +-------------------------------- The ARA realtime mode is used to dynamically load and update objects. This mode is used in the SIP and IAX2 channels, as well as in the voicemail -system. For SIP and IAX2 this is similar to the v1.0 MYSQL\_FRIENDS +system. For SIP and IAX2 this is similar to the v1.0 MYSQL_FRIENDS functionality. With the ARA, we now support many more databases for dynamic configuration of phones. @@ -42,8 +41,8 @@ modules that read configurations, there's no difference between a static file in the file system, like extensions.conf, and a configuration loaded from a database. -\subsubsection{Realtime SIP friends} - +* Realtime SIP friends +---------------------- The SIP realtime objects are users and peers that are loaded in memory when needed, then deleted. This means that Asterisk currently can't handle voicemail notification and NAT keepalives for these peers. Other than that, @@ -53,13 +52,13 @@ the ones in static configuration. With caching, the device stays in memory for a specified time. More information about this is to be found in the sip.conf sample file. -\subsubsection{Realtime H.323 friends} - +* Realtime H.323 friends +------------------------ Like SIP realtime friends, H.323 friends also can be configured using dynamic realtime objects. -\subsubsection{New function in the dial plan: The Realtime Switch} - +* New function in the dial plan: The Realtime Switch +---------------------------------------------------- The realtime switch is more than a port of functionality in v1.0 to the new architecture, this is a new feature of Asterisk based on the ARA. The realtime switch lets your Asterisk server do database lookups @@ -67,48 +66,43 @@ of extensions in realtime from your dial plan. You can have many Asterisk servers sharing a dynamically updated dial plan in real time with this solution. -Note that this switch does NOT support Caller ID matching, only -extension name or pattern matching. - -\subsubsection{Capabilities} +Note that this switch does _NOT_ support Caller ID matching, only +extension name/pattern matching. +* So what can you do? +--------------------- The realtime Architecture lets you store all of your configuration in databases and reload it whenever you want. You can force a reload over the AMI, Asterisk Manager Interface or by calling Asterisk from a shell script with - asterisk -rx "reload" You may also dynamically add SIP and IAX devices and extensions and making them available without a reload, by using the realtime objects and the realtime switch. -\subsubsection{Configuration in extconfig.conf} +* Configuration in extconfig.conf +--------------------------------- You configure the ARA in extconfig.conf (yes, it's a strange name, but is was defined in the early days of the realtime architecture and kind of stuck). Please see doc/extconfig.txt for database schemas. The part of Asterisk that connects to the ARA use a well defined family name to find the proper database driver. The syntax is easy: - -\begin{verbatim} - <family> => <realtime driver>,<db name>[,<table>] -\end{verbatim} + <family> => <realtime driver>,<db name>[,<table>] The options following the realtime driver identified depends on the driver. Defined well-known family names are: -\begin{itemize} - \item sippeers, sipusers - SIP peers and users - \item iaxpeers, iaxusers - IAX2 peers and users - \item voicemail - Voicemail accounts - \item queues - Queues - \item queue\_members - Queue members - \item extensions - Realtime extensions (switch) -\end{itemize} +* sippeers, sipusers SIP peers and users +* iaxpeers, iaxusers IAX2 peers and users +* voicemail Voicemail accounts +* queues Queues +* queue_members Queue members +* extensions Realtime extensions (switch) There is documentation of the SQL database in the file doc/extconfig.txt in your Asterisk source code tree. @@ -116,15 +110,17 @@ doc/extconfig.txt in your Asterisk source code tree. For voicemail storage with the support of ODBC, there is a doc/odbcstorage.txt documentation file. -\subsubsection{Limitations} +* Limitations +------------- Currently, realtime extensions do not support realtime hints. There is -a workaround available by using func\_odbc. See the sample func\_odbc.conf +a workaround available by using func_odbc. See the sample func_odbc.conf for more information. -\subsubsection{FreeTDS supported with connection pooling} +* FreeTDS supported with connection pooling +------------------------------------------- In order to use a FreeTDS-based database with realtime, you need to turn -connection pooling on in res\_odbc.conf. This is due to a limitation within +connection pooling on in res_odbc.conf. This is due to a limitation within the FreeTDS protocol itself. Please note that this includes databases such as MS SQL Server and Sybase. This support is new in the current release. diff --git a/doc/security.tex b/doc/security.txt index 188f42cab..0801679cc 100644 --- a/doc/security.tex +++ b/doc/security.txt @@ -1,4 +1,4 @@ -\subsection{Introduction} +==== Security Notes with Asterisk ==== PLEASE READ THE FOLLOWING IMPORTANT SECURITY RELATED INFORMATION. IMPROPER CONFIGURATION OF ASTERISK COULD ALLOW UNAUTHORIZED USE OF YOUR @@ -9,7 +9,7 @@ as well as dialplan security (authorization - who can access services in your pbx). If you are setting up Asterisk in production use, please make sure you understand the issues involved. -\subsection{Network Security} +* NETWORK SECURITY If you install Asterisk and use the "make samples" command to install a demonstration configuration, Asterisk will open a few ports for accepting @@ -28,7 +28,7 @@ The IAX2 protocol supports strong RSA key authentication as well as AES encryption of voice and signalling. The SIP channel does not support encryption in this version of Asterisk. -\subsection{Dialplan Security} +* DIALPLAN SECURITY First and foremost remember this: @@ -46,13 +46,10 @@ stations within you network. In particular, never ever put outgoing toll services in the "default" context. To make things easier, you can include the "default" context within other private contexts by using: -\begin{verbatim} include => default -\end{verbatim} in the appropriate section. A well designed PBX might look like this: -\begin{verbatim} [longdistance] exten => _91NXXNXXXXXX,1,Dial(Zap/g2/${EXTEN:1}) include => local @@ -63,13 +60,13 @@ include => default [default] exten => 6123,Dial(Zap/1) -\end{verbatim} + DON'T FORGET TO TAKE THE DEMO CONTEXT OUT OF YOUR DEFAULT CONTEXT. There isn't really a security reason, it just will keep people from wanting to play with your Asterisk setup remotely. -\subsection{Log Security} +* LOG SECURITY Please note that the Asterisk log files, as well as information printed to the Asterisk CLI, may contain sensitive information such as passwords and call diff --git a/doc/sla.pdf b/doc/sla.pdf Binary files differnew file mode 100644 index 000000000..c9f927ee8 --- /dev/null +++ b/doc/sla.pdf diff --git a/doc/sla.tex b/doc/sla.tex index efcd6b43f..c1159ce43 100644 --- a/doc/sla.tex +++ b/doc/sla.tex @@ -1,13 +1,13 @@ -%\documentclass[12pt,a4]{article} -%\usepackage{hyperref} +\documentclass[12pt,a4]{article} +\usepackage{hyperref} -%\author{Russell Bryant \\ Software Engineer \\ Digium, Inc.} -%\title{Shared Line Appearances} +\author{Russell Bryant \\ Software Engineer \\ Digium, Inc.} +\title{Shared Line Appearances} -%\begin{document} -%\maketitle +\begin{document} +\maketitle -%\tableofcontents +\tableofcontents \section{Introduction} @@ -375,4 +375,4 @@ have it on hold do not have private hold enabled. If connected, the appeareance of this trunk on this station will then show in use. All stations that are not currently connected to this trunk will show it on hold. -%\end{document} +\end{document} |