diff options
| author | russell <russell@f38db490-d61c-443f-a65b-d21fe96a405b> | 2007-10-15 13:12:51 +0000 |
|---|---|---|
| committer | russell <russell@f38db490-d61c-443f-a65b-d21fe96a405b> | 2007-10-15 13:12:51 +0000 |
| commit | f9c327b56545b226387601231f4864997172e0e3 (patch) | |
| tree | 10e1f9eaad925e0834d16a91560765b0c2259636 /doc/tex | |
| parent | 9940e48477e60733376232a897217c44858a8fb4 (diff) | |
Another major doc directory update from IgorG. This patch includes
- Many uses of the astlisting environment around verbatim text to ensure that
it gets properly formatted and doesn't run off the page.
- Update some things that have been deprecated.
- Add escaping as needed
- and more ...
(closes issue #10978)
Reported by: IgorG
Patches:
texdoc-85542-1.patch uploaded by IgorG (license 20)
git-svn-id: http://svn.digium.com/svn/asterisk/trunk@85547 f38db490-d61c-443f-a65b-d21fe96a405b
Diffstat (limited to 'doc/tex')
| -rw-r--r-- | doc/tex/ael.tex | 173 | ||||
| -rw-r--r-- | doc/tex/ajam.tex | 96 | ||||
| -rw-r--r-- | doc/tex/app-sms.tex | 33 | ||||
| -rw-r--r-- | doc/tex/billing.tex | 16 | ||||
| -rw-r--r-- | doc/tex/cdrdriver.tex | 136 | ||||
| -rw-r--r-- | doc/tex/channelvariables.tex | 120 | ||||
| -rw-r--r-- | doc/tex/cliprompt.tex | 37 | ||||
| -rw-r--r-- | doc/tex/configuration.tex | 51 | ||||
| -rw-r--r-- | doc/tex/dundi.tex | 8 | ||||
| -rw-r--r-- | doc/tex/extensions.tex | 6 | ||||
| -rw-r--r-- | doc/tex/imapstorage.tex | 51 | ||||
| -rw-r--r-- | doc/tex/jitterbuffer.tex | 68 | ||||
| -rw-r--r-- | doc/tex/localchannel.tex | 63 | ||||
| -rw-r--r-- | doc/tex/manager.tex | 39 | ||||
| -rw-r--r-- | doc/tex/misdn.tex | 62 | ||||
| -rw-r--r-- | doc/tex/privacy.tex | 22 | ||||
| -rw-r--r-- | doc/tex/queuelog.tex | 34 | ||||
| -rw-r--r-- | doc/tex/queues-with-callback-members.tex | 6 | ||||
| -rw-r--r-- | doc/tex/realtime.tex | 30 | ||||
| -rw-r--r-- | doc/tex/security.tex | 14 | ||||
| -rw-r--r-- | doc/tex/sla.tex | 33 |
21 files changed, 640 insertions, 458 deletions
diff --git a/doc/tex/ael.tex b/doc/tex/ael.tex index 76f3b385e..4d9fa2433 100644 --- a/doc/tex/ael.tex +++ b/doc/tex/ael.tex @@ -22,7 +22,7 @@ AEL is really the merger of 4 different 'languages', or syntaxes: 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 + 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. @@ -118,45 +118,47 @@ The AEL parser (pbx\_ael.so) is completely separate from the module that parses extensions.conf (pbx\_config.so). To use AEL, the only thing that has to be done is the module pbx\_ael.so must be loaded by Asterisk. This will be done automatically if using 'autoload=yes' in -/etc/asterisk/modules.conf. When the module is loaded, it will look -for 'extensions.ael' in /etc/asterisk/. extensions.conf and +\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. -Reloading extensions.ael - 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 + + *CLI$>$ ael debug contexts Enable AEL macros debug - *CLI> ael debug macros + + *CLI$>$ ael debug macros Enable AEL read debug - *CLI> ael debug read + + *CLI$>$ ael debug read Enable AEL tokens debug - *CLI> ael debug tokens + + *CLI$>$ ael debug tokens Disable AEL debug messages - *CLI> ael no debug + + *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 /var/log/asterisk. (from the checks done at load time). +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. @@ -177,7 +179,7 @@ aelparse has two optional arguments: \item -d \begin{itemize} \item Override the normal location of the config file dir, (usually - /etc/asterisk), and use the current directory instead as the + \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. @@ -200,12 +202,13 @@ 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) { @@ -218,9 +221,11 @@ else goto s,12; } \end{verbatim} +\end{astlisting} or: +\begin{astlisting} \begin{verbatim} if(${x}=1) { NoOp(hello!); @@ -230,9 +235,11 @@ if(${x}=1) { goto s,12; } \end{verbatim} +\end{astlisting} or: +\begin{astlisting} \begin{verbatim} if (${x}=1) { NoOp(hello!); goto s,3; @@ -240,6 +247,7 @@ if (${x}=1) { NoOp(Goodbye!); goto s,12; } \end{verbatim} +\end{astlisting} \section{Keywords} @@ -510,32 +518,33 @@ comments is after terminating semicolons, or on otherwise empty lines. 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); @@ -547,6 +556,7 @@ context default { _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 @@ -554,39 +564,45 @@ 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 @@ -599,6 +615,7 @@ as to have 7079953345 as their CallerID! Contexts can be included in other contexts. All included contexts are listed within a single block. +\begin{astlisting} \begin{verbatim} context default { includes { @@ -608,11 +625,13 @@ context default { } } \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 { @@ -622,14 +641,17 @@ context default { } } \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 @@ -637,7 +659,7 @@ 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 /etc/asterisk). +file (usually \path{/etc/asterisk}). @@ -647,6 +669,7 @@ 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 { @@ -658,20 +681,20 @@ context default { } } \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} @@ -680,16 +703,18 @@ just has to be specified with a value. Global variables are set in their own block. +\begin{astlisting} \begin{verbatim} globals { CONSOLE=Console/dsp; TRUNK=Zap/g2; } \end{verbatim} - +\end{astlisting} Variables can be set within extensions as well. +\begin{astlisting} \begin{verbatim} context foo { 555 => { @@ -700,6 +725,7 @@ context foo { } } \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 @@ -713,6 +739,7 @@ the if() test; the middle expression in the for( x; y; z) statement Writing to a dialplan function is treated the same as writing to a variable. +\begin{astlisting} \begin{verbatim} context blah { s => { @@ -721,9 +748,11 @@ context blah { } } \end{verbatim} +\end{astlisting} You can declare variables in Macros, as so: +\begin{astlisting} \begin{verbatim} Macro myroutine(firstarg, secondarg) { @@ -731,6 +760,7 @@ Macro myroutine(firstarg, secondarg) NoOp(Myvar is set to ${myvar}); } \end{verbatim} +\end{astlisting} \subsection{Local Variables} @@ -744,6 +774,7 @@ 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) { @@ -751,12 +782,13 @@ Macro myroutine(firstarg, secondarg) 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) { @@ -764,12 +796,12 @@ Macro myroutine(firstarg, secondarg) 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 => { @@ -786,8 +818,9 @@ context loops { } } \end{verbatim} +\end{astlisting} -NOTE: The conditional expression (the "\${y} $>$= 0" above) is wrapped in +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. @@ -801,6 +834,7 @@ braces around a single statement in the "true" branch of an if(), the random(), or an ifTime() statement. The if(), ifTime(), and random() statements allow optional else clause. +\begin{astlisting} \begin{verbatim} context conditional { _8XXX => { @@ -808,15 +842,15 @@ context conditional { if ("${DIALSTATUS}" = "BUSY") { NoOp(yessir); - Voicemail(${EXTEN}|b); + Voicemail(${EXTEN},b); } else - Voicemail(${EXTEN}|u); - ifTime (14:00-25:00|sat-sun|*|*) - Voicemail(${EXTEN}|b); + Voicemail(${EXTEN},u); + ifTime (14:00-25:00,sat-sun,*,*) + Voicemail(${EXTEN},b); else { - Voicemail(${EXTEN}|u); + Voicemail(${EXTEN},u); NoOp(hi, there!); } random(51) NoOp(This should appear 51% of the time); @@ -856,13 +890,14 @@ context conditional { } } \end{verbatim} +\end{astlisting} NOTE: The conditional expression in if() statements (the - "\${DIALSTATUS}" = "BUSY" above) is wrapped by the compiler in + "\$\{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. + 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 @@ -908,6 +943,7 @@ context, or macro, and can be used anywhere. This is an example of how to do a goto in AEL. +\begin{astlisting} \begin{verbatim} context gotoexample { s => { @@ -917,20 +953,21 @@ begin: goto begin; // go to label in same extension } 3 => { - goto s|begin; // go to label in different extension + goto s,begin; // go to label in different extension } 4 => { - goto gotoexample|s|begin; // overkill go to label in same context + 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 + 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 @@ -944,6 +981,7 @@ extension[,priority][@context] If priority is absent, it defaults to "1". If context is not present, it is assumed to be the same as that which contains the "jump". +\begin{astlisting} \begin{verbatim} context gotoexample { s => { @@ -967,25 +1005,20 @@ context gotoexample2 { } } \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; + 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 + 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. -NOTE: A NEW addition to AEL: you can now use ',' instead of '|' to - separate the items in the target address. You can't have a mix, - though, of '|' and ',' in the target. It's either one, or the other. - - - \subsection{Macros} @@ -994,15 +1027,16 @@ 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(b${ext}); + Voicemail(${ext},b); break; default: - Voicemail(u${ext}); + Voicemail(${ext},u); } catch a { @@ -1011,11 +1045,13 @@ macro std-exten( ext , dev ) { } } \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"); @@ -1024,10 +1060,12 @@ context example { _8XXX => &std-exten(,); } \end{verbatim} +\end{astlisting} \section{Examples} +\begin{astlisting} \begin{verbatim} context demo { s => { @@ -1045,34 +1083,35 @@ instructions: } 2 => { Background(demo-moreinfo); - goto s|instructions; + goto s,instructions; } 3 => { LANGUAGE()=fr; - goto s|restart; + goto s,restart; } 500 => { Playback(demo-abouttotry); Dial(IAX2/guest@misery.digium.com); Playback(demo-nogo); - goto s|instructions; + goto s,instructions; } 600 => { Playback(demo-echotest); Echo(); Playback(demo-echodone); - goto s|instructions; + goto s,instructions; } # => { hangup: Playback(demo-thanks); Hangup(); } - t => goto #|hangup; + t => goto #,hangup; i => Playback(invalid); } \end{verbatim} +\end{astlisting} \section{Semantic Checks} @@ -1128,7 +1167,7 @@ These checks will be: 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 /var/lib/asterisk/applist" on most systems). + 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. @@ -1137,9 +1176,9 @@ These checks will be: \section{Differences with the original version of AEL} \begin{enumerate} - \item The \$[...] expressions have been enhanced to include the ==, ||, + \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++ + =, $|$, 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 @@ -1161,19 +1200,19 @@ These checks will be: \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 /etc/asterisk/extensions.ael file, and shows the results of + 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 "/etc/asterisk/extensions.ael", using the original + 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 + \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 @@ -1216,15 +1255,15 @@ These checks will be: \section{Hints and Bugs} - The safest way to check for a null strings is to say \$[ "\${x}" = + The safest way to check for a null strings is to say \$[ "\$\{x\}" = "" ] The old way would do as shell scripts often do, and append - something on both sides, like this: \$[ \${x}foo = foo ]. The + something on both sides, like this: \$[ \$\{x\}foo = foo ]. The trouble with the old way, is that, if x contains any spaces, then problems occur, usually syntax errors. It is better practice and safer wrap all such tests with double quotes! Also, there are now some functions that can be used in a variable reference, ISNULL(), and LEN(), that can be used to test for an empty string: - \${ISNULL(\${x})} or \$[ \${LEN(\${x}) = 0 ]. + \$\{ISNULL(\$\{x\})\} or \$[ \$\{LEN(\$\{x\})\} = 0 ]. Assignment vs. Set(). Keep in mind that setting a variable to value can be done two different ways. If you choose say 'x=y;', @@ -1248,7 +1287,7 @@ available through AEL, via: \item Applications: See Asterisk - documentation of application commands - \item Functions: Functions were implemented inside \${ .. } variable + \item Functions: Functions were implemented inside \$\{ .. \} variable references, and supply many useful capabilities. \item Expressions: An expression evaluation engine handles items diff --git a/doc/tex/ajam.tex b/doc/tex/ajam.tex index b5e184931..3421cc0ed 100644 --- a/doc/tex/ajam.tex +++ b/doc/tex/ajam.tex @@ -1,85 +1,97 @@ \section{Asynchronous Javascript Asterisk Manger (AJAM)} -AJAM is a new technology which allows web browsers or other HTTP enabled -applications and web pages to directly access the Asterisk Manger -Interface (AMI) via HTTP. Setting up your server to process AJAM +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 /etc/asterisk/http.conf to enable +\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, +\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 +\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 + 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 /etc/asterisk/manager.conf +\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 +\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 "show http" at the Asterisk CLI. +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: - -http://localhost:8088/asterisk/manager?action=login\&username=foo\&secret=bar - -This logs you into the manager interface's "HTML" view. Once you're -logged in, Asterisk stores a cookie on your browser (valid for the -length of httptimeout) which is used to connect to the same session. - +\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 - -Assuming you've already logged into manager, this URI will give you a +\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 - -This will give you the same status view but represented as AJAX data, -theoretically compatible with RICO (http://www.openrico.org). - +\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 - -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 +\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 +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 +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/doc/tex/app-sms.tex b/doc/tex/app-sms.tex index a11de4a3b..aa515f61a 100644 --- a/doc/tex/app-sms.tex +++ b/doc/tex/app-sms.tex @@ -143,19 +143,21 @@ exten = _X.,3,Hangup UK this call is from a CLI of 080058752X0 where X is the sub address. As such a typical usage in the extensions.conf at the point of handling an incoming call is: - +\begin{astlisting} \begin{verbatim} exten = _X./8005875290,1,Goto(smsmtrx,${EXTEN},1) exten = _X./_80058752[0-8]0,1,Goto(smsmtrx,${EXTEN}-${CALLERID(num):8:1},1) \end{verbatim} +\end{astlisting} Alternatively, if you have the correct national prefix on incoming CLI, e.g. using zaphfc, you might use: - +\begin{astlisting} \begin{verbatim} exten = _X./08005875290,1,Goto(smsmtrx,${EXTEN},1) exten = _X./_080058752[0-8]0,1,Goto(smsmtrx,${EXTEN}-${CALLERID(num):9:1},1) \end{verbatim} +\end{astlisting} smsmorx is normally accessed by a call from a local sip device connected to a Magic Messenger. It could however by that you are @@ -164,11 +166,12 @@ exten = _X./_080058752[0-8]0,1,Goto(smsmtrx,${EXTEN}-${CALLERID(num):9:1},1) 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} @@ -181,7 +184,7 @@ exten = _1709400[0-8],1,Goto(smsmorx,${CALLERID(num)}-{EXTEN:7:1},1) 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 /var/spool/asterisk/outgoing + 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). @@ -191,10 +194,10 @@ exten = _1709400[0-8],1,Goto(smsmorx,${CALLERID(num)}-{EXTEN:7:1},1) connect to the message centre or device and actually send the pending message(s). - Using --process, smsq can however be used on received queues to run a + 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:- + smsq options: \begin{verbatim} --help Show help text @@ -341,14 +344,14 @@ exten = _1709400[0-8],1,Goto(smsmorx,${CALLERID(num)}-{EXTEN:7:1},1) Note that when smsq attempts to make a file in - /var/spool/asterisk/outgoing, it checks if there is already a call + \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 - --concurrent setting. If these files exist, then this means Asterisk + \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 --no-wait turns off this behaviour. Basically, + 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 @@ -361,7 +364,7 @@ exten = _1709400[0-8],1,Goto(smsmorx,${CALLERID(num)}-{EXTEN:7:1},1) 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 --no-dial is + 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. @@ -369,7 +372,7 @@ exten = _1709400[0-8],1,Goto(smsmorx,${CALLERID(num)}-{EXTEN:7:1},1) 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 --process option causes smsq to scan the specified queue (default + 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 @@ -404,10 +407,10 @@ exten = _1709400[0-8],1,Goto(smsmorx,${CALLERID(num)}-{EXTEN:7:1},1) \section{File formats} - By default all queues are held in a director /var/spool/asterisk/sms. + 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, - /var/log/asterisk/sms is a log file of all messages handled. + \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 @@ -424,7 +427,7 @@ exten = _1709400[0-8],1,Goto(smsmorx,${CALLERID(num)}-{EXTEN:7:1},1) 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:- + The keywords are as follows: \begin{verbatim} oa Originating address The phone number from which the message came @@ -450,7 +453,7 @@ exten = _1709400[0-8],1,Goto(smsmorx,${CALLERID(num)}-{EXTEN:7:1},1) Present on mobile originated messages, added by default if absent srr 0 or 1 for status report request - Does not work in UK yet, not implemented in app\_sms yet + Does not work in UK yet, not implemented in app_sms yet rp 0 or 1 return path See GSM specs for details diff --git a/doc/tex/billing.tex b/doc/tex/billing.tex index 82a90075e..9fae40be8 100644 --- a/doc/tex/billing.tex +++ b/doc/tex/billing.tex @@ -8,11 +8,11 @@ \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 + \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 +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} @@ -33,15 +33,15 @@ channel configuration files, like sip.conf, iax.conf etc. \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, + \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 + \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) + \item uniqueid: Unique Channel Identifier (32 characters) This needs to be enabled in the source code at compile time \end{itemize} @@ -55,13 +55,13 @@ 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 +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(src)} Source ${CDR(dst)} Destination ${CDR(dcontext)} Destination context ${CDR(channel)} Channel name diff --git a/doc/tex/cdrdriver.tex b/doc/tex/cdrdriver.tex index 35c39df97..174df5b68 100644 --- a/doc/tex/cdrdriver.tex +++ b/doc/tex/cdrdriver.tex @@ -14,6 +14,7 @@ Call data records can be stored in many different databases or even CSV text. \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 && @@ -21,8 +22,10 @@ Call data records can be stored in many different databases or even CSV text. 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 && @@ -30,20 +33,23 @@ Call data records can be stored in many different databases or even CSV text. --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] @@ -62,19 +68,23 @@ Call data records can be stored in many different databases or even CSV text. 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 + 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] @@ -83,9 +93,11 @@ Call data records can be stored in many different databases or even CSV text. 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 ( + CREATE TABLE cdr ( [calldate] [datetime] NOT NULL , [clid] [varchar] (80) NOT NULL , [src] [varchar] (80) NOT NULL , @@ -104,12 +116,14 @@ Call data records can be stored in many different databases or even CSV text. [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 && @@ -117,23 +131,29 @@ Call data records can be stored in many different databases or even CSV text. 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] @@ -144,7 +164,9 @@ Call data records can be stored in many different databases or even CSV text. 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 , @@ -166,6 +188,7 @@ Call data records can be stored in many different databases or even CSV text. [uniqueid] [varchar] (32) NULL ) \end{verbatim} +\end{astlisting} Start asterisk in verbose mode, you should see that asterisk logs a connection to the database and will now record every call to the database when it's complete. @@ -185,6 +208,7 @@ Using MySQL for CDR records is supported by using ODBC and the cdr\_odbc module. 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 @@ -196,8 +220,9 @@ Using MySQL for CDR records is supported by using ODBC and the cdr\_odbc module. 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 , @@ -218,6 +243,7 @@ Using MySQL for CDR records is supported by using ODBC and the cdr\_odbc module. userfield varchar (255) NOT NULL ); \end{verbatim} +\end{astlisting} \section{SQLLITE} @@ -278,46 +304,46 @@ SQLite version 2 is supported in cdr\_sqlite. 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 + 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 + 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"} + \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 + 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 + 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 + 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 + 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. + 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/} @@ -332,8 +358,8 @@ SQLite version 2 is supported in cdr\_sqlite. 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. + All the configuration files of FreeRADIUS server will be in + /usr/local/etc/raddb directory. \subsubsection{Configuration of the FreeRADIUS Server} @@ -343,9 +369,9 @@ SQLite version 2 is supported in cdr\_sqlite. 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 + 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. @@ -357,29 +383,29 @@ SQLite version 2 is supported in cdr\_sqlite. } \end{verbatim} - This fragment allows access from RADIUS clients on "myhost" if they use - "mysecret" as the shared secret. + 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 + 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 + 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. + 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} @@ -389,17 +415,17 @@ SQLite version 2 is supported in cdr\_sqlite. 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. + 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}. + 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. @@ -413,20 +439,20 @@ SQLite version 2 is supported in cdr\_sqlite. "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 + "Asterisk-Last-App", Last application run on the channel + "Asterisk-Last-Data", Argument to the last channel + "Asterisk-Start-Time", + "Asterisk-Answer-Time", + "Asterisk-End-Time", + "Asterisk-Duration", Duration is the whole length that the entire + call lasted. ie. call rx'd to hangup + "end time" minus "start time" + "Asterisk-Bill-Sec", The duration that a call was up after other + end answered which will be <= to duration + "end time" minus "answer time" + "Asterisk-Disposition", ANSWERED, NO ANSWER, BUSY + "Asterisk-AMA-Flags", DOCUMENTATION, BILL, IGNORE etc, specified on + a per channel basis like accountcode. + "Asterisk-Unique-ID", Unique call identifier + "Asterisk-User-Field" User field set via SetCDRUserField \end{verbatim} diff --git a/doc/tex/channelvariables.tex b/doc/tex/channelvariables.tex index 3bdfd9910..9d466e5cc 100644 --- a/doc/tex/channelvariables.tex +++ b/doc/tex/channelvariables.tex @@ -13,9 +13,11 @@ 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. @@ -36,29 +38,35 @@ 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} -You can substitute the value of a variable everywhere using \${variablename}. +\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 +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 +In fact, everything contained \$\{here\} is just replaced with the value of the variable "here". \section{Variable Inheritance} @@ -76,30 +84,33 @@ 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. - -However, - -NoOp(${__FOO}) is identical to NoOp(${FOO}) \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 @@ -109,33 +120,41 @@ 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} @@ -146,16 +165,20 @@ considered as an expression and it is evaluated. Evaluation works similar to 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. @@ -169,9 +192,11 @@ 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: @@ -195,7 +220,7 @@ 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. +with equal precedence are grouped within \{ \} symbols. \begin{itemize} \item \verb!expr1 | expr2! @@ -337,8 +362,7 @@ though! -- you still need to wrap variable names in curly braces! \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 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. @@ -436,7 +460,7 @@ TRUNC(-3.5) 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. +variable reference \$\{CALLERID(num)\}, for instance. \subsection{Numbers Vs. Strings} @@ -450,10 +474,11 @@ 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. @@ -463,18 +488,21 @@ 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} @@ -488,7 +516,7 @@ exten => s,6,GotoIf($[ "${CALLERID(num)}" = "3071234567" & & "${CALLERID(name) \end{verbatim} \end{astlisting} -You may see an error in /var/log/asterisk/messages like this: +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: @@ -508,11 +536,13 @@ 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. @@ -578,10 +608,10 @@ of possible concern with "legacy" extension.conf files: and the average regex expression is full of operators that the scanner will recognize as expression operators. Thus, unless the pattern is wrapped in double quotes, there will be trouble. - For instance, \${VAR1} : (Who|What*)+ + For instance, \$\{VAR1\} : (Who$|$What*)+ may have have worked before, but unless you wrap the pattern in double quotes now, look out for trouble! This is better: - "\${VAR1}" : "(Who|What*)+" + "\$\{VAR1\}" : "(Who$|$What*)+" and should work as previous. \item Variables and Double Quotes @@ -602,7 +632,7 @@ of possible concern with "legacy" extension.conf files: 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' +\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. @@ -615,23 +645,29 @@ 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: - -make check\_expr - +\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 @@ -645,33 +681,41 @@ 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 +The "simple-minded" variable substitution replaces \$\{varname\} variable references with '555'. You can override the 555 for variable values, by entering in var=val arguments after the filename on the command line. So... - - check\_expr /etc/asterisk/extensions.conf CALLERID(num)=3075551212 DIALSTATUS=TORTURE EXTEN=121 - -will substitute any \${CALLERIDNUM} variable references with -3075551212, any \${DIALSTATUS} variable references with 'TORTURE', and -any \${EXTEN} references with '121'. If there is any fancy stuff -going on in the reference, like \${EXTEN:2}, then the override will -not work. Everything in the \${...} has to match. So, to substitute -\${EXTEN:2} references, you'd best say: - - check\_expr /etc/asterisk/extensions.conf CALLERID(num)=3075551212 DIALSTATUS=TORTURE EXTEN:2=121 - +\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 diff --git a/doc/tex/cliprompt.tex b/doc/tex/cliprompt.tex index 6e7cf91b8..42e6b4bd1 100644 --- a/doc/tex/cliprompt.tex +++ b/doc/tex/cliprompt.tex @@ -6,25 +6,24 @@ you set from the Unix shell before starting Asterisk You may include the following variables, that will be replaced by the current value by Asterisk: -\begin{verbatim} -%d Date (year-month-date) -%s Asterisk system name (from asterisk.conf) -%h Full hostname -%H Short hostname -%t Time -%% Percent sign -%# '#' if Asterisk is run in console mode, '>' if running as remote console -%Cn[;n] Change terminal foreground (and optional background) color to specified -\end{verbatim} - -A full list of colors may be found in \path{include/asterisk/term.h} +\begin{itemize} + \item \%d - Date (year-month-date) + \item \%s - Asterisk system name (from asterisk.conf) + \item \%h - Full hostname + \item \%H - Short hostname + \item \%t - Time + \item \%\% - Percent sign + \item \%\# - '\#' if Asterisk is run in console mode, '$>$' if running as remote console + \item \%Cn[;n] - Change terminal foreground (and optional background) color to specified + A full list of colors may be found in \path{include/asterisk/term.h} +\end{itemize} On Linux systems, you may also use: -\begin{verbatim} -%l1 Load average over past minute -%l2 Load average over past 5 minutes -%l3 Load average over past 15 minutes -%l4 Process fraction (processes running / total processes) -%l5 The most recently allocated pid -\end{verbatim} +\begin{itemize} + \item \%l1 - Load average over past minute + \item \%l2 - Load average over past 5 minutes + \item \%l3 - Load average over past 15 minutes + \item \%l4 - Process fraction (processes running / total processes) + \item \%l5 - The most recently allocated pid +\end{itemize} diff --git a/doc/tex/configuration.tex b/doc/tex/configuration.tex index a501928bb..9257a86ba 100644 --- a/doc/tex/configuration.tex +++ b/doc/tex/configuration.tex @@ -7,20 +7,23 @@ 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. +all configuration files. \subsubsection{General syntax} Asterisk configuration files are defined as follows: +\begin{astlisting} \begin{verbatim} [section] label = value label2 = value \end{verbatim} +\end{astlisting} In some files, (e.g. mgcp.conf, zapata.conf and agents.conf), the syntax is a bit different. In these files the syntax is as follows: +\begin{astlisting} \begin{verbatim} [section] label1 = value1 @@ -31,17 +34,20 @@ is a bit different. In these files the syntax is as follows: 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 +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. @@ -53,52 +59,61 @@ No whitespace is allowed between the closing "]" and the parenthesis "(". All lines that starts with semi-colon ";" is treated as comments and is not parsed. -The ";--" is a marker for a multi-line comment. Everything after -that marker will be treated as a comment until the end-marker "--;" +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 + ;-- 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] + [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 @@ -107,29 +122,34 @@ 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 +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 +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 @@ -145,10 +165,12 @@ deny=192.168.1.1 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 +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 @@ -160,11 +182,13 @@ 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 @@ -176,9 +200,11 @@ allow=alaw #include accounts/*/sip.conf \end{verbatim} +\end{astlisting} -(in accounts/customer1/sip.conf) +(in \path{accounts/customer1/sip.conf}) +\begin{astlisting} \begin{verbatim} [def-customer1](!,defaults) secret=this_is_not_secret @@ -192,6 +218,7 @@ 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 diff --git a/doc/tex/dundi.tex b/doc/tex/dundi.tex index c61ddb051..aa2fbb24c 100644 --- a/doc/tex/dundi.tex +++ b/doc/tex/dundi.tex @@ -27,15 +27,15 @@ For more information visit \url{http://www.dundi.com} 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,Set(X=1) exten => 1,n,While($[${X} <= ${NUM}]) -exten => 1,n,NoOp(Result ${X} is ${DUNDIRESULT(${ID},${X})}) +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/doc/tex/extensions.tex b/doc/tex/extensions.tex index cb79926ce..262d14ecd 100644 --- a/doc/tex/extensions.tex +++ b/doc/tex/extensions.tex @@ -22,11 +22,11 @@ some modules which use explicitly GOTO's. Extensions frequently have data they pass to the executing application (most frequently a string). You can see the available dialplan applications -by entering the "show applications" command in the CLI. +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 "show functions" command. +functions in your Asterisk, use the "core show functions" command. \subsubsection{Example dialplan} @@ -63,7 +63,7 @@ There are some extensions with important meanings: \item T \begin{itemize} \item This is the extension that is executed when the 'absolute' - timeout is reached. See "show function TIMEOUT" for more + timeout is reached. See "core show function TIMEOUT" for more information on setting timeouts. \end{itemize} \item e diff --git a/doc/tex/imapstorage.tex b/doc/tex/imapstorage.tex index c95be2c6d..f3f4e626d 100644 --- a/doc/tex/imapstorage.tex +++ b/doc/tex/imapstorage.tex @@ -11,7 +11,7 @@ additional voicemail functionality, including: 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 + \item Deleting a voicemail recording email will also turn off the message waiting indicator, and delete the message from the voicemail system. \end{itemize} @@ -38,13 +38,16 @@ is outside the scope of this document. Building the c-client library is fairly straightforward; for example, on a Debian system there are two possibilities: -\begin{verbatim} -1) if you will not be using SSL to connect to the IMAP server: - $ make slx SSLTYPE=none - -2) if you will be using SSL to connect to the IMAP server: +\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{verbatim} +\end{enumerate} Once this completes you can proceed with the Asterisk build; there is no need to run 'make install'. @@ -66,7 +69,7 @@ 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> @@ -75,27 +78,29 @@ expungeonhangup=<yes or no> authuser=<username> authpassword=<password> \end{verbatim} +\end{astlisting} 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. +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 +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 +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. @@ -103,22 +108,22 @@ behavior of the current (file-based) voicemail system. 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. +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 +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 +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. +different set of features. \subsubsection{UW IMAP-2005 or earlier} @@ -134,23 +139,23 @@ 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. +if possible. \subsubsection{Cyrus IMAP} -Cyrus IMAP server v2.3.3 has been tested using a hierarchy delimiter of '/'. +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. +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 +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 diff --git a/doc/tex/jitterbuffer.tex b/doc/tex/jitterbuffer.tex index 59e1474cb..a29cf811a 100644 --- a/doc/tex/jitterbuffer.tex +++ b/doc/tex/jitterbuffer.tex @@ -1,30 +1,30 @@ \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 +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. +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. +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 +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 +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} @@ -33,25 +33,25 @@ 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 +do not enable both jitterbuffer and trunking for the involved peers/users in order to be able to communicate. Earlier systems will not support trunktimestamps. -You may also compile chan\_iax2.c without the new jitterbuffer, enabling the old +You may also compile chan\_iax2.c without the new jitterbuffer, enabling the old backwards compatible architecture. Look in the source code for instructions. \subsubsection{Testing and monitoring} -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 +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. +"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 +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: @@ -65,34 +65,34 @@ The stats shown are: \item Kpkts: The number of packets we've received / 1000. \end{itemize} -\subsubsection{Reporting problems} +\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 +\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 +\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 +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 +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 +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, +\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/doc/tex/localchannel.tex b/doc/tex/localchannel.tex index 896f3f1bb..6ada46da3 100644 --- a/doc/tex/localchannel.tex +++ b/doc/tex/localchannel.tex @@ -1,55 +1,55 @@ \subsection{Introduction} -chan\_local is a pseudo-channel. Use of this channel simply loops calls back +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] + 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, 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 +Adding "/n" at the end of the string will make the Local channel not do a +native transfer (the "n" stands for "n"o release) upon the remote end answering +the line. This is an esoteric, but important feature if you expect the Local +channel to handle calls exactly like a normal channel. If you do not have the +"no release" feature set, then as soon as the destination (inside of the Local +channel) answers the line, the variables and dial plan will revert back to that +of the original call, and the Local channel will become a zombie and be removed +from the active channels list. This is desirable in some circumstances, but can +result in unexpected dialplan behavior if you are doing fancy things with variables in your call handling. -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 +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 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 +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 +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 +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 @@ -60,18 +60,19 @@ exten => s,4,Hangup [internal] ; here where our phones falls for default exten => 200,1,Dial(sip/blah) exten => 200,102,VoiceMail(${EXTEN}@default) - + exten => 201,1,Dial(zap/1) exten => 201,102,VoiceMail(${EXTEN}@default) exten => _0.,1,Dial(Zap/g1/${EXTEN:1}) ; outgoing calls with 0+number \end{verbatim} +\end{astlisting} \subsection{Caveats} -If you use chan\_local from a call-file and you want to pass channel variables -into your context, make sure you append the '/n', because otherwise -chan\_local will 'optimize' itself out of the call-path, and the variables will +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} diff --git a/doc/tex/manager.tex b/doc/tex/manager.tex index 192587cda..c3b567bd4 100644 --- a/doc/tex/manager.tex +++ b/doc/tex/manager.tex @@ -15,9 +15,9 @@ 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 +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 @@ -40,16 +40,17 @@ 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. +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 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 + \item Event: An event reported by the Asterisk SERVER to the CLIENT \end{itemize} \section{Manager commands} @@ -107,7 +108,7 @@ Redirect with ExtraChannel: 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 +the mailing list archives and the documentation page on the \url{http://www.asterisk.org} web site for more information. @@ -117,7 +118,7 @@ the mailing list archives and the documentation page on the 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-IP: -- IPaddress Address-Port: -- IP port number Agent: <string> -- Agent name AMAflags: -- AMA flag (cdr_manager, sippeers) @@ -130,12 +131,12 @@ the mailing list archives and the documentation page on the 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" + 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" + Name or "<unknown>" or "unknown" (should change to "<unknown>" in app_queue) Callgroup: -- Call group for peer/user CallsTaken: <num> -- Queue status variable @@ -188,19 +189,19 @@ the mailing list archives and the documentation page on the 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 + 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) + Mix: <bool> -- Boolean parameter (monitor) NewMessages: <count> -- Count of new Mailbox messages (mailboxcount) - Newname: + Newname: ObjectName: -- Name of object in list OldName: -- Something in Rename (channel.c) - OldMessages: <count> -- Count of old mailbox messages (mailboxcount) + 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 + PeerStatus: <tech/name> -- Peer status code "Unregistered", "Registered", "Lagged", "Reachable" Penalty: <num> -- Queue penalty Priority: -- Extension priority @@ -218,8 +219,8 @@ the mailing list archives and the documentation page on the Reason: -- Originate reason code Seconds: -- Seconds (Status) Secret: <password> -- Authentication secret (for login) - SecretExist: <Y | N> -- Whether secret exists - Shutdown: -- "Uncleanly", "Cleanly" + SecretExist: <Y | N> -- Whether secret exists + Shutdown: -- "Uncleanly", "Cleanly" SIP-AuthInsecure: SIP-FromDomain: -- Peer FromDomain SIP-FromUser: -- Peer FromUser diff --git a/doc/tex/misdn.tex b/doc/tex/misdn.tex index 3aa34b722..84dbb7aaa 100644 --- a/doc/tex/misdn.tex +++ b/doc/tex/misdn.tex @@ -1,7 +1,7 @@ \subsection{Introduction} -This package contains the mISDN Channel Driver for the Asterisk PBX. It -supports every mISDN Hardware and provides an interface for asterisk. +This package contains the mISDN Channel Driver for the Asterisk PBX. It +supports every mISDN Hardware and provides an interface for asterisk. \subsection{Features} @@ -10,15 +10,15 @@ supports every mISDN Hardware and provides an interface for asterisk. \item PP and PMP mode \item BRI and PRI (with BNE1 and BN2E1 Cards) \item Hardware Bridging -\item DTMF Detection in HW+mISDNdsp +\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 EchoCancellation +\item Volume Control \item Crypting with mISDNdsp (Blowfish) -\item Data (HDLC) callthrough +\item Data (HDLC) callthrough \item Data Calling (with app\_ptyfork +pppd) \item Echo cancellation \item CallDeflection @@ -28,35 +28,35 @@ supports every mISDN Hardware and provides an interface for asterisk. \subsection{Fast Installation Guide} It is easy to install mISDN and mISDNuser. This can be done by: -\begin{itemize} +\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) + \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} - -Now you can compile chan\_misdn, just by making asterisk: - +\end{astlisting} +Now you can compile chan\_misdn, just by making asterisk: +\begin{astlisting} \begin{verbatim} -cd asterisk ; +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 @@ -69,7 +69,7 @@ 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 +You should use Kernels $>$= 2.6.9 \subsection{Configuration} @@ -77,12 +77,12 @@ You should use Kernels $>$= 2.6.9 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). @@ -122,6 +122,7 @@ send incoming calls to in the Asterisk dial plan (extension.conf). 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>] @@ -130,17 +131,18 @@ The Optionsstring looks Like: the ":" character is the delimiter. -The available Optchars are: +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, + 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: @@ -155,7 +157,7 @@ incoming channel. So if you like to use static encryption, the scenario looks as follows: \begin{verbatim} -Phone1 --> * Box 1 --> PSTN_TE +Phone1 --> * Box 1 --> PSTN_TE PSTN_TE --> * Box 2 --> Phone2 \end{verbatim} @@ -174,20 +176,21 @@ exten => ${CRYPT_MSN},2,dial(${PHONE2}) \subsection{mISDN CLI commands} -At the Asterisk cli you can try to type in: +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: +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, + -> display (sends a Text Message to a Asterisk channel, this channel must be an misdn channel) - set -> debug (sets debug level) @@ -198,11 +201,12 @@ Now you should see the misdn cli commands: -> stacks (shows the current ports, their protocols and states) -> fullstacks (shows the current active and inactive misdn channels) -- restart +- 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 @@ -217,10 +221,10 @@ msn (callerid) of the Phone to send the text to. \subsection{mISDN Variables} -mISDN Exports/Imports a few Variables: +mISDN Exports/Imports a few Variables: \begin{verbatim} -- MISDN_ADDRESS_COMPLETE : Is either set to 1 from the Provider, or you +- 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} @@ -243,6 +247,7 @@ provide all the information needed. 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 @@ -254,6 +259,7 @@ 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. diff --git a/doc/tex/privacy.tex b/doc/tex/privacy.tex index 25fc865ff..f8bf698f6 100644 --- a/doc/tex/privacy.tex +++ b/doc/tex/privacy.tex @@ -114,14 +114,16 @@ 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.) -603890zzzz hung up telemarket options. -"Integrated Sale" called a couple times. hung up in telemarket options -"UNITED STATES GOV" (-- maybe a military recruiter, trying to lure one of my sons). -800349zzzz -- hung up in charity intro -800349zzzz -- hung up in charity choices, intro, about the only one who actually travelled to the bitter bottom of the scripts! -216377zzzz -- hung up the magazine section -626757zzzz = "LIR " (pronounced "Liar"?) hung up in telemarket intro, then choices -757821zzzz -- hung up in new magazine subscription options. +\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 @@ -165,6 +167,7 @@ There are some variations, and these will be explained in due course. To use these options, set your Dial to something like: +\begin{astlisting} \begin{verbatim} exten => 3,3,Dial(Zap/5r3&Zap/6r3,35,tmPA(beep)) or @@ -172,6 +175,7 @@ exten => 3,3,Dial(Zap/5r3&Zap/6r3,35,tmP(something)A(beep)) or exten => 3,3,Dial(Zap/5r3&Zap/6r3,35,tmpA(beep)) \end{verbatim} +\end{astlisting} The 't' allows the dialed party to transfer the call using '\#'. It's optional. @@ -244,10 +248,12 @@ 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 diff --git a/doc/tex/queuelog.tex b/doc/tex/queuelog.tex index 0777b2b79..daf650a26 100644 --- a/doc/tex/queuelog.tex +++ b/doc/tex/queuelog.tex @@ -2,16 +2,16 @@ In order to properly manage ACD queues, it is important to be able to keep track of details of call setups and teardowns in much greater detail than traditional call detail records provide. In order to support this, extensive and detailed tracing of every queued call is stored in the -queue log, located (by default) in /var/log/asterisk/queue\_log. +queue log, located (by default) in \path{/var/log/asterisk/queue_log}. These are the events (and associated information) in the queue log: -\textbf{ABANDON(position|origposition|waittime)} +\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, and the waittime is how long the call had been waiting in the queue at the time of disconnect. \textbf{AGENTDUMP} @@ -26,26 +26,26 @@ The agent logged in. The channel is recorded. The callback agent logged in. The login extension and context is recorded. -\textbf{AGENTLOGOFF(channel|logintime)} +\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)} +\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 +reason for the logoff if it was not a normal logoff (e.g., Autologoff, Chanunavail) -\textbf{COMPLETEAGENT(holdtime|calltime|origposition)} +\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)} +\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 @@ -56,7 +56,7 @@ origposition. The configuration has been reloaded (e.g. with asterisk -rx reload) -\textbf{CONNECT(holdtime|bridgedchanneluniqueid|ringtime)} +\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 @@ -65,27 +65,27 @@ 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)} +\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)} +\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 +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)} +\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)} +\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 @@ -103,10 +103,10 @@ member! \textbf{SYSCOMPAT} -A call was answered by an agent, but the call was dropped because the +A call was answered by an agent, but the call was dropped because the channels were not compatible. -\textbf{TRANSFER(extension|context|holdtime|calltime)} +\textbf{TRANSFER(extension$|$context$|$holdtime$|$calltime)} Caller was transferred to a different extension. Context and extension are recorded. The caller's hold time and the length of the call are both diff --git a/doc/tex/queues-with-callback-members.tex b/doc/tex/queues-with-callback-members.tex index 9454876cb..a5f94689d 100644 --- a/doc/tex/queues-with-callback-members.tex +++ b/doc/tex/queues-with-callback-members.tex @@ -471,7 +471,7 @@ context agents \end{verbatim} \end{astlisting} -In the above, the variables \${RAQUEL}, etc stand for +In the above, the variables \$\{RAQUEL\}, etc stand for actual devices to ring that person's phone (like Zap/37). @@ -513,7 +513,7 @@ macro callagent(device,exten) \end{verbatim} \end{astlisting} -In the callagent macro above, the \${exten} will +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 @@ -522,7 +522,7 @@ 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 +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. diff --git a/doc/tex/realtime.tex b/doc/tex/realtime.tex index 406cc98c6..6753d325a 100644 --- a/doc/tex/realtime.tex +++ b/doc/tex/realtime.tex @@ -1,19 +1,19 @@ \subsubsection{Introduction} -The Asterisk Realtime Architecture is a new set of drivers and +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. +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 +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 +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: @@ -22,7 +22,7 @@ Currently there are three realtime database drivers: \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 svn.digium.com + \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} @@ -30,7 +30,7 @@ Currently there are three realtime database drivers: The ARA realtime mode is used to dynamically load and update objects. This mode is used in the SIP and IAX2 channels, as well as in the voicemail -system. For SIP and IAX2 this is similar to the v1.0 MYSQL\_FRIENDS +system. For SIP and IAX2 this is similar to the v1.0 MYSQL\_FRIENDS functionality. With the ARA, we now support many more databases for dynamic configuration of phones. @@ -41,13 +41,13 @@ from a database. \subsubsection{Realtime SIP friends} -The SIP realtime objects are users and peers that are loaded in memory +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 +With caching, the device stays in memory for a specified time. More information about this is to be found in the sip.conf sample file. \subsubsection{Realtime H.323 friends} @@ -58,7 +58,7 @@ 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 +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 @@ -71,12 +71,12 @@ extension name or pattern matching. 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 +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 +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. @@ -101,14 +101,14 @@ 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 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 -docs/odbcstorage.tex (\ref{odbcstorage}). +Voicemail storage with the support of ODBC described in file +\path{docs/odbcstorage.tex} (\ref{odbcstorage}). \subsubsection{Limitations} diff --git a/doc/tex/security.tex b/doc/tex/security.tex index 188f42cab..4eb4e1095 100644 --- a/doc/tex/security.tex +++ b/doc/tex/security.tex @@ -1,11 +1,11 @@ \subsection{Introduction} -PLEASE READ THE FOLLOWING IMPORTANT SECURITY RELATED INFORMATION. +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 +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. @@ -37,7 +37,7 @@ 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. +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 @@ -46,12 +46,15 @@ stations within you network. In particular, never ever put outgoing toll services in the "default" context. To make things easier, you can include the "default" context within other private contexts by using: +\begin{astlisting} \begin{verbatim} include => default \end{verbatim} +\end{astlisting} in the appropriate section. A well designed PBX might look like this: +\begin{astlisting} \begin{verbatim} [longdistance] exten => _91NXXNXXXXXX,1,Dial(Zap/g2/${EXTEN:1}) @@ -64,13 +67,14 @@ include => default [default] exten => 6123,Dial(Zap/1) \end{verbatim} +\end{astlisting} DON'T FORGET TO TAKE THE DEMO CONTEXT OUT OF YOUR DEFAULT CONTEXT. There -isn't really a security reason, it just will keep people from wanting to +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 +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/doc/tex/sla.tex b/doc/tex/sla.tex index 35975407f..afafd2ae4 100644 --- a/doc/tex/sla.tex +++ b/doc/tex/sla.tex @@ -56,13 +56,14 @@ An SLA trunk is a mapping between a virtual trunk and a real Asterisk device. This device may be an analog FXO line, or something like a SIP trunk. A trunk must be configured in two places. First, configure the device itself in the channel specific configuration file such as zapata.conf or sip.conf. Once the -trunk is configured, then map it to an SLA trunk in sla.conf. - +trunk is configured, then map it to an SLA trunk in sla.conf. +\begin{astlisting} \begin{verbatim} [line1] type=trunk device=Zap/1 \end{verbatim} +\end{astlisting} Be sure to configure the trunk's context to be the same one that is set for the "autocontext" option in sla.conf if automatic dialplan configuration is used. @@ -84,26 +85,27 @@ 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], +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) +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 @@ -116,8 +118,9 @@ SIP trunk. 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. +as a station, you must configure sla.conf and sip.conf. +\begin{astlisting} \begin{verbatim} [station1] type=station @@ -125,6 +128,7 @@ device=SIP/station1 trunk=line1 trunk=line2 \end{verbatim} +\end{astlisting} Here are some hints on configuring a SIP phone for use with SLA: @@ -141,7 +145,7 @@ Here are some hints on configuring a SIP phone for use with SLA: 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 @@ -165,6 +169,7 @@ 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 @@ -190,8 +195,8 @@ device=SIP/station2 [station3](station) device=SIP/station3 - \end{verbatim} +\end{astlisting} With this configuration, the dialplan is generated automatically. The first zap channel should have its context set to "line1" and the second should be @@ -199,6 +204,7 @@ set to "line2" in zapata.conf. In sip.conf, station1, station2, and station3 should all have their context set to "sla\_stations". For reference, here is the automatically generated dialplan for this situation: +\begin{astlisting} \begin{verbatim} [line1] exten => s,1,SLATrunk(line1) @@ -225,7 +231,7 @@ 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} @@ -247,6 +253,7 @@ NANP numbers for outbound calls, or 8500 for checking voicemail. sla.conf: +\begin{astlisting} \begin{verbatim} [line1] type=trunk @@ -271,9 +278,10 @@ device=SIP/station2 device=SIP/station3 \end{verbatim} - +\end{astlisting} extensions.conf: +\begin{astlisting} \begin{verbatim} [macro-slaline] exten => s,1,SLATrunk(${ARG1}) @@ -318,6 +326,7 @@ exten => station3_line2,hint,SLA:station3_line2 exten => station3_line2,1,SLAStation(station3_line2) \end{verbatim} +\end{astlisting} \section{Call Handling} \subsection{Summary} |