diff options
Diffstat (limited to 'trunk/doc/tex')
35 files changed, 7970 insertions, 0 deletions
diff --git a/trunk/doc/tex/Makefile b/trunk/doc/tex/Makefile new file mode 100644 index 000000000..70ad5f14a --- /dev/null +++ b/trunk/doc/tex/Makefile @@ -0,0 +1,44 @@ +include ../../makeopts + +pdf: asterisk.pdf + +asterisk.pdf: $(wildcard *.tex) +ifeq ($(findstring rubber,$(RUBBER)),) + @echo "**********************************************" + @echo "** You must install the \"rubber\" tool ***" + @echo "** to generate the Asterisk reference PDF. ***" + @echo "**********************************************" +else + @echo "**********************************************" + @echo "** The Asterisk reference PDF will now be ***" + @echo "** generated. When complete, it will be ***" + @echo "** located at asterisk.pdf. ***" + @echo "**********************************************" +ifneq ($(findstring kpsewhich,$(KPATHSEA)),) +ifeq ($(findstring fncychap.sty,$(shell find `$(KPATHSEA) --expand-braces='$$(TEXMF)'| tr -d \! | sed 's/:/ /g'` -name fncychap.sty -print)),) + @echo + @echo "WARNING: The fncychap.sty document was not found" + @echo "On Ubuntu, install the texlive-latex-extra package." + @echo + @exit +endif +endif + @cp asterisk.tex asterisk.tex.orig + sed -i -e 's/ASTERISKVERSION/$(shell echo $(ASTERISKVERSION) | sed -e 's/\//\\\//g')/' asterisk.tex + @$(RUBBER) --pdf asterisk.tex + @mv asterisk.tex.orig asterisk.tex +endif + +html: + @echo "**********************************************" + @echo "** The Asterisk reference HTML will now be ***" + @echo "** generated. When complete, it will be ***" + @echo "** located in the asterisk/ directory. ***" + @echo "** Note that the latex2html tool is ***" + @echo "** required for this to work. ***" + @echo "**********************************************" + @cp asterisk.tex asterisk.tex.orig + @sed -i -e 's/ASTERISKVERSION/$(ASTERISKVERSION)/' asterisk.tex + @latex2html asterisk.tex + @mv asterisk.tex.orig asterisk.tex + diff --git a/trunk/doc/tex/README.txt b/trunk/doc/tex/README.txt new file mode 100644 index 000000000..460d330a0 --- /dev/null +++ b/trunk/doc/tex/README.txt @@ -0,0 +1,24 @@ +Asterisk Reference Documentation +-------------------------------- + +1) To generate a PDF from this documentation, you will need the rubber tool, + and all of its dependencies. The web site for this tool is: + + http://www.pps.jussieu.fr/~beffara/soft/rubber/ + + Then, once this tool is installed, running "make pdf" will generate + the PDF automatically using this tool. The result will be asterisk.pdf. + + NOTE: After installing rubber, you will need to re-run the top level + configure script. It checks to see if rubber is installed, so that the + asterisk.pdf Makefile target can produce a useful error message when it is + not installed. + +2) To generate HTML from this documentation, you will need the latex2html tool, + and all of its dependencies. The web site for this tool is: + + http://www.latex2html.org/ + + Then, once this tool is installed, running "make html" will generate the + HTML documentation. The result will be an asterisk directory full of + HTML files. diff --git a/trunk/doc/tex/ael.tex b/trunk/doc/tex/ael.tex new file mode 100644 index 000000000..4d9fa2433 --- /dev/null +++ b/trunk/doc/tex/ael.tex @@ -0,0 +1,1305 @@ +\section{Introduction} + +AEL is a specialized language intended purely for +describing Asterisk dial plans. + +The current version was written by Steve Murphy, and is a rewrite of +the original version. + +This new version further extends AEL, and +provides more flexible syntax, better error messages, and some missing +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 + provided near the end of this document. + + \item 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 \$[ ... ] + 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 + 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 + 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 + priorities, and passes them via function calls into + Asterisk. Embedded in this language is the Application/AGI + 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 acts as a server. Devices involved in telephony, like Zapata +cards, or Voip phones, all indicate some context that should be +activated in their behalf. See the config file formats for IAX, SIP, +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 are a grouping of extensions. + +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} + +A Context contains zero or more Extensions. There are several +predefined extensions. The "s" extension is the "start" extension, and +when a device activates a context the "s" extension is the one that is +going to be run. Other extensions are the timeout "t" extension, the +invalid response, or "i" extension, and there's a "fax" extension. For +instance, a normal call will activate the "s" extension, but an +incoming FAX call will come into the "fax" extension, if it +exists. (BTW, asterisk can tell it's a fax call by the little "beep" +that the calling fax machine emits every so many seconds.). + +Extensions contain several priorities, which are individual +instructions to perform. Some are as simple as setting a variable to a +value. Others are as complex as initiating the Voicemail application, +for instance. Priorities are executed in order. + +When the 's" extension completes, asterisk waits until the timeout for +a response. If the response matches an extension's pattern in the +context, then control is transferred to that extension. Usually the +responses are tones emitted when a user presses a button on their +phone. For instance, a context associated with a desk phone might not +have any "s" extension. It just plays a dialtone until someone starts +hitting numbers on the keypad, gather the number, find a matching +extension, and begin executing it. That extension might Dial out over +a connected telephone line for the user, and then connect the two +lines together. + +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} + +Think of a macro as a combination of a context with one nameless +extension, and a subroutine. It has arguments like a subroutine +might. A macro call can be made within an extension, and the +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} + +Application calls, like "Dial()", or "Hangup()", or "Answer()", are +available for users to use to accomplish the work of the +dialplan. There are over 145 of them at the moment this was written, +and the list grows as new needs and wants are uncovered. Some +applications do fairly simple things, some provide amazingly complex +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 +Asterisk. This will be done automatically if using 'autoload=yes' in +\path{/etc/asterisk/modules.conf}. When the module is loaded, it will look +for 'extensions.ael' in \path{/etc/asterisk/}. extensions.conf and +extensions.ael can be used in conjunction with +each other if that is what is desired. Some users may want to keep +extensions.conf for the features that are configured in the 'general' +section of extensions.conf. + +To reload extensions.ael, the following command can be issued at the +CLI: + + *CLI> ael reload + +\section{Debugging} + +Right at this moment, the following commands are available, but do +nothing: + +Enable AEL contexts debug + + *CLI$>$ ael debug contexts + +Enable AEL macros debug + + *CLI$>$ ael debug macros + +Enable AEL read debug + + *CLI$>$ ael debug read + +Enable AEL tokens debug + + *CLI$>$ ael debug tokens + +Disable AEL debug messages + + *CLI$>$ ael no debug + +If things are going wrong in your dialplan, you can use the following +facilities to debug your file: + +1. The messages log in \path{/var/log/asterisk}. (from the checks done at load time). +2. the "show dialplan" command in asterisk +3. the standalone executable, "aelparse" built in the utils/ dir in the source. + + +\section{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 +most errors before giving the file to asterisk? + +aelparse is compiled in the utils directory of the asterisk release. +It isn't installed anywhere (yet). You can copy it to your favorite +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 + \path{/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 + 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} + +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 +keyword that precedes them. Statements can be split across lines, as +long as tokens are not broken by doing so. More than one statement can +be included on a single line. Whatever you think is best! + +You can just as easily say, + +\begin{astlisting} +\begin{verbatim} +if(${x}=1) { NoOp(hello!); goto s,3; } else { NoOp(Goodbye!); goto s,12; } +\end{verbatim} +\end{astlisting} +as you can say: +\begin{astlisting} +\begin{verbatim} +if(${x}=1) +{ + NoOp(hello!); + goto s,3; +} +else +{ + NoOp(Goodbye!); + goto s,12; +} +\end{verbatim} +\end{astlisting} + +or: + +\begin{astlisting} +\begin{verbatim} +if(${x}=1) { + NoOp(hello!); + goto s,3; +} else { + NoOp(Goodbye!); + goto s,12; +} +\end{verbatim} +\end{astlisting} + +or: + +\begin{astlisting} +\begin{verbatim} +if (${x}=1) { + NoOp(hello!); goto s,3; +} else { + NoOp(Goodbye!); goto s,12; +} +\end{verbatim} +\end{astlisting} + +\section{Keywords} + +The AEL keywords are case-sensitive. If an application name and a +keyword overlap, there is probably good reason, and you should +consider replacing the application call with an AEL statement. If you +do not wish to do so, you can still use the application, by using a +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 local + \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, + for those who would like to do so. + \item catch + \item switches + \item eswitches + \item includes +\end{itemize} + + +\section{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. + +This tree is then handed to the semantic check routine. + +Then the tree is handed to the compiler. + +After that, it is freed from memory. + +A program could be written that could build a tree of pval structures, and +a pretty printing function is provided, that would dump the data to a file, +or the tree could be handed to the compiler to merge the data into the +asterisk dialplan. The modularity of the design offers several opportunities +for developers to simplify apps to generate dialplan data. + + +\subsection{AEL version 2 BNF} + +(hopefully, something close to bnf). + +First, some basic objects + +\begin{astlisting} +\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> + +<objects> :== <object> + | <objects> <object> + + +<object> :== <context> + | <macro> + | <globals> + | ';' + + +<context> :== 'context' <word> '{' <elements> '}' + | 'context' <word> '{' '}' + | 'context' 'default' '{' <elements> '}' + | 'context' 'default' '{' '}' + | 'abstract' 'context' <word> '{' <elements> '}' + | 'abstract' 'context' <word> '{' '}' + | 'abstract' 'context' 'default' '{' <elements> '}' + | 'abstract' 'context' 'default' '{' '}' + + +<macro> :== 'macro' <word> '(' <arglist> ')' '{' <macro_statements> '}' + | 'macro' <word> '(' <arglist> ')' '{' '}' + | 'macro' <word> '(' ')' '{' <macro_statements> '}' + | 'macro' <word> '(' ')' '{' '}' + + +<globals> :== 'globals' '{' <global_statements> '}' + | 'globals' '{' '}' + + +<global_statements> :== <global_statement> + | <global_statements> <global_statement> + + +<global_statement> :== <word> '=' <collected-word> ';' + + +<arglist> :== <word> + | <arglist> ',' <word> + + +<elements> :== <element> + | <elements> <element> + + +<element> :== <extension> + | <includes> + | <switches> + | <eswitches> + | <ignorepat> + | <word> '=' <collected-word> ';' + | 'local' <word> '=' <collected-word> ';' + | ';' + + +<ignorepat> :== 'ignorepat' '=>' <word> ';' + + +<extension> :== <word> '=>' <statement> + | 'regexten' <word> '=>' <statement> + | 'hint' '(' <word3-list> ')' <word> '=>' <statement> + | 'regexten' 'hint' '(' <word3-list> ')' <word> '=>' <statement> + + +<statements> :== <statement> + | <statements> <statement> + +<if_head> :== 'if' '(' <collected-word> ')' + +<random_head> :== 'random' '(' <collected-word> ')' + +<ifTime_head> :== 'ifTime' '(' <word3-list> ':' <word3-list> ':' <word3-list> '|' <word3-list> '|' <word3-list> '|' <word3-list> ')' + | 'ifTime' '(' <word> '|' <word3-list> '|' <word3-list> '|' <word3-list> ')' + + +<word3-list> :== <word> + | <word> <word> + | <word> <word> <word> + +<switch_head> :== 'switch' '(' <collected-word> ')' '{' + + +<statement> :== '{' <statements> '}' + | <word> '=' <collected-word> ';' + | 'local' <word> '=' <collected-word> ';' + | 'goto' <target> ';' + | 'jump' <jumptarget> ';' + | <word> ':' + | 'for' '(' <collected-word> ';' <collected-word> ';' <collected-word> ')' <statement> + | 'while' '(' <collected-word> ')' <statement> + | <switch_head> '}' + | <switch_head> <case_statements> '}' + | '&' macro_call ';' + | <application_call> ';' + | <application_call> '=' <collected-word> ';' + | 'break' ';' + | 'return' ';' + | 'continue' ';' + | <random_head> <statement> + | <random_head> <statement> 'else' <statement> + | <if_head> <statement> + | <if_head> <statement> 'else' <statement> + | <ifTime_head> <statement> + | <ifTime_head> <statement> 'else' <statement> + | ';' + +<target> :== <word> + | <word> '|' <word> + | <word> '|' <word> '|' <word> + | 'default' '|' <word> '|' <word> + | <word> ',' <word> + | <word> ',' <word> ',' <word> + | 'default' ',' <word> ',' <word> + +<jumptarget> :== <word> + | <word> ',' <word> + | <word> ',' <word> '@' <word> + | <word> '@' <word> + | <word> ',' <word> '@' 'default' + | <word> '@' 'default' + +<macro_call> :== <word> '(' <eval_arglist> ')' + | <word> '(' ')' + +<application_call_head> :== <word> '(' + +<application_call> :== <application_call_head> <eval_arglist> ')' + | <application_call_head> ')' + +<eval_arglist> :== <collected-word> + | <eval_arglist> ',' <collected-word> + | /* nothing */ + | <eval_arglist> ',' /* nothing */ + +<case_statements> :== <case_statement> + | <case_statements> <case_statement> + + +<case_statement> :== 'case' <word> ':' <statements> + | 'default' ':' <statements> + | 'pattern' <word> ':' <statements> + | 'case' <word> ':' + | 'default' ':' + | 'pattern' <word> ':' + +<macro_statements> :== <macro_statement> + | <macro_statements> <macro_statement> + +<macro_statement> :== <statement> + | 'catch' <word> '{' <statements> '}' + +<switches> :== 'switches' '{' <switchlist> '}' + | 'switches' '{' '}' + +<eswitches> :== 'eswitches' '{' <switchlist> '}' + | 'eswitches' '{' '}' + +<switchlist> :== <word> ';' + | <switchlist> <word> ';' + +<includeslist> :== <includedname> ';' + | <includedname> '|' <word3-list> ':' <word3-list> ':' <word3-list> '|' <word3-list> '|' <word3-list> '|' <word3-list> ';' + | <includedname> '|' <word> '|' <word3-list> '|' <word3-list> '|' <word3-list> ';' + | <includeslist> <includedname> ';' + | <includeslist> <includedname> '|' <word3-list> ':' <word3-list> ':' <word3-list> '|' <word3-list> '|' <word3-list> '|' <word3-list> ';' + | <includeslist> <includedname> '|' <word> '|' <word3-list> '|' <word3-list> '|' <word3-list> ';' + +<includedname> :== <word> + | 'default' + +<includes> :== 'includes' '{' <includeslist> '}' + | 'includes' '{' '}' +\end{verbatim} +\end{astlisting} + +\section{AEL Example USAGE} + +\subsection{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 +comments is after terminating semicolons, or on otherwise empty lines. + + +\subsection{Context} + +Contexts in AEL represent a set of extensions in the same way that +they do in extensions.conf. +\begin{astlisting} +\begin{verbatim} +context default { + +} +\end{verbatim} +\end{astlisting} + +A context can be declared to be "abstract", in which case, this +declaration expresses the intent of the writer, that this context will +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{astlisting} +\begin{verbatim} +abstract context longdist { + _1NXXNXXXXXX => NoOp(generic long distance dialing actions in the US); +} +\end{verbatim} +\end{astlisting} + +\subsection{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{astlisting} +\begin{verbatim} +context default { + 1234 => Playback(tt-monkeys); + 8000 => { + NoOp(one); + NoOp(two); + NoOp(three); + }; + _5XXX => NoOp(it's a pattern!); +} +\end{verbatim} +\end{astlisting} + +Two optional items have been added to the AEL syntax, that allow the +specification of hints, and a keyword, regexten, that will force the +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{astlisting} +\begin{verbatim} +context default { + + regexten _5XXX => NoOp(it's a pattern!); +} +\end{verbatim} +\end{astlisting} + +\begin{astlisting} +\begin{verbatim} +context default { + + hint(Sip/1) _5XXX => NoOp(it's a pattern!); +} +\end{verbatim} +\end{astlisting} + +\begin{astlisting} +\begin{verbatim} +context default { + + regexten hint(Sip/1) _5XXX => NoOp(it's a pattern!); +} +\end{verbatim} +\end{astlisting} + +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{astlisting} +\begin{verbatim} +context zoombo +{ + 819/7079953345 => { NoOp(hello, 3345); } +} +\end{verbatim} +\end{astlisting} + +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 +another 819 extension defined for all those who wish 819, that are not so lucky +as to have 7079953345 as their CallerID! + + +\subsection{Includes} + +Contexts can be included in other contexts. All included contexts are +listed within a single block. + +\begin{astlisting} +\begin{verbatim} +context default { + includes { + local; + longdistance; + international; + } +} +\end{verbatim} +\end{astlisting} + +Time-limited inclusions can be specified, as in extensions.conf +format, with the fields described in the wiki page Asterisk cmd +GotoIfTime. + +\begin{astlisting} +\begin{verbatim} +context default { + includes { + local; + longdistance|16:00-23:59|mon-fri|*|*; + international; + } +} +\end{verbatim} +\end{astlisting} + +\subsection{\#include} + +You can include other files with the \#include "filepath" construct. + +\begin{astlisting} +\begin{verbatim} + #include "/etc/asterisk/testfor.ael" +\end{verbatim} +\end{astlisting} + +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 +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 +file (usually \path{/etc/asterisk}). + + + +\subsection{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{astlisting} +\begin{verbatim} +context default { + switches { + DUNDi/e164; + IAX2/box5; + }; + eswitches { + IAX2/context@${CURSERVER}; + } +} +\end{verbatim} +\end{astlisting} + +\subsection{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{astlisting} +\begin{verbatim} +context outgoing { + ignorepat => 9; +} +\end{verbatim} +\end{astlisting} + +\subsection{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{astlisting} +\begin{verbatim} +globals { + CONSOLE=Console/dsp; + TRUNK=Zap/g2; +} +\end{verbatim} +\end{astlisting} + +Variables can be set within extensions as well. + +\begin{astlisting} +\begin{verbatim} +context foo { + 555 => { + x=5; + y=blah; + divexample=10/2 + NoOp(x is ${x} and y is ${y} !); + } +} +\end{verbatim} +\end{astlisting} + +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. + +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]) + +Writing to a dialplan function is treated the same as writing to a variable. + +\begin{astlisting} +\begin{verbatim} +context blah { + s => { + CALLERID(name)=ChickenMan; + NoOp(My name is ${CALLERID(name)} !); + } +} +\end{verbatim} +\end{astlisting} + +You can declare variables in Macros, as so: + +\begin{astlisting} +\begin{verbatim} +Macro myroutine(firstarg, secondarg) +{ + Myvar=1; + NoOp(Myvar is set to ${myvar}); +} +\end{verbatim} +\end{astlisting} + +\subsection{Local Variables} + +In 1.2, and 1.4, ALL VARIABLES are CHANNEL variables, including the function +arguments and associated ARG1, ARG2, etc variables. Sorry. + +In trunk (1.6 and higher), we have made all arguments local variables to +a macro call. They will not affect channel variables of the same name. +This includes the ARG1, ARG2, etc variables. + +Users can declare their own local variables by using the keyword 'local' +before setting them to a value; + +\begin{astlisting} +\begin{verbatim} +Macro myroutine(firstarg, secondarg) +{ + local Myvar=1; + NoOp(Myvar is set to ${Myvar}, and firstarg is ${firstarg}, and secondarg is ${secondarg}); +} +\end{verbatim} +\end{astlisting} + +In the above example, Myvar, firstarg, and secondarg are all local variables, +and will not be visible to the calling code, be it an extension, or another Macro. + +If you need to make a local variable within the Set() application, you can do it this way: +\begin{astlisting} +\begin{verbatim} +Macro myroutine(firstarg, secondarg) +{ + Set(LOCAL(Myvar)=1); + NoOp(Myvar is set to ${Myvar}, and firstarg is ${firstarg}, and secondarg is ${secondarg}); +} +\end{verbatim} +\end{astlisting} + +\subsection{Loops} + +AEL has implementations of 'for' and 'while' loops. +\begin{astlisting} +\begin{verbatim} +context loops { + 1 => { + for (x=0; ${x} < 3; x=${x} + 1) { + Verbose(x is ${x} !); + } + } + 2 => { + y=10; + while (${y} >= 0) { + Verbose(y is ${y} !); + y=${y}-1; + } + } +} +\end{verbatim} +\end{astlisting} + +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} + +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 +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{astlisting} +\begin{verbatim} +context conditional { + _8XXX => { + Dial(SIP/${EXTEN}); + if ("${DIALSTATUS}" = "BUSY") + { + NoOp(yessir); + Voicemail(${EXTEN},b); + } + else + Voicemail(${EXTEN},u); + ifTime (14:00-25:00,sat-sun,*,*) + Voicemail(${EXTEN},b); + else + { + Voicemail(${EXTEN},u); + NoOp(hi, there!); + } + random(51) NoOp(This should appear 51% of the time); + + random( 60 ) + { + NoOp( This should appear 60% of the time ); + } + else + { + random(75) + { + NoOp( This should appear 30% of the time! ); + } + else + { + NoOp( This should appear 10% of the time! ); + } + } + } + _777X => { + switch (${EXTEN}) { + case 7771: + NoOp(You called 7771!); + break; + case 7772: + NoOp(You called 7772!); + break; + case 7773: + NoOp(You called 7773!); + // fall thru- + pattern 777[4-9]: + NoOp(You called 777 something!); + default: + NoOp(In the default clause!); + } + } +} +\end{verbatim} +\end{astlisting} + +NOTE: The conditional expression in if() statements (the + "\$\{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: AEL generates each case as a separate extension. case clauses + with no terminating 'break', or 'goto', have a goto inserted, to + the next clause, which creates a 'fall thru' effect. + +NOTE: AEL introduces the ifTime keyword/statement, which works just + like the if() statement, but the expression is a time value, + exactly like that used by the application GotoIfTime(). See + Asterisk cmd GotoIfTime + +NOTE: The pattern statement makes sure the new extension that is + 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 + are included verbatim in the labels generated. So watch out for + spaces! + +NOTE: NEW: Previous to version 0.13, the random statement used the + "Random()" application, which has been deprecated. It now uses + the RAND() function instead, in the GotoIf application. + + +\subsection{Break, Continue, and Return} + +Three keywords, break, continue, and return, are included in the +syntax to provide flow of control to loops, and switches. + +The break can be used in switches and loops, to jump to the end of the +loop or switch. + +The continue can be used in loops (while and for) to immediately jump +to the end of the loop. In the case of a for loop, the increment and +test will then be performed. In the case of the while loop, the +continue will jump to the test at the top of the loop. + +The return keyword will cause an immediate jump to the end of the +context, or macro, and can be used anywhere. + + + +\subsection{goto, jump, and labels} + +This is an example of how to do a goto in AEL. + +\begin{astlisting} +\begin{verbatim} +context gotoexample { + s => { +begin: + NoOp(Infinite Loop! yay!); + Wait(1); + goto begin; // go to label in same extension + } + 3 => { + goto s,begin; // go to label in different extension + } + 4 => { + goto gotoexample,s,begin; // overkill go to label in same context + } +} + +context gotoexample2 { + s => { + end: + goto gotoexample,s,begin; // go to label in different context + } +} +\end{verbatim} +\end{astlisting} + +You can use the special label of "1" in the goto and jump +statements. It means the "first" statement in the extension. I would +not advise trying to use numeric labels other than "1" in goto's or +jumps, nor would I advise declaring a "1" label anywhere! As a matter +of fact, it would be bad form to declare a numeric label, and it might +conflict with the priority numbers used internally by asterisk. + +The syntax of the jump statement is: jump +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{astlisting} +\begin{verbatim} +context gotoexample { + s => { +begin: + NoOp(Infinite Loop! yay!); + Wait(1); + jump s; // go to first extension in same extension + } + 3 => { + jump s,begin; // go to label in different extension + } + 4 => { + jump s,begin@gotoexample; // overkill go to label in same context + } +} + +context gotoexample2 { + s => { + end: + jump s@gotoexample; // go to label in different context + } +} +\end{verbatim} +\end{astlisting} + +NOTE: goto labels follow the same requirements as the Goto() + application, except the last value has to be a label. If the + label does not exist, you will have run-time errors. If the + label exists, but in a different extension, you have to specify + both the extension name and label in the goto, as in: goto s,z; + if the label is in a different context, you specify + context,extension,label. There is a note about using goto's in a + switch statement below... + +NOTE AEL introduces the special label "1", which is the beginning + context number for most extensions. + + +\subsection{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{astlisting} +\begin{verbatim} +macro std-exten( ext , dev ) { + Dial(${dev}/${ext},20); + switch(${DIALSTATUS) { + case BUSY: + Voicemail(${ext},b); + break; + default: + Voicemail(${ext},u); + + } + catch a { + VoiceMailMain(${ext}); + return; + } +} +\end{verbatim} +\end{astlisting} + +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{astlisting} +\begin{verbatim} +context example { + _5XXX => &std-exten(${EXTEN}, "IAX2"); + _6XXX => &std-exten(, "IAX2"); + _7XXX => &std-exten(${EXTEN},); + _8XXX => &std-exten(,); +} +\end{verbatim} +\end{astlisting} + + +\section{Examples} + +\begin{astlisting} +\begin{verbatim} +context demo { + s => { + Wait(1); + Answer(); + TIMEOUT(digit)=5; + TIMEOUT(response)=10; +restart: + Background(demo-congrats); +instructions: + for (x=0; ${x} < 3; x=${x} + 1) { + Background(demo-instruct); + WaitExten(); + } + } + 2 => { + Background(demo-moreinfo); + goto s,instructions; + } + 3 => { + LANGUAGE()=fr; + goto s,restart; + } + + 500 => { + Playback(demo-abouttotry); + Dial(IAX2/guest@misery.digium.com); + Playback(demo-nogo); + goto s,instructions; + } + 600 => { + Playback(demo-echotest); + Echo(); + Playback(demo-echodone); + goto s,instructions; + } + # => { +hangup: + Playback(demo-thanks); + Hangup(); + } + t => goto #,hangup; + i => Playback(invalid); +} +\end{verbatim} +\end{astlisting} + + +\section{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", + "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, + 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 + 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 + 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 + 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} + +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 + of the 'j' option is reported as error. + \item 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 + 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 + 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 + in \path{/var/lib/asterisk/applist}" on most systems). + \item 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} + +\section{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++ + hackers feel at home here. + \item 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 + 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 + matching paren/bracket counts. + \item 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 + 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 + 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 + debugging AEL files. One is called "aelparse", and it reads in + the \path{/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 "\path{/etc/asterisk/extensions.ael}", using the original + 'pbx\_ael.so' instead. + \item 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 + extension/Macro. + \item 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 + construct. See examples above. + \item 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 + 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 + will cause its arguments to be inserted in the extension under + 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 + expected. (0.6) + \item 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 + 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 + 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 ( + $<$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\}" = + "" ] The old way would do as shell scripts often do, and append + 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 ]. + + 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, + then say "Set(x=y);" instead. + + +\section{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?", +"Where's all the cool operators that other languages have to offer?", +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 + commands + + \item 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 + facilities, arithmetic expressions, etc. + + \item 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 + with them, and asterisk provides some global variables. These can be + manipulated and/or consulted by the above mechanisms. +\end{itemize} diff --git a/trunk/doc/tex/ajam.tex b/trunk/doc/tex/ajam.tex new file mode 100644 index 000000000..3421cc0ed --- /dev/null +++ b/trunk/doc/tex/ajam.tex @@ -0,0 +1,97 @@ +\section{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} + +\begin{enumerate} +\item Uncomment the line "enabled=yes" in \path{/etc/asterisk/http.conf} to enable + Asterisk's builtin micro HTTP server. + +\item 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 + your desired accessibility + +\item 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} + +\begin{enumerate} +\item Make sure you have both "enabled = yes" and "webenabled = yes" setup + in \path{/etc/asterisk/manager.conf} + +\item You may also use "httptimeout" to set a default timeout for HTTP + connections. + +\item Make sure you have a manager username/secret +\end{enumerate} + +Once those configurations are complete you can reload or restart +Asterisk and you should be able to point your web browser to specific +URI's which will allow you to access various web functions. A complete +list can be found by typing "http show status" at the Asterisk CLI. + +examples: +\begin{astlisting} +\begin{verbatim} +http://localhost:8088/asterisk/manager?action=login&username=foo&secret=bar +\end{verbatim} +\end{astlisting} +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 +length of httptimeout) which is used to connect to the same session. +\begin{astlisting} +\begin{verbatim} +http://localhost:8088/asterisk/rawman?action=status +\end{verbatim} +\end{astlisting} +Assuming you've already logged into manager, this URI will give you a +"raw" manager output for the "status" command. +\begin{astlisting} +\begin{verbatim} +http://localhost:8088/asterisk/mxml?action=status +\end{verbatim} +\end{astlisting} +This will give you the same status view but represented as AJAX data, +theoretically compatible with RICO (\url{http://www.openrico.org}). +\begin{astlisting} +\begin{verbatim} +http://localhost:8088/asterisk/static/ajamdemo.html +\end{verbatim} +\end{astlisting} +If you have enabled static content support and have done a make install, +Asterisk will serve up a demo page which presents a live, but very +basic, "astman" like interface. You can login with your username/secret +for manager and have a basic view of channels as well as transfer and +hangup calls. It's only tested in Firefox, but could probably be made +to run in other browsers as well. + +A sample library (astman.js) is included to help ease the creation of +manager HTML interfaces. + +Note that for the demo, there is no need for *any* external web server. + +\subsection{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 +minimal interfaces required. Even without the addition of an external +web server, one can use Asterisk's interfaces to implement screen pops +and similar tools pulling data from other web servers using iframes, +div's etc. If you want to integrate CGI's, databases, PHP, etc. you +will likely need to use a more traditional web server like Apache and +link in your Asterisk micro HTTP server with something like this: +\begin{astlisting} +\begin{verbatim} +ProxyPass /asterisk http://localhost:8088/asterisk +\end{verbatim} +\end{astlisting} + diff --git a/trunk/doc/tex/app-sms.tex b/trunk/doc/tex/app-sms.tex new file mode 100644 index 000000000..aa515f61a --- /dev/null +++ b/trunk/doc/tex/app-sms.tex @@ -0,0 +1,518 @@ +\section{Introduction} + + The SMS module for Asterisk was developed by Adrian Kennard, and is an + implementation of the ETSI specification for landline SMS, ETSI ES 201 + 912, which is available from \url{www.etsi.org}. Landline SMS is starting to + be available in various parts of Europe, and is available from BT in + the UK. However, Asterisk would allow gateways to be created in other + 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} + + Short Message Service (SMS), or texting is very popular between mobile + phones. A message can be sent between two phones, and normally + contains 160 characters. There are ways in which various types of data + 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 + message centre your telco provides by making a normal call and sending + the data using 1200 Baud FSK signaling according to the ETSI spec. To + receive a message the message centre calls the line with a specific + calling number, and the text capable phone answers the call and + receives the data using 1200 Baud FSK signaling. This works + particularly well in the UK as the calling line identity is sent + before the first ring, so no phones in the house would ring when a + message arrives. + +\section{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} + +\begin{itemize} + \item SMS - + Short Message Service + i.e. text messages + + \item SMSC - + Short Message Service Centre + The system responsible for storing and forwarding messages + + \item MO - + Mobile Originated + A message on its way from a mobile or landline device to the SMSC + + \item MT - + Mobile Terminated + A message on its way from the SMSC to the mobile or landline device + + \item RX - + Receive + A message coming in to the Asterisk box + + \item TX - + Transmit + A message going out of the Asterisk box +\end{itemize} + +\section{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 + device the message is sent to the landline number with an extra digit + appended to the end. The telco can define a default sub address (9 in + the UK) which is used when the extra digit is not appended to the end. + 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} + + The following contexts are recommended. + +\begin{astlisting} +\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 +in the queue and handle them, e.g. email them. +; The app may be something like smsq --process=somecommand --queue=${EXTEN} +to run a command for each received message +; See below for usage +[smsmtrx] +exten = _X.,1, SMS(${EXTEN},a) +exten = _X.,2,System("someapptohandleincomingsms ${EXTEN}") +exten = _X.,3,Hangup +; Mobile originated, RX. This is receiving a message from a device, e.g. +; a Magic Messenger on a sip extension +; Running an app after receipt of the text allows the app to find all messages +; in the queue and handle then, e.g. sending them to the public SMSC +; The app may be something like smsq --process=somecommand --queue=${EXTEN} +; to run a command for each received message +; See below for example usage +[smsmorx] +exten = _X.,1, SMS(${EXTEN},sa) +exten = _X.,2,System("someapptohandlelocalsms ${EXTEN}") +exten = _X.,3,Hangup +\end{verbatim} +\end{astlisting} + + smsmtrx is normally accessed by an incoming call from the SMSC. In the + UK this call is from a CLI of 080058752X0 where X is the sub address. + As such a typical usage in the extensions.conf at the point of + handling an incoming call is: +\begin{astlisting} +\begin{verbatim} +exten = _X./8005875290,1,Goto(smsmtrx,${EXTEN},1) +exten = _X./_80058752[0-8]0,1,Goto(smsmtrx,${EXTEN}-${CALLERID(num):8:1},1) +\end{verbatim} +\end{astlisting} + + Alternatively, if you have the correct national prefix on incoming + CLI, e.g. using zaphfc, you might use: +\begin{astlisting} +\begin{verbatim} +exten = _X./08005875290,1,Goto(smsmtrx,${EXTEN},1) +exten = _X./_080058752[0-8]0,1,Goto(smsmtrx,${EXTEN}-${CALLERID(num):9:1},1) +\end{verbatim} +\end{astlisting} + + smsmorx is normally accessed by a call from a local sip device + connected to a Magic Messenger. It could however by that you are + operating Asterisk as a message centre for calls from outside. Either + way, you look at the called number and goto smsmorx. In the UK, the + SMSC number that would be dialed is 1709400X where X is the caller sub + address. As such typical usage in extension.config at the point of + handling a call from a sip phone is: +\begin{astlisting} +\begin{verbatim} +exten = 17094009,1,Goto(smsmorx,${CALLERID(num)},1) +exten = _1709400[0-8],1,Goto(smsmorx,${CALLERID(num)}-{EXTEN:7:1},1) +\end{verbatim} +\end{astlisting} + +\section{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 + queue 0 to send the text "This is a test to 0123456789" to 0123456789. + It would then place a file in the \path{/var/spool/asterisk/outgoing} + 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 \verb!--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 + Show usage + --queue + -q + Specify a specific queue + In no specified, messages are queued under queue "0" + --da + -d + Specify destination address + --oa + -o + Specify originating address + This also implies that we are generating a mobile terminated message + --ud + -m + Specify the actual message + --ud-file + -f + Specify a file to be read for the context of the message + A blank filename (e.g. --ud-file= on its own) means read stdin. Very + useful when using via ssh where command line parsing could mess up the + message. + --mt + -t + Mobile terminated message to be generated + --mo + Mobile originated message to be generated + Default + --tx + Transmit message + Default + --rx + -r + Generate a message in the receive queue + --UTF-8 + Treat the file as UTF-8 encoded (default) + --UCS-1 + Treat the file as raw 8 bit UCS-1 data, not UTF-8 encoded + --UCS-2 + Treat the file as raw 16 bit bigendian USC-2 data + --process + Specific a command to process for each file in the queue + Implies --rx and --mt if not otherwise specified. + Sets environment variables for every possible variable, and also ud, + ud8 (USC-1 hex), and ud16 (USC-2 hex) for each call. Removes files. + --motx-channel + Specify the channel for motx calls + May contain X to use sub address based on queue name or may be full + number + Default is Local/1709400X + --motx-callerid + Specify the caller ID for motx calls + The default is the queue name without -X suffix + --motx-wait + Wait time for motx call + Default 10 + --motx-delay + Retry time for motx call + Default 1 + --motx-retries + Retries for motx call + Default 10 + --mttx-channel + Specify the channel for mttx calls + Default is Local/ and the queue name without -X suffix + --mtttx-callerid + Specify the callerid for mttx calls + May include X to use sub address based on queue name or may be full + number + Default is 080058752X0 + --mttx-wait + Wait time for mttx call + Default 10 + --mttx-delay + Retry time for mttx call + Default 30 + --mttx-retries + Retries for mttx call + Default 100 + --default-sub-address + The default sub address assumed (e.g. for X in CLI and dialled numbers + as above) when none added (-X) to queue + Default 9 + --no-dial + -x + Create queue, but do not dial to send message + --no-wait + Do not wait if a call appears to be in progress + This could have a small window where a message is queued but not + sent, so regular calls to smsq should be done to pick up any missed + messages + --concurrent + How many concurrent calls to allow (per queue), default 1 + --mr + -n + Message reference + --pid + -p + Protocol ID + --dcs + Data coding scheme + --udh + Specific hex string of user data header specified (not including the + initial length byte) + May be a blank string to indicate header is included in the user data + already but user data header indication to be set. + --srr + Status report requested + --rp + Return path requested + --vp + Specify validity period (seconds) + --scts + Specify timestamp (YYYY-MM-DDTHH:MM:SS) + --spool-dir + Spool dir (in which sms and outgoing are found) + Default /var/spool/asterisk +\end{verbatim} + + Other arguments starting '-' or '\verb!--!' are invalid and will cause an + error. Any trailing arguments are processed as follows:- + +\begin{itemize} + + \item If the message is mobile originating and no destination address + has been specified, then the first argument is assumed to be a + destination address + + \item If the message is mobile terminating and no destination address + has been specified, then the first argument is assumed to be the + queue name + + \item If there is no user data, or user data file specified, then any + following arguments are assumed to be the message, which are + concatenated. + + \item If no user data is specified, then no message is sent. However, + unless \verb!--no-dial! is specified, smsq checks for pending messages + and generates an outgoing anyway +\end{itemize} + + + Note that when smsq attempts to make a file in + \path{/var/spool/asterisk/outgoing}, it checks if there is already a call + queued for that queue. It will try several filenames, up to the + \verb!--concurrent! setting. If these files exist, then this means Asterisk + is already queued to send all messages for that queue, and so Asterisk + should pick up the message just queued. However, this alone could + create a race condition, so if the files exist then smsq will wait up + to 3 seconds to confirm it still exists or if the queued messages have + been sent already. The \verb!--no-wait! turns off this behaviour. Basically, + this means that if you have a lot of messages to send all at once, + Asterisk will not make unlimited concurrent calls to the same message + 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 + queued message it finds. A outgoing call will normally send all queued + messages for that queue. One way to use smsq would be to run with no + queue name (so any queue) every minute or every few seconds to send + pending message. This is not normally necessary unless \verb!--no-dial! is + 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). + The \verb!--process! option causes smsq to scan the specified queue (default + is mtrx) for messages (matching the queue specified, or any if queue + not specified) and run a command and delete the file. The command is + 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 + srr is set (to blank) if srr defined and has value 1. + $?rp + rp is set (to blank) if rp defined and has value 1. + $ud + User data, UTF-8 encoding, including any control characters, but with + nulls stripped out + Useful for the content of emails, for example, as it includes any + newlines, etc. + $ude + User data, escaped UTF-8, including all characters, but control + characters \n, \r, \t, \f, \xxx and \ is escaped as \\ + Useful guaranteed one line printable text, so useful in Subject lines + of emails, etc + $ud8 + Hex UCS-1 coding of user data (2 hex digits per character) + Present only if all user data is in range U+0000 to U+00FF + $ud16 + Hex UCS-2 coding of user data (4 hex digits per character) + 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} + + By default all queues are held in a director \path{/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, + \path{/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 + address) appended. If no queue ID is known, then 0 is used by smsq by + default. After this is a dot, and then any text. Files are scanned for + matching queue ID and a dot at the start. This means temporary files + being created can be given a different name not starting with a queue + (we recommend a . on the start of the file name for temp files). + 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 + da + Destination Address + The phone number to which the message is sent + Present on mobile originated messages + scts + The service centre time stamp + Format YYYY-MM-DDTHH:MM:SS + Present on mobile terminated messages + pid + One byte decimal protocol ID + See GSM specs for more details + Normally 0 or absent + dcs + One byte decimal data coding scheme + If omitted, a sensible default is used (see below) + See GSM specs for more details + mr + One byte decimal message reference + 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 + rp + 0 or 1 return path + See GSM specs for details + vp + Validity period in seconds + Does not work in UK yet + udh + Hex string of user data header prepended to the SMS contents, + excluding initial length byte. + Consistent with ud, this is specified as udh# rather than udh= + If blank, this means that the udhi flag will be set but any user data + 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). + 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 + byte) containing characters U+0000 to U+00FF only. + + 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 + 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. + +\section{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 + application may have a UK specific bodge in the near future to handle + these. + + The main changes that are proposed for delivery report handling are : + +\begin{itemize} + \item New queues for sent messages, one file for each destination + address and message reference. + + \item New field in message format, user reference, allowing applications + to tie up their original message with a report. + + \item Handling of the delivery confirmation/rejection and connecting to + 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{itemize} diff --git a/trunk/doc/tex/asterisk-conf.tex b/trunk/doc/tex/asterisk-conf.tex new file mode 100644 index 000000000..e25bc996f --- /dev/null +++ b/trunk/doc/tex/asterisk-conf.tex @@ -0,0 +1,141 @@ +\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{astlisting} +\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 + +; Stop accepting calls when free memory falls below this amount specified in MB +minmemfree = 256 + +; 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 + +; Locking mode for voicemail +; - lockfile: default, for normal use +; - flock: for where the lockfile locking method doesn't work +; eh. on SMB/CIFS mounts +lockmode = lockfile | flock + + +[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} +\end{astlisting} diff --git a/trunk/doc/tex/asterisk.tex b/trunk/doc/tex/asterisk.tex new file mode 100644 index 000000000..0feb3d7d9 --- /dev/null +++ b/trunk/doc/tex/asterisk.tex @@ -0,0 +1,162 @@ +% 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} + +\usepackage{url} +\makeatletter +\def\url@aststyle{% + \@ifundefined{selectfont}{\def\UrlFont{\sf}}{\def\UrlFont{\small\ttfamily}}} +\makeatother +\urlstyle{ast} + +\usepackage[titles]{tocloft} +\renewcommand{\cftchapfont}{% + \fontsize{11}{13}\usefont{OT1}{phv}{bc}{n}\selectfont +} + +\newenvironment{astlisting} +{\begin{list}{}{\setlength{\leftmargin}{1em}}\item\scriptsize\bfseries} +{\end{list}} + +\usepackage{sectsty} +\allsectionsfont{\usefont{OT1}{phv}{bc}{n}\selectfont} + +\usepackage[Lenny]{fncychap} + + +\author{Asterisk Development Team \\ Asterisk.org} +\title{Asterisk Reference Information \\ Version } + +\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 Quality of Service} + \input{qos.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} + \label{odbcstorage} + \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} + +\chapter{Phone Provisioning} + \input{phoneprov.tex} + +\chapter{Development} + \section{Backtrace} + \input{backtrace.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 +% +%callfiles.txt Asterisk callfiles using instruction +%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 + +\end{document} diff --git a/trunk/doc/tex/backtrace.tex b/trunk/doc/tex/backtrace.tex new file mode 100644 index 000000000..f43f42327 --- /dev/null +++ b/trunk/doc/tex/backtrace.tex @@ -0,0 +1,217 @@ +This document is intended to provide information on how to obtain the +backtraces required on the asterisk bug tracker, available at +\url{http://bugs.digium.com}. The information is required by developers to +help fix problem with bugs of any kind. Backtraces provide information +about what was wrong when a program crashed; in our case, +Asterisk. There are two kind of backtraces (aka 'bt') which are +useful: bt and bt full. + +First of all, when you start Asterisk, you MUST start it with option +-g. This tells Asterisk to produce a core file if it crashes. + +If you start Asterisk with the safe\_asterisk script, it automatically +starts using the option -g. + +If you're not sure if Asterisk is running with the -g option, type the +following command in your shell: + +\begin{astlisting} +\begin{verbatim} +debian:/tmp# ps aux | grep asterisk +root 17832 0.0 1.2 2348 788 pts/1 S Aug12 0:00 /bin/sh /usr/sbin/safe_asterisk +root 26686 0.0 2.8 15544 1744 pts/1 S Aug13 0:02 asterisk -vvvg -c +[...] +\end{verbatim} +\end{astlisting} + +The interesting information is located in the last column. + +Second, your copy of Asterisk must have been built without +optimization or the backtrace will be (nearly) unusable. This can be +done by selecting the 'DONT\_OPTIMIZE' option in the Compiler Flags +submenu in the 'make menuselect' tree before building Asterisk. + +After Asterisk crashes, a core file will be "dumped" in your \path{/tmp/} +directory. To make sure it's really there, you can just type the +following command in your shell: + +\begin{astlisting} +\begin{verbatim} +debian:/tmp# ls -l /tmp/core.* +-rw------- 1 root root 10592256 Aug 12 19:40 /tmp/core.26252 +-rw------- 1 root root 9924608 Aug 12 20:12 /tmp/core.26340 +-rw------- 1 root root 10862592 Aug 12 20:14 /tmp/core.26374 +-rw------- 1 root root 9105408 Aug 12 20:19 /tmp/core.26426 +-rw------- 1 root root 9441280 Aug 12 20:20 /tmp/core.26462 +-rw------- 1 root root 8331264 Aug 13 00:32 /tmp/core.26647 +debian:/tmp# +\end{verbatim} +\end{astlisting} + +In the event that there are multiple core files present (as in the +above example), it is important to look at the file timestamps in +order to determine which one you really intend to look at. + +Now that we've verified the core file has been written to disk, the +final part is to extract 'bt' from the core file. Core files are +pretty big, don't be scared, it's normal. + +\textbf{NOTE: Don't attach core files on the bug tracker, we only need the bt and bt full.} + +For extraction, we use a really nice tool, called gdb. To verify that +you have gdb installed on your system: + +\begin{astlisting} +\begin{verbatim} +debian:/tmp# gdb -v +GNU gdb 6.3-debian +Copyright 2004 Free Software Foundation, Inc. +GDB is free software, covered by the GNU General Public License, and you are +welcome to change it and/or distribute copies of it under certain conditions. +Type "show copying" to see the conditions. +There is absolutely no warranty for GDB. Type "show warranty" for details. +This GDB was configured as "i386-linux". +debian:/tmp# +\end{verbatim} +\end{astlisting} + +Which is great, we can continue. If you don't have gdb installed, go install gdb. + +Now load the core file in gdb, as follows: + +\begin{astlisting} +\begin{verbatim} +debian:/tmp# gdb asterisk /tmp/core.26252 +[...] +(You would see a lot of output here.) +[...] +Reading symbols from /usr/lib/asterisk/modules/app_externalivr.so...done. +Loaded symbols for /usr/lib/asterisk/modules/app_externalivr.so +#0 0x29b45d7e in ?? () +(gdb) +\end{verbatim} +\end{astlisting} + +Now at the gdb prompt, type: bt +You would see output similar to: + +\begin{astlisting} +\begin{verbatim} +(gdb) bt +#0 0x29b45d7e in ?? () +#1 0x08180bf8 in ?? () +#2 0xbcdffa58 in ?? () +#3 0x08180bf8 in ?? () +#4 0xbcdffa60 in ?? () +#5 0x08180bf8 in ?? () +#6 0x180bf894 in ?? () +#7 0x0bf80008 in ?? () +#8 0x180b0818 in ?? () +#9 0x08068008 in ast_stopstream (tmp=0x40758d38) at file.c:180 +#10 0x000000a0 in ?? () +#11 0x000000a0 in ?? () +#12 0x00000000 in ?? () +#13 0x407513c3 in confcall_careful_stream (conf=0x8180bf8, filename=0x8181de8 "Zap/pseudo-1324221520") at app_meetme.c:262 +#14 0x40751332 in streamconfthread (args=0x8180bf8) at app_meetme.c:1965 +#15 0xbcdffbe0 in ?? () +#16 0x40028e51 in pthread_start_thread () from /lib/libpthread.so.0 +#17 0x401ec92a in clone () from /lib/libc.so.6 +(gdb) +\end{verbatim} +\end{astlisting} + +The bt's output is the information that we need on the bug tracker. + +\begin{astlisting} +\begin{verbatim} +Now do a bt full as follows: +(gdb) bt full +#0 0x29b45d7e in ?? () +No symbol table info available. +#1 0x08180bf8 in ?? () +No symbol table info available. +#2 0xbcdffa58 in ?? () +No symbol table info available. +#3 0x08180bf8 in ?? () +No symbol table info available. +#4 0xbcdffa60 in ?? () +No symbol table info available. +#5 0x08180bf8 in ?? () +No symbol table info available. +#6 0x180bf894 in ?? () +No symbol table info available. +#7 0x0bf80008 in ?? () +No symbol table info available. +#8 0x180b0818 in ?? () +No symbol table info available. +#9 0x08068008 in ast_stopstream (tmp=0x40758d38) at file.c:180 +No locals. +#10 0x000000a0 in ?? () +No symbol table info available. +#11 0x000000a0 in ?? () +No symbol table info available. +#12 0x00000000 in ?? () +No symbol table info available. +#13 0x407513c3 in confcall_careful_stream (conf=0x8180bf8, filename=0x8181de8 "Zap/pseudo-1324221520") at app_meetme.c:262 + f = (struct ast_frame *) 0x8180bf8 + trans = (struct ast_trans_pvt *) 0x0 +#14 0x40751332 in streamconfthread (args=0x8180bf8) at app_meetme.c:1965 +No locals. +#15 0xbcdffbe0 in ?? () +No symbol table info available. +#16 0x40028e51 in pthread_start_thread () from /lib/libpthread.so.0 +No symbol table info available. +#17 0x401ec92a in clone () from /lib/libc.so.6 +No symbol table info available. +(gdb) +\end{verbatim} +\end{astlisting} + +We also need gdb's output. That output gives more details compared to +the simple "bt". So we recommend that you use bt full instead of bt. +But, if you could include both, we appreciate that. + +The final "extraction" would be to know all traces by all +threads. Even if asterisk runs on the same thread for each call, it +could have created some new threads. + +To make sure we have the correct information, just do: +(gdb) thread apply all bt + +\begin{astlisting} +\begin{verbatim} +Thread 1 (process 26252): +#0 0x29b45d7e in ?? () +#1 0x08180bf8 in ?? () +#2 0xbcdffa58 in ?? () +#3 0x08180bf8 in ?? () +#4 0xbcdffa60 in ?? () +#5 0x08180bf8 in ?? () +#6 0x180bf894 in ?? () +#7 0x0bf80008 in ?? () +#8 0x180b0818 in ?? () +#9 0x08068008 in ast_stopstream (tmp=0x40758d38) at file.c:180 +#10 0x000000a0 in ?? () +#11 0x000000a0 in ?? () +#12 0x00000000 in ?? () +#13 0x407513c3 in confcall_careful_stream (conf=0x8180bf8, filename=0x8181de8 "Zap/pseudo-1324221520") at app_meetme.c:262 +#14 0x40751332 in streamconfthread (args=0x8180bf8) at app_meetme.c:1965 +#15 0xbcdffbe0 in ?? () +#16 0x40028e51 in pthread_start_thread () from /lib/libpthread.so.0 +#17 0x401ec92a in clone () from /lib/libc.so.6 +(gdb) +\end{verbatim} +\end{astlisting} + +That output tells us crucial information about each thread. + +Now, just create an output.txt file and dump your "bt full" +(and/or "bt") ALONG WITH "thread apply all bt" into it. + +Note: Please ATTACH your output, DO NOT paste it as a note. + +And you're ready for upload on the bug tracker. + +If you have questions or comments regarding this documentation, feel +free to pass by the \#asterisk-bugs channel on irc.freenode.net. + diff --git a/trunk/doc/tex/billing.tex b/trunk/doc/tex/billing.tex new file mode 100644 index 000000000..9fae40be8 --- /dev/null +++ b/trunk/doc/tex/billing.tex @@ -0,0 +1,86 @@ +\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/trunk/doc/tex/cdrdriver.tex b/trunk/doc/tex/cdrdriver.tex new file mode 100644 index 000000000..174df5b68 --- /dev/null +++ b/trunk/doc/tex/cdrdriver.tex @@ -0,0 +1,458 @@ +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{astlisting} +\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} +\end{astlisting} + + Compile, configure, and install the latest FreeTDS package: +\begin{astlisting} +\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} +\end{astlisting} + + Compile, or recompile, asterisk so that it will now add support + for cdr\_odbc. +\begin{astlisting} +\begin{verbatim} + make clean && ./configure --with-odbc && + make update && + make && + make install +\end{verbatim} +\end{astlisting} + + 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{astlisting} +\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} +\end{astlisting} + + 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{astlisting} +\begin{verbatim} + [ -f /etc/asterisk/cdr_tds.conf ] > /etc/asterisk/cdr_tds.conf +\end{verbatim} +\end{astlisting} + 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{astlisting} +\begin{verbatim} + /etc/asterisk/cdr_odbc.conf + [global] + dsn=MSSQL-asterisk + username=voipdbuser + password=voipdbpass + loguniqueid=yes +\end{verbatim} +\end{astlisting} + And finally, create the 'cdr' table in your mssql database. +\begin{astlisting} +\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} +\end{astlisting} + 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{astlisting} +\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} +\end{astlisting} + Compile, or recompile, asterisk so that it will now add support + for cdr\_tds. +\begin{astlisting} +\begin{verbatim} + make clean && ./configure --with-tds && + make update && + make && + make install +\end{verbatim} +\end{astlisting} + 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{astlisting} +\begin{verbatim} + [ -f /etc/asterisk/cdr_odbc.conf ] > /etc/asterisk/cdr_odbc.conf +\end{verbatim} +\end{astlisting} + 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{astlisting} +\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} +\end{astlisting} + And finally, create the 'cdr' table in your mssql database. +\begin{astlisting} +\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} +\end{astlisting} + 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{astlisting} +\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} +\end{astlisting} + Now create a table in postgresql for your cdrs +\begin{astlisting} +\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} +\end{astlisting} + +\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} + + Download the sources from + \url{http://developer.berlios.de/projects/radiusclient-ng/} + + Untar the source tarball: + +\begin{verbatim} + root@localhost:/usr/local/src# tar xvfz radiusclient-ng-0.5.2.tar.gz +\end{verbatim} + + Compile and install the library: + +\begin{verbatim} + 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 \path{/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. + + \textbf{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 \path{/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. + + \textbf{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 + \path{/usr/local/etc/radiusclient-ng/dictionary} the line: + + \$INCLUDE /path/to/dictionary.digium + +\subsubsection{Install FreeRADIUS Server (Version 1.1.1)} + + Download sources tarball from: + + \url{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 \path{/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 \path{/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 \path{/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 + \path{/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 \path{/include/asterisk/cdr.h} + for all the fields which are recorded. By default, records in comma + separated values will be created in \path{/var/log/asterisk/cdr-csv}. + + The configuration file for cdr\_radius.so module is \path{/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/trunk/doc/tex/chaniax.tex b/trunk/doc/tex/chaniax.tex new file mode 100644 index 000000000..954e068b0 --- /dev/null +++ b/trunk/doc/tex/chaniax.tex @@ -0,0 +1,84 @@ +\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/trunk/doc/tex/channelvariables.tex b/trunk/doc/tex/channelvariables.tex new file mode 100644 index 000000000..d6981ec0b --- /dev/null +++ b/trunk/doc/tex/channelvariables.tex @@ -0,0 +1,974 @@ +\section{Introduction} + +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 + references with their values. +\item 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{astlisting} +\begin{verbatim} +exten => s,5,BackGround,blabla +\end{verbatim} +\end{astlisting} +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 \textbackslash. Special characters that must +be quoted to be used, are [ ] \$ " \textbackslash. (to write \textbackslash itself, use \textbackslash). + +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} + +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{astlisting} +\begin{verbatim} + exten => 1,2,Set(varname=value) +\end{verbatim} +\end{astlisting} +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{astlisting} +\begin{verbatim} + exten => 1,2,Set(koko=${blabla}${lala}) +\end{verbatim} +\end{astlisting} + +There are two reference modes - reference by value and reference by name. +To refer to a variable with its name (as an argument to a function that +requires a variable), just write the name. To refer to the variable's value, +enclose it inside \$\{\}. For example, Set takes as the first argument +(before the =) a variable name, so: +\begin{astlisting} +\begin{verbatim} + exten => 1,2,Set(koko=lala) + exten => 1,3,Set(${koko}=blabla) +\end{verbatim} +\end{astlisting} +stores to the variable "koko" the value "lala" and to variable "lala" the +value "blabla". + +In fact, everything contained \$\{here\} is just replaced with the value of +the variable "here". + +\section{Variable Inheritance} + +Variable names which are prefixed by "\_" will be inherited to channels +that are created in the process of servicing the original channel in +which the variable was set. When the inheritance takes place, the +prefix will be removed in the channel inheriting the variable. If the +name is prefixed by "\_\_" in the channel, then the variable is +inherited and the "\_\_" will remain intact in the new channel. + +In the dialplan, all references to these variables refer to the same +variable, regardless of having a prefix or not. Note that setting any +version of the variable removes any other version of the variable, +regardless of prefix. + +\subsection{Example} +\begin{astlisting} +\begin{verbatim} +Set(__FOO=bar) ; Sets an inherited version of "FOO" variable +Set(FOO=bar) ; Removes the inherited version and sets a local + ; variable. +\end{verbatim} +\end{astlisting} + +However, NoOp(\$\{\_\_FOO\}) is identical to NoOp(\$\{FOO\}) + +\section{Selecting Characters from Variables} + +The format for selecting characters from a variable can be expressed as: +\begin{astlisting} +\begin{verbatim} + ${variable_name[:offset[:length]]} +\end{verbatim} +\end{astlisting} +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{astlisting} +\begin{verbatim} + ; Remove the first character of extension, save in "number" variable + exten => _9X.,1,Set(number=${EXTEN:1}) +\end{verbatim} +\end{astlisting} +Assuming we've dialed 918005551234, the value saved to the 'number' variable +would be 18005551234. This is useful in situations when we require users to +dial a number to access an outside line, but do not wish to pass the first +digit. + +If you use a negative offset number, Asterisk starts counting from the end +of the string and then selects everything after the new position. The following +example will save the numbers 1234 to the 'number' variable, still assuming +we've dialed 918005551234. +\begin{astlisting} +\begin{verbatim} + ; Remove everything before the last four digits of the dialed string + exten => _9X.,1,Set(number=${EXTEN:-4}) +\end{verbatim} +\end{astlisting} +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{astlisting} +\begin{verbatim} + ; Only save the middle numbers 555 from the string 918005551234 + exten => _9X.,1,Set(number=${EXTEN:5:3}) +\end{verbatim} +\end{astlisting} +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{astlisting} +\begin{verbatim} + ; Save the numbers 555 to the 'number' variable + exten => _9X.,1,Set(number=${EXTEN:-7:3}) +\end{verbatim} +\end{astlisting} +If a negative length value is entered, Asterisk will remove that many characters +from the end of the string. +\begin{astlisting} +\begin{verbatim} + ; Set pin to everything but the trailing #. + exten => _XXXX#,1,Set(pin=${EXTEN:0:-1}) +\end{verbatim} +\end{astlisting} + +\section{Expressions} + +Everything contained inside a bracket pair prefixed by a \$ (like \$[this]) is +considered as an expression and it is evaluated. Evaluation works similar to +(but is done on a later stage than) variable substitution: the expression +(including the square brackets) is replaced by the result of the expression +evaluation. + +For example, after the sequence: +\begin{astlisting} +\begin{verbatim} +exten => 1,1,Set(lala=$[1 + 2]) +exten => 1,2,Set(koko=$[2 * ${lala}]) +\end{verbatim} +\end{astlisting} +the value of variable koko is "6". + +and, further: +\begin{astlisting} +\begin{verbatim} +exten => 1,1,Set,(lala=$[ 1 + 2 ]); +\end{verbatim} +\end{astlisting} +will parse as intended. Extra spaces are ignored. + + +\subsection{Spaces Inside Variables Values} + +If the variable being evaluated contains spaces, there can be problems. + +For these cases, double quotes around text that may contain spaces +will force the surrounded text to be evaluated as a single token. +The double quotes will be counted as part of that lexical token. + +As an example: + +\begin{astlisting} +\begin{verbatim} +exten => s,6,GotoIf($[ "${CALLERID(name)}" : "Privacy Manager" ]?callerid-liar,s,1:s,7) +\end{verbatim} +\end{astlisting} + +The variable CALLERID(name) 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 are listed below in order of increasing precedence. Operators +with equal precedence are grouped within \{ \} symbols. + +\begin{itemize} + \item \verb!expr1 | expr2! + + Return the evaluation of expr1 if it is neither an empty string + nor zero; otherwise, returns the evaluation of expr2. + + \item \verb!expr1 & expr2! + + Return the evaluation of expr1 if neither expression evaluates to + an empty string or zero; otherwise, returns zero. + + \item \verb+expr1 {=, >, >=, <, <=, !=} expr2+ + + Return the results of floating point comparison if both arguments are + numbers; otherwise, returns the results of string comparison + using the locale-specific collation sequence. The result of each + comparison is 1 if the specified relation is true, or 0 if the + relation is false. + + \item \verb!expr1 {+, -} expr2! + + Return the results of addition or subtraction of floating point-valued + arguments. + + \item \verb!expr1 {*, /, %} expr2! + + Return the results of multiplication, floating point division, or + remainder of arguments. + + \item \verb!- expr1! + + Return the result of subtracting expr1 from 0. + This, the unary minus operator, is right associative, and + has the same precedence as the ! operator. + + \item \verb+! expr1+ + + Return the result of a logical complement of expr1. + In other words, if expr1 is null, 0, an empty string, + or the string "0", return a 1. Otherwise, return a 0. + It has the same precedence as the unary minus operator, and + is also right associative. + + \item \verb!expr1 : expr2! + + The `:' operator matches expr1 against expr2, which must be a + regular expression. The regular expression is anchored to the + beginning of the string with an implicit `\^'. + + If the match succeeds and the pattern contains at least one regular + expression subexpression `\(...\)', the string corresponing + to `\textbackslash1' is returned; otherwise the matching operator + returns the number of characters matched. If the match fails and + the pattern contains a regular expression subexpression the null + string is returned; otherwise 0. + + Normally, the double quotes wrapping a string are left as part + of the string. This is disastrous to the : operator. Therefore, + before the regex match is made, beginning and ending double quote + characters are stripped from both the pattern and the string. + + \item \verb!expr1 =~ expr2! + + Exactly the same as the ':' operator, except that the match is + not anchored to the beginning of the string. Pardon any similarity + to seemingly similar operators in other programming languages! + The ":" and "=\~" operators share the same precedence. + + \item \verb!expr1 ? expr2 :: expr3! + + Traditional Conditional operator. If expr1 is a number + that evaluates to 0 (false), expr3 is result of the this + expression evaluation. Otherwise, expr2 is the result. + If expr1 is a string, and evaluates to an empty string, + or the two characters (""), then expr3 is the + result. Otherwise, expr2 is the result. In Asterisk, all + 3 exprs will be "evaluated"; if expr1 is "true", expr2 + will be the result of the "evaluation" of this + expression. expr3 will be the result otherwise. This + operator has the lowest precedence. +\end{itemize} + +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{Floating Point Numbers} + +In 1.6 and above, we shifted the \$[...] expressions to be calculated +via floating point numbers instead of integers. We use 'long double' numbers +when possible, which provide around 16 digits of precision with 12 byte numbers. + +To specify a floating point constant, the number has to have this format: D.D, where D is +a string of base 10 digits. So, you can say 0.10, but you can't say .10 or 20.-- we hope +this is not an excessive restriction! + +Floating point numbers are turned into strings via the '\%g'/'\%Lg' format of the printf +function set. This allows numbers to still 'look' like integers to those counting +on integer behavior. If you were counting on 1/4 evaluating to 0, you need to now say +TRUNC(1/4). For a list of all the truncation/rounding capabilities, see the next section. + + +\subsection{Functions} + +In 1.6 and above, we upgraded the \$[] expressions to handle floating point numbers. +Because of this, folks counting on integer behavior would be disrupted. To make +the same results possible, some rounding and integer truncation functions have been +added to the core of the Expr2 parser. Indeed, dialplan functions can be called from +\$[..] expressions without the \$\{...\} operators. The only trouble might be in the fact that +the arguments to these functions must be specified with a comma. If you try to call +the MATH function, for example, and try to say 3 + MATH(7*8), the expression parser will +evaluate 7*8 for you into 56, and the MATH function will most likely complain that its +input doesn't make any sense. + +We also provide access to most of the floating point functions in the C library. (but not all of them). + +While we don't expect someone to want to do Fourier analysis in the dialplan, we +don't want to preclude it, either. + +Here is a list of the 'builtin' functions in Expr2. All other dialplan functions +are available by simply calling them (read-only). In other words, you don't need to +surround function calls in \$[...] expressions with \$\{...\}. Don't jump to conclusions, +though! -- you still need to wrap variable names in curly braces! + +\begin{enumerate} +\item COS(x) x is in radians. Results vary from -1 to 1. +\item SIN(x) x is in radians. Results vary from -1 to 1. +\item TAN(x) x is in radians. +\item ACOS(x) x should be a value between -1 and 1. +\item ASIN(x) x should be a value between -1 and 1. +\item ATAN(x) returns the arc tangent in radians; between -PI/2 and PI/2. +\item ATAN2(x,y) returns a result resembling y/x, except that the signs of both args are used to determine the quadrant of the result. Its result is in radians, between -PI and PI. +\item POW(x,y) returns the value of x raised to the power of y. +\item SQRT(x) returns the square root of x. +\item FLOOR(x) rounds x down to the nearest integer. +\item CEIL(x) rounds x up to the nearest integer. +\item ROUND(x) rounds x to the nearest integer, but round halfway cases away from zero. +\item RINT(x) rounds x to the nearest integer, rounding halfway cases to the nearest even integer. +\item TRUNC(x) rounds x to the nearest integer not larger in absolute value. +\item REMAINDER(x,y) computes the remainder of dividing x by y. The return value is x - n*y, where n is the value x/y, rounded to the nearest integer. If this quotient is 1/2, it is rounded to the nearest even number. +\item EXP(x) returns e to the x power. +\item EXP2(x) returns 2 to the x power. +\item LOG(x) returns the natural logarithm of x. +\item LOG2(x) returns the base 2 log of x. +\item LOG10(x) returns the base 10 log of x. +\end{enumerate} + +\subsection{Examples} + +\begin{astlisting} +\begin{verbatim} + "One Thousand Five Hundred" =~ "(T[^ ]+)" + returns: Thousand + + "One Thousand Five Hundred" =~ "T[^ ]+" + returns: 8 + + "One Thousand Five Hundred" : "T[^ ]+" + returns: 0 + + "8015551212" : "(...)" + returns: 801 + + "3075551212":"...(...)" + returns: 555 + + ! "One Thousand Five Hundred" =~ "T[^ ]+" + returns: 0 (because it applies to the string, which is non-null, + which it turns to "0", and then looks for the pattern + in the "0", and doesn't find it) + + !( "One Thousand Five Hundred" : "T[^ ]+" ) + returns: 1 (because the string doesn't start with a word starting + with T, so the match evals to 0, and the ! operator + inverts it to 1 ). + + 2 + 8 / 2 + returns 6. (because of operator precedence; the division is done first, then the addition). + + 2+8/2 + returns 6. Spaces aren't necessary. + +(2+8)/2 + returns 5, of course. + +(3+8)/2 + returns 5.5 now. + +TRUNC((3+8)/2) + returns 5. + +FLOOR(2.5) + returns 2 + +FLOOR(-2.5) + returns -3 + +CEIL(2.5) + returns 3. + +CEIL(-2.5) + returns -2. + +ROUND(2.5) + returns 3. + +ROUND(3.5) + returns 4. + +ROUND(-2.5) + returns -3 + +RINT(2.5) + returns 2. + +RINT(3.5) + returns 4. + +RINT(-2.5) + returns -2. + +RINT(-3.5) + returns -4. + +TRUNC(2.5) + returns 2. + +TRUNC(3.5) + returns 3. + +TRUNC(-3.5) + returns -3. +\end{verbatim} +\end{astlisting} + +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 \$\{CALLERID(num)\}, for instance. + + +\subsection{Numbers Vs. Strings} + +Tokens consisting only of numbers are converted to 'long double' if possible, which +are from 80 bits to 128 bits depending on the OS, compiler, and hardware. +This means that overflows can occur when the +numbers get above 18 digits (depending on the number of bits involved). Warnings will appear in the logs in this +case. + +\subsection{Conditionals} + +There is one conditional application - the conditional goto : +\begin{astlisting} +\begin{verbatim} + exten => 1,2,GotoIf(condition?label1:label2) +\end{verbatim} +\end{astlisting} + +If condition is true go to label1, else go to label2. Labels are interpreted +exactly as in the normal goto command. + +"condition" is just a string. If the string is empty or "0", the condition +is considered to be false, if it's anything else, the condition is true. +This is designed to be used together with the expression syntax described +above, eg : + +\begin{astlisting} +\begin{verbatim} + exten => 1,2,GotoIf($[${CALLERID(all)} = 123456]?2,1:3,1) +\end{verbatim} +\end{astlisting} + +Example of use : +\begin{astlisting} +\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} +\end{astlisting} + +\subsection{Parse Errors} + +Syntax errors are now output with 3 lines. + +If the extensions.conf file contains a line like: + +\begin{astlisting} +\begin{verbatim} +exten => s,6,GotoIf($[ "${CALLERID(num)}" = "3071234567" & & "${CALLERID(name)}" : "Privacy Manager" ]?callerid-liar,s,1:s,7) +\end{verbatim} +\end{astlisting} + +You may see an error in \path{/var/log/asterisk/messages} like this: +\begin{astlisting} +\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} +\end{astlisting} + +The log line tells you that a syntax error was encountered. It now +also tells you (in grand standard bison format) that it hit an "AND" +(\&) token unexpectedly, and that was hoping for for a MINUS (-), LP +(left parenthesis), or a plain token (a string or number). + +The next line shows the evaluated expression, and the line after +that, the position of the parser in the expression when it became confused, +marked with the "\^" character. + +\subsection{NULL Strings} +Testing to see if a string is null can be done in one of two different ways: +\begin{astlisting} +\begin{verbatim} + exten => _XX.,1,GotoIf($["${calledid}" != ""]?3) + or + exten => _XX.,1,GotoIf($[foo${calledid} != foo]?3) +\end{verbatim} +\end{astlisting} + +The second example above is the way suggested by the WIKI. It will +work as long as there are no spaces in the evaluated value. + +The first way should work in all cases, and indeed, might now +be the safest way to handle this situation. + +\subsection{Warning} + +If you need to do complicated things with strings, asterisk expressions +is most likely NOT the best way to go about it. AGI scripts are an +excellent option to this need, and make available the full power of +whatever language you desire, be it Perl, C, C++, Cobol, RPG, Java, +Snobol, PL/I, Scheme, Common Lisp, Shell scripts, Tcl, Forth, Modula, +Pascal, APL, assembler, etc. + +\subsection{Incompatabilities} + +The asterisk expression parser has undergone some evolution. It is hoped +that the changes will be viewed as positive. + +The "original" expression parser had a simple, hand-written scanner, +and a simple bison grammar. This was upgraded to a more involved bison +grammar, and a hand-written scanner upgraded to allow extra spaces, +and to generate better error diagnostics. This upgrade required bison +1.85, and part of the user community felt the pain of having to +upgrade their bison version. + +The next upgrade included new bison and flex input files, and the makefile +was upgraded to detect current version of both flex and bison, conditionally +compiling and linking the new files if the versions of flex and bison would +allow it. + +If you have not touched your extensions.conf files in a year or so, the +above upgrades may cause you some heartburn in certain circumstances, as +several changes have been made, and these will affect asterisk's behavior on +legacy extension.conf constructs. The changes have been engineered +to minimize these conflicts, but there are bound to be problems. + +The following list gives some (and most likely, not all) of areas +of possible concern with "legacy" extension.conf files: + +\begin{enumerate} +\item Tokens separated by space(s). + Previously, tokens were separated by spaces. Thus, ' 1 + 1 ' would evaluate + to the value '2', but '1+1' would evaluate to the string '1+1'. If this + behavior was depended on, then the expression evaluation will break. '1+1' + will now evaluate to '2', and something is not going to work right. + To keep such strings from being evaluated, simply wrap them in double + quotes: ' "1+1" ' + +\item The colon operator. In versions previous to double quoting, the + colon operator takes the right hand string, and using it as a + regex pattern, looks for it in the left hand string. It is given + an implicit \^ operator at the beginning, meaning the pattern + will match only at the beginning of the left hand string. + If the pattern or the matching string had double quotes around + them, these could get in the way of the pattern match. Now, + the wrapping double quotes are stripped from both the pattern + and the left hand string before applying the pattern. This + was done because it recognized that the new way of + scanning the expression doesn't use spaces to separate tokens, + and the average regex expression is full of operators that + the scanner will recognize as expression operators. Thus, unless + the pattern is wrapped in double quotes, there will be trouble. + For instance, \$\{VAR1\} : (Who$|$What*)+ + may have have worked before, but unless you wrap the pattern + in double quotes now, look out for trouble! This is better: + "\$\{VAR1\}" : "(Who$|$What*)+" + and should work as previous. + +\item 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, + 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. + +\item 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 + 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' + is returned as the result. See above for details. + +\item Unary operators '-' and '!' were made right associative. +\end{enumerate} + +\subsection{Debugging Hints} + +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: +\begin{astlisting} +\begin{verbatim} +make testexpr2 +\end{verbatim} +\end{astlisting} +in the top level asterisk source directory. This will build a small +executable, that is able to take the first command line argument, and +run it thru the expression parser. No variable substitutions will be +performed. It might be safest to wrap the expression in single +quotes... +\begin{astlisting} +\begin{verbatim} +testexpr2 '2*2+2/2' +\end{verbatim} +\end{astlisting} +is an example. + +And, in the utils directory, you can say: +\begin{astlisting} +\begin{verbatim} +make check_expr +\end{verbatim} +\end{astlisting} +and a small program will be built, that will check the file mentioned +in the first command line argument, for any expressions that might be +have problems when you move to flex-2.5.31. It was originally +designed to help spot possible incompatibilities when moving from the +pre-2.5.31 world to the upgraded version of the lexer. + +But one more capability has been added to check\_expr, that might make +it more generally useful. It now does a simple minded evaluation of +all variables, and then passes the \$[] exprs to the parser. If there +are any parse errors, they will be reported in the log file. You can +use check\_expr to do a quick sanity check of the expressions in your +extensions.conf file, to see if they pass a crude syntax check. + +The "simple-minded" variable substitution replaces \$\{varname\} variable +references with '555'. You can override the 555 for variable values, +by entering in var=val arguments after the filename on the command +line. So... +\begin{astlisting} +\begin{verbatim} + check_expr /etc/asterisk/extensions.conf CALLERID(num)=3075551212 DIALSTATUS=TORTURE EXTEN=121 +\end{verbatim} +\end{astlisting} +will substitute any \$\{CALLERID(num)\} 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: +\begin{astlisting} +\begin{verbatim} + check_expr /etc/asterisk/extensions.conf CALLERID(num)=3075551212 DIALSTATUS=TORTURE EXTEN:2=121 +\end{verbatim} +\end{astlisting} +on stdout, you will see something like: + +\begin{astlisting} +\begin{verbatim} + OK -- $[ "${DIALSTATUS}" = "TORTURE" | "${DIALSTATUS}" = "DONTCALL" ] at line 416 +\end{verbatim} +\end{astlisting} + +In the expr2\_log file that is generated, you will see: + +\begin{astlisting} +\begin{verbatim} + line 416, evaluation of $[ "TORTURE" = "TORTURE" | "TORTURE" = "DONTCALL" ] result: 1 +\end{verbatim} +\end{astlisting} + +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} + +There are a number of variables that are defined or read +by Asterisk. Here is a list of them. More information is +available in each application's help text. All these variables +are in UPPER CASE only. + +Variables marked with a * are builtin functions and can't be set, +only read in the dialplan. Writes to such variables are silently +ignored. + +\begin{verbatim} +${CDR(accountcode)} * Account code (if specified) +${BLINDTRANSFER} The name of the channel on the other side of a blind transfer +${BRIDGEPEER} Bridged peer +${CALLERID(ani)} * Caller ANI (PRI channels) +${CALLERID(ani2)} * ANI2 (Info digits) also called Originating line information or OLI +${CALLERID(all)} * Caller ID +${CALLERID(dnid)} * Dialed Number Identifier +${CALLERID(name)} * Caller ID Name only +${CALLERID(num)} * Caller ID Number only +${CALLERID(rdnis)} * Redirected Dial Number ID Service +${CALLINGANI2} * Caller ANI2 (PRI channels) +${CALLINGPRES} * Caller ID presentation for incoming calls (PRI channels) +${CALLINGTNS} * Transit Network Selector (PRI channels) +${CALLINGTON} * Caller Type of Number (PRI channels) +${CHANNEL} * Current channel name +${CONTEXT} * Current context +${DATETIME} * Current date time in the format: DDMMYYYY-HH:MM:SS + (Deprecated; use ${STRFTIME(${EPOCH},,%d%m%Y-%H:%M:%S)}) +${DB_RESULT} Result value of DB_EXISTS() dial plan function +${EPOCH} * Current unix style epoch +${EXTEN} * Current extension +${ENV(VAR)} Environmental variable VAR +${GOTO_ON_BLINDXFR} Transfer to the specified context/extension/priority + after a blind transfer (use ^ characters in place of + | to separate context/extension/priority when setting + this variable from the dialplan) +${HANGUPCAUSE} * Asterisk cause of hangup (inbound/outbound) +${HINT} * Channel hints for this extension +${HINTNAME} * Suggested Caller*ID name for this extension +${INVALID_EXTEN} The invalid called extension (used in the "i" extension) +${LANGUAGE} * Current language (Deprecated; use ${LANGUAGE()}) +${LEN(VAR)} * String length of VAR (integer) +${PRIORITY} * Current priority in the dialplan +${PRIREDIRECTREASON} Reason for redirect on PRI, if a call was directed +${TIMESTAMP} * Current date time in the format: YYYYMMDD-HHMMSS + (Deprecated; use ${STRFTIME(${EPOCH},,%Y%m%d-%H%M%S)}) +${TRANSFER_CONTEXT} Context for transferred calls +${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} + +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() +${CHECKGROUPSTATUS} * checkgroup() +${CHECKMD5STATUS} * checkmd5() +${CPLAYBACKSTATUS} * controlplayback() +${DIALSTATUS} * dial() +${DBGETSTATUS} * dbget() +${ENUMSTATUS} * enumlookup() +${HASVMSTATUS} * hasnewvoicemail() +${LOOKUPBLSTATUS} * lookupblacklist() +${OSPAUTHSTATUS} * ospauth() +${OSPLOOKUPSTATUS} * osplookup() +${OSPNEXTSTATUS} * ospnext() +${OSPFINISHSTATUS} * ospfinish() +${PARKEDAT} * parkandannounce() +${PLAYBACKSTATUS} * playback() +${PQMSTATUS} * pausequeuemember() +${PRIVACYMGRSTATUS} * privacymanager() +${QUEUESTATUS} * queue() +${RQMSTATUS} * removequeuemember() +${SENDIMAGESTATUS} * sendimage() +${SENDTEXTSTATUS} * sendtext() +${SENDURLSTATUS} * sendurl() +${SYSTEMSTATUS} * system() +${TRANSFERSTATUS} * transfer() +${TXTCIDNAMESTATUS} * txtcidname() +${UPQMSTATUS} * unpausequeuemember() +${VMSTATUS} * voicmail() +${VMBOXEXISTSSTATUS} * vmboxexists() +${WAITSTATUS} * waitforsilence() +\end{verbatim} + +\subsection{Various application variables} +\begin{verbatim} +${CURL} * Resulting page content for curl() +${ENUM} * Result of application EnumLookup +${EXITCONTEXT} Context to exit to in IVR menu (app background()) + or in the RetryDial() application +${MONITOR} * Set to "TRUE" if the channel is/has been monitored (app monitor()) +${MONITOR_EXEC} Application to execute after monitoring a call +${MONITOR_EXEC_ARGS} Arguments to application +${MONITOR_FILENAME} File for monitoring (recording) calls in queue +${QUEUE_PRIO} Queue priority +${QUEUE_MAX_PENALTY} Maximum member penalty allowed to answer caller +${QUEUE_MIN_PENALTY} Minimum member penalty allowed to answer caller +${QUEUESTATUS} Status of the call, one of: + (TIMEOUT | FULL | JOINEMPTY | LEAVEEMPTY | JOINUNAVAIL | LEAVEUNAVAIL) +${RECORDED_FILE} * Recorded file in record() +${TALK_DETECTED} * Result from talkdetect() +${TOUCH_MONITOR} The filename base to use with Touch Monitor (auto record) +${TOUCH_MONITOR_PREF} * The prefix for automonitor recording filenames. +${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} +${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 +${CONF_LIMIT_TIMEOUT_FILE} File to play when time is up. Used with the L() option. +${CONF_LIMIT_WARNING_FILE} File to play as warning if 'y' is defined. + The default is to say the time remaining. Used with the L() option. +\end{verbatim} + +\subsection{The VoiceMail() application} +\begin{verbatim} +${VM_CATEGORY} Sets voicemail category +${VM_NAME} * Full name in voicemail +${VM_DUR} * Voicemail duration +${VM_MSGNUM} * Number of voicemail message in mailbox +${VM_CALLERID} * Voicemail Caller ID (Person leaving vm) +${VM_CIDNAME} * Voicemail Caller ID Name +${VM_CIDNUM} * Voicemail Caller ID Number +${VM_DATE} * Voicemail Date +${VM_MESSAGEFILE} * Path to message left by caller +\end{verbatim} + +\subsection{The VMAuthenticate() application} +\begin{verbatim} +${AUTH_MAILBOX} * Authenticated mailbox +${AUTH_CONTEXT} * Authenticated mailbox context +\end{verbatim} + +\subsection{DUNDiLookup()} +\begin{verbatim} +${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} +${ANI2} * The ANI2 Code provided by the network on the incoming call. + (ie, Code 29 identifies call as a Prison/Inmate Call) +${CALLTYPE} * Type of call (Speech, Digital, etc) +${CALLEDTON} * Type of number for incoming PRI extension + i.e. 0=unknown, 1=international, 2=domestic, 3=net_specific, + 4=subscriber, 6=abbreviated, 7=reserved +${CALLINGSUBADDR} * Called PRI Subaddress +${FAXEXTEN} * The extension called before being redirected to "fax" +${PRIREDIRECTREASON} * Reason for redirect, if a call was directed +${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} +${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) +${SIPURI} * SIP uri +${SIP_CODEC} Set the SIP codec for a call +${SIP_URI_OPTIONS} * additional options to add to the URI for an outgoing call +${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} +${AGENTMAXLOGINTRIES} Set the maximum number of failed logins +${AGENTUPDATECDR} Whether to update the CDR record with Agent channel data +${AGENTGOODBYE} Sound file to use for "Good Bye" when agent logs out +${AGENTACKCALL} Whether the agent should acknowledge the incoming call +${AGENTAUTOLOGOFF} Auto logging off for an agent +${AGENTWRAPUPTIME} Setting the time for wrapup between incoming calls +${AGENTNUMBER} * Agent number (username) set at login +${AGENTSTATUS} * Status of login ( fail | on | off ) +${AGENTEXTEN} * Extension for logged in agent +\end{verbatim} + + +\subsection{The Dial() application} +\begin{verbatim} +${DIALEDPEERNAME} * Dialed peer name +${DIALEDPEERNUMBER} * Dialed peer number +${DIALEDTIME} * Time for the call (seconds) +${ANSWEREDTIME} * Time from dial to answer (seconds) +${DIALSTATUS} * Status of the call, one of: + (CHANUNAVAIL | CONGESTION | BUSY | NOANSWER + | ANSWER | CANCEL | DONTCALL | TORTURE) +${DYNAMIC_FEATURES} * The list of features (from the [applicationmap] section of + features.conf) to activate during the call, with feature + names separated by '#' characters +${LIMIT_PLAYAUDIO_CALLER} Soundfile for call limits +${LIMIT_PLAYAUDIO_CALLEE} Soundfile for call limits +${LIMIT_WARNING_FILE} Soundfile for call limits +${LIMIT_TIMEOUT_FILE} Soundfile for call limits +${LIMIT_CONNECT_FILE} Soundfile for call limits +${OUTBOUND_GROUP} Default groups for peer channels (as in SetGroup) + * See "show application dial" for more information +\end{verbatim} + +\subsection{The chanisavail() application} +\begin{verbatim} +${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} +${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} +${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} +${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 +${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} diff --git a/trunk/doc/tex/cliprompt.tex b/trunk/doc/tex/cliprompt.tex new file mode 100644 index 000000000..42e6b4bd1 --- /dev/null +++ b/trunk/doc/tex/cliprompt.tex @@ -0,0 +1,29 @@ +\subsubsection{Changing the CLI Prompt} + +The CLI prompt is set with the ASTERISK\_PROMPT UNIX environment variable that +you set from the Unix shell before starting Asterisk + +You may include the following variables, that will be replaced by +the current value by Asterisk: + +\begin{itemize} + \item \%d - Date (year-month-date) + \item \%s - Asterisk system name (from asterisk.conf) + \item \%h - Full hostname + \item \%H - Short hostname + \item \%t - Time + \item \%\% - Percent sign + \item \%\# - '\#' if Asterisk is run in console mode, '$>$' if running as remote console + \item \%Cn[;n] - Change terminal foreground (and optional background) color to specified + A full list of colors may be found in \path{include/asterisk/term.h} +\end{itemize} + +On Linux systems, you may also use: + +\begin{itemize} + \item \%l1 - Load average over past minute + \item \%l2 - Load average over past 5 minutes + \item \%l3 - Load average over past 15 minutes + \item \%l4 - Process fraction (processes running / total processes) + \item \%l5 - The most recently allocated pid +\end{itemize} diff --git a/trunk/doc/tex/configuration.tex b/trunk/doc/tex/configuration.tex new file mode 100644 index 000000000..9257a86ba --- /dev/null +++ b/trunk/doc/tex/configuration.tex @@ -0,0 +1,225 @@ +\subsubsection{Introduction} + +The Asterisk configuration parser in the 1.2 version +and beyond series has been improved in a number of ways. In +addition to the realtime architecture, we now have the ability to create +templates in configuration files, and use these as templates when we +configure phones, voicemail accounts and queues. + +These changes are general to the configuration parser, and works in +all configuration files. + +\subsubsection{General syntax} +Asterisk configuration files are defined as follows: + +\begin{astlisting} +\begin{verbatim} + [section] + label = value + label2 = value +\end{verbatim} +\end{astlisting} + +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{astlisting} +\begin{verbatim} + [section] + label1 = value1 + label2 = value2 + object => name + + label3 = value3 + label2 = value4 + object2 => name2 +\end{verbatim} +\end{astlisting} + +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{astlisting} +\begin{verbatim} + [section](options) + label = value +\end{verbatim} +\end{astlisting} + +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} + +All lines that starts with semi-colon ";" is treated as comments +and is not parsed. + +The "\verb!;--!" is a marker for a multi-line comment. Everything after +that marker will be treated as a comment until the end-marker "\verb!--;!" +is found. Parsing begins directly after the end-marker. + +\begin{astlisting} +\begin{verbatim} + ;This is a comment + label = value + ;-- This is + a comment --; + + ;-- Comment --; exten=> 1000,1,dial(SIP/lisa) +\end{verbatim} +\end{astlisting} + +\subsubsection{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. + +\begin{astlisting} +\begin{verbatim} + #include myusers.conf +\end{verbatim} +\end{astlisting} + +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{astlisting} +\begin{verbatim} + [options] + execincludes=yes +\end{verbatim} +\end{astlisting} + +The exec directive is used like this: +\begin{astlisting} +\begin{verbatim} + #exec /usr/local/bin/myasteriskconfigurator.sh +\end{verbatim} +\end{astlisting} + +\subsubsection{Adding to an existing section} +\begin{astlisting} +\begin{verbatim} + [section] + label = value + + [section](+) + label2 = value2 +\end{verbatim} +\end{astlisting} + +In this case, the plus sign indicates that the second section (with the +same name) is an addition to the first section. The second section can +be in another file (by using the \#include statement). If the section +name referred to before the plus is missing, the configuration will fail +to load. + +\subsubsection{Defining a template-only section} +\begin{astlisting} +\begin{verbatim} + [section](!) + label = value +\end{verbatim} +\end{astlisting} + +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{astlisting} +\begin{verbatim} + [section](name[,name]) + label = value +\end{verbatim} +\end{astlisting} + +The name within the parenthesis refers to other sections, either +templates or standard sections. The referred sections are included +before the configuration engine parses the local settings within the +section as though their entire contents (and anything they were +previously based upon) were included in the new section. For example +consider the following: + +\begin{astlisting} +\begin{verbatim} +[foo] +permit=192.168.0.2 +host=asdf +deny=192.168.0.1 + +[bar] +permit=192.168.1.2 +host=jkl +deny=192.168.1.1 + +[baz](foo,bar) +permit=192.168.3.1 +host=bnm +\end{verbatim} +\end{astlisting} + +The [baz] section will be processed as though it had been written in the +following way: + +\begin{astlisting} +\begin{verbatim} +[baz] +permit=192.168.0.2 +host=asdf +deny=192.168.0.1 +permit=192.168.1.2 +host=jkl +deny=192.168.1.1 +permit=192.168.3.1 +host=bnm +\end{verbatim} +\end{astlisting} + +\subsubsection{Additional Examples} + +(in top-level sip.conf) + +\begin{astlisting} +\begin{verbatim} +[defaults](!) +type=friend +nat=yes +qualify=on +dtmfmode=rfc2833 +disallow=all +allow=alaw + +#include accounts/*/sip.conf +\end{verbatim} +\end{astlisting} + +(in \path{accounts/customer1/sip.conf}) + +\begin{astlisting} +\begin{verbatim} +[def-customer1](!,defaults) +secret=this_is_not_secret +context=from-customer1 +callerid=Customer 1 <300> +accountcode=0001 + +[phone1](def-customer1) +mailbox=phone1@customer1 + +[phone2](def-customer1) +mailbox=phone2@customer1 +\end{verbatim} +\end{astlisting} + +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/trunk/doc/tex/dundi.tex b/trunk/doc/tex/dundi.tex new file mode 100644 index 000000000..aa2fbb24c --- /dev/null +++ b/trunk/doc/tex/dundi.tex @@ -0,0 +1,41 @@ +\url{http://www.dundi.com} + +Mark Spencer, Digium, Inc. + +DUNDi is essentially a trusted, peer-to-peer system for being able to +call any phone number from the Internet. DUNDi works by creating a +network of nodes called the "DUNDi E.164 Trust Group" which are bound by +a common peering agreement known as the General Peering Agreement or +GPA. The GPA legally binds the members of the Trust Group to provide +good-faith accurate information to the other nodes on the network, and +provides standards by which the community can insure the integrity of +the information on the nodes themselves. Unlike ENUM or similar +systems, DUNDi is explicitly designed to preclude any necessity for a +single centralized system which could be a source of fees, regulation, +etc. + +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, +administrators can locally add extensions which become immediately +available to the other nodes in the system. + +For more information visit \url{http://www.dundi.com} + +\section{DUNDIQUERY and DUNDIRESULT} + +The DUNDIQUERY and DUNDIRESULT dialplan functions will let you initiate +a DUNDi query from the dialplan, see how many results there are, and access +each one. Here is some example usage: +\begin{astlisting} +\begin{verbatim} +exten => 1,1,Set(ID=${DUNDIQUERY(1,dundi_test,b)}) +exten => 1,n,Set(NUM=${DUNDIRESULT(${ID},getnum)}) +exten => 1,n,NoOp(There are ${NUM} results) +exten => 1,n,Set(X=1) +exten => 1,n,While($[${X} <= ${NUM}]) +exten => 1,n,NoOp(Result ${X} is ${DUNDIRESULT(${ID},${X})}) +exten => 1,n,Set(X=$[${X} + 1]) +exten => 1,n,EndWhile +\end{verbatim} +\end{astlisting} diff --git a/trunk/doc/tex/enum.tex b/trunk/doc/tex/enum.tex new file mode 100644 index 000000000..9a3384d46 --- /dev/null +++ b/trunk/doc/tex/enum.tex @@ -0,0 +1,355 @@ +\section{The ENUMLOOKUP dialplan function} + +The ENUMLOOKUP function is more complex than it first may appear, and +this guide is to give a general overview and set of examples that may +be well-suited for the advanced user to evaluate in their +consideration of ENUM or ENUM-like lookup strategies. This document +assumes a familiarity with ENUM (RFC3761) or ENUM-like methods, as +well as familiarity with NAPTR DNS records (RFC2915, RFC3401-3404). +For an overview of NAPTR records, and the use of NAPTRs in the ENUM +global phone-number-to-DNS mapping scheme, please see +\url{http://www.voip-info.org/tiki-index.php?page=ENUM} for more detail. + +Using ENUM within Asterisk can be simple or complex, depending on how +many failover methods and redundancy procedures you wish to utilize. +Implementation of ENUM paths is supposedly defined by the person +creating the NAPTR records, but the local administrator may choose to +ignore certain NAPTR response methods (URI types) or prefer some over +others, which is in contradiction to the RFC. The ENUMLOOKUP method +simply provides administrators a method for determining NAPTR results +in either the globally unique ENUM (e164.arpa) DNS tree, or in other +ENUM-like DNS trees which are not globally unique. The methods to +actually create channels ("dial") results given by the ENUMLOOKUP +function is then up to the administrator to implement in a way that +best suits their environment. + +\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], + ALL. Default type is "sip". + Special name of "ALL" will create a list of method types across + all NAPTR records for the search number, and then put the results + in an ordinal list starting with 1. The position <number> + specified will then be returned, starting with 1 as the first + record (lowest value) in the list. The service types are not + hardcoded in Asterisk except for the default (sip) if no other + service type specified; any method type string (IANA-approved or + not) may be used except for the string "ALL". + \end{itemize} + + \item options + \begin{itemize} + \item c + \begin{itemize} + \item count. Returns the number of records of this type are returned + (regardless of order or priority.) If "ALL" is the specified + service\_type, then a count of all methods will be returned for the + DNS record. + \end{itemize} + \end{itemize} + + \item record\# + \begin{itemize} + \item 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 + 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} + + \item zone\_suffix + \begin{itemize} + \item allows customization of the ENUM zone. Default is e164.arpa. + \end{itemize} +\end{itemize} + +\subsection{Examples} + +Let's use this ENUM list as an example (note that these examples exist +in the DNS, and will hopefully remain in place as example +destinations, but they may change or become invalid over time. The +end result URIs are not guaranteed to actually work, since some of +these hostnames or SIP proxies are imaginary. Of course, the tel: +replies go to directory assistance for New York City and San +Francisco...) Also note that the complex SIP NAPTR at weight 30 will +strip off the leading "+" from the dialed string if it exists. This +is probably a better NAPTR than hard-coding the number into the NAPTR, +and it is included as a more complex regexp example, though other +simpler NAPTRs will work just as well. + +\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} + +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 + explanation. All E.164 numbers ("global phone numbers") by + definition need a leading "+" during ENUM lookup. If you neglect to + add a leading "+", you may discover that numbers that seem to exist + in the DNS aren't getting matched by the system or are returned with + a null string result. This is due to the NAPTR reply requiring a + "+" in the regular expression matching sequence. Older versions of + Asterisk add a "+" from within the code, which may confuse + administrators converting to the new function. Please ensure that + all ENUM (e164.arpa) lookups contain a leading "+" before lookup, so + ensure your lookup includes the leading plus sign. Other DNS trees + may or may not require a leading "+" - check before using those + trees, as it is possible the parsed NAPTRs will not provide correct + results unless you have the correct dialed string. If you get + console messages like "WARNING[24907]: enum.c:222 parse\_naptr: NAPTR + Regex match failed." then it is very possible that the returned + NAPTR expects a leading "+" in the search string (or the returned + NAPTR is mis-formed.) + + \item If a query is performed of type "c" ("count") and let's say you + get back 5 records and then some seconds later a query is made + against record 5 in the list, it may not be the case that the DNS + resolver has the same answers as it did a second or two ago - maybe + there are only 4 records in the list in the newest query. The + resolver should be the canonical storage location for DNS records, + since that is the intent of ENUM. However, some obscure future + cases may have wildly changing NAPTR records within several seconds. + This is a corner case, and probably only worth noting as a very rare + circumstance. (note: I do not object to Asterisk's dnsmgr method of + locally caching DNS replies, but this method needs to honor the TTL + given by the remote zone master. Currently, the ENUMLOOKUP function + does not use the dnsmgr method of caching local DNS replies.) + + \item If you want strict NAPTR value ordering, then it will be + necessary to use the "ALL" method to incrementally step through the + different returned NAPTR pointers. You will need to use string + manipulation to strip off the returned method types, since the + results will look like "sip:12125551212" in the returned value. + This is a non-trivial task, though it is required in order to have + strict RFC compliance and to comply with the desires of the remote + party who is presenting NAPTRs in a particular order for a reason. + + \item Default behavior for the function (even in event of an error) is + to move to the next priority, and the result is a null value. Most + ENUM lookups are going to be failures, and it is the responsibility + of the dialplan administrator to manage error conditions within + their dialplan. This is a change from the old app\_enumlookup method + and it's arbitrary priority jumping based on result type or failure. + + \item 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 + 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 + 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 + (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 + there are multiple NAPTRs with (as an example) a method of + "E2U+voice:sip" and then another NAPTR in the same DNS record with a + method of ""E2U+sip", the system will treat these both as method + "sip" and they will be separate records from the perspective of the + function. Of course, if both records point to the same URI and have + equal priority/weight (as is often the case) then this will cause no + serious difficulty, but it bears mentioning. + + \item 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 + \url{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} + +All examples below except where noted use "e164.arpa" as the +referenced domain, which is the default domain name for ENUMLOOKUP. +All numbers are assumed to not have a leading "+" as dialed by the +inbound channel, so that character is added where necessary during +ENUMLOOKUP function calls. + +\begin{astlisting} +\begin{verbatim} +; example 1 +; +; Assumes North American international dialing (011) prefix. +; Look up the first SIP result and send the call there, otherwise +; send the call out a PRI. This is the most simple possible +; ENUM example, but only uses the first SIP reply in the list of +; NAPTR(s). +; +exten => _011.,1,Set(enumresult=${ENUMLOOKUP(+${EXTEN:3})}) +exten => _011.,n,Dial(SIP/${enumresult}) +exten => _011.,n,Dial(Zap/g1/${EXTEN}) +; +; end example 1 + +; example 2 +; +; Assumes North American international dialing (011) prefix. +; Check to see if there are multiple SIP NAPTRs returned by +; the lookup, and dial each in order. If none work (or none +; exist) then send the call out a PRI, group 1. +; +exten => _011.,1,Set(sipcount=${ENUMLOOKUP(${EXTEN:3},sip,c)}|counter=0) +exten => _011.,n,While($["${counter}"<"${sipcount}"]) +exten => _011.,n,Set(counter=$[${counter}+1]) +exten => _011.,n,Dial(SIP/${ENUMLOOKUP(+${EXTEN:3},sip,,${counter})}) +exten => _011.,n,EndWhile +exten => _011.,n,Dial(Zap/g1/${EXTEN}) +; +; end example 2 + +; example 3 +; +; This example expects an ${EXTEN} that is an e.164 number (like +; 14102241145 or 437203001721) +; Search through e164.arpa and then also search through e164.org +; to see if there are any valid SIP or IAX termination capabilities. +; If none, send call out via Zap channel 1. +; +; Start first with e164.arpa zone... +; +exten => _X.,1,Set(sipcount=${ENUMLOOKUP(+${EXTEN},sip,c)}|counter=0) +exten => _X.,2,GotoIf($["${counter}"<"${sipcount}"]?3:6) +exten => _X.,3,Set(counter=$[${counter}+1]) +exten => _X.,4,Dial(SIP/${ENUMLOOKUP(+${EXTEN},sip,,${counter})}) +exten => _X.,5,GotoIf($["${counter}"<"${sipcount}"]?3:6) +; +exten => _X.,6,Set(iaxcount=${ENUMLOOKUP(+${EXTEN},iax2,c)}|counter=0) +exten => _X.,7,GotoIf($["${counter}"<"${iaxcount}"]?8:11) +exten => _X.,8,Set(counter=$[${counter}+1]) +exten => _X.,9,Dial(IAX2/${ENUMLOOKUP(+${EXTEN},iax2,,${counter})}) +exten => _X.,10,GotoIf($["${counter}"<"${iaxcount}"]?8:11) +; +exten => _X.,11,NoOp("No valid entries in e164.arpa for ${EXTEN} - checking in e164.org") +; +; ...then also try e164.org, and look for SIP and IAX NAPTRs... +; +exten => _X.,12,Set(sipcount=${ENUMLOOKUP(+${EXTEN},sip,c,,e164.org)}|counter=0) +exten => _X.,13,GotoIf($["${counter}"<"${sipcount}"]?14:17) +exten => _X.,14,Set(counter=$[${counter}+1]) +exten => _X.,15,Dial(SIP/${ENUMLOOKUP(+${EXTEN},sip,,${counter},e164.org)}) +exten => _X.,16,GotoIf($["${counter}"<"${sipcount}"]?14:17) +; +exten => _X.,17,Set(iaxcount=${ENUMLOOKUP(+${EXTEN},iax2,c,,e164.org)}|counter=0) +exten => _X.,18,GotoIf($["${counter}"<"${iaxcount}"]?19:22) +exten => _X.,19,Set(counter=$[${counter}+1]) +exten => _X.,20,Dial(IAX2/${ENUMLOOKUP(+${EXTEN},iax2,,${counter},e164.org)}) +exten => _X.,21,GotoIf($["${counter}"<"${iaxcount}"]?19:22) +; +; ...then send out PRI. +; +exten => _X.,22,NoOp("No valid entries in e164.org for ${EXTEN} - sending out via Zap") +exten => _X.,23,Dial(Zap/g1/${EXTEN}) +; +; end example 3 + +\end{verbatim} +\end{astlisting} diff --git a/trunk/doc/tex/extensions.tex b/trunk/doc/tex/extensions.tex new file mode 100644 index 000000000..262d14ecd --- /dev/null +++ b/trunk/doc/tex/extensions.tex @@ -0,0 +1,82 @@ +\subsubsection{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 +must be added to a context. Then, you configure the calling "line" to have +access to this context. + +If you change the dialplan, you can use the Asterisk CLI command +"extensions reload" to load the new dialplan without disrupting +service in your PBX. + +Extensions are routed according to priority and may be based on any set +of characters (a-z), digits, \#, and *. Please note that when matching a +pattern, "N", "X", and "Z" are interpreted as classes of digits. + +For each extension, several actions may be listed and must be given a unique +priority. When each action completes, the call continues at the next priority +(except for some modules which use explicitly GOTO's). + +When each action completes, it generally moves to the next priority (except for +some modules which use explicitly GOTO's. + +Extensions frequently have data they pass to the executing application +(most frequently a string). You can see the available dialplan applications +by entering the "core show applications" command in the CLI. + +In this version of Asterisk, dialplan functions are added. These can +be used as arguments to any application. For a list of the installed +functions in your Asterisk, use the "core show functions" command. + +\subsubsection{Example dialplan} + +The example dial plan, in the \path{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} + +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 "core show function TIMEOUT" for more + information on setting timeouts. + \end{itemize} + \item e + \begin{itemize} + \item This extension will substitute as a catchall for any of the + 'i', 't', or 'T' extensions, if any of them do not exist and + catching the error in a single routine is desired. The + function EXCEPTION may be used to query the type of exception + or the location where it occurred. + \end{itemize} +\end{itemize} + +And finally, the extension context "default" is used when either a) an +extension context is deleted while an extension is in use, or b) a specific +starting extension handler has not been defined (unless overridden by the +low level channel interface). diff --git a/trunk/doc/tex/freetds.tex b/trunk/doc/tex/freetds.tex new file mode 100644 index 000000000..8dcbec29a --- /dev/null +++ b/trunk/doc/tex/freetds.tex @@ -0,0 +1,16 @@ +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 +that from 0.63 onwards, this is not considered a published API +of FreeTDS and is subject to change without notice. + +Between 0.62.x and 0.63 of FreeTDS, many incompatible changes +have been made to the libtds API. + +For newer versions of FreeTDS, it is recommended that you use the +ODBC driver. + diff --git a/trunk/doc/tex/hardware.tex b/trunk/doc/tex/hardware.tex new file mode 100644 index 000000000..30fa587aa --- /dev/null +++ b/trunk/doc/tex/hardware.tex @@ -0,0 +1,100 @@ +\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, etc.), 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) + \url{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\texttrademark 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. + \url{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: \url{http://www.misdn.org/} + +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) + \url{http://www.digium.com} + \begin{itemize} + \item B410P - 4 Port BRI card (TE/NT) + \end{itemize} +\end{itemize} + +\begin{itemize} + \item beroNet + \url{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 + \url{http://www.alsa-project.org} + \begin{itemize} + \item Any ALSA compatible full-duplex sound card + \end{itemize} + + \item OSS + \url{http://www.opensound.com} + \begin{itemize} + \item Any OSS compatible full-duplex sound card + \end{itemize} +\end{itemize} diff --git a/trunk/doc/tex/ices.tex b/trunk/doc/tex/ices.tex new file mode 100644 index 000000000..39872be57 --- /dev/null +++ b/trunk/doc/tex/ices.tex @@ -0,0 +1,7 @@ +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 +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 \path{contrib/asterisk-ices.xml}. + diff --git a/trunk/doc/tex/imapstorage.tex b/trunk/doc/tex/imapstorage.tex new file mode 100644 index 000000000..3a952ce54 --- /dev/null +++ b/trunk/doc/tex/imapstorage.tex @@ -0,0 +1,196 @@ +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 + a user's mailbox automatically. + \item 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 + waiting indicator (MWI) on the user's phone. + \item 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} + +\subsubsection{University of Washington IMAP C-Client} + +If you do not have the University of Washington's IMAP c-client +installed on your system, you will need to download the c-client +source distribution (\url{http://www.washington.edu/imap/}) and compile it. +Asterisk supports both the 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, +but building it also builds an IMAP server and various other utilities. +Because of this, the build instructions for the IMAP toolkit are somewhat +complicated and can lead to confusion about what is needed. + +If you are going to be connecting Asterisk to an existing IMAP server, +then you don't need to care about the server or utilities in the IMAP +toolkit at all. If you want to also install the UW IMAPD server, that +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{enumerate} + \item If you will not be using SSL to connect to the IMAP server: + \begin{verbatim} + $ make slx SSLTYPE=none! + \end{verbatim} + \item If you will be using SSL to connect to the IMAP server: + \begin{verbatim} + $ make slx EXTRACFLAGS="-I/usr/include/openssl" + \end{verbatim} +\end{enumerate} + +Once this completes you can proceed with the Asterisk build; there is no +need to run 'make install'. + +\subsubsection{Compiling Asterisk} + +To use the system c-client library, configure Asterisk with +./configure --with-imap=system. If you downloaded the c-client source +and compiled it according to the above instructions, configure +Asterisk with with ./configure --with-imap=/usr/src/imap or where ever +you built the UWashington IMAP Toolkit. When you run 'make +menuselect', choose 'Voicemail Build Options' and the IMAP\_STORAGE +option should be available for selection. + +After selecting the IMAP\_STORAGE option, use the 'x' key to exit +menuselect and save your changes, and the build/install Asterisk +normally. + +\subsection{Modify voicemail.conf} + +The following directives have been added to voicemail.conf: +\begin{astlisting} +\begin{verbatim} +imapserver=<name or IP address of IMAP mail server> +imapport=<IMAP port, defaults to 143> +imapflags=<IMAP flags, "novalidate-cert" for example> +imapfolder=<IMAP folder to store messages to> +imapgreetings=<yes or no> +greetingsfolder=<IMAP folder to store greetings in if imapgreetings is enabled> +expungeonhangup=<yes or no> +authuser=<username> +authpassword=<password> +opentimeout=<TCP open timeout in seconds> +closetimeout=<TCP close timeout in seconds> +readtimeout=<TCP read timeout in seconds> +writetimeout=<TCP write timeout in seconds> +\end{verbatim} +\end{astlisting} + +The "imapfolder" can be used to specify an alternative folder on your IMAP server +to store voicemails in. If not specified, the default folder 'INBOX' will be used. + +The "imapgreetings" parameter can be enabled in order to store voicemail greetings +on the IMAP server. If disabled, then they will be stored on the local file system +as normal. + +The "greetingsfolder" can be set to store greetings on the IMAP server when +"imapgreetings" is enabled in an alternative folder than that set by "imapfolder" +or the default folder for voicemails. + +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. + +Each mailbox definition should also have imapuser=$<$imap username$>$. +For example: +\begin{astlisting} +\begin{verbatim} +4123=>4123,James Rothenberger,jar@onebiztone.com,,attach=yes|imapuser=jar +\end{verbatim} +\end{astlisting} + +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} + +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} + +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. + +By implementing a single IMAP mailbox, the user will see voicemail messages +appear in the same INBOX as other messages. The disadvantage of this method +is that if the IMAP server does NOT support UIDPLUS, Asterisk voicemail will +expunge ALL messages marked for deletion when the user exits the voicemail +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} + +There are various IMAP server implementations, each supports a potentially +different set of features. + + +\subsubsection{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 +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 +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 +if possible. + +\subsubsection{Cyrus IMAP} + +Cyrus IMAP server v2.3.3 has been tested using a hierarchy delimiter of '/'. + + +\subsection{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} + +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 +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 +X-Asterisk-VM-Extension +X-Asterisk-VM-Priority +X-Asterisk-VM-Caller-channel +X-Asterisk-VM-Caller-ID-Num +X-Asterisk-VM-Caller-ID-Name +X-Asterisk-VM-Duration +X-Asterisk-VM-Category +X-Asterisk-VM-Orig-date +X-Asterisk-VM-Orig-time +\end{verbatim} diff --git a/trunk/doc/tex/jitterbuffer.tex b/trunk/doc/tex/jitterbuffer.tex new file mode 100644 index 000000000..a29cf811a --- /dev/null +++ b/trunk/doc/tex/jitterbuffer.tex @@ -0,0 +1,98 @@ +\subsubsection{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} + +The new jitterbuffer detects packet loss. PLC is done to try to recreate these +lost packets in the codec decoding stage, as the encoded audio is translated to slinear. +PLC is also used to mask jitterbuffer growth. + +This facility is enabled by default in iLBC and speex, as it has no additional cost. +This facility can be enabled in adpcm, alaw, g726, gsm, lpc10, and ulaw by setting +genericplc =$>$ true in the [plc] section of codecs.conf. + +\subsubsection{Trunktimestamps} + +To use this, both sides must be using Asterisk v1.2 or later. +Setting "trunktimestamps=yes" in iax.conf will cause your box to send 16-bit timestamps +for each trunked frame inside of a trunk frame. This will enable you to use jitterbuffer +for an IAX2 trunk, something that was not possible in the old architecture. + +The other side must also support this functionality, or else, well, bad things will happen. +If you don't use trunktimestamps, there's lots of ways the jitterbuffer can get confused because +timestamps aren't necessarily sent through the trunk correctly. + +\subsubsection{Communication with Asterisk v1.0.x systems} + +You can set up communication with v1.0.x systems with the new jitterbuffer, but +you can't use trunks with trunktimestamps in this communication. + +If you are connecting to an Asterisk server with earlier versions of the software (1.0.x), +do not enable both jitterbuffer and trunking for the involved peers/users +in order to be able to communicate. Earlier systems will not support trunktimestamps. + +You may also compile chan\_iax2.c without the new jitterbuffer, enabling the old +backwards compatible architecture. Look in the source code for instructions. + + +\subsubsection{Testing and monitoring} + +You can test the effectiveness of PLC and the new jitterbuffer's detection of loss by using +the new CLI command "iax2 test losspct $<$n$>$". This will simulate n percent packet loss +coming \_in\_ to chan\_iax2. You should find that with PLC and the new JB, 10 percent packet +loss should lead to just a tiny amount of distortion, while without PLC, it would lead to +silent gaps in your audio. + +"iax2 show netstats" shows you statistics for each iax2 call you have up. +The columns are "RTT" which is the round-trip time for the last PING, and then a bunch of s +tats for both the local side (what you're receiving), and the remote side (what the other +end is telling us they are seeing). The remote stats may not be complete if the remote +end isn't using the new jitterbuffer. + +The stats shown are: +\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} + +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. +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 +nonsensical timestamps, it can confuse the jitterbuffer. In particular, discontinuities +in timestamps will really upset it: Things like timestamps sequences which go 0, 20, 40, +60, 80, 34000, 34020, 34040, 34060... It's going to think you've got about 34 seconds +of jitter in this case, etc.. +The right solution to this is to find out what's causing the sender to send us such nonsense, +and fix that. But we should also figure out how to make the receiver more robust in +cases like this. + +chan\_iax2 will actually help fix this a bit if it's more than 3 seconds or so, but at +some point we should try to think of a better way to detect this kind of thing and +resynchronize. + +Different clock rates are handled very gracefully though; it will actually deal with a +sender sending 20\% faster or slower than you expect just fine. + +\item 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} diff --git a/trunk/doc/tex/localchannel.tex b/trunk/doc/tex/localchannel.tex new file mode 100644 index 000000000..ab42606f7 --- /dev/null +++ b/trunk/doc/tex/localchannel.tex @@ -0,0 +1,80 @@ +\subsection{Introduction} + +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. + +\subsection{Syntax} +\begin{verbatim} + Local/extension@context[/{n|j}] +\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 and one audio frame passes, 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. + +There is another option that can be used with local channels, which is the "j" +option. The "j" option must be used with the "n" option to make sure that the +local channel does not get optimized out of the call. This option will enable +a jitterbuffer on the local channel. The jitterbuffer will be used to de-jitter +audio that it receives from the channel that called the local channel. This is +especially in the case of putting chan\_local in between an incoming SIP call +and Asterisk applications, so that the incoming audio will be de-jittered. + +\subsection{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 +\path{/var/spool/outgoing}) but you do want to be able to use your dialplans +least-cost-routes or other intelligent stuff. What you could do before we had +chan\_local was create a cross-link between two ports of the TE410P and then +Dial out one port and in the other. This way you could control where the call +was going. + +Of course, this was a nasty hack, and to make it more sensible, chan\_local was +built. + +The "Local" channel driver allows you to convert an arbitrary extension into a +channel. It is used in a variety of places, including agents, etc. + +This also allows us to hop to contexts like a GoSub routine; See examples below. + +\subsection{Examples} +\begin{astlisting} +\begin{verbatim} +[inbound] ; here falls all incoming calls +exten => s,1,Answer +exten => s,2,Dial(local/200@internal,30,r) +exten => s,3,Playback(sorrynoanswer) +exten => s,4,Hangup + +[internal] ; here where our phones falls for default +exten => 200,1,Dial(sip/blah) +exten => 200,102,VoiceMail(${EXTEN}@default) + +exten => 201,1,Dial(zap/1) +exten => 201,102,VoiceMail(${EXTEN}@default) + +exten => _0.,1,Dial(Zap/g1/${EXTEN:1}) ; outgoing calls with 0+number +\end{verbatim} +\end{astlisting} + +\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. + +\begin{verbatim} + Local/00531234567@pbx becomes Local/00531234567@pbx/n +\end{verbatim} diff --git a/trunk/doc/tex/manager.tex b/trunk/doc/tex/manager.tex new file mode 100644 index 000000000..c3b567bd4 --- /dev/null +++ b/trunk/doc/tex/manager.tex @@ -0,0 +1,258 @@ +\section{The Asterisk Manager TCP/IP API} + +The manager is a client/server model over TCP. With the manager interface, +you'll be able to control the PBX, originate calls, check mailbox status, +monitor channels and queues as well as execute Asterisk commands. + +AMI is the standard management interface into your Asterisk server. +You configure AMI in manager.conf. By default, AMI is available on +TCP port 5038 if you enable it in manager.conf. + +AMI receive commands, called "actions". These generate a "response" +from Asterisk. Asterisk will also send "Events" containing various +information messages about changes within Asterisk. Some actions +generate an initial response and data in the form list of events. +This format is created to make sure that extensive reports do not +block the manager interface fully. + +Management users are configured in the configuration file manager.conf and are +given permissions for read and write, where write represents their ability +to perform this class of "action", and read represents their ability to +receive this class of "event". + +If you develop AMI applications, treat the headers +in Actions, Events and Responses as local to that particular +message. There is no cross-message standardization of headers. + +If you develop applications, please try to reuse existing manager +headers and their interpretation. If you are unsure, discuss on +the asterisk-dev mailing list. + +\section{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 +and device configuration. Please check each channel configuration +file for more information. (in sip.conf, check the section on +subscriptions and call limits) + + +\section{Command Syntax} + +Management communication consists of tags of the form "header: value", +terminated with an empty newline (\textbackslash r\textbackslash 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} + +\section{Manager commands} + +To see all of the available manager commands, use the "manager show commands" +CLI command. + +You can get more information about a manager command +with the "manager show command $<$command$>$" CLI command in Asterisk. + +\section{Examples} + +Login - Log a user into the manager interface. + +\begin{verbatim} + Action: Login + Username: testuser + Secret: testsecret +\end{verbatim} + +Originate - Originate a call from a channel to an extension. + +\begin{verbatim} + Action: Originate + Channel: sip/12345 + Exten: 1234 + Context: default +\end{verbatim} + +Originate - Originate a call from a channel to an extension without waiting +for call to complete. + +\begin{verbatim} + Action: Originate + Channel: sip/12345 + Exten: 1234 + Context: default + Async: yes +\end{verbatim} + +Redirect with ExtraChannel: + + Attempted goal: + Have a 'robot' program Redirect both ends of an already-connected call + to a meetme room using the ExtraChannel feature through the management interface. + +\begin{verbatim} + Action: Redirect + Channel: Zap/1-1 + ExtraChannel: SIP/3064-7e00 (varies) + Exten: 680 + Priority: 1 +\end{verbatim} + +Where 680 is an extension that sends you to a MeetMe room. + +There are a number of GUI tools that use the manager interface, please search +the mailing list archives and the documentation page on the +\url{http://www.asterisk.org} web site for more information. + + +\section{Some standard AMI headers} +\begin{verbatim} + Account: -- Account Code (Status) + AccountCode: -- Account Code (cdr_manager) + ACL: <Y | N> -- Does ACL exist for object ? + Action: <action> -- Request or notification of a particular action + Address-IP: -- IPaddress + Address-Port: -- IP port number + Agent: <string> -- Agent name + AMAflags: -- AMA flag (cdr_manager, sippeers) + AnswerTime: -- Time of answer (cdr_manager) + Append: <bool> -- CDR userfield Append flag + Application: -- Application to use + Async: -- Whether or not to use fast setup + AuthType: -- Authentication type (for login or challenge) + "md5" + BillableSeconds: -- Billable seconds for call (cdr_manager) + CallerID: -- Caller id (name and number in Originate & cdr_manager) + CallerID: -- CallerID number + Number or "<unknown>" or "unknown" + (should change to "<unknown>" in app_queue) + CallerID1: -- Channel 1 CallerID (Link event) + CallerID2: -- Channel 2 CallerID (Link event) + CallerIDName: -- CallerID name + Name or "<unknown>" or "unknown" + (should change to "<unknown>" in app_queue) + Callgroup: -- Call group for peer/user + CallsTaken: <num> -- Queue status variable + Cause: <value> -- Event change cause - "Expired" + Cause: <value> -- Hangupcause (channel.c) + CID-CallingPres: -- Caller ID calling presentation + Channel: <channel> -- Channel specifier + Channel: <dialstring> -- Dialstring in Originate + Channel: <tech/[peer/username]> -- Channel in Registry events (SIP, IAX2) + Channel: <tech> -- Technology (SIP/IAX2 etc) in Registry events + ChannelType: -- Tech: SIP, IAX2, ZAP, MGCP etc + Channel1: -- Link channel 1 + Channel2: -- Link channel 2 + ChanObjectType: -- "peer", "user" + Codecs: -- Codec list + CodecOrder: -- Codec order, separated with comma "," + Command: -- Cli command to run + Context: -- Context + Count: <num> -- Number of callers in queue + Data: -- Application data + Default-addr-IP: -- IP address to use before registration + Default-Username: -- Username part of URI to use before registration + Destination: -- Destination for call (Dialstring ) (dial, cdr_manager) + DestinationContext: -- Destination context (cdr_manager) + DestinationChannel: -- Destination channel (cdr_manager) + DestUniqueID: -- UniqueID of destination (dial event) + Disposition: -- Call disposition (CDR manager) + Domain: <domain> -- DNS domain + Duration: <secs> -- Duration of call (cdr_manager) + Dynamic: <Y | N> -- Device registration supported? + Endtime: -- End time stamp of call (cdr_manager) + EventList: <flag> -- Flag being "Start", "End", "Cancelled" or "ListObject" + Events: <eventmask> -- Eventmask filter ("on", "off", "system", "call", "log") + Exten: -- Extension (Redirect command) + Extension: -- Extension (Status) + Family: <string> -- ASTdb key family + File: <filename> -- Filename (monitor) + Format: <format> -- Format of sound file (monitor) + From: <time> -- Parking time (ParkedCall event) + Hint: -- Extension hint + Incominglimit: -- SIP Peer incoming limit + Key: + Key: -- ASTdb Database key + LastApplication: -- Last application executed (cdr_manager) + LastCall: <num> -- Last call in queue + LastData: -- Data for last application (cdr_manager) + Link: -- (Status) + ListItems: <number> -- Number of items in Eventlist (Optionally sent in "end" packet) + Location: -- Interface (whatever that is -maybe tech/name in app_queue ) + Loginchan: -- Login channel for agent + Logintime: <number> -- Login time for agent + Mailbox: -- VM Mailbox (id@vmcontext) (mailboxstatus, mailboxcount) + MD5SecretExist: <Y | N> -- Whether secret exists in MD5 format + Membership: <string> -- "Dynamic" or "static" member in queue + Message: <text> -- Text message in ACKs, errors (explanation) + Mix: <bool> -- Boolean parameter (monitor) + NewMessages: <count> -- Count of new Mailbox messages (mailboxcount) + Newname: + ObjectName: -- Name of object in list + OldName: -- Something in Rename (channel.c) + OldMessages: <count> -- Count of old mailbox messages (mailboxcount) + Outgoinglimit: -- SIP Peer outgoing limit + Paused: <num> -- Queue member paused status + Peer: <tech/name> -- "channel" specifier :-) + PeerStatus: <tech/name> -- Peer status code + "Unregistered", "Registered", "Lagged", "Reachable" + Penalty: <num> -- Queue penalty + Priority: -- Extension priority + Privilege: <privilege> -- AMI authorization class (system, call, log, verbose, command, agent, user) + Pickupgroup: -- Pickup group for peer + Position: <num> -- Position in Queue + Queue: -- Queue name + Reason: -- "Autologoff" + Reason: -- "Chanunavail" + Response: <response> -- response code, like "200 OK" + "Success", "Error", "Follows" + Restart: -- "True", "False" + RegExpire: -- SIP registry expire + RegExpiry: -- SIP registry expiry + Reason: -- Originate reason code + Seconds: -- Seconds (Status) + Secret: <password> -- Authentication secret (for login) + SecretExist: <Y | N> -- Whether secret exists + Shutdown: -- "Uncleanly", "Cleanly" + SIP-AuthInsecure: + SIP-FromDomain: -- Peer FromDomain + SIP-FromUser: -- Peer FromUser + SIP-NatSupport: + SIPLastMsg: + Source: -- Source of call (dial event, cdr_manager) + SrcUniqueID: -- UniqueID of source (dial event) + StartTime: -- Start time of call (cdr_manager) + State: -- Channel state + Status: -- Registration status (Registry events SIP) + Status: -- Extension status (Extensionstate) + Status: -- Peer status (if monitored) ** Will change name ** + "unknown", "lagged", "ok" + Status: <num> -- Queue Status + Status: -- DND status (DNDState) + Time: <sec> -- Roundtrip time (latency) + Timeout: -- Parking timeout time + Timeout: -- Timeout for call setup (Originate) + Timeout: <seconds> -- Timeout for call + Uniqueid: -- Channel Unique ID + Uniqueid1: -- Channel 1 Unique ID (Link event) + Uniqueid2: -- Channel 2 Unique ID (Link event) + User: -- Username (SIP registry) + UserField: -- CDR userfield (cdr_manager) + Val: -- Value to set/read in ASTdb + Variable: -- Variable AND value to set (multiple separated with | in Originate) + Variable: <name> -- For channel variables + Value: <value> -- Value to set + VoiceMailbox: -- VM Mailbox in SIPpeers + Waiting: -- Count of mailbox messages (mailboxstatus) +\end{verbatim} + + ** Please try to re-use existing headers to simplify manager message parsing in clients. + +Read the CODING-GUIDELINES if you develop new manager commands or events. diff --git a/trunk/doc/tex/misdn.tex b/trunk/doc/tex/misdn.tex new file mode 100644 index 000000000..84dbb7aaa --- /dev/null +++ b/trunk/doc/tex/misdn.tex @@ -0,0 +1,272 @@ +\subsection{Introduction} + +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} + +It is easy to install mISDN and mISDNuser. This can be done by: +\begin{itemize} + \item You can download latest stable releases from \url{http://www.misdn.org/downloads/} + + \item Just fetch the newest head of the GIT (mISDN provect moved from CVS) + In details this process described here: \url{http://www.misdn.org/index.php/GIT} +\end{itemize} + + +then compile and install both with: +\begin{astlisting} +\begin{verbatim} +cd mISDN ; +make && make install +\end{verbatim} +\end{astlisting} +(you will need at least your kernel headers to compile mISDN). +\begin{astlisting} +\begin{verbatim} +cd mISDNuser ; +make && make install +\end{verbatim} +\end{astlisting} +Now you can compile chan\_misdn, just by making asterisk: +\begin{astlisting} +\begin{verbatim} +cd asterisk ; +./configure && make && make install +\end{verbatim} +\end{astlisting} +That's all! + +Follow the instructions in the mISDN Package for how to load the Kernel +Modules. Also install process described in \url{http://www.misdn.org/index.php/Installing_mISDN} + +\subsection{Pre-Requisites} + +To compile and install this driver, you'll need at least one mISDN Driver and +the mISDNuser package. Chan\_misdn works with both, the current release version +and the development (svn trunk) version of Asterisk. mISDNuser and mISDN must +be fetched from cvs.isdn4linux.de. + +You should use Kernels $>$= 2.6.9 + + +\subsection{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{astlisting} +\begin{verbatim} +/etc/init.d/misdn-init and +/etc/misdn-init.conf +\end{verbatim} +\end{astlisting} +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 +contain misdn port settings and different Asterisk contexts. + +In the general subsection 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} + +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. + +\subsubsection{misdn.conf: user/port subsections} + +The user subsections have names which are unequal to "general". Those subsections +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 +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 +send incoming calls to in the Asterisk dial plan (extension.conf). + + +\subsubsection{Dial and Options String} + +The dial string of chan\_misdn got more complex, because we added more features, +so the generic dial string looks like: + +\begin{astlisting} +\begin{verbatim} +mISDN/<port>|g:<group>/<extension>[/<OPTIONSSTRING>] + +The Optionsstring looks Like: +:<optchar1><OptParam1>:<optchar2><OptParam2> + +the ":" character is the delimiter. + +The available Optchars are: + d - Send display text on called phone, text is the optparam + n - don't detect dtmf tones on called channel + h - make digital outgoing call + c - make crypted outgoing call, param is keyindex + e - perform echo cancellation on this channel, + takes taps as arguments (32,64,128,256) + s - send Non Inband DTMF as inband + vr - rxgain control + vt - txgain control +\end{verbatim} +\end{astlisting} + +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 +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} + +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{astlisting} +\begin{verbatim} +- clean + -> pid (cleans a broken call, use with care, leads often + to a segmentation fault) +- send + -> display (sends a Text Message to a Asterisk channel, + this channel must be an misdn channel) +- set + -> debug (sets debug level) +- show + -> config (shows the configuration options) + -> channels (shows the current active misdn channels) + -> channel (shows details about the given misdn channels) + -> stacks (shows the current ports, their protocols and states) + -> fullstacks (shows the current active and inactive misdn channels) + +- restart + -> port (restarts given port (L2 Restart) ) + +- reload (reloads misdn.conf) +\end{verbatim} +\end{astlisting} + +You can only use "misdn send display" when an Asterisk channel is created and +isdn is in the correct state. "correct state" means that you have established a +call to another phone (mustn't be isdn though). + +Then you use it like this: + +misdn send display mISDN/1/101 "Hello World!" + +where 1 is the Port of the Card where the phone is plugged in, and 101 is the +msn (callerid) of the Phone to send the text to. + +\subsection{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} + +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 +parts. Misdn Debug messages begin with an 'I', asterisk messages begin with +an '*', the rest is clear I think. + +Please take a trace of the problem and open a report in the Asterisk issue +tracker at \url{http://bugs.digium.com} in the "channel drivers" project, +"chan\_misdn" category. Read the bug guidelines to make sure you +provide all the information needed. + + +\subsection{Examples} + +Here are some examples of how to use chan\_misdn in the dialplan +(extensions.conf): + +\begin{astlisting} +\begin{verbatim} +[globals] +OUT_PORT=1 ; The physical Port of the Card +OUT_GROUP=ExternE1 ; The Group of Ports defined in misdn.conf + +[misdnIn] +exten => _X.,1,Dial(mISDN/${OUT_PORT}/${EXTEN}) +exten => _0X.,1,Dial(mISDN/g:${OUT_GROUP}/${EXTEN:1}) +exten => _1X.,1,Dial(mISDN/g:${OUT_GROUP}/${EXTEN:1}/:dHello) +exten => _1X.,1,Dial(mISDN/g:${OUT_GROUP}/${EXTEN:1}/:dHello Test:n) +\end{verbatim} +\end{astlisting} + +On the last line, you will notice the last argument (Hello); this is sent +as Display Message to the Phone. + +\subsection{Known Problems} + +Q: I cannot hear any tone after a successful CONNECT to the other end + +A: You forgot to load mISDNdsp, which is now needed by chan\_misdn for switching +and dtmf tone detection diff --git a/trunk/doc/tex/mp3.tex b/trunk/doc/tex/mp3.tex new file mode 100644 index 000000000..aeb02a0ea --- /dev/null +++ b/trunk/doc/tex/mp3.tex @@ -0,0 +1,11 @@ +\subsubsection{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. + +However, if you still need to use mp3 as your music on hold format, a format +driver for reading MP3 audio files is available in the asterisk-addons SVN +repository on svn.digium.com or in the asterisk-addons release at +\url{http://downloads.digium.com/pub/telephony/asterisk/}. + diff --git a/trunk/doc/tex/odbcstorage.tex b/trunk/doc/tex/odbcstorage.tex new file mode 100644 index 000000000..fed96e9d1 --- /dev/null +++ b/trunk/doc/tex/odbcstorage.tex @@ -0,0 +1,31 @@ + + +ODBC Storage allows you to store voicemail messages within a database +instead of using a file. This is \textbf{not} a full realtime engine and +\textbf{only} supports ODBC. The table description for the "voicemessages" +table is as follows: + +\begin{verbatim} ++----------------+-------------+------+-----+---------+-------+ +| Field | Type | Null | Key | Default | Extra | ++----------------+-------------+------+-----+---------+-------+ +| msgnum | int(11) | YES | | NULL | | +| dir | varchar(80) | YES | MUL | NULL | | +| context | varchar(80) | YES | | NULL | | +| macrocontext | varchar(80) | YES | | NULL | | +| callerid | varchar(40) | YES | | NULL | | +| origtime | varchar(40) | YES | | NULL | | +| duration | varchar(20) | YES | | NULL | | +| mailboxuser | varchar(80) | YES | | NULL | | +| mailboxcontext | varchar(80) | YES | | NULL | | +| recording | longblob | YES | | NULL | | ++----------------+-------------+------+-----+---------+-------+ +\end{verbatim} + +The database name (from \path{/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. + + diff --git a/trunk/doc/tex/phoneprov.tex b/trunk/doc/tex/phoneprov.tex new file mode 100644 index 000000000..cb236a89a --- /dev/null +++ b/trunk/doc/tex/phoneprov.tex @@ -0,0 +1,307 @@ +\section{Introduction} + +Asterisk includes basic phone provisioning support through the res\_phoneprov module. The +current implementation is based on a templating system using Asterisk dialplan function +and variable substitution and obtains information to substitute into those templates from +\path{phoneprov.conf} and \path{users.conf}. A profile and set of templates is provided +for provisioning Polycom phones. Note that res\_phoneprov is currently limited to +provisioning a single user per device. + +\section{Configuration of phoneprov.conf} + +The configuration file, \path{phoneprov.conf}, is used to set up the built-in variables +SEVER and SERVER\_PORT, to define a default phone profile to use, and to define different +phone profiles available for provisioning. + +\subsection{The [general] section} + +Below is a sample of the general section of \path{phoneprov.conf}: + +\begin{astlisting} +\begin{verbatim} +[general] +;serveriface=eth0 +;serveraddr=192.168.1.1 +;serverport=5060 +default_profile=polycom +\end{verbatim} +\end{astlisting} + +By default, res\_phoneprov will set the SERVER variable to the IP address on the server +that the requesting phone uses to contact the asterisk HTTP server. The SERVER\_PORT +variable will default to the \textbf{bindport} setting in sip.conf. + +Should the defaults be insufficient, there are two choices for overriding the default +setting of the SERVER variable. If the IP address of the server is known, or the hostname +resolvable by the phones, the appropriate \textbf{serveraddr} value should be set. +Alternatively, the network interface that the server listens on can be set by specifying a +\textbf{serveriface} and SERVER will be set to the IP address of that interface. Only one +of these options should be set. + +The default SERVER\_PORT variable can be overridden by setting the \textbf{serverport}. +If \textbf{bindport} is not set in \path{sip.conf} and serverport is not specified, it +is set to a default value of 5060. + +Any user set for auto-provisioning in users.conf without a specified profile will be +assumed to belong to the profile set with \textbf{default\_profile}. + +\subsection{Creating phone profiles} + +A phone profile is basically a list of files that a particular group of phones needs to +function. For most phone types there are files that are identical for all phones +(firmware, for instance) as well as a configuration file that is specific to individual +phones. res\_phoneprov breaks these two groups of files into static files and dynamic +files, respectively. A sample profile: + +\begin{astlisting} +\begin{verbatim} +[polycom] +staticdir => configs/ +mime_type => text/xml +setvar => CUSTOM_CONFIG=/var/lib/asterisk/phoneprov/configs/custom.cfg +static_file => bootrom.ld,application/octet-stream +static_file => bootrom.ver,plain/text +static_file => sip.ld,application/octet-stream +static_file => sip.ver,plain/text +static_file => sip.cfg +static_file => custom.cfg +${TOLOWER(${MAC})}.cfg => 000000000000.cfg +${TOLOWER(${MAC})}-phone.cfg => 000000000000-phone.cfg +config/${TOLOWER(${MAC})} => polycom.xml +${TOLOWER(${MAC})}-directory.xml => 000000000000-directory.xml +\end{verbatim} +\end{astlisting} + +A \textbf{static\_file} is set by specifying the file name, relative to +\path{AST\_DATA\_DIR/phoneprov}. The mime-type of the file can optionally be specified +after a comma. If \textbf{staticdir} is set, all static files will be relative to the +subdirectory of AST\_DATA\_DIR/phoneprov specified. + +Since phone-specific config files generally have file names based on phone-specifc data, +dynamic filenames in res\_phoneprov can be defined with Asterisk dialplan function and +variable substitution. In the above example, \$\{TOLOWER(\$\{MAC\})\}.cfg $\Rightarrow$ +000000000000.cfg would define a relative URI to be served that matches the format of +MACADDRESS.cfg, all lower case. A request for that file would then point to the template +found at AST\_DATA\_DIR/phoneprov/000000000000.cfg. The template can be followed by a +comma and mime-type. Notice that the dynamic filename (URI) can contain contain +directories. Since these files are dynamically generated, the config file itself does not +reside on the filesystem--only the template. To view the generated config file, open it +in a web browser. If the config file is XML, Firefox should display it. Some browsers +will require viewing the source of the page requested. + +A default mime-type for the profile can be defined by setting \textbf{mime-type}. If a +custom variable is required for a template, it can be specified with \textbf{setvar}. +Variable substitution on this value is done while building the route list, so +\$\{USERNAME\} would expand to the username of the users.conf user that registers the +dynamic filename. + +NOTE: Any dialplan function that is used for generation of dynamic file names MUST be +loaded before res\_phoneprov. Add "preload $\Rightarrow$ modulename.so" to +\path{modules.conf} for required functions. In the example above, "preload $\Rightarrow$ +func\_strings.so" would be required. + +\section{Configuration of users.conf} + +The asterisk-gui sets up extensions, SIP/IAX2 peers, and a host of other settings. +User-specific settings are stored in users.conf. If the asterisk-gui is not being used, +manual entries to users.conf can be made. + +\subsection{The [general] section} + +There are only two settings in the general section of \path{users.conf} that apply to +phone provisioning: localextenlength which maps to template variable EXTENSION\_LENGTH +and \textbf{vmexten} which maps to the VOICEMAIL\_EXTEN variable. + +\subsection{Invdividual Users} + +To enable auto-provisioning of a phone, the user in \path{users.conf} needs to have: + +\begin{astlisting} +\begin{verbatim} +... +autoprov=yes +macaddress=deadbeef4dad +profile=polycom +\end{verbatim} +\end{astlisting} + +The profile is optional if a \textbf{default\_profile} is set in \path{phoneprov.conf}. +The following is a sample users.conf entry, with the template variables commented next to +the settings: + +\begin{astlisting} +\begin{verbatim} +[6001] +callwaiting = yes +context = numberplan-custom-1 +hasagent = no +hasdirectory = yes +hasiax = no +hasmanager = no +hassip = yes +hasvoicemail = yes +host = dynamic +mailbox = 6001 +threewaycalling = yes +deletevoicemail = no +autoprov = yes +profile = polycom +canreinvite = no +nat = no +fullname = User Two ; ${DISPLAY_NAME} +secret = test ; ${SECRET} +username = 6001 ; ${USERNAME} +macaddress = deadbeef4dad ; ${MAC} +label = 6001 ; ${LABEL} +cid_number = 6001 ; ${CALLERID} +\end{verbatim} +\end{astlisting} + +The variables above, are the user-specfic variables that can be substituted into dynamic +filenames and config templates. + +\section{Templates} + +Configuration templates are a generic way to configure phones with text-based +configuration files. Templates can use any loaded dialplan function and all of the +variables created by \path{phoneprov.conf} and \path{users.conf}. A short example is the +included 000000000000.cfg Polycom template: + +\begin{astlisting} +\begin{verbatim} +<?xml version="1.0" standalone="yes"?> + <APPLICATION + APP_FILE_PATH="sip.ld" + CONFIG_FILES="${IF($[${STAT(e|${CUSTOM_CONFIG})}] ? "custom.cfg, +")}config/${TOLOWER(${MAC})}, sip.cfg" + MISC_FILES="" LOG_FILE_DIRECTORY="" + /> +\end{verbatim} +\end{astlisting} + +This template uses dialplan functions, expressions, and a couple of variables to generate +a config file to instruct the Polycom where to pull other needed config files. If a phone +with MAC address 0xDEADBEEF4DAD requests this config file, and the filename that is +stored in variable CUSTOM\_CONFIG does not exist, then the generated output would be: + +\begin{astlisting} +\begin{verbatim} +<?xml version="1.0" standalone="yes"?> + <APPLICATION + APP_FILE_PATH="sip.ld" + CONFIG_FILES="config/deadbeef4dad, sip.cfg" + MISC_FILES="" LOG_FILE_DIRECTORY="" + /> +\end{verbatim} +\end{astlisting} + +The Polycom phone would then download both sip.cfg (which would be registered in +\path{phoneprov.conf} as a static file) and config/deadbeef4dad (which would be +registered as a dynamic file pointing to another template, polycom.xml). + +res\_phoneprov also registers its own dialplan function: PP\_EACH\_USER. This function +was designed to be able to print out a particular string for each user that +res\_phoneprov knows about. An example use of this function is the template for a Polycom +contact directory: + +\begin{astlisting} +\begin{verbatim} +<?xml version="1.0" standalone="yes"?> +<directory> + <item_list> + ${PP_EACH_USER(<item><fn>%{DISPLAY_NAME}</fn><ct>%{CALLERID}</ct><bw>1</bw></item>|${MAC})} + </item_list> +</directory> +\end{verbatim} +\end{astlisting} + +PP\_EACH\_USER takes two arguments. The first is the string to be printed for each user. +Any variables that are to be substituted need to be in the format \%\{VARNAME\} so that +Asterisk doesn't try to substitute the variable immediately before it is passed to +PP\_EACH\_USER. The second, optional, argument is a MAC address to exclude from the list +iterated over (so, in this case, a phone won't be listed in its own contact directory). + +\section{Putting it all together} + +Make sure that \path{manager.conf} has: + +\begin{astlisting} +\begin{verbatim} +[general] +enabled = yes +webenabled = yes +\end{verbatim} +\end{astlisting} + +and that \path{http.conf} has: + +\begin{astlisting} +\begin{verbatim} +[general] +enabled = yes +bindaddr = 192.168.1.1 ; Your IP here ;-) +bindport = 8088 ; Or port 80 if it is the only http server running on the machine +\end{verbatim} +\end{astlisting} + +With \path{phoneprov.conf} and \path{users.conf} in place, start Astersik. From the CLI, +type "http show status". An example output: +\begin{astlisting} +\begin{verbatim} +HTTP Server Status: +Prefix: /asterisk +Server Enabled and Bound to 192.168.1.1:8088 + +Enabled URI's: +/asterisk/httpstatus => Asterisk HTTP General Status +/asterisk/phoneprov/... => Asterisk HTTP Phone Provisioning Tool +/asterisk/manager => HTML Manager Event Interface +/asterisk/rawman => Raw HTTP Manager Event Interface +/asterisk/static/... => Asterisk HTTP Static Delivery +/asterisk/mxml => XML Manager Event Interface + +Enabled Redirects: + None. + +POST mappings: +None. +\end{verbatim} +\end{astlisting} + +There should be a phoneprov URI listed. Next, from the CLI, type "phoneprov show routes" +and verify that the information there is correct. An example output for Polycom phones +woud look like: + +\begin{astlisting} +\begin{verbatim} +Static routes + +Relative URI Physical location +sip.ver configs/sip.ver +sip.ld configs/sip.ld +bootrom.ver configs/bootrom.ver +sip.cfg configs/sip.cfg +bootrom.ld configs/bootrom.ld +custom.cfg configs/custom.cfg + +Dynamic routes + +Relative URI Template +deadbeef4dad.cfg 000000000000.cfg +deadbeef4dad-directory.xml 000000000000-directory.xml +deadbeef4dad-phone.cfg 000000000000-phone.cfg +config/deadbeef4dad polycom.xml +\end{verbatim} +\end{astlisting} + +With the above examples, the phones would be pointed to +\url{http://192.168.1.1:8080/asterisk/phoneprov} for pulling config files. Templates +would all be placed in AST\_DATA\_DIR/phoneprov and static files would be placed in +AST\_DATA\_DIR/phoneprov/configs. Examples of valid URIs would be: + +\begin{itemize} +\item http://192.168.1.1:8080/asterisk/phoneprov/sip.cfg +\item http://192.168.1.1:8080/asterisk/phoneprov/deadbeef4dad.cfg +\item http://192.168.1.1:8080/asterisk/phoneprov/config/deadbeef4dad +\end{itemize} + diff --git a/trunk/doc/tex/privacy.tex b/trunk/doc/tex/privacy.tex new file mode 100644 index 000000000..f8bf698f6 --- /dev/null +++ b/trunk/doc/tex/privacy.tex @@ -0,0 +1,354 @@ +So, you want to avoid talking to pesky telemarketers/charity +seekers/poll takers/magazine renewers/etc? + +\subsection{First of all} + + the FTC "Don't call" database, this alone will reduce your +telemarketing call volume considerably. (see: +\url{https://www.donotcall.gov/default.aspx} ) But, this list won't protect +from the Charities, previous business relationships, etc. + +\subsection{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, +the number you have called is no longer in service." + +Most humans, even those with unlisted/callerid-blocked numbers, will +not immediately slam the handset down on the hook the moment they hear +the three tones. But autodialers seem pretty quick to do this. + +I just counted 40 hangups in Zapateller over the last year in my +CDR's. So, that is possibly 40 different telemarketers/charities that have +hopefully slashed my back-waters, out-of-the-way, humble home phone +number from their lists. + +I highly advise Zapateller for those seeking the nirvana of "privacy". + + +\subsection{Next, Fight against the empty CALLERID!} + +A considerable percentage of the calls you don't want, come from +sites that do not provide CallerID. + +Null callerid's are a fact of life, and could be a friend with an +unlisted number, or some charity looking for a handout. The +PrivacyManager application can help here. It will ask the caller to +enter a 10-digit phone number. They get 3 tries(configurable), and this is +configurable, with control being passed to priority+101 if they won't +supply one. + +PrivacyManager can't guarantee that the number they supply is any +good, tho, as there is no way to find out, short of hanging up and +calling them back. But some answers are obviously wrong. For instance, +it seems a common practice for telemarketers to use your own number +instead of giving you theirs. A simple test can detect this. More +advanced tests would be to look for -555- numbers, numbers that count +up or down, numbers of all the same digit, etc. + +My logs show that 39 have hung up in the PrivacyManager script over +the last year. + +(Note: Demanding all unlisted incoming callers to enter their CID may +not always be appropriate for all users. Another option might be to +use call screening. See below.) + + +\subsection{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 +you. In the vast majority of situations, a telemarketer will simply +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{astlisting} +\begin{verbatim} +[homeline] +exten => s,1,Answer +exten => s,2,SetVar,repeatcount=0 +exten => s,3,Zapateller,nocallerid +exten => s,4,PrivacyManager + ;; do this if they don't enter a number to Privacy Manager +exten => s,105,Background(tt-allbusy) +exten => s,106,Background(tt-somethingwrong) +exten => s,107,Background(tt-monkeysintro) +exten => s,108,Background(tt-monkeys) +exten => s,109,Background(tt-weasels) +exten => s,110,Hangup +exten => s,5,GotoIf($[ "${CALLERID(num)}" = "7773334444" & "${CALLERID(name)}" : "Privacy Manager" ]?callerid-liar,s,1:s,7) +\end{verbatim} +\end{astlisting} + +I suggest using Zapateller at the beginning of the context, before +anything else, on incoming calls.This can be followed by the +PrivacyManager App. + +Make sure, if you do the PrivacyManager app, that you take care of the +error condition! or their non-compliance will be rewarded with access +to the system. In the above, if they can't enter a 10-digit number in +3 tries, they get the humorous "I'm sorry, but all household members +are currently helping other telemarketers...", "something is terribly +wrong", "monkeys have carried them away...", various loud monkey +screechings, "weasels have...", and a hangup. There are plenty of +other paths to my torture scripts, I wanted to have some fun. + +In nearly all cases now, the telemarketers/charity-seekers that +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!} + +I have developed an elaborate script to torture Telemarketers, and +entertain friends. (See +\url{http://www.voip-info.org/wiki-Asterisk+Telemarketer+Torture} ) + +While mostly those that call in and traverse my teletorture scripts +are those we know, and are doing so out of curiosity, there have been +these others from Jan 1st,2004 thru June 1st, 2004: +(the numbers may or may not be correct.) + +\begin{itemize} + \item 603890zzzz -- hung up telemarket options. + \item "Integrated Sale" -- called a couple times. hung up in telemarket options + \item "UNITED STATES GOV" -- maybe a military recruiter, trying to lure one of my sons. + \item 800349zzzz -- hung up in charity intro + \item 800349zzzz -- hung up in charity choices, intro, about the only one who actually travelled to the bitter bottom of the scripts! + \item 216377zzzz -- hung up the magazine section + \item 626757zzzz = "LIR " (pronounced "Liar"?) hung up in telemarket intro, then choices + \item 757821zzzz -- hung up in new magazine subscription options. +\end{itemize} + +That averages out to maybe 1 a month. That puts into question whether +the ratio of the amount of labor it took to make the scripts versus +the benefits of lower call volumes was worth it, but, well, I had fun, +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} + +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 +how the callee wants the call handled, and the other, which does not +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 +option or enters an extension number that would dial your extension. + +\item 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 +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 +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} + +There are some variations, and these will be explained in due course. + + +To use these options, set your Dial to something like: +\begin{astlisting} +\begin{verbatim} +exten => 3,3,Dial(Zap/5r3&Zap/6r3,35,tmPA(beep)) + or +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} +\end{astlisting} + +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 +party gets to hear all the ringing, and lack thereof. It is generally +better to use Music On Hold. Lots of folks hang up after the 3rd or +4th ring, and you might lose the call before you can enter an option! + +The 'P' option alone will database everything using the extension as a +default 'tree'. To get multiple extensions sharing the same database, use +P(some-shared-key). Also, if the same person has multiple extensions, +use P(unique-id) on all their dial commands. + +Use little 'p' for screening. Every incoming call will include a +prompt for the callee's choice. + +the A(beep), will generate a 'beep' that the callee will hear if they +choose to talk to the caller. It's kind of a prompt to let the callee +know that he has to say 'hi'. It's not required, but I find it +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 +\path{/var/lib/asterisk/sounds/priv-callerintros} dir, under the name +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} + +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 +options, but they only affect things if P or p are also in the +options. + +'N' says, "Only screen the call if no CallerID is present". So, if a +callerID were supplied, it will come straight thru to your extension. + +'n' says, "Don't save any introductions". Folks will be asked to +supply an introduction ("At the tone, say your name") every time they +call. Their introductions will be removed after the callee makes a +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. + + +\subsection{Recorded Introductions} + +\subsubsection{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 \path{/var/lib/asterisk/sounds/priv-callerintros}, if they have +a CallerID. Just the 10-digit callerid numbers are used as filenames, +with a ".gsm" at the end. + +Having these recordings around can be very useful, however... + +First of all, if a callerid is supplied, and a recorded intro for that +number is already present, the caller is spared the inconvenience of +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{astlisting} +\begin{verbatim} +exten => s,6,Set(PATH=/var/lib/asterisk/sounds/priv-callerintros) +exten => s,7,System(/usr/bin/play ${PATH}/${CALLERID(num)}.gsm&,0) +\end{verbatim} +\end{astlisting} + +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 +gives us a hint who is calling. + +(Note: the ,0 option at the end of the System command above, is a +local mod I made to the System command. It forces a 0 result code to +be returned, whether the play command successfully completed or +not. Therefore, I don't have to ensure that the file exists or +not. While I've turned this mod into the developers, it hasn't been +incorporated yet. You might want to write an AGI or shell script to +handle it a little more intelligently) + +And one other thing. You can easily supply your callers with an option +to listen to, and re-record their introductions. Here's what I did in +the home system's extensions.conf. (assume that a +Goto(home-introduction,s,1) exists somewhere in your main menu as an +option): + +\begin{astlisting} +\begin{verbatim} +[home-introduction] +exten => s,1,Background(intro-options) ;; Script: + ;; To hear your Introduction, dial 1. + ;; to record a new introduction, dial 2. + ;; to return to the main menu, dial 3. + ;; to hear what this is all about, dial 4. +exten => 1,1,Playback,priv-callerintros/${CALLERID(num)} +exten => 1,2,Goto(s,1) +exten => 2,1,Goto(home-introduction-record,s,1) +exten => 3,1,Goto(homeline,s,7) +exten => 4,1,Playback(intro-intro) + ;; Script: + ;; This may seem a little strange, but it really is a neat + ;; thing, both for you and for us. I've taped a short introduction + ;; for many of the folks who normally call us. Using the Caller ID + ;; from each incoming call, the system plays the introduction + ;; for that phone number over a speaker, just as the call comes in. + ;; This helps the folks + ;; here in the house more quickly determine who is calling. + ;; and gets the right ones to gravitate to the phone. + ;; You can listen to, and record a new intro for your phone number + ;; using this menu. +exten => 4,2,Goto(s,1) +exten => t,1,Goto(s,1) +exten => i,1,Background(invalid) +exten => i,2,Goto(s,1) +exten => o,1,Goto(s,1) + +[home-introduction-record] +exten => s,1,Background(intro-record-choices) ;; Script: + ;; If you want some advice about recording your + ;; introduction, dial 1. + ;; otherwise, dial 2, and introduce yourself after + ;; the beep. +exten => 1,1,Playback(intro-record) + ;; Your introduction should be short and sweet and crisp. + ;; Your introduction will be limited to 4 seconds. + ;; This is NOT meant to be a voice mail message, so + ;; please, don't say anything about why you are calling. + ;; After we are done making the recording, your introduction + ;; will be saved for playback. + ;; If you are the only person that would call from this number, + ;; please state your name. Otherwise, state your business + ;; or residence name instead. For instance, if you are + ;; friend of the family, say, Olie McPherson, and both + ;; you and your kids might call here a lot, you might + ;; say: "This is the distinguished Olie McPherson Residence!" + ;; If you are the only person calling, you might say this: + ;; "This is the illustrious Kermit McFrog! Pick up the Phone, someone!!" + ;; If you are calling from a business, you might pronounce a more sedate introduction,like, + ;; "Fritz from McDonalds calling.", or perhaps the more original introduction: + ;; "John, from the Park County Morgue. You stab 'em, we slab 'em!". + ;; Just one caution: the kids will hear what you record every time + ;; you call. So watch your language! + ;; I will begin recording after the tone. + ;; When you are done, hit the # key. Gather your thoughts and get + ;; ready. Remember, the # key will end the recording, and play back + ;; your intro. Good Luck, and Thank you!" +exten => 1,2,Goto(2,1) +exten => 2,1,Background(intro-start) + ;; OK, here we go! After the beep, please give your introduction. +exten => 2,2,Background(beep) +exten => 2,3,Record(priv-callerintros/${CALLERID(num)}:gsm,4) +exten => 2,4,Background(priv-callerintros/${CALLERID(num)}) +exten => 2,5,Goto(home-introduction,s,1) +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} +\end{astlisting} + +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. + + diff --git a/trunk/doc/tex/qos.tex b/trunk/doc/tex/qos.tex new file mode 100644 index 000000000..acbf7f443 --- /dev/null +++ b/trunk/doc/tex/qos.tex @@ -0,0 +1,135 @@ +\subsubsection{Introduction} + +Asterisk support different QoS settings on application level on various protocol +on any of signaling and media. Type of Service (TOS) byte can be set 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. + +Also asterisk running on Linux can set 802.1p CoS marks in VLAN packets for all +used VoIP protocols. It is useful when you are working in switched environment. +In fact asterisk only set priority for Linux socket. For mapping this priority +and VLAN CoS mark you need to use this command: + +\begin{verbatim} +vconfig set_egress_map [vlan-device] [skb-priority] [vlan-qos] +\end{verbatim} + +In table behind shown all voice channels and other modules of asterisk, that +support QoS settings for network traffic and type of traffic which can have +QoS settings. + +\begin{verbatim} + Channel Drivers ++==============+===========+=====+=====+=====+ +| | Signaling |Audio|Video| Text| ++==============+===========+=====+=====+=====+ +|chan_sip | + | + | + | + | +|--------------+-----------+-----+-----+-----+ +|chan_skinny | + | + | + | | +|--------------+-----------+-----+-----+-----+ +|chan_mgcp | + | + | | | +|--------------+-----------+-----+-----+-----+ +|chan_unistim | + | + | | | +|--------------+-----------+-----+-----+-----+ +|chan_h323 | | + | | | +|--------------+-----------+-----+-----+-----+ +|chan_iax2 | + | ++==============+=============================+ + Other ++==============+=============================+ +| dundi.conf | + (tos setting) | +|--------------+-----------------------------+ +| iaxprov.conf | + (tos setting) | ++==============+=============================+ +\end{verbatim} + + +\subsubsection{IP TOS values} + +The allowable values for any of the tos* parameters are: +CS0, CS1, CS2, CS3, CS4, CS5, CS6, CS7, AF11, AF12, AF13, AF21, AF22, AF23, +AF31, AF32, AF33, AF41, AF42, AF43 and ef (expedited forwarding), + +The tos* parameters also take numeric values. + +Note, that on Linux system you can use ef value in case your asterisk is running +from a user other then root only when you have compiled asterisk with libcap. + +The lowdelay, throughput, reliability, mincost, and none values are removed +in current releases. + +\subsubsection{802.1p CoS values} + +As far as 802.1p uses 3 bites from VLAN header, there are parameter can take +integer values from 0 to 7. + +\subsubsection{Recommended values} +Recommended values shown above and also included in sample configuration files: +\begin{verbatim} ++============+=========+======+ +| | tos | cos | ++============+=========+======+ +|Signaling | cs3 | 3 | +|Audio | ef | 5 | +|Video | af41 | 4 | +|Text | af41 | 3 | +|Other | ef | | ++============+=========+======+ +\end{verbatim} + +\subsubsection{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 +signalling, audio, and video into one UDP stream, it is not possible +to set the TOS separately for the different types of traffic. + +In iaxprov.conf, there is a "tos" parameter that tells the IAXy what TOS +to set on packets it generates. As with the parameter in iax.conf, +IAX packets generated by an IAXy cannot have different TOS settings +based upon the type of packet. However different IAXy devices can +have different TOS settings. + +\subsubsection{SIP} + +In sip.conf, there are three parameters that control the TOS settings: +"tos\_sip", "tos\_audio", "tos\_video" and "tos\_text". tos\_sip controls +what TOS SIP call signaling packets are set to. tos\_audio, tos\_video +and tos\_text controls what TOS RTP audio, video or text accordingly +packets are set to. + +There are four parameters to control 802.1p CoS: "cos\_sip", "cos\_audio", +"cos\_video" and "cos\_text". It behavior the same as written above. + +\subsubsection{Other RTP channels} + +chan\_mgcp, chan\_h323, chan\_skinny and chan\_unistim also support TOS and +CoS via setting tos and cos parameters in correspond to module config +files. Naming style and behavior same as for chan\_sip. + +\subsubsection{Reference} + +IEEE 802.1Q Standard: +\url{http://standards.ieee.org/getieee802/download/802.1Q-1998.pdf} +Related protocols: IEEE 802.3, 802.2, 802.1D, 802.1Q + +RFC 2474 - "Definition of the Differentiated Services Field +(DS field) in the IPv4 and IPv6 Headers", Nichols, K., et al, +December 1998. + +IANA Assignments, DSCP registry +Differentiated Services Field Codepoints +\url{http://www.iana.org/assignments/dscp-registry} + +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 +\url{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: +\url{http://www.cisco.com/application/pdf/en/us/guest/netsol/ns432/c649/ccmigration\_09186a008049b062.pdf} diff --git a/trunk/doc/tex/queuelog.tex b/trunk/doc/tex/queuelog.tex new file mode 100644 index 000000000..daf650a26 --- /dev/null +++ b/trunk/doc/tex/queuelog.tex @@ -0,0 +1,118 @@ +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 \path{/var/log/asterisk/queue_log}. + +These are the events (and associated information) in the queue log: + +\textbf{ABANDON(position$|$origposition$|$waittime)} + +The caller abandoned their position in the queue. The position is the +caller's position in the queue when they hungup, the origposition is +the original position the caller was when they first entered the +queue, and the waittime is how long the call had been waiting in the +queue at the time of disconnect. + +\textbf{AGENTDUMP} + +The agent dumped the caller while listening to the queue announcement. + +\textbf{AGENTLOGIN(channel)} + +The agent logged in. The channel is recorded. + +\textbf{AGENTCALLBACKLOGIN(exten@context)} + +The callback agent logged in. The login extension and context is recorded. + +\textbf{AGENTLOGOFF(channel$|$logintime)} + +The agent logged off. The channel is recorded, along with the total time +the agent was logged in. + +\textbf{AGENTCALLBACKLOGOFF(exten@context$|$logintime$|$reason)} + +The callback agent logged off. The last login extension and context is +recorded, along with the total time the agent was logged in, and the +reason for the logoff if it was not a normal logoff +(e.g., Autologoff, Chanunavail) + +\textbf{COMPLETEAGENT(holdtime$|$calltime$|$origposition)} + +The caller was connected to an agent, and the call was terminated normally +by the *agent*. The caller's hold time and the length of the call are both +recorded. The caller's original position in the queue is recorded in +origposition. + +\textbf{COMPLETECALLER(holdtime$|$calltime$|$origposition)} + +The caller was connected to an agent, and the call was terminated normally +by the *caller*. The caller's hold time and the length of the call are both +recorded. The caller's original position in the queue is recorded in +origposition. + +\textbf{CONFIGRELOAD} + +The configuration has been reloaded (e.g. with asterisk -rx reload) + +\textbf{CONNECT(holdtime$|$bridgedchanneluniqueid$|$ringtime)} + +The caller was connected to an agent. Hold time represents the amount +of time the caller was on hold. The bridged channel unique ID contains +the unique ID of the queue member channel that is taking the call. This +is useful when trying to link recording filenames to a particular +call in the queue. Ringtime represents the time the queue members phone +was ringing prior to being answered. + +\textbf{ENTERQUEUE(url$|$callerid)} + +A call has entered the queue. URL (if specified) and Caller*ID are placed +in the log. + +\textbf{EXITEMPTY(position$|$origposition$|$waittime)} + +The caller was exited from the queue forcefully because the queue had no +reachable members and it's configured to do that to callers when there +are no reachable members. The position is the caller's position in the +queue when they hungup, the origposition is the original position the +caller was when they first entered the queue, and the waittime is how +long the call had been waiting in the queue at the time of disconnect. + +\textbf{EXITWITHKEY(key$|$position$|$origposition$|$waittime)} + +The caller elected to use a menu key to exit the queue. The key and +the caller's position in the queue are recorded. The caller's entry +position and amoutn of time waited is also recorded. + +\textbf{EXITWITHTIMEOUT(position$|$origposition$|$waittime)} + +The caller was on hold too long and the timeout expired. The position in the +queue when the timeout occurred, the entry position, and the amount of time +waited are logged. + +\textbf{QUEUESTART} + +The queueing system has been started for the first time this session. + +\textbf{RINGNOANSWER(ringtime)} + +After trying for ringtime ms to connect to the available queue member, +the attempt ended without the member picking up the call. Bad queue +member! + +\textbf{SYSCOMPAT} + +A call was answered by an agent, but the call was dropped because the +channels were not compatible. + +\textbf{TRANSFER(extension$|$context$|$holdtime$|$calltime)} + +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 +a transfer is performed by a queue member is to use the built-in transfer +functionality of Asterisk. + diff --git a/trunk/doc/tex/queues-with-callback-members.tex b/trunk/doc/tex/queues-with-callback-members.tex new file mode 100644 index 000000000..36e642845 --- /dev/null +++ b/trunk/doc/tex/queues-with-callback-members.tex @@ -0,0 +1,551 @@ + +\section{Introduction} + +Pardon, but the dialplan in this tutorial will be expressed +in AEL, the new Asterisk Extension Language. If you are +not used to its syntax, we hope you will find it to some +degree intuitive. If not, there are documents explaining +its syntax and constructs. + + +\section{Configuring Call Queues} + +\subsection{queues.conf} +First of all, set up call queues in queue.conf + +Here is an example: + +\begin{astlisting} +\begin{verbatim} + =========== queues.conf =========== + | ; Cool Digium Queues | + | [general] | + | persistentmembers = yes | + | | + | ; General sales queue | + | [sales-general] | + | music=default | + | context=sales | + | strategy=ringall | + | joinempty=strict | + | leavewhenempty=strict | + | | + | ; Customer service queue | + | [customerservice] | + | music=default | + | context=customerservice | + | strategy=ringall | + | joinempty=strict | + | leavewhenempty=strict | + | | + | ; Support dispatch queue | + | [dispatch] | + | music=default | + | context=dispatch | + | strategy=ringall | + | joinempty=strict | + | leavewhenempty=strict | + =================================== +\end{verbatim} +\end{astlisting} + +In the above, we have defined 3 separate calling queues: +sales-general, customerservice, and dispatch. + +Please note that the sales-general queue specifies a +context of "sales", and that customerservice specifies the +context of "customerservice", and the dispatch +queue specifies the context "dispatch". These three +contexts must be defined somewhere in your dialplan. +We will show them after the main menu below. + +In the [general] section, specifying the persistentmembers=yes, +will cause the agent lists to be stored in astdb, and +recalled on startup. + +The strategy=ringall will cause all agents to be dialed +together, the first to answer is then assigned the incoming +call. + +"joinempty" set to "strict" will keep incoming callers from +being placed in queues where there are no agents to take calls. +The Queue() application will return, and the dial plan can +determine what to do next. + +If there are calls queued, and the last agent logs out, the +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} + + +Then in extensions.ael, you can do these things: + +\subsubsection{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{astlisting} +\begin{verbatim} +context mainmenu { + + includes { + digium; + queues-loginout; + } + + 0 => goto dispatch,s,1; + 2 => goto sales,s,1; + 3 => goto customerservice,s,1; + 4 => goto dispatch,s,1; + + s => { + Ringing(); + Wait(1); + Set(attempts=0); + Answer(); + Wait(1); + Background(digium/ThankYouForCallingDigium); + Background(digium/YourOpenSourceTelecommunicationsSupplier); + WaitExten(0.3); + repeat: + Set(attempts=$[${attempts} + 1]); + Background(digium/IfYouKnowYourPartysExtensionYouMayDialItAtAnyTime); + WaitExten(0.1); + Background(digium/Otherwise); + WaitExten(0.1); + Background(digium/ForSalesPleasePress2); + WaitExten(0.2); + Background(digium/ForCustomerServicePleasePress3); + WaitExten(0.2); + Background(digium/ForAllOtherDepartmentsPleasePress4); + WaitExten(0.2); + Background(digium/ToSpeakWithAnOperatorPleasePress0AtAnyTime); + if( ${attempts} < 2 ) { + WaitExten(0.3); + Background(digium/ToHearTheseOptionsRepeatedPleaseHold); + } + WaitExten(5); + if( ${attempts} < 2 ) goto repeat; + Background(digium/YouHaveMadeNoSelection); + Background(digium/ThisCallWillBeEnded); + Background(goodbye); + Hangup(); + } +} +\end{verbatim} +\end{astlisting} + +\subsubsection{The Contexts referenced from the queues.conf file} + +\begin{astlisting} +\begin{verbatim} +context sales { + + 0 => goto dispatch,s,1; + 8 => Voicemail(${SALESVM}); + + s => { + Ringing(); + Wait(2); + Background(digium/ThankYouForContactingTheDigiumSalesDepartment); + WaitExten(0.3); + Background(digium/PleaseHoldAndYourCallWillBeAnsweredByOurNextAvailableSalesRepresentative); + WaitExten(0.3); + Background(digium/AtAnyTimeYouMayPress0ToSpeakWithAnOperatorOr8ToLeaveAMessage); + Set(CALLERID(name)=Sales); + Queue(sales-general,t); + Set(CALLERID(name)=EmptySalQ); + goto dispatch,s,1; + Playback(goodbye); + Hangup(); + } +} +\end{verbatim} +\end{astlisting} + +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{astlisting} +\begin{verbatim} +context customerservice { + + 0 => { + SetCIDName(CSVTrans); + goto dispatch|s|1; + } + 8 => Voicemail(${CUSTSERVVM}); + + s => { + Ringing(); + Wait(2); + Background(digium/ThankYouForCallingDigiumCustomerService); + WaitExten(0.3); + notracking: + Background(digium/PleaseWaitForTheNextAvailableCustomerServiceRepresentative); + WaitExten(0.3); + Background(digium/AtAnyTimeYouMayPress0ToSpeakWithAnOperatorOr8ToLeaveAMessage); + Set(CALLERID(name)=Cust Svc); + Set(QUEUE_MAX_PENALTY=10); + Queue(customerservice,t); + Set(QUEUE_MAX_PENALTY=0); + Queue(customerservice,t); + Set(CALLERID(name)=EmptyCSVQ); + goto dispatch,s,1; + Background(digium/NoCustomerServiceRepresentativesAreAvailableAtThisTime); + Background(digium/PleaseLeaveAMessageInTheCustomerServiceVoiceMailBox); + Voicemail(${CUSTSERVVM}); + Playback(goodbye); + Hangup(); + } +} +\end{verbatim} +\end{astlisting} + +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, +then all agents are rung. + +\begin{astlisting} +\begin{verbatim} +context dispatch +{ + + s => { + Ringing(); + Wait(2); + Background(digium/ThankYouForCallingDigium); + WaitExten(0.3); + Background(digium/YourCallWillBeAnsweredByOurNextAvailableOperator); + Background(digium/PleaseHold); + Set(QUEUE_MAX_PENALTY=10); + Queue(dispatch|t); + Set(QUEUE_MAX_PENALTY=20); + Queue(dispatch|t); + Set(QUEUE_MAX_PENALTY=0); + Queue(dispatch|t); + Background(digium/NoOneIsAvailableToTakeYourCall); + Background(digium/PleaseLeaveAMessageInOurGeneralVoiceMailBox); + Voicemail(${DISPATCHVM}); + Playback(goodbye); + Hangup(); + } +} +\end{verbatim} +\end{astlisting} + +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 +Queue($<$queue-name$>$,option,...) (see the Queue application documetation for details) + +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 +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 +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 +to zero, which means to try all available agents. + + +\subsection{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, +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. + +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{astlisting} +\begin{verbatim} +context queues-loginout +{ + 6092 => { + Answer(); + Read(AGENT_NUMBER,agent-enternum); + VMAuthenticate(${AGENT_NUMBER}@default,s); + Set(queue-announce-success=1); + goto queues-manip,I${AGENT_NUMBER},1; + } + + 6093 => { + Answer(); + Read(AGENT_NUMBER,agent-enternum); + Set(queue-announce-success=1); + goto queues-manip,O${AGENT_NUMBER},1; + } +} +\end{verbatim} +\end{astlisting} + +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 +for their agent number, and if they are logging in, their passcode, +and then they are transferred to the proper extension in the +queues-manip context. The queues-manip context does all the +actual work: + +\begin{astlisting} +\begin{verbatim} +context queues-manip { + + // Raquel Squelch + _[IO]6121 => { + &queue-addremove(dispatch,10,${EXTEN}); + &queue-success(${EXTEN}); + } + + // Brittanica Spears + _[IO]6165 => { + &queue-addremove(dispatch,20,${EXTEN}); + &queue-success(${EXTEN}); + } + + // Rock Hudson + _[IO]6170 => { + &queue-addremove(sales-general,10,${EXTEN}); + &queue-addremove(customerservice,20,${EXTEN}); + &queue-addremove(dispatch,30,${EXTEN}); + &queue-success(${EXTEN}); + } + + // Saline Dye-on + _[IO]6070 => { + &queue-addremove(sales-general,20,${EXTEN}); + &queue-addremove(customerservice,30,${EXTEN}); + &queue-addremove(dispatch,30,${EXTEN}); + &queue-success(${EXTEN}); + } +} +\end{verbatim} +\end{astlisting} + +In the above extensions, note that the queue-addremove macro is used +to actually add or remove the agent from the applicable queue, +with the applicable priority level. Note that agents with a +priority level of 10 will be called before agents with levels +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 +dial Rock and Saline simultaneously. + +Also note that Rock will be among the first to be called in the sales-general +queue, and among the last in the dispatch queue. As you can see in +main menu, the callerID is set in the main menu so they can tell +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{astlisting} +\begin{verbatim} +macro queue-success(exten) +{ + if( ${queue-announce-success} > 0 ) + { + switch(${exten:0:1}) + { + case I: + Playback(agent-loginok); + Hangup(); + break; + case O: + Playback(agent-loggedoff); + Hangup(); + break; + } + } +} +\end{verbatim} +\end{astlisting} + +The queue-addremove macro is defined in this manner: + +\begin{astlisting} +\begin{verbatim} +macro queue-addremove(queuename,penalty,exten) +{ + switch(${exten:0:1}) + { + case I: // Login + AddQueueMember(${queuename},Local/${exten:1}@agents,${penalty}); + break; + case O: // Logout + RemoveQueueMember(${queuename},Local/${exten:1}@agents); + break; + case P: // Pause + PauseQueueMember(${queuename},Local/${exten:1}@agents); + break; + case U: // Unpause + UnpauseQueueMember(${queuename},Local/${exten:1}@agents); + break; + default: // Invalid + Playback(invalid); + break; + } +} +\end{verbatim} +\end{astlisting} + +Basically, it uses the first character of the 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} + +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{astlisting} +\begin{verbatim} +context agents +{ + // General sales queue + 8010 => + { + Set(QUEUE_MAX_PENALTY=10); + Queue(sales-general,t); + Set(QUEUE_MAX_PENALTY=0); + Queue(sales-general,t); + Set(CALLERID(name)=EmptySalQ); + goto dispatch,s,1; + } + // Customer Service queue + 8011 => + { + Set(QUEUE_MAX_PENALTY=10); + Queue(customerservice,t); + Set(QUEUE_MAX_PENALTY=0); + Queue(customerservice,t); + Set(CALLERID(name)=EMptyCSVQ); + goto dispatch,s,1; + } + 8013 => + { + Dial(iax2/sweatshop/9456@from-ecstacy); + + Set(CALLERID(name)=EmptySupQ); + Set(QUEUE_MAX_PENALTY=10); + Queue(support-dispatch,t); + Set(QUEUE_MAX_PENALTY=20); + Queue(support-dispatch,t); + Set(QUEUE_MAX_PENALTY=0); // means no max + Queue(support-dispatch,t); + goto dispatch,s,1; + } + 6121 => &callagent(${RAQUEL},${EXTEN}); + 6165 => &callagent(${SPEARS},${EXTEN}); + 6170 => &callagent(${ROCK},${EXTEN}); + 6070 => &callagent(${SALINE},${EXTEN}); +} +\end{verbatim} +\end{astlisting} + +In the above, the variables \$\{RAQUEL\}, etc stand for +actual devices to ring that person's +phone (like Zap/37). + +The 8010, 8011, and 8013 extensions are purely for transferring +incoming callers to queues. For instance, a customer service +agent might want to transfer the caller to talk to sales. The +agent only has to transfer to extension 8010, in this case. + +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{astlisting} +\begin{verbatim} +macro callagent(device,exten) +{ + if( ${GROUP_COUNT(${exten}@agents)}=0 ) + { + Set(OUTBOUND_GROUP=${exten}@agents); + Dial(${device},300,t); + switch(${DIALSTATUS}) + { + case BUSY: + Busy(); + break; + case NOANSWER: + Set(queue-announce-success=0); + goto queues-manip,O${exten},1; + default: + Hangup(); + break; + } + } + else + { + Busy(); + } +} +\end{verbatim} +\end{astlisting} + +In the callagent macro above, the \$\{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 +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 +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() +is returned without actually trying to dial the agent. + +\subsection{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{astlisting} +\begin{verbatim} +[macro-screen] +exten=>s,1,Wait(.25) +exten=>s,2,Read(ACCEPT,screen-callee-options,1) +exten=>s,3,Gotoif($[${ACCEPT} = 1] ?50) +exten=>s,4,Gotoif($[${ACCEPT} = 2] ?30) +exten=>s,5,Gotoif($[${ACCEPT} = 3] ?40) +exten=>s,6,Gotoif($[${ACCEPT} = 4] ?30:30) +exten=>s,30,Set(MACRO_RESULT=CONTINUE) +exten=>s,40,Read(TEXTEN,custom/screen-exten,) +exten=>s,41,Gotoif($[${LEN(${TEXTEN})} = 3]?42:45) +exten=>s,42,Set(MACRO_RESULT=GOTO:from-internal^${TEXTEN}^1) +exten=>s,45,Gotoif($[${TEXTEN} = 0] ?46:4) +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} +\end{astlisting} + +\subsection{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/trunk/doc/tex/realtime.tex b/trunk/doc/tex/realtime.tex new file mode 100644 index 000000000..62349f60c --- /dev/null +++ b/trunk/doc/tex/realtime.tex @@ -0,0 +1,127 @@ +\subsubsection{Introduction} + +The Asterisk Realtime Architecture is a new set of drivers and +functions implemented in Asterisk. + +The benefits of this architecture are many, both from a code management +standpoint and from an installation perspective. + +The ARA is designed to be independent of storage. Currently, most +drivers are based on SQL, but the architecture should be able to handle +other storage methods in the future, like LDAP. + +The main benefit comes in the database support. In Asterisk v1.0 some +functions supported MySQL database, some PostgreSQL and other ODBC. +With the ARA, we have a unified database interface internally in Asterisk, +so if one function supports database integration, all databases that has a +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 \url{www.unixodbc.org} for more information. + \item MySQL: Found in the asterisk-addons subversion repository on \url{svn.digium.com} + \item PostgreSQL: Native support for Postgres, integrated into Asterisk +\end{itemize} + +\subsubsection{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 +functionality. With the ARA, we now support many more databases for +dynamic configuration of phones. + +The ARA static mode is used to load configuration files. For the Asterisk +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} + +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, +most of the functionality works the same way for realtime friends as for +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. + +If you specify a separate family called "sipregs" SIP registration +data will be stored in that table and not in the "sippeers" table. + +\subsubsection{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} + +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 +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} + +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} + +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). + +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} + +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} + +Voicemail storage with the support of ODBC described in file +\path{docs/odbcstorage.tex} (\ref{odbcstorage}). + +\subsubsection{Limitations} + +Currently, realtime extensions do not support realtime hints. There is +a workaround available by using func\_odbc. See the sample func\_odbc.conf +for more information. + +\subsubsection{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 +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/trunk/doc/tex/security.tex b/trunk/doc/tex/security.tex new file mode 100644 index 000000000..4eb4e1095 --- /dev/null +++ b/trunk/doc/tex/security.tex @@ -0,0 +1,80 @@ +\subsection{Introduction} + +PLEASE READ THE FOLLOWING IMPORTANT SECURITY RELATED INFORMATION. +IMPROPER CONFIGURATION OF ASTERISK COULD ALLOW UNAUTHORIZED USE OF YOUR +FACILITIES, POTENTIALLY INCURRING SUBSTANTIAL CHARGES. + +Asterisk security involves both network security (encryption, authentication) +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} + +If you install Asterisk and use the "make samples" command to install +a demonstration configuration, Asterisk will open a few ports for accepting +VoIP calls. Check the channel configuration files for the ports and IP addresses. + +If you enable the manager interface in manager.conf, please make sure that +you access manager in a safe environment or protect it with SSH or other +VPN solutions. + +For all TCP/IP connections in Asterisk, you can set ACL lists that +will permit or deny network access to Asterisk services. Please check +the "permit" and "deny" configuration options in manager.conf and +the VoIP channel configurations - i.e. sip.conf and iax.conf. + +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} + +First and foremost remember this: + +USE THE EXTENSION CONTEXTS TO ISOLATE OUTGOING OR TOLL SERVICES FROM ANY +INCOMING CONNECTIONS. + +You should consider that if any channel, incoming line, etc can enter an +extension context that it has the capability of accessing any extension +within that context. + +Therefore, you should NOT allow access to outgoing or toll services in +contexts that are accessible (especially without a password) from incoming +channels, be they IAX channels, FX or other trunks, or even untrusted +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{astlisting} +\begin{verbatim} + include => default +\end{verbatim} +\end{astlisting} + +in the appropriate section. A well designed PBX might look like this: + +\begin{astlisting} +\begin{verbatim} +[longdistance] +exten => _91NXXNXXXXXX,1,Dial(Zap/g2/${EXTEN:1}) +include => local + +[local] +exten => _9NXXNXXX,1,Dial(Zap/g2/${EXTEN:1}) +include => default + +[default] +exten => 6123,Dial(Zap/1) +\end{verbatim} +\end{astlisting} + +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} + +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 +history. Keep this in mind when providing access to these resources. diff --git a/trunk/doc/tex/sla.tex b/trunk/doc/tex/sla.tex new file mode 100644 index 000000000..afafd2ae4 --- /dev/null +++ b/trunk/doc/tex/sla.tex @@ -0,0 +1,387 @@ +%\documentclass[12pt,a4]{article} +%\usepackage{hyperref} + +%\author{Russell Bryant \\ Software Engineer \\ Digium, Inc.} +%\title{Shared Line Appearances} + +%\begin{document} +%\maketitle + +%\tableofcontents + +\section{Introduction} + +The "SLA" functionality in Asterisk is intended to allow a setup that emulates +a simple key system. It uses the various abstraction layers already built into +Asterisk to emulate key system functionality across various devices, including +IP channels. + +\section{Configuration} + +\subsection{Summary} + +An SLA system is built up of virtual trunks and stations mapped to real +Asterisk devices. The configuration for all of this is done in three +different files: extensions.conf, sla.conf, and the channel specific +configuration file such as sip.conf or zapata.conf. + +\subsection{Dialplan} + +The SLA implementation can automatically generate the dialplan necessary for +basic operation if the "autocontext" option is set for trunks and stations in +sla.conf. However, for reference, here is an automatically generated dialplan +to help with custom building of the dialplan to include other features, such as +voicemail (\ref{voicemail}). + +However, note that there is a little bit of additional configuration needed if +the trunk is an IP channel. This is discussed in the section on trunks (\ref{trunks}). + +There are extensions for incoming calls on a specific trunk, which execute the SLATrunk +application, as well as incoming calls from a station, which execute SLAStation. +Note that there are multiple extensions for incoming calls from a station. This is +because the SLA system has to know whether the phone just went off hook, or if the +user pressed a specific line button. + +Also note that there is a hint for every line on every station. This lets the SLA +system control each individual light on every phone to ensure that it shows the +correct state of the line. The phones must subscribe to the state of each of their +line appearances. + +Please refer to the examples section for full dialplan samples for SLA. + +\subsection{Trunks} +\label{trunks} + +An SLA trunk is a mapping between a virtual trunk and a real Asterisk device. +This device may be an analog FXO line, or something like a SIP trunk. A trunk +must be configured in two places. First, configure the device itself in the +channel specific configuration file such as zapata.conf or sip.conf. Once the +trunk is configured, then map it to an SLA trunk in sla.conf. +\begin{astlisting} +\begin{verbatim} +[line1] +type=trunk +device=Zap/1 +\end{verbatim} +\end{astlisting} + +Be sure to configure the trunk's context to be the same one that is set for the +"autocontext" option in sla.conf if automatic dialplan configuration is used. +This would be done in the regular device entry in zapata.conf, sip.conf, etc. +Note that the automatic dialplan generation creates the SLATrunk() extension +at extension 's'. This is perfect for Zap channels that are FXO trunks, for +example. However, it may not be good enough for an IP trunk, since the call +coming in over the trunk may specify an actual number. + +If the dialplan is being built manually, ensure that calls coming in on a trunk +execute the SLATrunk() application with an argument of the trunk name, as shown +in the dialplan example before. + +IP trunks can be used, but they require some additional configuration to work. + +For this example, let's say we have a SIP trunk called "mytrunk" that is going +to be used as line4. Furthermore, when calls come in on this trunk, they are +going to say that they are calling the number "12564286000". Also, let's say +that the numbers that are valid for calling out this trunk are NANP numbers, +of the form \_1NXXNXXXXXX. + +In sip.conf, there would be an entry for [mytrunk]. For [mytrunk], +set context=line4. + +\begin{astlisting} +\begin{verbatim} +[line4] +type=trunk +device=Local/disa@line4_outbound +\end{verbatim} +\end{astlisting} + +\begin{astlisting} +\begin{verbatim} +[line4] +exten => 12564286000,1,SLATrunk(line4) + +[line4_outbound] +exten => disa,1,Disa(no-password,line4_outbound) +exten => _1NXXNXXXXXX,1,Dial(SIP/${EXTEN}@mytrunk) +\end{verbatim} +\end{astlisting} + +So, when a station picks up their phone and connects to line 4, they are +connected to the local dialplan. The Disa application plays dialtone to the +phone and collects digits until it matches an extension. In this case, once +the phone dials a number like 12565551212, the call will proceed out the +SIP trunk. + +\subsection{Stations} + +An SLA station is a mapping between a virtual station and a real Asterisk device. +Currently, the only channel driver that has all of the features necessary to +support an SLA environment is chan\_sip. So, to configure a SIP phone to use +as a station, you must configure sla.conf and sip.conf. + +\begin{astlisting} +\begin{verbatim} +[station1] +type=station +device=SIP/station1 +trunk=line1 +trunk=line2 +\end{verbatim} +\end{astlisting} + +Here are some hints on configuring a SIP phone for use with SLA: + +\begin{enumerate} +\item Add the SIP channel as a [station] in sla.conf. + +\item Configure the phone in sip.conf. If automatic dialplan configuration was + used by enabling the "autocontext" option in sla.conf, then this entry in + sip.conf should have the same context setting. + +\item On the phone itself, there are various things that must be configured to + make everything work correctly: + + Let's say this phone is called "station1" in sla.conf, and it uses trunks + named "line1" and line2". + \begin{enumerate} + + \item Two line buttons must be configured to subscribe to the state of the + following extensions: + - station1\_line1 + - station1\_line2 + + \item The line appearance buttons should be configured to dial the extensions + that they are subscribed to when they are pressed. + + \item If you would like the phone to automatically connect to a trunk when it + is taken off hook, then the phone should be automatically configured to + dial "station1" when it is taken off hook. + + \end{enumerate} +\end{enumerate} + + +\section{Configuration Examples} +\subsection{Basic SLA} + +This is an example of the most basic SLA setup. It uses the automatic +dialplan generation so the configuration is minimal. + +sla.conf: +\begin{astlisting} +\begin{verbatim} +[line1] +type=trunk +device=Zap/1 +autocontext=line1 + +[line2] +type=trunk +device=Zap/2 +autocontext=line2 + +[station](!) +type=station +trunk=line1 +trunk=line2 +autocontext=sla_stations + +[station1](station) +device=SIP/station1 + +[station2](station) +device=SIP/station2 + +[station3](station) +device=SIP/station3 +\end{verbatim} +\end{astlisting} + +With this configuration, the dialplan is generated automatically. The first +zap channel should have its context set to "line1" and the second should be +set to "line2" in zapata.conf. In sip.conf, station1, station2, and station3 +should all have their context set to "sla\_stations". + +For reference, here is the automatically generated dialplan for this situation: +\begin{astlisting} +\begin{verbatim} +[line1] +exten => s,1,SLATrunk(line1) + +[line2] +exten => s,2,SLATrunk(line2) + +[sla_stations] +exten => station1,1,SLAStation(station1) +exten => station1_line1,hint,SLA:station1_line1 +exten => station1_line1,1,SLAStation(station1_line1) +exten => station1_line2,hint,SLA:station1_line2 +exten => station1_line2,1,SLAStation(station1_line2) + +exten => station2,1,SLAStation(station2) +exten => station2_line1,hint,SLA:station2_line1 +exten => station2_line1,1,SLAStation(station2_line1) +exten => station2_line2,hint,SLA:station2_line2 +exten => station2_line2,1,SLAStation(station2_line2) + +exten => station3,1,SLAStation(station3) +exten => station3_line1,hint,SLA:station3_line1 +exten => station3_line1,1,SLAStation(station3_line1) +exten => station3_line2,hint,SLA:station3_line2 +exten => station3_line2,1,SLAStation(station3_line2) +\end{verbatim} +\end{astlisting} + +\subsection{SLA and Voicemail} +\label{voicemail} + +This is an example of how you could set up a single voicemail box for the +phone system. The voicemail box number used in this example is 1234, which +would be configured in voicemail.conf. + +For this example, assume that there are 2 trunks and 3 stations. The trunks +are Zap/1 and Zap/2. The stations are SIP/station1, SIP/station2, and +SIP/station3. + +In zapata.conf, channel 1 has context=line1 and channel 2 has context=line2. + +In sip.conf, all three stations are configured with context=sla\_stations. + +When the stations pick up their phones to dial, they are allowed to dial +NANP numbers for outbound calls, or 8500 for checking voicemail. + + +sla.conf: +\begin{astlisting} +\begin{verbatim} +[line1] +type=trunk +device=Local/disa@line1_outbound + +[line2] +type=trunk +device=Local/disa@line2_outbound + +[station](!) +type=station +trunk=line1 +trunk=line2 + +[station1](station) +device=SIP/station1 + +[station2](station) +device=SIP/station2 + +[station3](station) +device=SIP/station3 + +\end{verbatim} +\end{astlisting} + +extensions.conf: +\begin{astlisting} +\begin{verbatim} +[macro-slaline] +exten => s,1,SLATrunk(${ARG1}) +exten => s,n,Goto(s-${SLATRUNK_STATUS},1) +exten => s-FAILURE,1,Voicemail(1234,u) +exten => s-UNANSWERED,1,Voicemail(1234,u) + +[line1] +exten => s,1,Macro(slaline,line1) + +[line2] +exten => s,2,Macro(slaline,line2) + +[line1_outbound] +exten => disa,1,Disa(no-password,line1_outbound) +exten => _1NXXNXXXXXX,1,Dial(Zap/1/${EXTEN}) +exten => 8500,1,VoicemailMain(1234) + +[line2_outbound] +exten => disa,1,Disa(no-password|line2_outbound) +exten => _1NXXNXXXXXX,1,Dial(Zap/2/${EXTEN}) +exten => 8500,1,VoicemailMain(1234) + +[sla_stations] + +exten => station1,1,SLAStation(station1) +exten => station1_line1,hint,SLA:station1_line1 +exten => station1_line1,1,SLAStation(station1_line1) +exten => station1_line2,hint,SLA:station1_line2 +exten => station1_line2,1,SLAStation(station1_line2) + +exten => station2,1,SLAStation(station2) +exten => station2_line1,hint,SLA:station2_line1 +exten => station2_line1,1,SLAStation(station2_line1) +exten => station2_line2,hint,SLA:station2_line2 +exten => station2_line2,1,SLAStation(station2_line2) + +exten => station3,1,SLAStation(station3) +exten => station3_line1,hint,SLA:station3_line1 +exten => station3_line1,1,SLAStation(station3_line1) +exten => station3_line2,hint,SLA:station3_line2 +exten => station3_line2,1,SLAStation(station3_line2) + +\end{verbatim} +\end{astlisting} + +\section{Call Handling} +\subsection{Summary} + +This section is intended to describe how Asterisk handles calls inside of the +SLA system so that it is clear what behavior is expected. + +\subsection{Station goes off hook (not ringing)} + +When a station goes off hook, it should initiate a call to Asterisk with the +extension that indicates that the phone went off hook without specifying a +specific line. In the examples in this document, for the station named +"station1", this extension is simply named, "station1". + +Asterisk will attempt to connect this station to the first available trunk +that is not in use. Asterisk will check the trunks in the order that they +were specified in the station entry in sla.conf. If all trunks are in use, +the call will be denied. + +If Asterisk is able to acquire an idle trunk for this station, then trunk +is connected to the station and the station will hear dialtone. The station +can then proceed to dial a number to call. As soon as a trunk is acquired, +all appearances of this line on stations will show that the line is in use. + +\subsection{Station goes off hook (ringing)} + +When a station goes off hook while it is ringing, it should simply answer +the call that had been initiated to it to make it ring. Once the station +has answered, Asterisk will figure out which trunk to connect it to. It +will connect it to the highest priority trunk that is currently ringing. +Trunk priority is determined by the order that the trunks are listed in +the station entry in sla.conf. + +\subsection{Line button on a station is pressed} + +When a line button is pressed on a station, the station should initiate a +call to Asterisk with the extension that indicates which line button was +pressed. In the examples given in this document, for a station named +"station1" and a trunk named "line1", the extension would be "station1\_line1". + +If the specified trunk is not in use, then the station will be connected to it and +will hear dialtone. All appearances of this trunk will then show that it +is now in use. + +If the specified trunk is on hold by this station, then this station will be +reconnected to the trunk. The line appearance for this trunk on this station +will now show in use. If this was the only station that had the call on hold, +then all appearances of this trunk will now show that it is in use. Otherwise, +all stations that are not currently connected to this trunk will show it +on hold. + +If the specified trunk is on hold by a different station, then this station +will be connected to the trunk only if the trunk itself and the station(s) that +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} |