diff options
| author | tilghman <tilghman@f38db490-d61c-443f-a65b-d21fe96a405b> | 2008-12-01 22:57:05 +0000 |
|---|---|---|
| committer | tilghman <tilghman@f38db490-d61c-443f-a65b-d21fe96a405b> | 2008-12-01 22:57:05 +0000 |
| commit | 8038604a3a40919f839b5241905ae67a3fe9a228 (patch) | |
| tree | 369a6c754208dc473bfcf48d8ff087de882d7295 /1.6.1/doc/tex | |
| parent | 5066802c18012df31ea69d1addad55c074ab38aa (diff) | |
| parent | 05f03ae252450919784d7188e1871417c0616a0a (diff) | |
Creating tag for the release of asterisk-1.6.1-beta3
git-svn-id: http://svn.digium.com/svn/asterisk/tags/1.6.1-beta3@160164 f38db490-d61c-443f-a65b-d21fe96a405b
Diffstat (limited to '1.6.1/doc/tex')
35 files changed, 0 insertions, 8025 deletions
diff --git a/1.6.1/doc/tex/Makefile b/1.6.1/doc/tex/Makefile deleted file mode 100644 index bdb29dd07..000000000 --- a/1.6.1/doc/tex/Makefile +++ /dev/null @@ -1,46 +0,0 @@ -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 -e 's/ASTERISKVERSION/$(shell echo $(ASTERISKVERSION) | sed -e 's/\//\\\//g')/' asterisk.tex > asterisk_local.tex - @mv asterisk_local.tex 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 -e 's/ASTERISKVERSION/$(ASTERISKVERSION)/' asterisk.tex > asterisk_local.tex - @mv asterisk_local.tex asterisk.tex - @latex2html asterisk.tex - @mv asterisk.tex.orig asterisk.tex - diff --git a/1.6.1/doc/tex/README.txt b/1.6.1/doc/tex/README.txt deleted file mode 100644 index 460d330a0..000000000 --- a/1.6.1/doc/tex/README.txt +++ /dev/null @@ -1,24 +0,0 @@ -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/1.6.1/doc/tex/ael.tex b/1.6.1/doc/tex/ael.tex deleted file mode 100644 index c483947d8..000000000 --- a/1.6.1/doc/tex/ael.tex +++ /dev/null @@ -1,1305 +0,0 @@ -\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 its 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 DAHDI -cards, or Voip phones, all indicate some context that should be -activated in their behalf. See the config file formats for IAX, SIP, -dahdi.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 (res\_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 res\_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=DAHDI/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/1.6.1/doc/tex/ajam.tex b/1.6.1/doc/tex/ajam.tex deleted file mode 100644 index 3421cc0ed..000000000 --- a/1.6.1/doc/tex/ajam.tex +++ /dev/null @@ -1,97 +0,0 @@ -\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/1.6.1/doc/tex/app-sms.tex b/1.6.1/doc/tex/app-sms.tex deleted file mode 100644 index d40d57aa1..000000000 --- a/1.6.1/doc/tex/app-sms.tex +++ /dev/null @@ -1,518 +0,0 @@ -\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 dahdi\_hfc, 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/1.6.1/doc/tex/asterisk-conf.tex b/1.6.1/doc/tex/asterisk-conf.tex deleted file mode 100644 index f39d4dc05..000000000 --- a/1.6.1/doc/tex/asterisk-conf.tex +++ /dev/null @@ -1,146 +0,0 @@ -\subsubsection{Asterisk Main Configuration File} - -Below is a sample of the main Asterisk configuration file, -asterisk.conf. Note that this file is not provided in -sample form, because the Makefile creates it when needed -and does not touch it when it already exists. - -\begin{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 - -; Entity ID. This is in the form of a MAC address. It should be universally -; unique. It must be unique between servers communicating with a protocol -; that uses this value. The only thing that uses this currently is DUNDi, -; but other things will use it in the future. -; entityid=00:11:22:33:44:55 - -[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/1.6.1/doc/tex/asterisk.tex b/1.6.1/doc/tex/asterisk.tex deleted file mode 100644 index 7bb217265..000000000 --- a/1.6.1/doc/tex/asterisk.tex +++ /dev/null @@ -1,155 +0,0 @@ -% To generate a PDF from this, install the "rubber" tool, and the LaTeX -% dependencies for it. Then, run: -% -% rubber asterisk.tex -% -% http://www.pps.jussieu.fr/~beffara/soft/rubber/ - -\documentclass[12pt,a4]{report} - -\usepackage{hyperref} - -\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 ASTERISKVERSION} - -\begin{document} -\maketitle - -\tableofcontents - -\chapter{Introduction} - -This document contains various pieces of information that are useful for -reference purposes. - - \section{License Information} - \input{../../LICENSE} - \subsection{Hold Music} - Digium has licensed the music included with - the Asterisk distribution From FreePlayMusic - for use and distribution with Asterisk. It - is licensed ONLY for use as hold music within - an Asterisk based PBX. - \section{Security} - \input{security.tex} - \section{Hardware} - \input{hardware.tex} - -\chapter{Configuration} - \section{General Configuration Information} - \subsection{Configuration Parser} - \input{configuration.tex} - \subsection{Asterisk.conf} - \input{asterisk-conf.tex} - \subsection{CLI Prompt} - \input{cliprompt.tex} - \subsection{Extensions} - \input{extensions.tex} - \subsection{IP 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) -% -% Note that there is some developer documentation in the doc directory, but -% the goal is to have developer documentation all integrated into the doxygen -% documentation. - -\end{document} diff --git a/1.6.1/doc/tex/backtrace.tex b/1.6.1/doc/tex/backtrace.tex deleted file mode 100644 index fd1c39d00..000000000 --- a/1.6.1/doc/tex/backtrace.tex +++ /dev/null @@ -1,217 +0,0 @@ -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 "DAHDI/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 "DAHDI/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 "DAHDI/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/1.6.1/doc/tex/billing.tex b/1.6.1/doc/tex/billing.tex deleted file mode 100644 index 9fae40be8..000000000 --- a/1.6.1/doc/tex/billing.tex +++ /dev/null @@ -1,86 +0,0 @@ -\section{Applications} - -\begin{itemize} - \item SetAccount - Set account code for billing - \item SetAMAFlags - Sets AMA flags - \item NoCDR - Make sure no CDR is saved for a specific call - \item ResetCDR - Reset CDR - \item ForkCDR - Save current CDR and start a new CDR for this call - \item Authenticate - Authenticates and sets the account code - \item SetCDRUserField - Set CDR user field - \item AppendCDRUserField - Append data to CDR User field -\end{itemize} - -For more information, use the "core show application $<$application$>$" command. -You can set default account codes and AMA flags for devices in -channel configuration files, like sip.conf, iax.conf etc. - -\section{Fields of the CDR in Asterisk} - -\begin{itemize} - \item accountcode: What account number to use, (string, 20 characters) - \item src: Caller*ID number (string, 80 characters) - \item dst: Destination extension (string, 80 characters) - \item dcontext: Destination context (string, 80 characters) - \item clid: Caller*ID with text (80 characters) - \item channel: Channel used (80 characters) - \item dstchannel: Destination channel if appropriate (80 characters) - \item lastapp: Last application if appropriate (80 characters) - \item lastdata: Last application data (arguments) (80 characters) - \item start: Start of call (date/time) - \item answer: Answer of call (date/time) - \item end: End of call (date/time) - \item duration: Total time in system, in seconds (integer), from dial to hangup - \item billsec: Total time call is up, in seconds (integer), from answer to hangup - \item disposition: What happened to the call: ANSWERED, NO ANSWER, BUSY - \item amaflags: What flags to use: DOCUMENTATION, BILL, IGNORE etc, - specified on a per channel basis like accountcode. - \item user field: A user-defined field, maximum 255 characters -\end{itemize} - -In some cases, uniqueid is appended: - -\begin{itemize} - \item uniqueid: Unique Channel Identifier (32 characters) - This needs to be enabled in the source code at compile time -\end{itemize} - -NOTE: If you use IAX2 channels for your calls, and allow 'full' transfers -(not media-only transfers), then when the calls is transferred the server -in the middle will no longer be involved in the signaling path, and thus -will not generate accurate CDRs for that call. If you can, use media-only -transfers with IAX2 to avoid this problem, or turn off transfers completely -(although this can result in a media latency increase since the media packets -have to traverse the middle server(s) in the call). - -\section{CDR Variables} - -If the channel has a cdr, that cdr record has its own set of variables which -can be accessed just like channel variables. The following builtin variables -are available. - -\begin{verbatim} -${CDR(clid)} Caller ID -${CDR(src)} Source -${CDR(dst)} Destination -${CDR(dcontext)} Destination context -${CDR(channel)} Channel name -${CDR(dstchannel)} Destination channel -${CDR(lastapp)} Last app executed -${CDR(lastdata)} Last app's arguments -${CDR(start)} Time the call started. -${CDR(answer)} Time the call was answered. -${CDR(end)} Time the call ended. -${CDR(duration)} Duration of the call. -${CDR(billsec)} Duration of the call once it was answered. -${CDR(disposition)} ANSWERED, NO ANSWER, BUSY -${CDR(amaflags)} DOCUMENTATION, BILL, IGNORE etc -${CDR(accountcode)} The channel's account code. -${CDR(uniqueid)} The channel's unique id. -${CDR(userfield)} The channels uses specified field. -\end{verbatim} - -In addition, you can set your own extra variables by using Set(CDR(name)=value). -These variables can be output into a text-format CDR by using the cdr\_custom -CDR driver; see the cdr\_custom.conf.sample file in the configs directory for -an example of how to do this. diff --git a/1.6.1/doc/tex/cdrdriver.tex b/1.6.1/doc/tex/cdrdriver.tex deleted file mode 100644 index 7865958c1..000000000 --- a/1.6.1/doc/tex/cdrdriver.tex +++ /dev/null @@ -1,459 +0,0 @@ -Call data records can be stored in many different databases or even CSV text. - -\section{MSSQL} - - Asterisk can currently store CDRs into an MSSQL database in - two different ways: cdr\_odbc or cdr\_tds - - Call Data Records can be stored using unixODBC (which requires - the FreeTDS package) [cdr\_odbc] or directly by using just the - FreeTDS package [cdr\_tds] The following provide some - examples known to get asterisk working with mssql. - - NOTE: Only choose one db connector. - -\subsection{ODBC using cdr\_odbc} - Compile, configure, and install the latest unixODBC package: -\begin{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 , - [userfield] [varchar] (256) 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/1.6.1/doc/tex/chaniax.tex b/1.6.1/doc/tex/chaniax.tex deleted file mode 100644 index 954e068b0..000000000 --- a/1.6.1/doc/tex/chaniax.tex +++ /dev/null @@ -1,84 +0,0 @@ -\subsection{Introduction} - -This section is intended as an introduction to the Inter-Asterisk -eXchange v2 (or simply IAX2) protocol. It provides both a theoretical -background and practical information on its use. - -\subsection{Why IAX2?} - -The first question most people are thinking at this point is "Why do you -need another VoIP protocol? Why didn't you just use SIP or H.323?" - -Well, the answer is a fairly complicated one, but in a nutshell it's like -this... Asterisk is intended as a very flexible and powerful -communications tool. As such, the primary feature we need from a VoIP -protocol is the ability to meet our own goals with Asterisk, and one with -enough flexibility that we could use it as a kind of laboratory for -inventing and implementing new concepts in the field. Neither H.323 or -SIP fit the roles we needed, so we developed our own protocol, which, -while not standards based, provides a number of advantages over both SIP -and H.323, some of which are: - -\begin{itemize} - \item Interoperability with NAT/PAT/Masquerade firewalls - \begin{itemize} - \item IAX seamlessly interoperates through all sorts of NAT and PAT - and other firewalls, including the ability to place and - receive calls, and transfer calls to other stations. - \end{itemize} - \item High performance, low overhead protocol - \begin{itemize} - \item When running on low-bandwidth connections, or when running - large numbers of calls, optimized bandwidth utilization is - imperative. IAX uses only 4 bytes of overhead - \end{itemize} - \item Internationalization support - \begin{itemize} - \item IAX transmits language information, so that remote PBX - content can be delivered in the native language of the - calling party. - \end{itemize} - \item Remote dialplan polling - \begin{itemize} - \item IAX allows a PBX or IP phone to poll the availability of a - number from a remote server. This allows PBX dialplans to - be centralized. - \end{itemize} - \item Flexible authentication - \begin{itemize} - \item IAX supports cleartext, md5, and RSA authentication, - providing flexible security models for outgoing calls and - registration services. - \end{itemize} - \item Multimedia protocol - \begin{itemize} - \item IAX supports the transmission of voice, video, images, text, - HTML, DTMF, and URL's. Voice menus can be presented in both - audibly and visually. - \end{itemize} - \item Call statistic gathering - \begin{itemize} - \item IAX gathers statistics about network performance (including - latency and jitter, as well as providing end-to-end latency - measurement. - \end{itemize} - \item Call parameter communication - \begin{itemize} - \item Caller*ID, requested extension, requested context, etc are - all communicated through the call. - \end{itemize} - \item Single socket design - \begin{itemize} - \item IAX's single socket design allows up to 32768 calls to be - multiplexed. - \end{itemize} -\end{itemize} - -While we value the importance of standards based (i.e. SIP) call handling, -hopefully this will provide a reasonable explanation of why we developed -IAX rather than starting with SIP. - -\subsection{Configuration} - -For examples of a configuration, please see the iax.conf.sample in -your the /configs directory of you source code distribution. diff --git a/1.6.1/doc/tex/channelvariables.tex b/1.6.1/doc/tex/channelvariables.tex deleted file mode 100644 index ae28818d3..000000000 --- a/1.6.1/doc/tex/channelvariables.tex +++ /dev/null @@ -1,1000 +0,0 @@ -\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. - - \item \verb!expr1 ~~ expr2! - - Concatenation operator. The two exprs are evaluated and - turned into strings, stripped of surrounding double quotes, - and are turned into a single string with no invtervening spaces. - This operator is new to trunk after 1.6.0; it is not needed - in existing extensions.conf code. Because of the way asterisk - evaluates ${ } and $[ ] constructs (recursively, bottom- - up), no $[] or ${} is ever present when the contents - of a ${} or $[] is evaluated. Thus, tokens are usually - already merged at evaluation time. But, in AEL, various - exprs are evaluated raw, and ${} and $[] are gathered - and treated as tokens. And in AEL, no two tokens can - sit side by side without an intervening operator. - So, in AEL, concatenation must be explicitly specified - in expressions. This new operator will play well into - future plans, where expressions ($[] constructs, and - variable references (${} constructs) are merged into a - single grammar. - -\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 -${BRIDGEPVTCALLID} Bridged peer PVT call ID (SIP Call ID if a SIP call) -${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 -${ENTITYID} * Global Entity ID set automatically, or from asterisk.conf -\end{verbatim} - -\subsection{Application return values} - -Many applications return the result in a variable that you read to -get the result of the application. These status fields are unique -for each application. -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) -${TOUCH_MONITOR_MESSAGE_START} Recorded file to play for both channels at start of monitoring session -${TOUCH_MONITOR_MESSAGE_STOP} Recorded file to play for both channels at end of monitoring session -${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 (DAHDI 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\_dahdi} -\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/1.6.1/doc/tex/cliprompt.tex b/1.6.1/doc/tex/cliprompt.tex deleted file mode 100644 index aaa2afb0e..000000000 --- a/1.6.1/doc/tex/cliprompt.tex +++ /dev/null @@ -1,29 +0,0 @@ -\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 \%u - Username - \item \%g - Groupname - \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 systems which implement getloadavg(3), 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 -\end{itemize} diff --git a/1.6.1/doc/tex/configuration.tex b/1.6.1/doc/tex/configuration.tex deleted file mode 100644 index 712b6b308..000000000 --- a/1.6.1/doc/tex/configuration.tex +++ /dev/null @@ -1,225 +0,0 @@ -\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, dahdi.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/1.6.1/doc/tex/dundi.tex b/1.6.1/doc/tex/dundi.tex deleted file mode 100644 index aa2fbb24c..000000000 --- a/1.6.1/doc/tex/dundi.tex +++ /dev/null @@ -1,41 +0,0 @@ -\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/1.6.1/doc/tex/enum.tex b/1.6.1/doc/tex/enum.tex deleted file mode 100644 index 9341a6ea1..000000000 --- a/1.6.1/doc/tex/enum.tex +++ /dev/null @@ -1,355 +0,0 @@ -\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(DAHDI/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(DAHDI/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 DAHDI 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 DAHDI") -exten => _X.,23,Dial(DAHDI/g1/${EXTEN}) -; -; end example 3 - -\end{verbatim} -\end{astlisting} diff --git a/1.6.1/doc/tex/extensions.tex b/1.6.1/doc/tex/extensions.tex deleted file mode 100644 index 7521616a1..000000000 --- a/1.6.1/doc/tex/extensions.tex +++ /dev/null @@ -1,82 +0,0 @@ -\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 -"dialplan 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/1.6.1/doc/tex/freetds.tex b/1.6.1/doc/tex/freetds.tex deleted file mode 100644 index 8db589f09..000000000 --- a/1.6.1/doc/tex/freetds.tex +++ /dev/null @@ -1,6 +0,0 @@ -The cdr\_tds module now works with most modern release versions of FreeTDS (from -at least 0.60 through 0.82). Although versions of FreeTDS prior to 0.82 will -work, we recommend using the latest available version for performance and -stability reasons. - -The latest release of FreeTDS is available from http://www.freetds.org/ diff --git a/1.6.1/doc/tex/hardware.tex b/1.6.1/doc/tex/hardware.tex deleted file mode 100644 index a678167de..000000000 --- a/1.6.1/doc/tex/hardware.tex +++ /dev/null @@ -1,100 +0,0 @@ -\subsection{Introduction} - -A PBX is only really useful if you can get calls into it. Of course, you -can use Asterisk with VoIP calls (SIP, H.323, IAX, etc.), but you can also -talk to the real PSTN through various cards. - -Supported Hardware is divided into two general groups: DAHDI devices and -non-DAHDI devices. The DAHDI compatible hardware supports pseudo-TDM -conferencing and all call features through chan\_dahdi, whereas non-DAHDI -compatible hardware may have different features. - -\subsection{DAHDI 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-DAHDI 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/1.6.1/doc/tex/ices.tex b/1.6.1/doc/tex/ices.tex deleted file mode 100644 index 39872be57..000000000 --- a/1.6.1/doc/tex/ices.tex +++ /dev/null @@ -1,7 +0,0 @@ -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/1.6.1/doc/tex/imapstorage.tex b/1.6.1/doc/tex/imapstorage.tex deleted file mode 100644 index 608a39fbb..000000000 --- a/1.6.1/doc/tex/imapstorage.tex +++ /dev/null @@ -1,210 +0,0 @@ -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 'c-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} - -Configure with ./configure --with-imap=/usr/src/imap -or where ever you built thfe UWashington IMAP Toolkit. This directory -will be searched for a source installation. If no source installation is -found there, then a package installation of the IMAP c-client will be -searched for in this directory. If one is not found, then configure will fail. - -A second configure option is to not specify a directory (i.e. -./configure --with-imap). This will assume that you have the -imap-2004g source installed in the .. directory relative to the -Asterisk source. If you do not have this source, then configure will -default to the "system" option defined in the next paragraph - -A third option is ./configure --with-imap=system. This will assume -that you have installed a dynamically linked version of the c-client -library (most likely via a package provided by your distro). This will -attempt to link agains -lc-client and will search for c-client headers -in your include path starting with the imap directory, and upon failure, -in the c-client directory. - -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/1.6.1/doc/tex/jitterbuffer.tex b/1.6.1/doc/tex/jitterbuffer.tex deleted file mode 100644 index a29cf811a..000000000 --- a/1.6.1/doc/tex/jitterbuffer.tex +++ /dev/null @@ -1,98 +0,0 @@ -\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/1.6.1/doc/tex/localchannel.tex b/1.6.1/doc/tex/localchannel.tex deleted file mode 100644 index 528421e0b..000000000 --- a/1.6.1/doc/tex/localchannel.tex +++ /dev/null @@ -1,80 +0,0 @@ -\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(DAHDI/1) -exten => 201,102,VoiceMail(${EXTEN}@default) - -exten => _0.,1,Dial(DAHDI/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/1.6.1/doc/tex/manager.tex b/1.6.1/doc/tex/manager.tex deleted file mode 100644 index 1f9fa1495..000000000 --- a/1.6.1/doc/tex/manager.tex +++ /dev/null @@ -1,258 +0,0 @@ -\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: DAHDI/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, DAHDI, 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/1.6.1/doc/tex/misdn.tex b/1.6.1/doc/tex/misdn.tex deleted file mode 100644 index 84dbb7aaa..000000000 --- a/1.6.1/doc/tex/misdn.tex +++ /dev/null @@ -1,272 +0,0 @@ -\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/1.6.1/doc/tex/mp3.tex b/1.6.1/doc/tex/mp3.tex deleted file mode 100644 index aeb02a0ea..000000000 --- a/1.6.1/doc/tex/mp3.tex +++ /dev/null @@ -1,11 +0,0 @@ -\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/1.6.1/doc/tex/odbcstorage.tex b/1.6.1/doc/tex/odbcstorage.tex deleted file mode 100644 index fed96e9d1..000000000 --- a/1.6.1/doc/tex/odbcstorage.tex +++ /dev/null @@ -1,31 +0,0 @@ - - -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/1.6.1/doc/tex/phoneprov.tex b/1.6.1/doc/tex/phoneprov.tex deleted file mode 100644 index cb236a89a..000000000 --- a/1.6.1/doc/tex/phoneprov.tex +++ /dev/null @@ -1,307 +0,0 @@ -\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/1.6.1/doc/tex/privacy.tex b/1.6.1/doc/tex/privacy.tex deleted file mode 100644 index a4ae7b94e..000000000 --- a/1.6.1/doc/tex/privacy.tex +++ /dev/null @@ -1,364 +0,0 @@ -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 next priority where you can -check the channelvariable PRIVACYMGRSTATUS. If the callerid was valid this -variable will have the value SUCCESS, otherwise it will have the value -FAILED. - -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. - -PrivacyManager can be told about a context where you can have patterns -that describe valid phone numbers. If none of the patterns match the -input, it will be considered a non-valid phonenumber and the user -can try again until the retry counter is reached. -This helps in resolving the issues stated in the previous paragraph. - -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,5,GotoIf($[ "${PRIVACYMGRSTATUS}" = "FAILED" ]?s,105) -exten => s,6,GotoIf($[ "${CALLERID(num)}" = "7773334444" & "${CALLERID(name)}" : "Privacy Manager" ]?callerid-liar,s,1:s,7) -exten => s,7,Dial(SIP/yourphone) -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 -\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(DAHDI/5r3&DAHDI/6r3,35,tmPA(beep)) - or -exten => 3,3,Dial(DAHDI/5r3&DAHDI/6r3,35,tmP(something)A(beep)) - or -exten => 3,3,Dial(DAHDI/5r3&DAHDI/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/1.6.1/doc/tex/qos.tex b/1.6.1/doc/tex/qos.tex deleted file mode 100644 index acbf7f443..000000000 --- a/1.6.1/doc/tex/qos.tex +++ /dev/null @@ -1,135 +0,0 @@ -\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/1.6.1/doc/tex/queuelog.tex b/1.6.1/doc/tex/queuelog.tex deleted file mode 100644 index 312ef7c5e..000000000 --- a/1.6.1/doc/tex/queuelog.tex +++ /dev/null @@ -1,118 +0,0 @@ -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$|$origposition)} - -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, as is the caller's entry position at the time of the transfer. -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/1.6.1/doc/tex/queues-with-callback-members.tex b/1.6.1/doc/tex/queues-with-callback-members.tex deleted file mode 100644 index 30051eecf..000000000 --- a/1.6.1/doc/tex/queues-with-callback-members.tex +++ /dev/null @@ -1,551 +0,0 @@ - -\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 DAHDI/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/1.6.1/doc/tex/realtime.tex b/1.6.1/doc/tex/realtime.tex deleted file mode 100644 index 26f937e87..000000000 --- a/1.6.1/doc/tex/realtime.tex +++ /dev/null @@ -1,141 +0,0 @@ -\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. - -You just have to always make sure the var\_metric values are properly set and -ordered as you expect in your database server if you're using the static mode -with ARA (either sequentially or with the same var\_metric value for everybody). - -If you have an option that depends on another one in a given configuration -file (i.e, 'musiconhold' depending on 'agent' from agents.conf) but their -var\_metric are not sequential you'll probably get default values being assigned for -those options instead of the desired ones. You can still use the same -var\_metric for all entries in your DB, just make sure the entries -are recorded in an order that does not break the option dependency. - -That doesn't happen when you use a static file in the file system. Although -this might be interpreted as a bug or limitation, it is not. - -\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/1.6.1/doc/tex/security.tex b/1.6.1/doc/tex/security.tex deleted file mode 100644 index 975f4bdde..000000000 --- a/1.6.1/doc/tex/security.tex +++ /dev/null @@ -1,80 +0,0 @@ -\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(DAHDI/g2/${EXTEN:1}) -include => local - -[local] -exten => _9NXXNXXX,1,Dial(DAHDI/g2/${EXTEN:1}) -include => default - -[default] -exten => 6123,Dial(DAHDI/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/1.6.1/doc/tex/sla.tex b/1.6.1/doc/tex/sla.tex deleted file mode 100644 index 844a4f2a7..000000000 --- a/1.6.1/doc/tex/sla.tex +++ /dev/null @@ -1,387 +0,0 @@ -%\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 dahdi.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 dahdi.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=DAHDI/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 dahdi.conf, sip.conf, etc. -Note that the automatic dialplan generation creates the SLATrunk() extension -at extension 's'. This is perfect for DAHDI 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=DAHDI/1 -autocontext=line1 - -[line2] -type=trunk -device=DAHDI/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 -DAHDI channel should have its context set to "line1" and the second should be -set to "line2" in dahdi.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 DAHDI/1 and DAHDI/2. The stations are SIP/station1, SIP/station2, and -SIP/station3. - -In dahdi.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(DAHDI/1/${EXTEN}) -exten => 8500,1,VoicemailMain(1234) - -[line2_outbound] -exten => disa,1,Disa(no-password|line2_outbound) -exten => _1NXXNXXXXXX,1,Dial(DAHDI/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} |