kenmirrors/asterisk
1
0
Fork 0
mirror of https://github.com/asterisk/asterisk.git synced 2025-11-21 01:01:02 +00:00
Code Issues Packages Projects Releases Wiki Activity

* Move LaTeX docs into a tex/ subdirectory of the doc/ dir

Browse Source 
* Add a Makefile in doc/tex/ for generating PDF and HTML
* Add a README.txt file to doc/tex/ to document which tools are used and what
  web sites to visit for getting them.
* Update build_tools/prep_tarball to put the proper Asterisk version string
  in the automatically generated PDF for release tarballs


git-svn-id: https://origsvn.digium.com/svn/asterisk/trunk@72982 65c4cc65-6c06-0410-ace0-fbb531ad65f3
This commit is contained in:
Russell Bryant
2007-07-02 22:27:46 +00:00
parent 94b934c8f6
commit df1a340774
40 changed files with 64 additions and 21 deletions
Download Patch File Download Diff File Expand all files Collapse all files

35
doc/tex/Makefile Normal file
View File

@@ -0,0 +1,35 @@
include ../../makeopts
pdf: asterisk.pdf
asterisk.pdf: $(wildcard *.tex)
ifeq ($(findstring rubber,$(RUBBER)),)
@echo "**********************************************"
@echo "** You must install the \"rubber\" tool ***"
@echo "** to generate the Asterisk reference PDF. ***"
@echo "**********************************************"
else
@echo "**********************************************"
@echo "** The Asterisk reference PDF will now be ***"
@echo "** generated. When complete, it will be ***"
@echo "** located at asterisk.pdf. ***"
@echo "**********************************************"
@cp asterisk.tex asterisk.tex.orig
@sed -i -e 's/ASTERISKVERSION/$(ASTERISKVERSION)/' asterisk.tex
@$(RUBBER) --pdf asterisk.tex
@mv asterisk.tex.orig asterisk.tex
endif
html:
@echo "**********************************************"
@echo "** The Asterisk reference HTML will now be ***"
@echo "** generated. When complete, it will be ***"
@echo "** located in the asterisk/ directory. ***"
@echo "** Note that the latex2html tool is ***"
@echo "** required for this to work. ***"
@echo "**********************************************"
@cp asterisk.tex asterisk.tex.orig
@sed -i -e 's/ASTERISKVERSION/$(ASTERISKVERSION)/' asterisk.tex
@latex2html asterisk.tex
@mv asterisk.tex.orig asterisk.tex

24
doc/tex/README.txt Normal file
View File

@@ -0,0 +1,24 @@
Asterisk Reference Documentation
--------------------------------
1) To generate a PDF from this documentation, you will need the rubber tool,
and all of its dependencies. The web site for this tool is:
http://www.pps.jussieu.fr/~beffara/soft/rubber/
Then, once this tool is installed, running "make pdf" will generate
the PDF automatically using this tool. The result will be asterisk.pdf.
NOTE: After installing rubber, you will need to re-run the top level
configure script. It checks to see if rubber is installed, so that the
asterisk.pdf Makefile target can produce a useful error message when it is
not installed.
2) To generate HTML from this documentation, you will need the latex2html tool,
and all of its dependencies. The web site for this tool is:
http://www.latex2html.org/
Then, once this tool is installed, running "make html" will generate the
HTML documentation. The result will be an asterisk directory full of
HTML files.

1268
doc/tex/ael.tex Normal file
View File

File diff suppressed because it is too large Load Diff

85
doc/tex/ajam.tex Normal file
View File

@@ -0,0 +1,85 @@
\section{Asynchronous Javascript Asterisk Manger (AJAM)}
AJAM is a new technology which allows web browsers or other HTTP enabled
applications and web pages to directly access the Asterisk Manger
Interface (AMI) via HTTP. Setting up your server to process AJAM
involves a few steps:
\subsection{Setup the Asterisk HTTP server}
\begin{enumerate}
\item Uncomment the line "enabled=yes" in /etc/asterisk/http.conf to enable
Asterisk's builtin micro HTTP server.
\item If you want Asterisk to actually deliver simple HTML pages, CSS,
javascript, etc. you should uncomment "enablestatic=yes"
\item Adjust your "bindaddr" and "bindport" settings as appropriate for
your desired accessibility
\item Adjust your "prefix" if appropriate, which must be the beginning of
any URI on the server to match. The default is "asterisk" and the
rest of these instructions assume that value.
\end{enumerate}
\subsection{Allow Manager Access via HTTP}
\begin{enumerate}
\item Make sure you have both "enabled = yes" and "webenabled = yes" setup
in /etc/asterisk/manager.conf
\item You may also use "httptimeout" to set a default timeout for HTTP
connections.
\item Make sure you have a manager username/secret
\end{enumerate}
Once those configurations are complete you can reload or restart
Asterisk and you should be able to point your web browser to specific
URI's which will allow you to access various web functions. A complete
list can be found by typing "show http" 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.
http://localhost:8088/asterisk/rawman?action=status
Assuming you've already logged into manager, this URI will give you a
"raw" manager output for the "status" command.
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).
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
hangup calls. It's only tested in Firefox, but could probably be made
to run in other browsers as well.
A sample library (astman.js) is included to help ease the creation of
manager HTML interfaces.
Note that for the demo, there is no need for *any* external web server.
\subsection{Integration with other web servers}
Asterisk's micro HTTP server is *not* designed to replace a general
purpose web server and it is intentionally created to provide only the
minimal interfaces required. Even without the addition of an external
web server, one can use Asterisk's interfaces to implement screen pops
and similar tools pulling data from other web servers using iframes,
div's etc. If you want to integrate CGI's, databases, PHP, etc. you
will likely need to use a more traditional web server like Apache and
link in your Asterisk micro HTTP server with something like this:
ProxyPass /asterisk http://localhost:8088/asterisk

491
doc/tex/app-sms.tex Normal file
View File

@@ -0,0 +1,491 @@
\section{Introduction}
The SMS module for Asterisk was developed by Adrian Kennard, and is an
implementation of the ETSI specification for landline SMS, ETSI ES 201
912, which is available from www.etsi.org. Landline SMS is starting to
be available in various parts of Europe, and is available from BT in
the UK. However, Asterisk would allow gateways to be created in other
locations such as the US, and use of SMS capable phones such as the
Magic Messenger. SMS works using analogue or ISDN lines.
\section{Background}
Short Message Service (SMS), or texting is very popular between mobile
phones. A message can be sent between two phones, and normally
contains 160 characters. There are ways in which various types of data
can be encoded in a text message such as ring tones, and small
graphic, etc. Text messaging is being used for voting and
competitions, and also SPAM...
Sending a message involves the mobile phone contacting a message
centre (SMSC) and passing the message to it. The message centre then
contacts the destination mobile to deliver the message. The SMSC is
responsible for storing the message and trying to send it until the
destination mobile is available, or a timeout.
Landline SMS works in basically the same way. You would normally have
a suitable text capable landline phone, or a separate texting box such
as a Magic Messenger on your phone line. This sends a message to a
message centre your telco provides by making a normal call and sending
the data using 1200 Baud FSK signaling according to the ETSI spec. To
receive a message the message centre calls the line with a specific
calling number, and the text capable phone answers the call and
receives the data using 1200 Baud FSK signaling. This works
particularly well in the UK as the calling line identity is sent
before the first ring, so no phones in the house would ring when a
message arrives.
\section{Typical use with Asterisk}
Sending messages from an Asterisk box can be used for a variety of
reasons, including notification from any monitoring systems, email
subject lines, etc.
Receiving messages to an Asterisk box is typically used just to email
the messages to someone appropriate - we email and texts that are
received to our direct numbers to the appropriate person. Received
messages could also be used to control applications, manage
competitions, votes, post items to IRC, anything.
Using a terminal such as a magic messenger, an Asterisk box could ask
as a message centre sending messages to the terminal, which will beep
and pop up the message (and remember 100 or so messages in its
memory).
\section{Terminology}
\begin{itemize}
\item SMS -
Short Message Service
i.e. text messages
\item SMSC -
Short Message Service Centre
The system responsible for storing and forwarding messages
\item MO -
Mobile Originated
A message on its way from a mobile or landline device to the SMSC
\item MT -
Mobile Terminated
A message on its way from the SMSC to the mobile or landline device
\item RX -
Receive
A message coming in to the Asterisk box
\item TX -
Transmit
A message going out of the Asterisk box
\end{itemize}
\section{Sub address}
When sending a message to a landline, you simply send to the landline
number. In the UK, all of the mobile operators (bar one) understand
sending messages to landlines and pass the messages to the BTText
system for delivery to the landline.
The specification for landline SMS allows for the possibility of more
than one device on a single landline. These can be configured with Sub
addresses which are a single digit. To send a message to a specific
device the message is sent to the landline number with an extra digit
appended to the end. The telco can define a default sub address (9 in
the UK) which is used when the extra digit is not appended to the end.
When the call comes in, part of the calling line ID is the sub
address, so that only one device on the line answers the call and
receives the message.
Sub addresses also work for outgoing messages. Part of the number
called by the device to send a message is its sub address. Sending
from the default sub address (9 in the UK) means the message is
delivered with the sender being the normal landline number. Sending
from any other sub address makes the sender the landline number with
an extra digit on the end.
Using Asterisk, you can make use of the sub addresses for sending and
receiving messages. Using DDI (DID, i.e. multiple numbers on the line
on ISDN) you can also make use of many different numbers for SMS.
\section{extensions.conf}
The following contexts are recommended.
\begin{verbatim}
; Mobile Terminated, RX. This is used when an incoming call from the SMS arrive
s, with the queue (called number and sub address) in ${EXTEN}
; Running an app after receipt of the text allows the app to find all messages
in the queue and handle them, e.g. email them.
; The app may be something like smsq --process=somecommand --queue=${EXTEN}
to run a command for each received message
; See below for usage
[smsmtrx]
exten = _X.,1, SMS(${EXTEN}|a)
exten = _X.,2,System("someapptohandleincomingsms ${EXTEN}")
exten = _X.,3,Hangup
; Mobile originated, RX. This is receiving a message from a device, e.g. a Magi
c Messenger on a sip extension
; Running an app after receipt of the text allows the app to find all messages
in the queue and handle then, e.g. sending them to the public SMSC
; The app may be something like smsq --process=somecommand --queue=${EXTEN}
to run a command for each received message
; See below for example usage
[smsmorx]
exten = _X.,1, SMS(${EXTEN}|sa)
exten = _X.,2,System("someapptohandlelocalsms ${EXTEN}")
exten = _X.,3,Hangup
smsmtrx is normally accessed by an incoming call from the SMSC. In the
UK this call is from a CLI of 080058752X0 where X is the sub address.
As such a typical usage in the extensions.conf at the point of
handling an incoming call is:-
exten = _X./8005875290,1,Goto(smsmtrx,${EXTEN},1)
exten = _X./_80058752[0-8]0,1,Goto(smsmtrx,${EXTEN}-${CALLERIDNUM:8:1},1)
Alternatively, if you have the correct national prefix on incoming
CLI, e.g. using zaphfc, you might use:-
exten = _X./08005875290,1,Goto(smsmtrx,${EXTEN},1)
exten = _X./_080058752[0-8]0,1,Goto(smsmtrx,${EXTEN}-${CALLERIDNUM:9:1},1)
smsmorx is normally accessed by a call from a local sip device
connected to a Magic Messenger. It could however by that you are
operating Asterisk as a message centre for calls from outside. Either
way, you look at the called number and goto smsmorx. In the UK, the
SMSC number that would be dialed is 1709400X where X is the caller sub
address. As such typical usage in extension.config at the point of
handling a call from a sip phone is:-
exten = 17094009,1,Goto(smsmorx,${CALLERIDNUM},1)
exten = _1709400[0-8],1,Goto(smsmorx,${CALLERIDNUM}-{EXTEN:7:1},1)
\end{verbatim}
\section{Using smsq}
smsq is a simple helper application designed to make it easy to send
messages from a command line. it is intended to run on the Asterisk
box and have direct access to the queue directories for SMS and for
Asterisk.
In its simplest form you can send an SMS by a command such as
smsq 0123456789 This is a test to 0123456789
This would create a queue file for a mobile originated TX message in
queue 0 to send the text "This is a test to 0123456789" to 0123456789.
It would then place a file in the /var/spool/asterisk/outgoing
directory to initiate a call to 17094009 (the default message centre
in smsq) attached to application SMS with argument of the queue name
(0).
Normally smsq will queue a message ready to send, and will then create
a file in the Asterisk outgoing directory causing Asterisk to actually
connect to the message centre or device and actually send the pending
message(s).
Using --process, smsq can however be used on received queues to run a
command for each file (matching the queue if specified) with various
environment variables set based on the message (see below);
smsq options:-
\begin{verbatim}
--help
Show help text
--usage
Show usage
--queue
-q
Specify a specific queue
In no specified, messages are queued under queue "0"
--da
-d
Specify destination address
--oa
-o
Specify originating address
This also implies that we are generating a mobile terminated message
--ud
-m
Specify the actual message
--ud-file
-f
Specify a file to be read for the context of the message
A blank filename (e.g. --ud-file= on its own) means read stdin. Very
useful when using via ssh where command line parsing could mess up the
message.
--mt
-t
Mobile terminated message to be generated
--mo
Mobile originated message to be generated
Default
--tx
Transmit message
Default
--rx
-r
Generate a message in the receive queue
--UTF-8
Treat the file as UTF-8 encoded (default)
--UCS-1
Treat the file as raw 8 bit UCS-1 data, not UTF-8 encoded
--UCS-2
Treat the file as raw 16 bit bigendian USC-2 data
--process
Specific a command to process for each file in the queue
Implies --rx and --mt if not otherwise specified.
Sets environment variables for every possible variable, and also ud,
ud8 (USC-1 hex), and ud16 (USC-2 hex) for each call. Removes files.
--motx-channel
Specify the channel for motx calls
May contain X to use sub address based on queue name or may be full
number
Default is Local/1709400X
--motx-callerid
Specify the caller ID for motx calls
The default is the queue name without -X suffix
--motx-wait
Wait time for motx call
Default 10
--motx-delay
Retry time for motx call
Default 1
--motx-retries
Retries for motx call
Default 10
--mttx-channel
Specify the channel for mttx calls
Default is Local/ and the queue name without -X suffix
--mtttx-callerid
Specify the callerid for mttx calls
May include X to use sub address based on queue name or may be full
number
Default is 080058752X0
--mttx-wait
Wait time for mttx call
Default 10
--mttx-delay
Retry time for mttx call
Default 30
--mttx-retries
Retries for mttx call
Default 100
--default-sub-address
The default sub address assumed (e.g. for X in CLI and dialled numbers
as above) when none added (-X) to queue
Default 9
--no-dial
-x
Create queue, but do not dial to send message
--no-wait
Do not wait if a call appears to be in progress
This could have a small window where a message is queued but not
sent, so regular calls to smsq should be done to pick up any missed
messages
--concurrent
How many concurrent calls to allow (per queue), default 1
--mr
-n
Message reference
--pid
-p
Protocol ID
--dcs
Data coding scheme
--udh
Specific hex string of user data header specified (not including the
initial length byte)
May be a blank string to indicate header is included in the user data
already but user data header indication to be set.
--srr
Status report requested
--rp
Return path requested
--vp
Specify validity period (seconds)
--scts
Specify timestamp (YYYY-MM-DDTHH:MM:SS)
--spool-dir
Spool dir (in which sms and outgoing are found)
Default /var/spool/asterisk
Other arguments starting '-' or '--' are invalid and will cause an
error. Any trailing arguments are processed as follows:-
* If the message is mobile originating and no destination address
has been specified, then the first argument is assumed to be a
destination address
* If the message is mobile terminating and no destination address
has been specified, then the first argument is assumed to be the
queue name
* If there is no user data, or user data file specified, then any
following arguments are assumed to be the message, which are
concatenated.
* If no user data is specified, then no message is sent. However,
unless --no-dial is specified, smsq checks for pending messages
and generates an outgoing anyway
\end{verbatim}
Note that when smsq attempts to make a file in
/var/spool/asterisk/outgoing, it checks if there is already a call
queued for that queue. It will try several filenames, up to the
--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,
this means that if you have a lot of messages to send all at once,
Asterisk will not make unlimited concurrent calls to the same message
centre or device for the same queue. This is because it is generally
more efficient to make one call and send all of the messages one after
the other.
smsq can be used with no arguments, or with a queue name only, and it
will check for any pending messages and cause an outgoing if there are
any. It only sets up one outgoing call at a time based on the first
queued message it finds. A outgoing call will normally send all queued
messages for that queue. One way to use smsq would be to run with no
queue name (so any queue) every minute or every few seconds to send
pending message. This is not normally necessary unless --no-dial is
selected. Note that smsq does only check motx or mttx depending on the
options selected, so it would need to be called twice as a general
check.
UTF-8 is used to parse command line arguments for user data, and is
the default when reading a file. If an invalid UTF-8 sequence is
found, it is treated as UCS-1 data (i.e, as is).
The --process option causes smsq to scan the specified queue (default
is mtrx) for messages (matching the queue specified, or any if queue
not specified) and run a command and delete the file. The command is
run with a number of environment variables set as follows. Note that
these are unset if not needed and not just taken from the calling
environment. This allows simple processing of incoming messages
\begin{verbatim}
$queue
Set if a queue specified
$?srr
srr is set (to blank) if srr defined and has value 1.
$?rp
rp is set (to blank) if rp defined and has value 1.
$ud
User data, UTF-8 encoding, including any control characters, but with
nulls stripped out
Useful for the content of emails, for example, as it includes any
newlines, etc.
$ude
User data, escaped UTF-8, including all characters, but control
characters \n, \r, \t, \f, \xxx and \ is escaped as \\
Useful guaranteed one line printable text, so useful in Subject lines
of emails, etc
$ud8
Hex UCS-1 coding of user data (2 hex digits per character)
Present only if all user data is in range U+0000 to U+00FF
$ud16
Hex UCS-2 coding of user data (4 hex digits per character)
other
Other fields set using their field name, e.g. mr, pid, dcs, etc. udh
is a hex byte string
\end{verbatim}
\section{File formats}
By default all queues are held in a director /var/spool/asterisk/sms.
Within this directory are sub directories mtrx, mttx, morx, motx which
hold the received messages and the messages ready to send. Also,
/var/log/asterisk/sms is a log file of all messages handled.
The file name in each queue directory starts with the queue parameter
to SMS which is normally the CLI used for an outgoing message or the
called number on an incoming message, and may have -X (X being sub
address) appended. If no queue ID is known, then 0 is used by smsq by
default. After this is a dot, and then any text. Files are scanned for
matching queue ID and a dot at the start. This means temporary files
being created can be given a different name not starting with a queue
(we recommend a . on the start of the file name for temp files).
Files in these queues are in the form of a simple text file where each
line starts with a keyword and an = and then data. udh and ud have
options for hex encoding, see below.
UTF-8. The user data (ud) field is treated as being UTF-8 encoded
unless the DCS is specified indicating 8 bit format. If 8 bit format
is specified then the user data is sent as is.
The keywords are as follows:-
\begin{verbatim}
oa Originating address
The phone number from which the message came
Present on mobile terminated messages and is the CLI for morx messages
da
Destination Address
The phone number to which the message is sent
Present on mobile originated messages
scts
The service centre time stamp
Format YYYY-MM-DDTHH:MM:SS
Present on mobile terminated messages
pid
One byte decimal protocol ID
See GSM specs for more details
Normally 0 or absent
dcs
One byte decimal data coding scheme
If omitted, a sensible default is used (see below)
See GSM specs for more details
mr
One byte decimal message reference
Present on mobile originated messages, added by default if absent
srr
0 or 1 for status report request
Does not work in UK yet, not implemented in app\_sms yet
rp
0 or 1 return path
See GSM specs for details
vp
Validity period in seconds
Does not work in UK yet
udh
Hex string of user data header prepended to the SMS contents,
excluding initial length byte.
Consistent with ud, this is specified as udh# rather than udh=
If blank, this means that the udhi flag will be set but any user data
header must be in the ud field
ud
User data, may be text, or hex, see below
\end{verbatim}
udh is specified as as udh\# followed by hex (2 hex digits per byte).
If present, then the user data header indicator bit is set, and the
length plus the user data header is added to the start of the user
data, with padding if necessary (to septet boundary in 7 bit format).
User data can hold an USC character codes U+0000 to U+FFFF. Any other
characters are coded as U+FEFF
ud can be specified as ud= followed by UTF-8 encoded text if it
contains no control characters, i.e. only (U+0020 to U+FFFF). Any
invalid UTF-8 sequences are treated as is (U+0080-U+00FF).
ud can also be specified as ud\# followed by hex (2 hex digits per
byte) containing characters U+0000 to U+00FF only.
ud can also be specified as ud\#\# followed by hex (4 hex digits per
byte) containing UCS-2 characters.
When written by app\_sms (e.g. incoming messages), the file is written
with ud= if it can be (no control characters). If it cannot, the a
comment line ;ud= is used to show the user data for human readability
and ud\# or ud\#\# is used.
\section{Delivery reports}
The SMS specification allows for delivery reports. These are requested
using the srr bit. However, as these do not work in the UK yet they
are not fully implemented in this application. If anyone has a telco
that does implement these, please let me know. BT in the UK have a non
standard way to do this by starting the message with *0\#, and so this
application may have a UK specific bodge in the near future to handle
these.
\begin{verbatim}
The main changes that are proposed for delivery report handling are :-
* New queues for sent messages, one file for each destination
address and message reference.
* New field in message format, user reference, allowing applications
to tie up their original message with a report.
* Handling of the delivery confirmation/rejection and connecting to
the outgoing message - the received message file would then have
fields for the original outgoing message and user reference
allowing applications to handle confirmations better.
\end{verbatim}

582
doc/tex/ast_agi_commands.tex Normal file
View File

@@ -0,0 +1,582 @@
% This file is automatically generated by the "manager dump actiondocs" CLI command. Any manual edits will be lost.
\section{answer}
\subsection{Summary}
\begin{verbatim}
Answer channel
\end{verbatim}
\subsection{Usage}
\begin{verbatim}
Usage: ANSWER
Answers channel if not already in answer state. Returns -1 on
channel failure, or 0 if successful.
\end{verbatim}
\section{channel status}
\subsection{Summary}
\begin{verbatim}
Returns status of the connected channel
\end{verbatim}
\subsection{Usage}
\begin{verbatim}
Usage: CHANNEL STATUS [<channelname>]
Returns the status of the specified channel.
If no channel name is given the returns the status of the
current channel. Return values:
0 Channel is down and available
1 Channel is down, but reserved
2 Channel is off hook
3 Digits (or equivalent) have been dialed
4 Line is ringing
5 Remote end is ringing
6 Line is up
7 Line is busy
\end{verbatim}
\section{database del}
\subsection{Summary}
\begin{verbatim}
Removes database key/value
\end{verbatim}
\subsection{Usage}
\begin{verbatim}
Usage: DATABASE DEL <family> <key>
Deletes an entry in the Asterisk database for a
given family and key.
Returns 1 if successful, 0 otherwise.
\end{verbatim}
\section{database deltree}
\subsection{Summary}
\begin{verbatim}
Removes database keytree/value
\end{verbatim}
\subsection{Usage}
\begin{verbatim}
Usage: DATABASE DELTREE <family> [keytree]
Deletes a family or specific keytree within a family
in the Asterisk database.
Returns 1 if successful, 0 otherwise.
\end{verbatim}
\section{database get}
\subsection{Summary}
\begin{verbatim}
Gets database value
\end{verbatim}
\subsection{Usage}
\begin{verbatim}
Usage: DATABASE GET <family> <key>
Retrieves an entry in the Asterisk database for a
given family and key.
Returns 0 if <key> is not set. Returns 1 if <key>
is set and returns the variable in parentheses.
Example return code: 200 result=1 (testvariable)
\end{verbatim}
\section{database put}
\subsection{Summary}
\begin{verbatim}
Adds/updates database value
\end{verbatim}
\subsection{Usage}
\begin{verbatim}
Usage: DATABASE PUT <family> <key> <value>
Adds or updates an entry in the Asterisk database for a
given family, key, and value.
Returns 1 if successful, 0 otherwise.
\end{verbatim}
\section{exec}
\subsection{Summary}
\begin{verbatim}
Executes a given Application
\end{verbatim}
\subsection{Usage}
\begin{verbatim}
Usage: EXEC <application> <options>
Executes <application> with given <options>.
Returns whatever the application returns, or -2 on failure to find application
\end{verbatim}
\section{get data}
\subsection{Summary}
\begin{verbatim}
Prompts for DTMF on a channel
\end{verbatim}
\subsection{Usage}
\begin{verbatim}
Usage: GET DATA <file to be streamed> [timeout] [max digits]
Stream the given file, and recieve DTMF data. Returns the digits received
from the channel at the other end.
\end{verbatim}
\section{get full variable}
\subsection{Summary}
\begin{verbatim}
Evaluates a channel expression
\end{verbatim}
\subsection{Usage}
\begin{verbatim}
Usage: GET FULL VARIABLE <variablename> [<channel name>]
Returns 0 if <variablename> is not set or channel does not exist. Returns 1
if <variablename> is set and returns the variable in parenthesis. Understands
complex variable names and builtin variables, unlike GET VARIABLE.
example return code: 200 result=1 (testvariable)
\end{verbatim}
\section{get option}
\subsection{Summary}
\begin{verbatim}
Stream file, prompt for DTMF, with timeout
\end{verbatim}
\subsection{Usage}
\begin{verbatim}
Usage: GET OPTION <filename> <escape_digits> [timeout]
Behaves similar to STREAM FILE but used with a timeout option.
\end{verbatim}
\section{get variable}
\subsection{Summary}
\begin{verbatim}
Gets a channel variable
\end{verbatim}
\subsection{Usage}
\begin{verbatim}
Usage: GET VARIABLE <variablename>
Returns 0 if <variablename> is not set. Returns 1 if <variablename>
is set and returns the variable in parentheses.
example return code: 200 result=1 (testvariable)
\end{verbatim}
\section{hangup}
\subsection{Summary}
\begin{verbatim}
Hangup the current channel
\end{verbatim}
\subsection{Usage}
\begin{verbatim}
Usage: HANGUP [<channelname>]
Hangs up the specified channel.
If no channel name is given, hangs up the current channel
\end{verbatim}
\section{noop}
\subsection{Summary}
\begin{verbatim}
Does nothing
\end{verbatim}
\subsection{Usage}
\begin{verbatim}
Usage: NoOp
Does nothing.
\end{verbatim}
\section{receive char}
\subsection{Summary}
\begin{verbatim}
Receives one character from channels supporting it
\end{verbatim}
\subsection{Usage}
\begin{verbatim}
Usage: RECEIVE CHAR <timeout>
Receives a character of text on a channel. Specify timeout to be the
maximum time to wait for input in milliseconds, or 0 for infinite. Most channels
do not support the reception of text. Returns the decimal value of the character
if one is received, or 0 if the channel does not support text reception. Returns
-1 only on error/hangup.
\end{verbatim}
\section{receive text}
\subsection{Summary}
\begin{verbatim}
Receives text from channels supporting it
\end{verbatim}
\subsection{Usage}
\begin{verbatim}
Usage: RECEIVE TEXT <timeout>
Receives a string of text on a channel. Specify timeout to be the
maximum time to wait for input in milliseconds, or 0 for infinite. Most channels
do not support the reception of text. Returns -1 for failure or 1 for success, and the string in parentheses.
\end{verbatim}
\section{record file}
\subsection{Summary}
\begin{verbatim}
Records to a given file
\end{verbatim}
\subsection{Usage}
\begin{verbatim}
Usage: RECORD FILE <filename> <format> <escape digits> <timeout> \
[offset samples] [BEEP] [s=silence]
Record to a file until a given dtmf digit in the sequence is received
Returns -1 on hangup or error. The format will specify what kind of file
will be recorded. The timeout is the maximum record time in milliseconds, or
-1 for no timeout. "Offset samples" is optional, and, if provided, will seek
to the offset without exceeding the end of the file. "silence" is the number
of seconds of silence allowed before the function returns despite the
lack of dtmf digits or reaching timeout. Silence value must be
preceeded by "s=" and is also optional.
\end{verbatim}
\section{say alpha}
\subsection{Summary}
\begin{verbatim}
Says a given character string
\end{verbatim}
\subsection{Usage}
\begin{verbatim}
Usage: SAY ALPHA <number> <escape digits>
Say a given character string, returning early if any of the given DTMF digits
are received on the channel. Returns 0 if playback completes without a digit
being pressed, or the ASCII numerical value of the digit if one was pressed or
-1 on error/hangup.
\end{verbatim}
\section{say digits}
\subsection{Summary}
\begin{verbatim}
Says a given digit string
\end{verbatim}
\subsection{Usage}
\begin{verbatim}
Usage: SAY DIGITS <number> <escape digits>
Say a given digit string, returning early if any of the given DTMF digits
are received on the channel. Returns 0 if playback completes without a digit
being pressed, or the ASCII numerical value of the digit if one was pressed or
-1 on error/hangup.
\end{verbatim}
\section{say number}
\subsection{Summary}
\begin{verbatim}
Says a given number
\end{verbatim}
\subsection{Usage}
\begin{verbatim}
Usage: SAY NUMBER <number> <escape digits> [gender]
Say a given number, returning early if any of the given DTMF digits
are received on the channel. Returns 0 if playback completes without a digit
being pressed, or the ASCII numerical value of the digit if one was pressed or
-1 on error/hangup.
\end{verbatim}
\section{say phonetic}
\subsection{Summary}
\begin{verbatim}
Says a given character string with phonetics
\end{verbatim}
\subsection{Usage}
\begin{verbatim}
Usage: SAY PHONETIC <string> <escape digits>
Say a given character string with phonetics, returning early if any of the
given DTMF digits are received on the channel. Returns 0 if playback
completes without a digit pressed, the ASCII numerical value of the digit
if one was pressed, or -1 on error/hangup.
\end{verbatim}
\section{say date}
\subsection{Summary}
\begin{verbatim}
Says a given date
\end{verbatim}
\subsection{Usage}
\begin{verbatim}
Usage: SAY DATE <date> <escape digits>
Say a given date, returning early if any of the given DTMF digits are
received on the channel. <date> is number of seconds elapsed since 00:00:00
on January 1, 1970, Coordinated Universal Time (UTC). Returns 0 if playback
completes without a digit being pressed, or the ASCII numerical value of the
digit if one was pressed or -1 on error/hangup.
\end{verbatim}
\section{say time}
\subsection{Summary}
\begin{verbatim}
Says a given time
\end{verbatim}
\subsection{Usage}
\begin{verbatim}
Usage: SAY TIME <time> <escape digits>
Say a given time, returning early if any of the given DTMF digits are
received on the channel. <time> is number of seconds elapsed since 00:00:00
on January 1, 1970, Coordinated Universal Time (UTC). Returns 0 if playback
completes without a digit being pressed, or the ASCII numerical value of the
digit if one was pressed or -1 on error/hangup.
\end{verbatim}
\section{say datetime}
\subsection{Summary}
\begin{verbatim}
Says a given time as specfied by the format given
\end{verbatim}
\subsection{Usage}
\begin{verbatim}
Usage: SAY DATETIME <time> <escape digits> [format] [timezone]
Say a given time, returning early if any of the given DTMF digits are
received on the channel. <time> is number of seconds elapsed since 00:00:00
on January 1, 1970, Coordinated Universal Time (UTC). [format] is the format
the time should be said in. See voicemail.conf (defaults to "ABdY
'digits/at' IMp"). Acceptable values for [timezone] can be found in
/usr/share/zoneinfo. Defaults to machine default. Returns 0 if playback
completes without a digit being pressed, or the ASCII numerical value of the
digit if one was pressed or -1 on error/hangup.
\end{verbatim}
\section{send image}
\subsection{Summary}
\begin{verbatim}
Sends images to channels supporting it
\end{verbatim}
\subsection{Usage}
\begin{verbatim}
Usage: SEND IMAGE <image>
Sends the given image on a channel. Most channels do not support the
transmission of images. Returns 0 if image is sent, or if the channel does not
support image transmission. Returns -1 only on error/hangup. Image names
should not include extensions.
\end{verbatim}
\section{send text}
\subsection{Summary}
\begin{verbatim}
Sends text to channels supporting it
\end{verbatim}
\subsection{Usage}
\begin{verbatim}
Usage: SEND TEXT "<text to send>"
Sends the given text on a channel. Most channels do not support the
transmission of text. Returns 0 if text is sent, or if the channel does not
support text transmission. Returns -1 only on error/hangup. Text
consisting of greater than one word should be placed in quotes since the
command only accepts a single argument.
\end{verbatim}
\section{set autohangup}
\subsection{Summary}
\begin{verbatim}
Autohangup channel in some time
\end{verbatim}
\subsection{Usage}
\begin{verbatim}
Usage: SET AUTOHANGUP <time>
Cause the channel to automatically hangup at <time> seconds in the
future. Of course it can be hungup before then as well. Setting to 0 will
cause the autohangup feature to be disabled on this channel.
\end{verbatim}
\section{set callerid}
\subsection{Summary}
\begin{verbatim}
Sets callerid for the current channel
\end{verbatim}
\subsection{Usage}
\begin{verbatim}
Usage: SET CALLERID <number>
Changes the callerid of the current channel.
\end{verbatim}
\section{set context}
\subsection{Summary}
\begin{verbatim}
Sets channel context
\end{verbatim}
\subsection{Usage}
\begin{verbatim}
Usage: SET CONTEXT <desired context>
Sets the context for continuation upon exiting the application.
\end{verbatim}
\section{set extension}
\subsection{Summary}
\begin{verbatim}
Changes channel extension
\end{verbatim}
\subsection{Usage}
\begin{verbatim}
Usage: SET EXTENSION <new extension>
Changes the extension for continuation upon exiting the application.
\end{verbatim}
\section{set music}
\subsection{Summary}
\begin{verbatim}
Enable/Disable Music on hold generator
\end{verbatim}
\subsection{Usage}
\begin{verbatim}
Usage: SET MUSIC ON <on|off> <class>
Enables/Disables the music on hold generator. If <class> is
not specified, then the default music on hold class will be used.
Always returns 0.
\end{verbatim}
\section{set priority}
\subsection{Summary}
\begin{verbatim}
Set channel dialplan priority
\end{verbatim}
\subsection{Usage}
\begin{verbatim}
Usage: SET PRIORITY <priority>
Changes the priority for continuation upon exiting the application.
The priority must be a valid priority or label.
\end{verbatim}
\section{set variable}
\subsection{Summary}
\begin{verbatim}
Sets a channel variable
\end{verbatim}
\subsection{Usage}
\begin{verbatim}
Usage: SET VARIABLE <variablename> <value>
\end{verbatim}
\section{stream file}
\subsection{Summary}
\begin{verbatim}
Sends audio file on channel
\end{verbatim}
\subsection{Usage}
\begin{verbatim}
Usage: STREAM FILE <filename> <escape digits> [sample offset]
Send the given file, allowing playback to be interrupted by the given
digits, if any. Use double quotes for the digits if you wish none to be
permitted. If sample offset is provided then the audio will seek to sample
offset before play starts. Returns 0 if playback completes without a digit
being pressed, or the ASCII numerical value of the digit if one was pressed,
or -1 on error or if the channel was disconnected. Remember, the file
extension must not be included in the filename.
\end{verbatim}
\section{control stream file}
\subsection{Summary}
\begin{verbatim}
Sends audio file on channel and allows the listner to control the stream
\end{verbatim}
\subsection{Usage}
\begin{verbatim}
Usage: CONTROL STREAM FILE <filename> <escape digits> [skipms] [ffchar] [rewchr] [pausechr]
Send the given file, allowing playback to be controled by the given
digits, if any. Use double quotes for the digits if you wish none to be
permitted. Returns 0 if playback completes without a digit
being pressed, or the ASCII numerical value of the digit if one was pressed,
or -1 on error or if the channel was disconnected. Remember, the file
extension must not be included in the filename.
Note: ffchar and rewchar default to * and # respectively.
\end{verbatim}
\section{tdd mode}
\subsection{Summary}
\begin{verbatim}
Toggles TDD mode (for the deaf)
\end{verbatim}
\subsection{Usage}
\begin{verbatim}
Usage: TDD MODE <on|off>
Enable/Disable TDD transmission/reception on a channel. Returns 1 if
successful, or 0 if channel is not TDD-capable.
\end{verbatim}
\section{verbose}
\subsection{Summary}
\begin{verbatim}
Logs a message to the asterisk verbose log
\end{verbatim}
\subsection{Usage}
\begin{verbatim}
Usage: VERBOSE <message> <level>
Sends <message> to the console via verbose message system.
<level> is the the verbose level (1-4)
Always returns 1.
\end{verbatim}
\section{wait for digit}
\subsection{Summary}
\begin{verbatim}
Waits for a digit to be pressed
\end{verbatim}
\subsection{Usage}
\begin{verbatim}
Usage: WAIT FOR DIGIT <timeout>
Waits up to 'timeout' milliseconds for channel to receive a DTMF digit.
Returns -1 on channel failure, 0 if no digit is received in the timeout, or
the numerical value of the ascii of the digit if one is received. Use -1
for the timeout value if you desire the call to block indefinitely.
\end{verbatim}

3276
doc/tex/ast_appdocs.tex Normal file
View File

File diff suppressed because it is too large Load Diff

3505
doc/tex/ast_cli_commands.tex Normal file
View File

File diff suppressed because it is too large Load Diff

1704
doc/tex/ast_funcdocs.tex Normal file
View File

File diff suppressed because it is too large Load Diff

1144
doc/tex/ast_manager_actiondocs.tex Normal file
View File

File diff suppressed because it is too large Load Diff

133
doc/tex/asterisk-conf.tex Normal file
View File

@@ -0,0 +1,133 @@
\subsubsection{Asterisk Main Configuration File}
Below is a sample of the main Asterisk configuration file,
asterisk.conf. Note that this file is not provided in
sample form, because the Makefile creates it when needed
and does not touch it when it already exists.
\begin{verbatim}
[directories]
; Make sure these directories have the right permissions if not
; running Asterisk as root
; Where the configuration files (except for this one) are located
astetcdir => /etc/asterisk
; Where the Asterisk loadable modules are located
astmoddir => /usr/lib/asterisk/modules
; Where additional 'library' elements (scripts, etc.) are located
astvarlibdir => /var/lib/asterisk
; Where AGI scripts/programs are located
astagidir => /var/lib/asterisk/agi-bin
; Where spool directories are located
; Voicemail, monitor, dictation and other apps will create files here
; and outgoing call files (used with pbx_spool) must be placed here
astspooldir => /var/spool/asterisk
; Where the Asterisk process ID (pid) file should be created
astrundir => /var/run/asterisk
; Where the Asterisk log files should be created
astlogdir => /var/log/asterisk
[options]
;Under "options" you can enter configuration options
;that you also can set with command line options
; Verbosity level for logging (-v)
verbose = 0
; Debug: "No" or value (1-4)
debug = 3
; Background execution disabled (-f)
nofork=yes | no
; Always background, even with -v or -d (-F)
alwaysfork=yes | no
; Console mode (-c)
console= yes | no
; Execute with high priority (-p)
highpriority = yes | no
; Initialize crypto at startup (-i)
initcrypto = yes | no
; Disable ANSI colors (-n)
nocolor = yes | no
; Dump core on failure (-g)
dumpcore = yes | no
; Run quietly (-q)
quiet = yes | no
; Force timestamping in CLI verbose output (-T)
timestamp = yes | no
; User to run asterisk as (-U) NOTE: will require changes to
; directory and device permissions
runuser = asterisk
; Group to run asterisk as (-G)
rungroup = asterisk
; Enable internal timing support (-I)
internal_timing = yes | no
; These options have no command line equivalent
; Cache record() files in another directory until completion
cache_record_files = yes | no
record_cache_dir = <dir>
; Build transcode paths via SLINEAR
transcode_via_sln = yes | no
; send SLINEAR silence while channel is being recorded
transmit_silence_during_record = yes | no
; The maximum load average we accept calls for
maxload = 1.0
; The maximum number of concurrent calls you want to allow
maxcalls = 255
; Stop accepting calls when free memory falls below this amount specified in MB
minmemfree = 256
; Allow #exec entries in configuration files
execincludes = yes | no
; Don't over-inform the Asterisk sysadm, he's a guru
dontwarn = yes | no
; System name. Used to prefix CDR uniqueid and to fill \${SYSTEMNAME}
systemname = <a_string>
; Should language code be last component of sound file name or first?
; when off, sound files are searched as <path>/<lang>/<file>
; when on, sound files are search as <lang>/<path>/<file>
; (only affects relative paths for sound files)
languageprefix = yes | no
[files]
; Changing the following lines may compromise your security
; Asterisk.ctl is the pipe that is used to connect the remote CLI
; (asterisk -r) to Asterisk. Changing these settings change the
; permissions and ownership of this file.
; The file is created when Asterisk starts, in the "astrundir" above.
;astctlpermissions = 0660
;astctlowner = root
;astctlgroup = asterisk
;astctl = asterisk.ctl
\end{verbatim}

154
doc/tex/asterisk.tex Normal file
View File

@@ -0,0 +1,154 @@
% To generate a PDF from this, install the "rubber" tool, and the LaTeX
% dependencies for it. Then, run:
%
% rubber asterisk.tex
%
% http://www.pps.jussieu.fr/~beffara/soft/rubber/
\documentclass[12pt,a4]{report}
\usepackage{hyperref}
\author{Asterisk Development Team \\ Asterisk.org}
\title{Asterisk Reference Information \\ Version SVN-trunk-r72921M}
\begin{document}
\maketitle
\tableofcontents
\chapter{Introduction}
This document contains various pieces of information that are useful for
reference purposes.
\section{License Information}
\input{../../LICENSE}
\subsection{Hold Music}
Digium has licensed the music included with
the Asterisk distribution From FreePlayMusic
for use and distribution with Asterisk. It
is licensed ONLY for use as hold music within
an Asterisk based PBX.
\section{Security}
\input{security.tex}
\section{Hardware}
\input{hardware.tex}
\chapter{Configuration}
\section{General Configuration Information}
\subsection{Configuration Parser}
\input{configuration.tex}
\subsection{Asterisk.conf}
\input{asterisk-conf.tex}
\subsection{CLI Prompt}
\input{cliprompt.tex}
\subsection{Extensions}
\input{extensions.tex}
\subsection{IP Quality of Service}
\input{qos.tex}
\subsection{MP3 Support}
\input{mp3.tex}
\subsection{ICES}
\input{ices.tex}
\section{Database Support}
\subsection{Realtime Database Configuration}
\input{realtime.tex}
\subsection{FreeTDS}
\input{freetds.tex}
\section{Privacy}
\input{privacy.tex}
\chapter{Channel Variables}
\input{channelvariables.tex}
\chapter{AEL, Asterisk Extension Language}
\input{ael.tex}
\chapter{SLA (Shared Line Appearances)}
\input{sla.tex}
\chapter{Channel Drivers}
\section{IAX2}
\input{chaniax.tex}
\subsection{IAX2 Jitterbuffer}
\input{jitterbuffer.tex}
\section{mISDN}
\input{misdn.tex}
\section{Local}
\input{localchannel.tex}
\chapter{Distributed Universal Number Discovery (DUNDi)}
\section{Introduction}
\input{dundi.tex}
\section{Peering Agreement}
\input{../PEERING}
\chapter{ENUM}
\input{enum.tex}
\chapter{AMI: Asterisk Manager Interface}
\input{manager.tex}
\input{ajam.tex}
\chapter{CDR: Call Detail Records}
\input{billing.tex}
\input{cdrdriver.tex}
\chapter{Voicemail}
\section{ODBC Storage}
\input{odbcstorage.tex}
\section{IMAP Storage}
\input{imapstorage.tex}
\chapter{SMS}
\input{app-sms.tex}
\chapter{Queues}
\input{queues-with-callback-members.tex}
\section{Queue Logs}
\input{queuelog.tex}
% Generate this using the "core dump clidocs" CLI command that is present
% when Asterisk is built with dev-mode enabled.
\chapter{CLI Command Reference}
\input{ast_cli_commands.tex}
% Generate this using the "core dump appdocs" CLI command that is present
% when Asterisk is built with dev-mode enabled.
\chapter{Dialplan Application Reference}
\input{ast_appdocs.tex}
% Generate this using the "core dump funcdocs" CLI command that is present
% when Asterisk is built with dev-mode enabled.
\chapter{Dialplan Function Reference}
\input{ast_funcdocs.tex}
% Generate this using the "manager dump actiondocs" CLI command that is present
% when Asterisk is built with dev-mode enabled.
\chapter{Manager Action Reference}
\input{ast_manager_actiondocs.tex}
% Generate this using the "agi dump commanddocs" CLI command that is present
% when Asterisk is built with dev-mode enabled.
\chapter{AGI Command Reference}
\input{ast_agi_commands.tex}
% This is a list of files not yet integrated into this document:
%
%Misc
%----
%asterisk-mib.txt SNMP mib for Asterisk (net-snmp)
%digium-mib.txt SNMP mib for Asterisk (net-snmp)
%
%For developers
%--------------
%See http://www.asterisk.org/developers for more information
%
%backtrace.txt How to produce a backtrace when Asterisk crashes
%CODING-GUIDELINES Guidelines for developers
%externalivr.txt Documentation of the protocol used in externalivr()
%modules.txt How Asterisk modules work
%datastores.txt About channel data stores
%speechrec.txt The Generic Speech Recognition API
\enddocument

87
doc/tex/billing.tex Normal file
View File

@@ -0,0 +1,87 @@
\section{Applications}
\begin{itemize}
\item SetAccount - Set account code for billing
\item SetAMAFlags - Sets AMA flags
\item NoCDR - Make sure no CDR is saved for a specific call
\item ResetCDR - Reset CDR
\item ForkCDR - Save current CDR and start a new CDR for this call
\item Authenticate - Authenticates and sets the account code
\item SetCDRUserField - Set CDR user field
\item AppendCDRUserField - Append data to CDR User field
\end{itemize}
For more information, use the "core show application <application>" command.
You can set default account codes and AMA flags for devices in
channel configuration files, like sip.conf, iax.conf etc.
\section{Fields of the CDR in Asterisk}
\begin{itemize}
\item accountcode: What account number to use, (string, 20 characters)
\item src: Caller*ID number (string, 80 characters)
\item dst: Destination extension (string, 80 characters)
\item dcontext: Destination context (string, 80 characters)
\item clid: Caller*ID with text (80 characters)
\item channel: Channel used (80 characters)
\item dstchannel: Destination channel if appropriate (80 characters)
\item lastapp: Last application if appropriate (80 characters)
\item lastdata: Last application data (arguments) (80 characters)
\item start: Start of call (date/time)
\item answer: Answer of call (date/time)
\item end: End of call (date/time)
\item duration: Total time in system, in seconds (integer), from dial to hangup
\item billsec: Total time call is up, in seconds (integer), from answer to hangup
\item disposition: What happened to the call: ANSWERED, NO ANSWER, BUSY
\item amaflags: What flags to use: DOCUMENTATION, BILL, IGNORE etc,
specified on a per channel basis like accountcode.
\item user field: A user-defined field, maximum 255 characters
\end{itemize}
In some cases, uniqueid is appended:
\begin{itemize}
\item uniqueid: Unique Channel Identifier (32 characters)
This needs to be enabled in the source code at compile time
\end{itemize}
NOTE: If you use IAX2 channels for your calls, and allow 'full' transfers
(not media-only transfers), then when the calls is transferred the server
in the middle will no longer be involved in the signaling path, and thus
will not generate accurate CDRs for that call. If you can, use media-only
transfers with IAX2 to avoid this problem, or turn off transfers completely
(although this can result in a media latency increase since the media packets
have to traverse the middle server(s) in the call).
\section{CDR Variables}
If the channel has a cdr, that cdr record has its own set of variables which
can be accessed just like channel variables. The following builtin variables
are available.
\begin{verbatim}
${CDR(clid)} Caller ID
${CDR(src)} Source
${CDR(dst)} Destination
${CDR(dcontext)} Destination context
${CDR(channel)} Channel name
${CDR(dstchannel)} Destination channel
${CDR(lastapp)} Last app executed
${CDR(lastdata)} Last app's arguments
${CDR(start)} Time the call started.
${CDR(answer)} Time the call was answered.
${CDR(end)} Time the call ended.
${CDR(duration)} Duration of the call.
${CDR(billsec)} Duration of the call once it was answered.
${CDR(disposition)} ANSWERED, NO ANSWER, BUSY
${CDR(amaflags)} DOCUMENTATION, BILL, IGNORE etc
${CDR(accountcode)} The channel's account code.
${CDR(uniqueid)} The channel's unique id.
${CDR(userfield)} The channels uses specified field.
\end{verbatim}
In addition, you can set your own extra variables by using Set(CDR(name)=value).
These variables can be output into a text-format CDR by using the cdr\_custom
CDR driver; see the cdr\_custom.conf.sample file in the configs directory for
an example of how to do this.

431
doc/tex/cdrdriver.tex Normal file
View File

@@ -0,0 +1,431 @@
Call data records can be stored in many different databases or even CSV text.
\section{MSSQL}
Asterisk can currently store CDRs into an MSSQL database in
two different ways: cdr\_odbc or cdr\_tds
Call Data Records can be stored using unixODBC (which requires
the FreeTDS package) [cdr\_odbc] or directly by using just the
FreeTDS package [cdr\_tds] The following provide some
examples known to get asterisk working with mssql.
NOTE: Only choose one db connector.
\subsection{ODBC using cdr\_odbc}
Compile, configure, and install the latest unixODBC package:
\begin{verbatim}
tar -zxvf unixODBC-2.2.9.tar.gz &&
cd unixODBC-2.2.9 &&
./configure --sysconfdir=/etc --prefix=/usr --disable-gui &&
make &&
make install
\end{verbatim}
Compile, configure, and install the latest FreeTDS package:
\begin{verbatim}
tar -zxvf freetds-0.62.4.tar.gz &&
cd freetds-0.62.4 &&
./configure --prefix=/usr --with-tdsver=7.0 \
--with-unixodbc=/usr/lib &&
make && make install
\end{verbatim}
Compile, or recompile, asterisk so that it will now add support
for cdr\_odbc.
\begin{verbatim}
make clean && ./configure --with-odbc &&
make update &&
make &&
make install
\end{verbatim}
Setup odbc configuration files. These are working examples
from my system. You will need to modify for your setup.
You are not required to store usernames or passwords here.
\begin{verbatim}
/etc/odbcinst.ini
[FreeTDS]
Description = FreeTDS ODBC driver for MSSQL
Driver = /usr/lib/libtdsodbc.so
Setup = /usr/lib/libtdsS.so
FileUsage = 1
/etc/odbc.ini
[MSSQL-asterisk]
description = Asterisk ODBC for MSSQL
driver = FreeTDS
server = 192.168.1.25
port = 1433
database = voipdb
tds_version = 7.0
language = us_english
\end{verbatim}
Only install one database connector. Do not confuse asterisk
by using both ODBC (cdr\_odbc) and FreeTDS (cdr\_tds).
This command will erase the contents of cdr\_tds.conf
\begin{verbatim}
[ -f /etc/asterisk/cdr_tds.conf ] > /etc/asterisk/cdr_tds.conf
\end{verbatim}
NOTE: unixODBC requires the freeTDS package, but asterisk does
not call freeTDS directly.
Now set up cdr\_odbc configuration files. These are working samples
from my system. You will need to modify for your setup. Define
your usernames and passwords here, secure file as well.
\begin{verbatim}
/etc/asterisk/cdr_odbc.conf
[global]
dsn=MSSQL-asterisk
username=voipdbuser
password=voipdbpass
loguniqueid=yes
\end{verbatim}
And finally, create the 'cdr' table in your mssql database.
\begin{verbatim}
CREATE TABLE cdr (
[calldate] [datetime] NOT NULL ,
[clid] [varchar] (80) NOT NULL ,
[src] [varchar] (80) NOT NULL ,
[dst] [varchar] (80) NOT NULL ,
[dcontext] [varchar] (80) NOT NULL ,
[channel] [varchar] (80) NOT NULL ,
[dstchannel] [varchar] (80) NOT NULL ,
[lastapp] [varchar] (80) NOT NULL ,
[lastdata] [varchar] (80) NOT NULL ,
[duration] [int] NOT NULL ,
[billsec] [int] NOT NULL ,
[disposition] [varchar] (45) NOT NULL ,
[amaflags] [int] NOT NULL ,
[accountcode] [varchar] (20) NOT NULL ,
[uniqueid] [varchar] (32) NOT NULL ,
[userfield] [varchar] (255) NOT NULL
)
\end{verbatim}
Start asterisk in verbose mode, you should see that asterisk
logs a connection to the database and will now record every
call to the database when it's complete.
\subsection{TDS, using cdr\_tds}
Compile, configure, and install the latest FreeTDS package:
\begin{verbatim}
tar -zxvf freetds-0.62.4.tar.gz &&
cd freetds-0.62.4 &&
./configure --prefix=/usr --with-tdsver=7.0
make &&
make install
\end{verbatim}
Compile, or recompile, asterisk so that it will now add support
for cdr\_tds.
\begin{verbatim}
make clean && ./configure --with-tds &&
make update &&
make &&
make install
\end{verbatim}
Only install one database connector. Do not confuse asterisk
by using both ODBC (cdr\_odbc) and FreeTDS (cdr\_tds).
This command will erase the contents of cdr\_odbc.conf
\begin{verbatim}
[ -f /etc/asterisk/cdr_odbc.conf ] > /etc/asterisk/cdr_odbc.conf
\end{verbatim}
Setup cdr\_tds configuration files. These are working samples
from my system. You will need to modify for your setup. Define
your usernames and passwords here, secure file as well.
\begin{verbatim}
/etc/asterisk/cdr_tds.conf
[global]
hostname=192.168.1.25
port=1433
dbname=voipdb
user=voipdbuser
password=voipdpass
charset=BIG5
\end{verbatim}
And finally, create the 'cdr' table in your mssql database.
\begin{verbatim}
CREATE TABLE cdr (
[accountcode] [varchar] (20) NULL ,
[src] [varchar] (80) NULL ,
[dst] [varchar] (80) NULL ,
[dcontext] [varchar] (80) NULL ,
[clid] [varchar] (80) NULL ,
[channel] [varchar] (80) NULL ,
[dstchannel] [varchar] (80) NULL ,
[lastapp] [varchar] (80) NULL ,
[lastdata] [varchar] (80) NULL ,
[start] [datetime] NULL ,
[answer] [datetime] NULL ,
[end] [datetime] NULL ,
[duration] [int] NULL ,
[billsec] [int] NULL ,
[disposition] [varchar] (20) NULL ,
[amaflags] [varchar] (16) NULL ,
[uniqueid] [varchar] (32) NULL
)
\end{verbatim}
Start asterisk in verbose mode, you should see that asterisk
logs a connection to the database and will now record every
call to the database when it's complete.
\section{MYSQL}
Using MySQL for CDR records is supported by using ODBC and the cdr\_odbc module.
\section{PGSQL}
If you want to go directly to postgresql database, and have the cdr\_pgsql.so
compiled you can use the following sample setup.
On Debian, before compiling asterisk, just install libpqxx-dev.
Other distros will likely have a similiar package.
Once you have the compile done,
copy the sample cdr\_pgsql.conf file or create your own.
Here is a sample:
\begin{verbatim}
/etc/asterisk/cdr_pgsql.conf
; Sample Asterisk config file for CDR logging to PostgresSQL
[global]
hostname=localhost
port=5432
dbname=asterisk
password=password
user=postgres
table=cdr
\end{verbatim}
Now create a table in postgresql for your cdrs
\begin{verbatim}
CREATE TABLE cdr (
calldate time NOT NULL ,
clid varchar (80) NOT NULL ,
src varchar (80) NOT NULL ,
dst varchar (80) NOT NULL ,
dcontext varchar (80) NOT NULL ,
channel varchar (80) NOT NULL ,
dstchannel varchar (80) NOT NULL ,
lastapp varchar (80) NOT NULL ,
lastdata varchar (80) NOT NULL ,
duration int NOT NULL ,
billsec int NOT NULL ,
disposition varchar (45) NOT NULL ,
amaflags int NOT NULL ,
accountcode varchar (20) NOT NULL ,
uniqueid varchar (32) NOT NULL ,
userfield varchar (255) NOT NULL
);
\end{verbatim}
\section{SQLLITE}
SQLite version 2 is supported in cdr\_sqlite.
\section{RADIUS}
\subsection{What is needed}
\begin{itemize}
\item FreeRADIUS server
\item Radiusclient-ng library
\item Asterisk PBX
\end{itemize}
\begin{verbatim}
+--------------------+
| Asterisk PBX |
| |
|********************|
| | +---------------+
| RADIUS client |------->| RADIUS server |
| |<-------| (FreeRADIUS) |
+--------------------+ +---------------+
\end{verbatim}
\subsection{Steps to follow in order to have RADIUS support}
\subsubsection{Installation of the Radiusclient library}
Installation:
\begin{verbatim}
Download the sources from:
http://developer.berlios.de/projects/radiusclient-ng/
Untar the source tarball.
root@localhost:/usr/local/src# tar xvfz radiusclient-ng-0.5.2.tar.gz
Compile and install the library.
root@localhost:/usr/local/src# cd radiusclient-ng-0.5.2
root@localhost:/usr/local/src/radiusclient-ng-0.5.2# ./configure
root@localhost:/usr/local/src/radiusclient-ng-0.5.2# make
root@localhost:/usr/local/src/radiusclient-ng-0.5.2# make install
\end{verbatim}
\subsubsection{Configuration of the Radiusclient library}
By default all the configuration files of the radiusclient library will
be in /usr/local/etc/radiusclient-ng directory.
File "radiusclient.conf"
Open the file and find lines containing the following:
authserver localhost
This is the hostname or IP address of the RADIUS server used for
authentication. You will have to change this unless the server is
running on the same host as your Asterisk PBX.
acctserver localhost
This is the hostname or IP address of the RADIUS server used for
accounting. You will have to change this unless the server is running
on the same host as your Asterisk PBX.
File "servers"
RADIUS protocol uses simple access control mechanism based on shared
secrets that allows RADIUS servers to limit access from RADIUS clients.
A RADIUS server is configured with a secret string and only RADIUS
clients that have the same secret will be accepted.
You need to configure a shared secret for each server you have
configured in radiusclient.conf file in the previous step. The shared
secrets are stored in /usr/local/etc/radiusclient-ng/servers file.
Each line contains hostname of a RADIUS server and shared secret
used in communication with that server. The two values are separated
by white spaces. Configure shared secrets for every RADIUS server you
are going to use.
File "dictionary"
Asterisk uses some attributes that are not included in the
dictionary of radiusclient library, therefore it is necessary to add
them. A file called dictionary.digium (kept in the contrib dir)
was created to list all new attributes used by Asterisk.
Add to the end of the main dictionary file
/usr/local/etc/radiusclient-ng/dictionary
the line:
\begin{verbatim}
\$INCLUDE /path/to/dictionary.digium
\end{verbatim}
\subsubsection{Install FreeRADIUS Server (Version 1.1.1)}
Download sources tarball from:
http://freeradius.org/
Untar, configure, build, and install the server:
\begin{verbatim}
root@localhost:/usr/local/src# tar xvfz freeradius-1.1.1.tar.gz
root@localhost:/usr/local/src# cd freeradius-1.1.1
root@localhost"/usr/local/src/freeradius-1.1.1# ./configure
root@localhost"/usr/local/src/freeradius-1.1.1# make
root@localhost"/usr/local/src/freeradius-1.1.1# make install
\end{verbatim}
All the configuration files of FreeRADIUS server will be in
/usr/local/etc/raddb directory.
\subsubsection{Configuration of the FreeRADIUS Server}
There are several files that have to be modified to configure the
RADIUS server. These are presented next.
File "clients.conf"
File /usr/local/etc/raddb/clients.conf contains description of
RADIUS clients that are allowed to use the server. For each of the
clients you need to specify its hostname or IP address and also a
shared secret. The shared secret must be the same string you configured
in radiusclient library.
Example:
\begin{verbatim}
client myhost {
secret = mysecret
shortname = foo
}
\end{verbatim}
This fragment allows access from RADIUS clients on "myhost" if they use
"mysecret" as the shared secret.
The file already contains an entry for localhost (127.0.0.1), so if you
are running the RADIUS server on the same host as your Asterisk server,
then modify the existing entry instead, replacing the default password.
File "dictionary"
Note : as of version 1.1.2, the dictionary.digium file ships with FreeRADIUS.
The following procedure brings the dictionary.digium file to previous versions
of FreeRADIUS.
File /usr/local/etc/raddb/dictionary contains the dictionary of
FreeRADIUS server. You have to add the same dictionary file
(dictionary.digium), which you added to the dictionary of radiusclient-ng
library. You can include it into the main file, adding the following line at the
end of file '/usr/local/etc/raddb/dictionary':
\$INCLUDE /path/to/dictionary.digium
That will include the same new attribute definitions that are used
in radiusclient-ng library so the client and server will understand each
other.
\subsubsection{Asterisk Accounting Configuration}
Compilation and installation:
The module will be compiled as long as the radiusclient-ng
library has been detected on your system.
By default FreeRADIUS server will log all accounting requests into
/usr/local/var/log/radius/radacct directory in form of plain text files.
The server will create one file for each hostname in the directory. The
following example shows how the log files look like.
Asterisk now generates Call Detail Records. See /include/asterisk/cdr.h
for all the fields which are recorded. By default, records in comma
separated values will be created in /var/log/asterisk/cdr-csv.
The configuration file for cdr\_radius.so module is :
/etc/asterisk/cdr.conf
This is where you can set CDR related parameters as well as the path to
the radiusclient-ng library configuration file.
\section{Logged Values}
\begin{verbatim}
"Asterisk-Acc-Code", The account name of detail records
"Asterisk-Src",
"Asterisk-Dst",
"Asterisk-Dst-Ctx", The destination context
"Asterisk-Clid",
"Asterisk-Chan", The channel
"Asterisk-Dst-Chan", (if applicable)
"Asterisk-Last-App", Last application run on the channel
"Asterisk-Last-Data", Argument to the last channel
"Asterisk-Start-Time",
"Asterisk-Answer-Time",
"Asterisk-End-Time",
"Asterisk-Duration", Duration is the whole length that the entire
call lasted. ie. call rx'd to hangup
"end time" minus "start time"
"Asterisk-Bill-Sec", The duration that a call was up after other
end answered which will be <= to duration
"end time" minus "answer time"
"Asterisk-Disposition", ANSWERED, NO ANSWER, BUSY
"Asterisk-AMA-Flags", DOCUMENTATION, BILL, IGNORE etc, specified on
a per channel basis like accountcode.
"Asterisk-Unique-ID", Unique call identifier
"Asterisk-User-Field" User field set via SetCDRUserField
\end{verbatim}

84
doc/tex/chaniax.tex Normal file
View File

@@ -0,0 +1,84 @@
\subsection{Introduction}
This section is intended as an introduction to the Inter-Asterisk
eXchange v2 (or simply IAX2) protocol. It provides both a theoretical
background and practical information on its use.
\subsection{Why IAX2?}
The first question most people are thinking at this point is "Why do you
need another VoIP protocol? Why didn't you just use SIP or H.323?"
Well, the answer is a fairly complicated one, but in a nutshell it's like
this... Asterisk is intended as a very flexible and powerful
communications tool. As such, the primary feature we need from a VoIP
protocol is the ability to meet our own goals with Asterisk, and one with
enough flexibility that we could use it as a kind of laboratory for
inventing and implementing new concepts in the field. Neither H.323 or
SIP fit the roles we needed, so we developed our own protocol, which,
while not standards based, provides a number of advantages over both SIP
and H.323, some of which are:
\begin{itemize}
\item Interoperability with NAT/PAT/Masquerade firewalls
\begin{itemize}
\item IAX seamlessly interoperates through all sorts of NAT and PAT
and other firewalls, including the ability to place and
receive calls, and transfer calls to other stations.
\end{itemize}
\item High performance, low overhead protocol
\begin{itemize}
\item When running on low-bandwidth connections, or when running
large numbers of calls, optimized bandwidth utilization is
imperative. IAX uses only 4 bytes of overhead
\end{itemize}
\item Internationalization support
\begin{itemize}
\item IAX transmits language information, so that remote PBX
content can be delivered in the native language of the
calling party.
\end{itemize}
\item Remote dialplan polling
\begin{itemize}
\item IAX allows a PBX or IP phone to poll the availability of a
number from a remote server. This allows PBX dialplans to
be centralized.
\end{itemize}
\item Flexible authentication
\begin{itemize}
\item IAX supports cleartext, md5, and RSA authentication,
providing flexible security models for outgoing calls and
registration services.
\end{itemize}
\item Multimedia protocol
\begin{itemize}
\item IAX supports the transmission of voice, video, images, text,
HTML, DTMF, and URL's. Voice menus can be presented in both
audibly and visually.
\end{itemize}
\item Call statistic gathering
\begin{itemize}
\item IAX gathers statistics about network performance (including
latency and jitter, as well as providing end-to-end latency
measurement.
\end{itemize}
\item Call parameter communication
\begin{itemize}
\item Caller*ID, requested extension, requested context, etc are
all communicated through the call.
\end{itemize}
\item Single socket design
\begin{itemize}
\item IAX's single socket design allows up to 32768 calls to be
multiplexed.
\end{itemize}
\end{itemize}
While we value the importance of standards based (i.e. SIP) call handling,
hopefully this will provide a reasonable explanation of why we developed
IAX rather than starting with SIP.
\subsection{Configuration}
For examples of a configuration, please see the iax.conf.sample in
your the /configs directory of you source code distribution.

791
doc/tex/channelvariables.tex Normal file
View File

@@ -0,0 +1,791 @@
\section{Introduction}
There are two levels of parameter evaluation done in the Asterisk
dial plan in extensions.conf.
\begin{enumerate}
\item The first, and most frequently used, is the substitution of variable
references with their values.
\item Then there are the evaluations of expressions done in \$[ .. ].
This will be discussed below.
\end{enumerate}
Asterisk has user-defined variables and standard variables set
by various modules in Asterisk. These standard variables are
listed at the end of this document.
\section{Parameter Quoting}
\begin{verbatim}
exten => s,5,BackGround,blabla
\end{verbatim}
The parameter (blabla) can be quoted ("blabla"). In this case, a
comma does not terminate the field. However, the double quotes
will be passed down to the Background command, in this example.
Also, characters special to variable substitution, expression evaluation, etc
(see below), can be quoted. For example, to literally use a \$ on the
string "\$1231", quote it with a preceding \\. Special characters that must
be quoted to be used, are [ ] \$ " \\. (to write \\ itself, use \\).
These Double quotes and escapes are evaluated at the level of the
asterisk config file parser.
Double quotes can also be used inside expressions, as discussed below.
\section{Variables}
Parameter strings can include variables. Variable names are arbitrary strings.
They are stored in the respective channel structure.
To set a variable to a particular value, do :
\begin{verbatim}
exten => 1,2,Set(varname=value)
\end{verbatim}
You can substitute the value of a variable everywhere using \${variablename}.
For example, to stringwise append \$lala to \$blabla and store result in \$koko,
do:
\begin{verbatim}
exten => 1,2,Set(koko=${blabla}${lala})
\end{verbatim}
There are two reference modes - reference by value and reference by name.
To refer to a variable with its name (as an argument to a function that
requires a variable), just write the name. To refer to the variable's value,
enclose it inside \${}. For example, Set takes as the first argument
(before the =) a variable name, so:
\begin{verbatim}
exten => 1,2,Set(koko=lala)
exten => 1,3,Set(${koko}=blabla)
\end{verbatim}
stores to the variable "koko" the value "lala" and to variable "lala" the
value "blabla".
In fact, everything contained \${here} is just replaced with the value of
the variable "here".
\section{Variable Inheritance}
Variable names which are prefixed by "\_" will be inherited to channels
that are created in the process of servicing the original channel in
which the variable was set. When the inheritance takes place, the
prefix will be removed in the channel inheriting the variable. If the
name is prefixed by "\_\_" in the channel, then the variable is
inherited and the "\_\_" will remain intact in the new channel.
In the dialplan, all references to these variables refer to the same
variable, regardless of having a prefix or not. Note that setting any
version of the variable removes any other version of the variable,
regardless of prefix.
\subsection{Example}
\begin{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}
\section{Selecting Characters from Variables}
The format for selecting characters from a variable can be expressed as:
\begin{verbatim}
${variable_name[:offset[:length]]}
\end{verbatim}
If you want to select the first N characters from the string assigned
to a variable, simply append a colon and the number of characters to
skip from the beginning of the string to the variable name.
\begin{verbatim}
;Remove the first character of extension, save in "number" variable
exten => _9X.,1,Set(number=${EXTEN:1})
\end{verbatim}
Assuming we've dialed 918005551234, the value saved to the 'number' variable
would be 18005551234. This is useful in situations when we require users to
dial a number to access an outside line, but do not wish to pass the first
digit.
If you use a negative offset number, Asterisk starts counting from the end
of the string and then selects everything after the new position. The following
example will save the numbers 1234 to the 'number' variable, still assuming
we've dialed 918005551234.
\begin{verbatim}
;Remove everything before the last four digits of the dialed string
exten => _9X.,1,Set(number=${EXTEN:-4})
\end{verbatim}
We can also limit the number of characters from our offset position that we
wish to use. This is done by appending a second colon and length value to the
variable name. The following example will save the numbers 555 to the 'number'
variable.
\begin{verbatim}
;Only save the middle numbers 555 from the string 918005551234
exten => _9X.,1,Set(number=${EXTEN:5:3})
\end{verbatim}
The length value can also be used in conjunction with a negative offset. This
may be useful if the length of the string is unknown, but the trailing digits
are. The following example will save the numbers 555 to the 'number' variable,
even if the string starts with more characters than expected (unlike the
previous example).
\begin{verbatim}
;Save the numbers 555 to the 'number' variable
exten => _9X.,1,Set(number=${EXTEN:-7:3})
\end{verbatim}
If a negative length value is entered, Asterisk will remove that many characters
from the end of the string.
\begin{verbatim}
;Set pin to everything but the trailing #.
exten => _XXXX#,1,Set(pin=${EXTEN:0:-1})
\end{verbatim}
\section{Expressions}
Everything contained inside a bracket pair prefixed by a \$ (like \$[this]) is
considered as an expression and it is evaluated. Evaluation works similar to
(but is done on a later stage than) variable substitution: the expression
(including the square brackets) is replaced by the result of the expression
evaluation.
For example, after the sequence:
\begin{verbatim}
exten => 1,1,Set(lala=$[1 + 2])
exten => 1,2,Set(koko=$[2 * ${lala}])
\end{verbatim}
the value of variable koko is "6".
and, further:
\begin{verbatim}
exten => 1,1,Set,(lala=$[ 1 + 2 ]);
\end{verbatim}
will parse as intended. Extra spaces are ignored.
\subsection{Spaces Inside Variables Values}
If the variable being evaluated contains spaces, there can be problems.
For these cases, double quotes around text that may contain spaces
will force the surrounded text to be evaluated as a single token.
The double quotes will be counted as part of that lexical token.
As an example:
\begin{verbatim}
exten => s,6,GotoIf($[ "${CALLERIDNAME}" : "Privacy Manager" ]?callerid-liar|s|1:s|7)
\end{verbatim}
The variable CALLERIDNAME could evaluate to "DELOREAN MOTORS" (with a space)
but the above will evaluate to:
\begin{verbatim}
"DELOREAN MOTORS" : "Privacy Manager"
\end{verbatim}
and will evaluate to 0.
The above without double quotes would have evaluated to:
\begin{verbatim}
DELOREAN MOTORS : Privacy Manager
\end{verbatim}
and will result in syntax errors, because token DELOREAN is immediately
followed by token MOTORS and the expression parser will not know how to
evaluate this expression, because it does not match its grammar.
\subsection{Operators}
Operators are listed below in order of increasing precedence. Operators
with equal precedence are grouped within { } symbols.
\begin{verbatim}
expr1 | expr2
Return the evaluation of expr1 if it is neither an empty string
nor zero; otherwise, returns the evaluation of expr2.
expr1 & expr2
Return the evaluation of expr1 if neither expression evaluates to
an empty string or zero; otherwise, returns zero.
expr1 {=, >, >=, <, <=, !=} expr2
Return the results of integer comparison if both arguments are
integers; otherwise, returns the results of string comparison
using the locale-specific collation sequence. The result of each
comparison is 1 if the specified relation is true, or 0 if the
relation is false.
expr1 {+, -} expr2
Return the results of addition or subtraction of integer-valued
arguments.
expr1 {*, /, %} expr2
Return the results of multiplication, integer division, or
remainder of integer-valued arguments.
- expr1
Return the result of subtracting expr1 from 0.
This, the unary minus operator, is right associative, and
has the same precedence as the ! operator.
! expr1
Return the result of a logical complement of expr1.
In other words, if expr1 is null, 0, an empty string,
or the string "0", return a 1. Otherwise, return a 0.
It has the same precedence as the unary minus operator, and
is also right associative.
expr1 : expr2
The `:' operator matches expr1 against expr2, which must be a
regular expression. The regular expression is anchored to the
beginning of the string with an implicit `^'.
If the match succeeds and the pattern contains at least one regu-
lar expression subexpression `\(...\)', the string correspond-
ing to `\1' is returned; otherwise the matching operator
returns the number of characters matched. If the match fails and
the pattern contains a regular expression subexpression the null
string is returned; otherwise 0.
Normally, the double quotes wrapping a string are left as part
of the string. This is disastrous to the : operator. Therefore,
before the regex match is made, beginning and ending double quote
characters are stripped from both the pattern and the string.
expr1 =~ expr2
Exactly the same as the ':' operator, except that the match is
not anchored to the beginning of the string. Pardon any similarity
to seemingly similar operators in other programming languages!
The ":" and "=~" operators share the same precedence.
expr1 ? expr2 :: expr3
Traditional Conditional operator. If expr1 is a number
that evaluates to 0 (false), expr3 is result of the this
expression evaluation. Otherwise, expr2 is the result.
If expr1 is a string, and evaluates to an empty string,
or the two characters (""), then expr3 is the
result. Otherwise, expr2 is the result. In Asterisk, all
3 exprs will be "evaluated"; if expr1 is "true", expr2
will be the result of the "evaluation" of this
expression. expr3 will be the result otherwise. This
operator has the lowest precedence.
\end{verbatim}
Parentheses are used for grouping in the usual manner.
Operator precedence is applied as one would expect in any of the C
or C derived languages.
\subsection{Examples}
\begin{verbatim}
"One Thousand Five Hundred" =~ "(T[^ ]+)"
returns: Thousand
"One Thousand Five Hundred" =~ "T[^ ]+"
returns: 8
"One Thousand Five Hundred" : "T[^ ]+"
returns: 0
"8015551212" : "(...)"
returns: 801
"3075551212":"...(...)"
returns: 555
! "One Thousand Five Hundred" =~ "T[^ ]+"
returns: 0 (because it applies to the string, which is non-null,
which it turns to "0", and then looks for the pattern
in the "0", and doesn't find it)
!( "One Thousand Five Hundred" : "T[^ ]+" )
returns: 1 (because the string doesn't start with a word starting
with T, so the match evals to 0, and the ! operator
inverts it to 1 ).
2 + 8 / 2
returns 6. (because of operator precedence; the division is done first, then the addition).
2+8/2
returns 6. Spaces aren't necessary.
(2+8)/2
returns 5, of course.
\begin{verbatim}
Of course, all of the above examples use constants, but would work the
same if any of the numeric or string constants were replaced with a
variable reference \${CALLERIDNUM}, for instance.
\subsection{Numbers Vs. Strings}
Tokens consisting only of numbers are converted to 64-bit numbers for
most of the operators. This means that overflows can occur when the
numbers get above 18 digits. Warnings will appear in the logs in this
case.
\subsection{Conditionals}
There is one conditional application - the conditional goto :
\begin{verbatim}
exten => 1,2,gotoif(condition?label1:label2)
\end{verbatim}
If condition is true go to label1, else go to label2. Labels are interpreted
exactly as in the normal goto command.
"condition" is just a string. If the string is empty or "0", the condition
is considered to be false, if it's anything else, the condition is true.
This is designed to be used together with the expression syntax described
above, eg :
\begin{verbatim}
exten => 1,2,gotoif($[${CALLERID} = 123456]?2|1:3|1)
\end{verbatim}
Example of use :
\begin{verbatim}
exten => s,2,Set(vara=1)
exten => s,3,Set(varb=$[${vara} + 2])
exten => s,4,Set(varc=$[${varb} * 2])
exten => s,5,GotoIf($[${varc} = 6]?99|1:s|6)
\end{verbatim}
\subsection{Parse Errors}
Syntax errors are now output with 3 lines.
If the extensions.conf file contains a line like:
\begin{verbatim}
exten => s,6,GotoIf($[ "${CALLERIDNUM}" = "3071234567" & & "${CALLERIDNAME}" : "Privacy Manager" ]?callerid-liar|s|1:s|7)
\end{verbatim}
You may see an error in /var/log/asterisk/messages like this:
\begin{verbatim}
Jul 15 21:27:49 WARNING[1251240752]: ast_yyerror(): syntax error: parse error, unexpected TOK_AND, expecting TOK_MINUS or TOK_LP or TOKEN; Input:
"3072312154" = "3071234567" & & "Steves Extension" : "Privacy Manager"
^
\end{verbatim}
The log line tells you that a syntax error was encountered. It now
also tells you (in grand standard bison format) that it hit an "AND"
(\&) token unexpectedly, and that was hoping for for a MINUS (-), LP
(left parenthesis), or a plain token (a string or number).
The next line shows the evaluated expression, and the line after
that, the position of the parser in the expression when it became confused,
marked with the "\^" character.
\subsection{NULL Strings}
Testing to see if a string is null can be done in one of two different ways:
\begin{verbatim}
exten => _XX.,1,GotoIf($["${calledid}" != ""]?3)
exten => _XX.,1,GotoIf($[foo${calledid} != foo]?3)
\end{verbatim}
The second example above is the way suggested by the WIKI. It will
work as long as there are no spaces in the evaluated value.
The first way should work in all cases, and indeed, might now
be the safest way to handle this situation.
\subsection{Warning}
If you need to do complicated things with strings, asterisk expressions
is most likely NOT the best way to go about it. AGI scripts are an
excellent option to this need, and make available the full power of
whatever language you desire, be it Perl, C, C++, Cobol, RPG, Java,
Snobol, PL/I, Scheme, Common Lisp, Shell scripts, Tcl, Forth, Modula,
Pascal, APL, assembler, etc.
\subsection{Incompatabilities}
The asterisk expression parser has undergone some evolution. It is hoped
that the changes will be viewed as positive.
The "original" expression parser had a simple, hand-written scanner,
and a simple bison grammar. This was upgraded to a more involved bison
grammar, and a hand-written scanner upgraded to allow extra spaces,
and to generate better error diagnostics. This upgrade required bison
1.85, and part of the user community felt the pain of having to
upgrade their bison version.
The next upgrade included new bison and flex input files, and the makefile
was upgraded to detect current version of both flex and bison, conditionally
compiling and linking the new files if the versions of flex and bison would
allow it.
If you have not touched your extensions.conf files in a year or so, the
above upgrades may cause you some heartburn in certain circumstances, as
several changes have been made, and these will affect asterisk's behavior on
legacy extension.conf constructs. The changes have been engineered
to minimize these conflicts, but there are bound to be problems.
The following list gives some (and most likely, not all) of areas
of possible concern with "legacy" extension.conf files:
\begin{enumerate}
\item Tokens separated by space(s).
Previously, tokens were separated by spaces. Thus, ' 1 + 1 ' would evaluate
to the value '2', but '1+1' would evaluate to the string '1+1'. If this
behavior was depended on, then the expression evaluation will break. '1+1'
will now evaluate to '2', and something is not going to work right.
To keep such strings from being evaluated, simply wrap them in double
quotes: ' "1+1" '
\item The colon operator. In versions previous to double quoting, the
colon operator takes the right hand string, and using it as a
regex pattern, looks for it in the left hand string. It is given
an implicit \^ operator at the beginning, meaning the pattern
will match only at the beginning of the left hand string.
If the pattern or the matching string had double quotes around
them, these could get in the way of the pattern match. Now,
the wrapping double quotes are stripped from both the pattern
and the left hand string before applying the pattern. This
was done because it recognized that the new way of
scanning the expression doesn't use spaces to separate tokens,
and the average regex expression is full of operators that
the scanner will recognize as expression operators. Thus, unless
the pattern is wrapped in double quotes, there will be trouble.
For instance, \${VAR1} : (Who|What*)+
may have have worked before, but unless you wrap the pattern
in double quotes now, look out for trouble! This is better:
"\${VAR1}" : "(Who|What*)+"
and should work as previous.
\item Variables and Double Quotes
Before these changes, if a variable's value contained one or more double
quotes, it was no reason for concern. It is now!
\item LE, GE, NE operators removed. The code supported these operators,
but they were not documented. The symbolic operators, <=, >=, and !=
should be used instead.
\item Added the unary '-' operator. So you can 3+ -4 and get -1.
\item Added the unary '!' operator, which is a logical complement.
Basically, if the string or number is null, empty, or '0',
a '1' is returned. Otherwise a '0' is returned.
\item Added the '=~' operator, just in case someone is just looking for
match anywhere in the string. The only diff with the ':' is that
match doesn't have to be anchored to the beginning of the string.
\item Added the conditional operator 'expr1 ? true\_expr :: false\_expr'
First, all 3 exprs are evaluated, and if expr1 is false, the 'false\_expr'
is returned as the result. See above for details.
\item Unary operators '-' and '!' were made right associative.
\end{enumerate}
\subsection{Debugging Hints}
There are two utilities you can build to help debug the \$[ ] in
your extensions.conf file.
The first, and most simplistic, is to issue the command:
make testexpr2
in the top level asterisk source directory. This will build a small
executable, that is able to take the first command line argument, and
run it thru the expression parser. No variable substitutions will be
performed. It might be safest to wrap the expression in single
quotes...
testexpr2 '2*2+2/2'
is an example.
And, in the utils directory, you can say:
make check\_expr
and a small program will be built, that will check the file mentioned
in the first command line argument, for any expressions that might be
have problems when you move to flex-2.5.31. It was originally
designed to help spot possible incompatibilities when moving from the
pre-2.5.31 world to the upgraded version of the lexer.
But one more capability has been added to check\_expr, that might make
it more generally useful. It now does a simple minded evaluation of
all variables, and then passes the \$[] exprs to the parser. If there
are any parse errors, they will be reported in the log file. You can
use check\_expr to do a quick sanity check of the expressions in your
extensions.conf file, to see if they pass a crude syntax check.
The "simple-minded" variable substitution replaces \${varname} variable
references with '555'. You can override the 555 for variable values,
by entering in var=val arguments after the filename on the command
line. So...
check\_expr /etc/asterisk/extensions.conf CALLERIDNUM=3075551212 DIALSTATUS=TORTURE EXTEN=121
will substitute any \${CALLERIDNUM} variable references with
3075551212, any \${DIALSTATUS} variable references with 'TORTURE', and
any \${EXTEN} references with '121'. If there is any fancy stuff
going on in the reference, like \${EXTEN:2}, then the override will
not work. Everything in the \${...} has to match. So, to substitute
\${EXTEN:2} references, you'd best say:
check\_expr /etc/asterisk/extensions.conf CALLERIDNUM=3075551212 DIALSTATUS=TORTURE EXTEN:2=121
on stdout, you will see something like:
OK -- \$[ "\${DIALSTATUS}" = "TORTURE" | "\${DIALSTATUS}" = "DONTCALL" ] at line 416
In the expr2\_log file that is generated, you will see:
line 416, evaluation of \$[ "TORTURE" = "TORTURE" | "TORTURE" = "DONTCALL" ] result: 1
check\_expr is a very simplistic algorithm, and it is far from being
guaranteed to work in all cases, but it is hoped that it will be
useful.
\section{Asterisk standard channel variables}
There are a number of variables that are defined or read
by Asterisk. Here is a list of them. More information is
available in each application's help text. All these variables
are in UPPER CASE only.
Variables marked with a * are builtin functions and can't be set,
only read in the dialplan. Writes to such variables are silently
ignored.
\begin{verbatim}
${ACCOUNTCODE} * Account code (if specified) (Deprecated; use ${CDR(accountcode)})
${BLINDTRANSFER} The name of the channel on the other side of a blind transfer
${BRIDGEPEER} Bridged peer
${CALLERANI} * Caller ANI (PRI channels) (Deprecated; use ${CALLERID(ani)})
${CALLERID} * Caller ID (Deprecated; use ${CALLERID(all)})
${CALLERIDNAME} * Caller ID Name only (Deprecated; use ${CALLERID(name)})
${CALLERIDNUM} * Caller ID Number only (Deprecated; use ${CALLERID(num)})
${CALLINGANI2} * Caller ANI2 (PRI channels)
${CALLINGPRES} * Caller ID presentation for incoming calls (PRI channels)
${CALLINGTNS} * Transit Network Selector (PRI channels)
${CALLINGTON} * Caller Type of Number (PRI channels)
${CHANNEL} * Current channel name
${CONTEXT} * Current context
${DATETIME} * Current date time in the format: DDMMYYYY-HH:MM:SS (Deprecated; use ${STRFTIME(${EPOCH},,%d%m%Y-%H:%M:%S)})
${DB_RESULT} Result value of DB_EXISTS() dial plan function
${DNID} * Dialed Number Identifier (Deprecated; use ${CALLERID(dnid)})
${EPOCH} * Current unix style epoch
${EXTEN} * Current extension
${ENV(VAR)} Environmental variable VAR
${GOTO_ON_BLINDXFR} Transfer to the specified context/extension/priority
after a blind transfer (use ^ characters in place of
| to separate context/extension/priority when setting
this variable from the dialplan)
${HANGUPCAUSE} * Asterisk cause of hangup (inbound/outbound)
${HINT} * Channel hints for this extension
${HINTNAME} * Suggested Caller*ID name for this extension
${INVALID_EXTEN} The invalid called extension (used in the "i" extension)
${LANGUAGE} * Current language (Deprecated; use ${LANGUAGE()})
${LEN(VAR)} * String length of VAR (integer)
${PRIORITY} * Current priority in the dialplan
${PRIREDIRECTREASON} Reason for redirect on PRI, if a call was directed
${RDNIS} * Redirected Dial Number ID Service (Deprecated; use ${CALLERID(rdnis)})
${TIMESTAMP} * Current date time in the format: YYYYMMDD-HHMMSS (Deprecated; use ${STRFTIME(${EPOCH},,%Y%m%d-%H%M%S)})
${TRANSFER_CONTEXT} Context for transferred calls
${FORWARD_CONTEXT} Context for forwarded calls
${UNIQUEID} * Current call unique identifier
${SYSTEMNAME} * value of the systemname option of asterisk.conf
\end{verbatim}
\subsection{Application return values}
-------------------------
In Asterisk 1.2, many applications return the result in a variable
instead of, as in Asterisk 1.0, changing the dial plan priority (+101).
For the various status values, see each application's help text.
\begin{verbatim}
${AGISTATUS} * agi()
${AQMSTATUS} * addqueuemember()
${AVAILSTATUS} * chanisavail()
${CHECKGROUPSTATUS} * checkgroup()
${CHECKMD5STATUS} * checkmd5()
${CPLAYBACKSTATUS} * controlplayback()
${DIALSTATUS} * dial()
${DBGETSTATUS} * dbget()
${ENUMSTATUS} * enumlookup()
${HASVMSTATUS} * hasnewvoicemail()
${LOOKUPBLSTATUS} * lookupblacklist()
${OSPAUTHSTATUS} * ospauth()
${OSPLOOKUPSTATUS} * osplookup()
${OSPNEXTSTATUS} * ospnext()
${OSPFINISHSTATUS} * ospfinish()
${PARKEDAT} * parkandannounce()
${PLAYBACKSTATUS} * playback()
${PQMSTATUS} * pausequeuemember()
${PRIVACYMGRSTATUS} * privacymanager()
${QUEUESTATUS} * queue()
${RQMSTATUS} * removequeuemember()
${SENDIMAGESTATUS} * sendimage()
${SENDTEXTSTATUS} * sendtext()
${SENDURLSTATUS} * sendurl()
${SYSTEMSTATUS} * system()
${TRANSFERSTATUS} * transfer()
${TXTCIDNAMESTATUS} * txtcidname()
${UPQMSTATUS} * unpausequeuemember()
${VMSTATUS} * voicmail()
${VMBOXEXISTSSTATUS} * vmboxexists()
${WAITSTATUS} * waitforsilence()
\end{verbatim}
\subsection{Various application variables}
\begin{verbatim}
${CURL} * Resulting page content for curl()
${ENUM} * Result of application EnumLookup
${EXITCONTEXT} Context to exit to in IVR menu (app background())
or in the RetryDial() application
${MONITOR} * Set to "TRUE" if the channel is/has been monitored (app monitor())
${MONITOR_EXEC} Application to execute after monitoring a call
${MONITOR_EXEC_ARGS} Arguments to application
${MONITOR_FILENAME} File for monitoring (recording) calls in queue
${QUEUE_PRIO} Queue priority
${QUEUE_MAX_PENALTY} Maximum member penalty allowed to answer caller
${QUEUESTATUS} Status of the call, one of:
(TIMEOUT | FULL | JOINEMPTY | LEAVEEMPTY | JOINUNAVAIL | LEAVEUNAVAIL)
${RECORDED_FILE} * Recorded file in record()
${TALK_DETECTED} * Result from talkdetect()
${TOUCH_MONITOR} The filename base to use with Touch Monitor (auto record)
${TOUCH_MONITOR_FORMAT} The audio format to use with Touch Monitor (auto record)
${TOUCH_MONITOR_OUTPUT} * Recorded file from Touch Monitor (auto record)
${TXTCIDNAME} * Result of application TXTCIDName
${VPB_GETDTMF} chan_vpb
\end{verbatim}
\subsection{The MeetMe Conference Bridge}
\begin{verbatim}
${MEETME_RECORDINGFILE} Name of file for recording a conference with
the "r" option
${MEETME_RECORDINGFORMAT} Format of file to be recorded
${MEETME_EXIT_CONTEXT} Context for exit out of meetme meeting
${MEETME_AGI_BACKGROUND} AGI script for Meetme (zap only)
${MEETMESECS} * Number of seconds a user participated in a MeetMe conference
\end{verbatim}
\subsection{The VoiceMail() application}
\begin{verbatim}
${VM_CATEGORY} Sets voicemail category
${VM_NAME} * Full name in voicemail
${VM_DUR} * Voicemail duration
${VM_MSGNUM} * Number of voicemail message in mailbox
${VM_CALLERID} * Voicemail Caller ID (Person leaving vm)
${VM_CIDNAME} * Voicemail Caller ID Name
${VM_CIDNUM} * Voicemail Caller ID Number
${VM_DATE} * Voicemail Date
${VM_MESSAGEFILE} * Path to message left by caller
\end{verbatim}
\subsection{The VMAuthenticate() application}
\begin{verbatim}
${AUTH_MAILBOX} * Authenticated mailbox
${AUTH_CONTEXT} * Authenticated mailbox context
\end{verbatim}
\subsection{DUNDiLookup()}
\begin{verbatim}
${DUNDTECH} * The Technology of the result from a call to DUNDiLookup()
${DUNDDEST} * The Destination of the result from a call to DUNDiLookup()
\end{verbatim}
\subsection{chan\_zap}
\begin{verbatim}
${ANI2} * The ANI2 Code provided by the network on the incoming call.
(ie, Code 29 identifies call as a Prison/Inmate Call)
${CALLTYPE} * Type of call (Speech, Digital, etc)
${CALLEDTON} * Type of number for incoming PRI extension
i.e. 0=unknown, 1=international, 2=domestic, 3=net_specific,
4=subscriber, 6=abbreviated, 7=reserved
${CALLINGSUBADDR} * Called PRI Subaddress
${FAXEXTEN} * The extension called before being redirected to "fax"
${PRIREDIRECTREASON} * Reason for redirect, if a call was directed
${SMDI_VM_TYPE} * When an call is received with an SMDI message, the 'type'
of message 'b' or 'u'
\end{verbatim}
\subsection{chan\_sip}
\begin{verbatim}
${SIPCALLID} * SIP Call-ID: header verbatim (for logging or CDR matching)
${SIPDOMAIN} * SIP destination domain of an inbound call (if appropriate)
${SIPUSERAGENT} * SIP user agent (deprecated)
${SIPURI} * SIP uri
${SIP_CODEC} Set the SIP codec for a call
${SIP_URI_OPTIONS} * additional options to add to the URI for an outgoing call
${RTPAUDIOQOS} RTCP QoS report for the audio of this call
${RTPVIDEOQOS} RTCP QoS report for the video of this call
\end{verbatim}
\subsection{chan\_agent}
\begin{verbatim}
${AGENTMAXLOGINTRIES} Set the maximum number of failed logins
${AGENTUPDATECDR} Whether to update the CDR record with Agent channel data
${AGENTGOODBYE} Sound file to use for "Good Bye" when agent logs out
${AGENTACKCALL} Whether the agent should acknowledge the incoming call
${AGENTAUTOLOGOFF} Auto logging off for an agent
${AGENTWRAPUPTIME} Setting the time for wrapup between incoming calls
${AGENTNUMBER} * Agent number (username) set at login
${AGENTSTATUS} * Status of login ( fail | on | off )
${AGENTEXTEN} * Extension for logged in agent
\end{verbatim}
\subsection{The Dial() application}
\begin{verbatim}
${DIALEDPEERNAME} * Dialed peer name
${DIALEDPEERNUMBER} * Dialed peer number
${DIALEDTIME} * Time for the call (seconds)
${ANSWEREDTIME} * Time from dial to answer (seconds)
${DIALSTATUS} * Status of the call, one of:
(CHANUNAVAIL | CONGESTION | BUSY | NOANSWER
| ANSWER | CANCEL | DONTCALL | TORTURE)
${DYNAMIC_FEATURES} * The list of features (from the [applicationmap] section of
features.conf) to activate during the call, with feature
names separated by '#' characters
${LIMIT_PLAYAUDIO_CALLER} Soundfile for call limits
${LIMIT_PLAYAUDIO_CALLEE} Soundfile for call limits
${LIMIT_WARNING_FILE} Soundfile for call limits
${LIMIT_TIMEOUT_FILE} Soundfile for call limits
${LIMIT_CONNECT_FILE} Soundfile for call limits
${OUTBOUND_GROUP} Default groups for peer channels (as in SetGroup)
* See "show application dial" for more information
\end{verbatim}
\subsection{The chanisavail() application}
\begin{verbatim}
${AVAILCHAN} * the name of the available channel if one was found
${AVAILORIGCHAN} * the canonical channel name that was used to create the channel
${AVAILSTATUS} * Status of requested channel
\end{verbatim}
\subsection{Dialplan Macros}
\begin{verbatim}
${MACRO_EXTEN} * The calling extensions
${MACRO_CONTEXT} * The calling context
${MACRO_PRIORITY} * The calling priority
${MACRO_OFFSET} Offset to add to priority at return from macro
\end{verbatim}
\subsection{The ChanSpy() application}
\begin{verbatim}
${SPYGROUP} * A ':' (colon) separated list of group names.
(To be set on spied on channel and matched against the g(grp) option)
\end{verbatim}
\subsection{OSP}
\begin{verbatim}
${OSPINHANDLE} OSP handle of in_bound call
${OSPINTIMELIMIT} Duration limit for in_bound call
${OSPOUTHANDLE} OSP handle of out_bound call
${OSPTECH} OSP technology
${OSPDEST} OSP destination
${OSPCALLING} OSP calling number
${OSPOUTTOKEN} OSP token to use for out_bound call
${OSPOUTTIMELIMIT} Duration limit for out_bound call
${OSPRESULTS} Number of remained destinations
\end{verbatim}

30
doc/tex/cliprompt.tex Normal file
View File

@@ -0,0 +1,30 @@
\subsubsection{Changing the CLI Prompt}
The CLI prompt is set with the ASTERISK\_PROMPT UNIX environment variable that
you set from the Unix shell before starting Asterisk
You may include the following variables, that will be replaced by
the current value by Asterisk:
\begin{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 include/asterisk/term.h
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}

198
doc/tex/configuration.tex Normal file
View File

@@ -0,0 +1,198 @@
\subsubsection{Introduction}
The Asterisk configuration parser in the 1.2 version
and beyond series has been improved in a number of ways. In
addition to the realtime architecture, we now have the ability to create
templates in configuration files, and use these as templates when we
configure phones, voicemail accounts and queues.
These changes are general to the configuration parser, and works in
all configuration files.
\subsubsection{General syntax}
Asterisk configuration files are defined as follows:
\begin{verbatim}
[section]
label = value
label2 = value
\end{verbatim}
In some files, (e.g. mgcp.conf, zapata.conf and agents.conf), the syntax
is a bit different. In these files the syntax is as follows:
\begin{verbatim}
[section]
label1 = value1
label2 = value2
object => name
label3 = value3
label2 = value4
object2 => name2
\end{verbatim}
In this syntax, we create objects with the settings defined above the object
creation. Note that settings are inherited from the top, so in the example
above object2 has inherited the setting for "label1" from the first object.
For template configurations, the syntax for defining a section is changed
to:
\begin{verbatim}
[section](options)
label = value
\end{verbatim}
The options field is used to define templates, refer to templates and hide
templates. Any object can be used as a template.
No whitespace is allowed between the closing "]" and the parenthesis "(".
\subsubsection{Comments}
All lines that starts with semi-colon ";" is treated as comments
and is not parsed.
The ";--" is a marker for a multi-line comment. Everything after
that marker will be treated as a comment until the end-marker "--;"
is found. Parsing begins directly after the end-marker.
\begin{verbatim}
;This is a comment
label = value
;-- This is
a comment --;
;-- Comment --; exten=> 1000,1,dial(SIP/lisa)
\end{verbatim}
\subsubsection{Including other files}
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{verbatim}
#include myusers.conf
\end{verbatim}
You may also include the output of a program with the \#exec directive,
if you enable it in asterisk.conf
In asterisk.conf, add the execincludes = yes statement in the options
section:
\begin{verbatim}
[options]
execincludes=yes
\end{verbatim}
The exec directive is used like this:
\begin{verbatim}
#exec /usr/local/bin/myasteriskconfigurator.sh
\end{verbatim}
\subsubsection{Adding to an existing section}
\begin{verbatim}
[section]
label = value
[section](+)
label2 = value2
\end{verbatim}
In this case, the plus sign indicates that the second section (with the
same name) is an addition to the first section. The second section can
be in another file (by using the \#include statement). If the section
name referred to before the plus is missing, the configuration will fail
to load.
\subsubsection{Defining a template-only section}
\begin{verbatim}
[section](!)
label = value
\end{verbatim}
The exclamation mark indicates to the config parser that this is a only
a template and should not itself be used by the Asterisk module for
configuration. The section can be inherited by other sections (see
section "Using templates" below) but is not used by itself.
\subsubsection{Using templates (or other configuration sections)}
\begin{verbatim}
[section](name[,name])
label = value
\end{verbatim}
The name within the parenthesis refers to other sections, either
templates or standard sections. The referred sections are included
before the configuration engine parses the local settings within the
section as though their entire contents (and anything they were
previously based upon) were included in the new section. For example
consider the following:
\begin{verbatim}
[foo]
permit=192.168.0.2
host=asdf
deny=192.168.0.1
[bar]
permit=192.168.1.2
host=jkl
deny=192.168.1.1
[baz](foo,bar)
permit=192.168.3.1
host=bnm
\end{verbatim}
The [baz] section will be processed as though it had been written in the
following way:
\begin{verbatim}
[baz]
permit=192.168.0.2
host=asdf
deny=192.168.0.1
permit=192.168.1.2
host=jkl
deny=192.168.1.1
permit=192.168.3.1
host=bnm
\end{verbatim}
\subsubsection{Additional Examples}
(in top-level sip.conf)
\begin{verbatim}
[defaults](!)
type=friend
nat=yes
qualify=on
dtmfmode=rfc2833
disallow=all
allow=alaw
#include accounts/*/sip.conf
\end{verbatim}
(in accounts/customer1/sip.conf)
\begin{verbatim}
[def-customer1](!,defaults)
secret=this_is_not_secret
context=from-customer1
callerid=Customer 1 <300>
accountcode=0001
[phone1](def-customer1)
mailbox=phone1@customer1
[phone2](def-customer1)
mailbox=phone2@customer1
\end{verbatim}
This example defines two phones - phone1 and phone2 with settings
inherited from "def-customer1". The "def-customer1" is a template that
inherits from "defaults", which also is a template.

40
doc/tex/dundi.tex Normal file
View File

@@ -0,0 +1,40 @@
http://www.dundi.com
Mark Spencer, Digium, Inc.
DUNDi is essentially a trusted, peer-to-peer system for being able to
call any phone number from the Internet. DUNDi works by creating a
network of nodes called the "DUNDi E.164 Trust Group" which are bound by
a common peering agreement known as the General Peering Agreement or
GPA. The GPA legally binds the members of the Trust Group to provide
good-faith accurate information to the other nodes on the network, and
provides standards by which the community can insure the integrity of
the information on the nodes themselves. Unlike ENUM or similar
systems, DUNDi is explicitly designed to preclude any necessity for a
single centralized system which could be a source of fees, regulation,
etc.
Much less dramatically, DUNDi can also be used within a private
enterprise to share a dialplan efficiently between multiple nodes,
without incurring a risk of a single point of failure. In this way,
administrators can locally add extensions which become immediately
available to the other nodes in the system.
For more information visit http://www.dundi.com
\section{DUNDIQUERY and DUNDIRESULT}
The DUNDIQUERY and DUNDIRESULT dialplan functions will let you initiate
a DUNDi query from the dialplan, see how many results there are, and access
each one. Here is some example usage:
\begin{verbatim}
exten => 1,1,Set(ID=${DUNDIQUERY(1|dundi_test|b)})
exten => 1,n,Set(NUM=${DUNDIRESULT(${ID}|getnum)})
exten => 1,n,NoOp(There are ${NUM} results)
exten => 1,n,Set(X=1)
exten => 1,n,While($[${X} <= ${NUM}])
exten => 1,n,NoOp(Result ${X} is ${DUNDIRESULT(${ID}|${X})})
exten => 1,n,Set(X=$[${X} + 1])
exten => 1,n,EndWhile
\end{verbatim}

353
doc/tex/enum.tex Normal file
View File

@@ -0,0 +1,353 @@
\section{The ENUMLOOKUP dialplan function}
The ENUMLOOKUP function is more complex than it first may appear, and
this guide is to give a general overview and set of examples that may
be well-suited for the advanced user to evaluate in their
consideration of ENUM or ENUM-like lookup strategies. This document
assumes a familiarity with ENUM (RFC3761) or ENUM-like methods, as
well as familiarity with NAPTR DNS records (RFC2915, RFC3401-3404).
For an overview of NAPTR records, and the use of NAPTRs in the ENUM
global phone-number-to-DNS mapping scheme, please see
http://www.voip-info.org/tiki-index.php?page=ENUM for more detail.
Using ENUM within Asterisk can be simple or complex, depending on how
many failover methods and redundancy procedures you wish to utilize.
Implementation of ENUM paths is supposedly defined by the person
creating the NAPTR records, but the local administrator may choose to
ignore certain NAPTR response methods (URI types) or prefer some over
others, which is in contradiction to the RFC. The ENUMLOOKUP method
simply provides administrators a method for determining NAPTR results
in either the globally unique ENUM (e164.arpa) DNS tree, or in other
ENUM-like DNS trees which are not globally unique. The methods to
actually create channels ("dial") results given by the ENUMLOOKUP
function is then up to the administrator to implement in a way that
best suits their environment.
\begin{verbatim}
Function: ENUMLOOKUP(number[|Method-type[|options[|record#[|zone-suffix]]]])
\end{verbatim}
Performs an ENUM tree lookup on the specified number, method type, and
ordinal record offset, and returns one of four different values:
\begin{enumerate}
\item post-parsed NAPTR of one method (URI) type
\item count of elements of one method (URI) type
\item count of all method types
\item full URI of method at a particular point in the list of all possible methods
\end{enumerate}
\subsection{Arguments}
\begin{itemize}
\item number
\begin{itemize}
\item telephone number or search string. Only numeric values
within this string are parsed; all other digits are ignored for
search, but are re-written during NAPTR regexp expansion.
\end{itemize}
\item service\_type
\begin{itemize}
\item tel, sip, h323, iax2, mailto, ...[any other string],
ALL. Default type is "sip".
Special name of "ALL" will create a list of method types across
all NAPTR records for the search number, and then put the results
in an ordinal list starting with 1. The position <number>
specified will then be returned, starting with 1 as the first
record (lowest value) in the list. The service types are not
hardcoded in Asterisk except for the default (sip) if no other
service type specified; any method type string (IANA-approved or
not) may be used except for the string "ALL".
\end{itemize}
\item options
\begin{itemize}
\item c
\begin{itemize}
\item count. Returns the number of records of this type are returned
(regardless of order or priority.) If "ALL" is the specified
service\_type, then a count of all methods will be returned for the
DNS record.
\end{itemize}
\end{itemize}
\item record\#
\begin{itemize}
\item which record to present if multiple answers are returned
<integer> = The record in priority/order sequence based on the
total count of records passed back by the query. If a service\_type
is specified, all entries of that type will be sorted into an
ordinal list starting with 1 (by order first, then priority).
The default of <options> is "1"
\end{itemize}
\item zone\_suffix
\begin{itemize}
\item allows customization of the ENUM zone. Default is e164.arpa.
\end{itemize}
\end{itemize}
\subsection{Examples}
Let's use this ENUM list as an example (note that these examples exist
in the DNS, and will hopefully remain in place as example
destinations, but they may change or become invalid over time. The
end result URIs are not guaranteed to actually work, since some of
these hostnames or SIP proxies are imaginary. Of course, the tel:
replies go to directory assistance for New York City and San
Francisco...) Also note that the complex SIP NAPTR at weight 30 will
strip off the leading "+" from the dialed string if it exists. This
is probably a better NAPTR than hard-coding the number into the NAPTR,
and it is included as a more complex regexp example, though other
simpler NAPTRs will work just as well.
\begin{verbatim}
0.2.0.1.1.6.5.1.0.3.1.loligo.com. 3600 IN NAPTR 10 100 "u"
"E2U+tel" "!^\\+13015611020$!tel:+12125551212!" .
0.2.0.1.1.6.5.1.0.3.1.loligo.com. 3600 IN NAPTR 21 100 "u"
"E2U+tel" "!^\\+13015611020$!tel:+14155551212!" .
0.2.0.1.1.6.5.1.0.3.1.loligo.com. 3600 IN NAPTR 25 100 "u"
"E2U+sip" "!^\\+13015611020$!sip:2203@sip.fox-den.com!" .
0.2.0.1.1.6.5.1.0.3.1.loligo.com. 3600 IN NAPTR 26 100 "u"
"E2U+sip" "!^\\+13015611020$!sip:1234@sip-2.fox-den.com!" .
0.2.0.1.1.6.5.1.0.3.1.loligo.com. 3600 IN NAPTR 30 100 "u"
"E2U+sip" "!^\\+*([^\\*]*)!sip:\\1@sip-3.fox-den.com!" .
0.2.0.1.1.6.5.1.0.3.1.loligo.com. 3600 IN NAPTR 55 100 "u"
"E2U+mailto" "!^\\+13015611020$!mailto:jtodd@fox-den.com!" .
\end{verbatim}
Example 1: Simplest case, using first SIP return (use all defaults
except for domain name)
\begin{verbatim}
exten => 100,1,Set(foo=${ENUMLOOKUP(+13015611020,,,,loligo.com)})
returns: ${foo}="2203@sip.fox-den.com"
\end{verbatim}
Example 2: What is the first "tel" pointer type for this number?
(after sorting by order/preference; default of "1" is assumed in
options field)
\begin{verbatim}
exten => 100,1,Set(foo=${ENUMLOOKUP(+13015611020,tel,,,loligo.com)})
returns: ${foo}="+12125551212"
\end{verbatim}
Example 3: How many "sip" pointer type entries are there for this number?
\begin{verbatim}
exten => 100,1,Set(foo=${ENUMLOOKUP(+13015611020,sip,c,,loligo.com)})
returns: ${foo}=3
\end{verbatim}
Example 4: For all the "tel" pointer type entries, what is the second
one in the list? (after sorting by preference)
\begin{verbatim}
exten => 100,1,Set(foo=${ENUMLOOKUP(+13015611020,tel,,2,loligo.com)})
returns: ${foo}="+14155551212"
\end{verbatim}
Example 5: How many NAPTRs (tel, sip, mailto, etc.) are in the list for this number?
\begin{verbatim}
exten => 100,1,Set(foo=${ENUMLOOKUP(+13015611020,ALL,c,,loligo.com)})
returns: ${foo}=6
\end{verbatim}
Example 6: Give back the second full URI in the sorted list of all NAPTR URIs:
\begin{verbatim}
exten => 100,1,Set(foo=${ENUMLOOKUP(+13015611020,ALL,,2,loligo.com)})
returns: ${foo}="tel:+14155551212" [note the "tel:" prefix in the string]
\end{verbatim}
Example 7: Look up first SIP entry for the number in the e164.arpa zone (all defaults)
\begin{verbatim}
exten => 100,1,Set(foo=${ENUMLOOKUP(+437203001721)})
returns: ${foo}="enum-test@sip.nemox.net" [note: this result is
subject to change as it is "live" DNS and not under my control]
\end{verbatim}
Example 8: Look up the ISN mapping in freenum.org alpha test zone
\begin{verbatim}
exten => 100,1,Set(foo=${ENUMLOOKUP(1234*256,,,,freenum.org)})
returns: ${foo}="1234@204.91.156.10" [note: this result is subject
to change as it is "live" DNS]
\end{verbatim}
Example 9: Give back the first SIP pointer for a number in the
\begin{verbatim}
enum.yoydynelabs.com zone (invalid lookup)
exten => 100,1,Set(foo=${ENUMLOOKUP(1234567890,sip,,1,enum.yoyodynelabs.com)})
returns: ${foo}=""
\end{verbatim}
\subsection{Usage notes and subtle features}
\begin{itemize}
\item The use of "+" in lookups is confusing, and warrants further
explanation. All E.164 numbers ("global phone numbers") by
definition need a leading "+" during ENUM lookup. If you neglect to
add a leading "+", you may discover that numbers that seem to exist
in the DNS aren't getting matched by the system or are returned with
a null string result. This is due to the NAPTR reply requiring a
"+" in the regular expression matching sequence. Older versions of
Asterisk add a "+" from within the code, which may confuse
administrators converting to the new function. Please ensure that
all ENUM (e164.arpa) lookups contain a leading "+" before lookup, so
ensure your lookup includes the leading plus sign. Other DNS trees
may or may not require a leading "+" - check before using those
trees, as it is possible the parsed NAPTRs will not provide correct
results unless you have the correct dialed string. If you get
console messages like "WARNING[24907]: enum.c:222 parse\_naptr: NAPTR
Regex match failed." then it is very possible that the returned
NAPTR expects a leading "+" in the search string (or the returned
NAPTR is mis-formed.)
\item If a query is performed of type "c" ("count") and let's say you
get back 5 records and then some seconds later a query is made
against record 5 in the list, it may not be the case that the DNS
resolver has the same answers as it did a second or two ago - maybe
there are only 4 records in the list in the newest query. The
resolver should be the canonical storage location for DNS records,
since that is the intent of ENUM. However, some obscure future
cases may have wildly changing NAPTR records within several seconds.
This is a corner case, and probably only worth noting as a very rare
circumstance. (note: I do not object to Asterisk's dnsmgr method of
locally caching DNS replies, but this method needs to honor the TTL
given by the remote zone master. Currently, the ENUMLOOKUP function
does not use the dnsmgr method of caching local DNS replies.)
\item If you want strict NAPTR value ordering, then it will be
necessary to use the "ALL" method to incrementally step through the
different returned NAPTR pointers. You will need to use string
manipulation to strip off the returned method types, since the
results will look like "sip:12125551212" in the returned value.
This is a non-trivial task, though it is required in order to have
strict RFC compliance and to comply with the desires of the remote
party who is presenting NAPTRs in a particular order for a reason.
\item Default behavior for the function (even in event of an error) is
to move to the next priority, and the result is a null value. Most
ENUM lookups are going to be failures, and it is the responsibility
of the dialplan administrator to manage error conditions within
their dialplan. This is a change from the old app\_enumlookup method
and it's arbitrary priority jumping based on result type or failure.
\item Anything other than digits will be ignored in lookup strings.
Example: a search string of "+4372030blah01721" will turn into
1.2.7.1.0.0.3.0.2.7.3.4.e164.arpa. for the lookup. The NAPTR
parsing may cause unexpected results if there are strings inside
your NAPTR lookups.
\item If there exist multiple records with the same weight and order as
a result of your query, the function will RANDOMLY select a single
NAPTR from those equal results.
\item Currently, the function ignores the settings in enum.conf as the
search zone name is now specified within the function, and the H323
driver can be chosen by the user via the dialplan. There were no
other values in this file, and so it becomes deprecated.
\item The function will digest and return NAPTRs which use older
(deprecated) style, reversed method strings such as "sip+E2U"
instead of the more modern "E2U+sip"
\item There is no provision for multi-part methods at this time. If
there are multiple NAPTRs with (as an example) a method of
"E2U+voice:sip" and then another NAPTR in the same DNS record with a
method of ""E2U+sip", the system will treat these both as method
"sip" and they will be separate records from the perspective of the
function. Of course, if both records point to the same URI and have
equal priority/weight (as is often the case) then this will cause no
serious difficulty, but it bears mentioning.
\item ISN (ITAD Subscriber Number) usage: If the search number is of
the form ABC*DEF (where ABC and DEF are at least one numeric digit)
then perform an ISN-style lookup where the lookup is manipulated to
C.B.A.DEF.domain.tld (all other settings and options apply.) See
http://www.freenum.org/ for more details on ISN lookups. In the
unlikely event you wish to avoid ISN re-writes, put an "n" as the
first digit of the search string - the "n" will be ignored for the search.
\end{itemize}
\subsection{Some more Examples}
All examples below except where noted use "e164.arpa" as the
referenced domain, which is the default domain name for ENUMLOOKUP.
All numbers are assumed to not have a leading "+" as dialed by the
inbound channel, so that character is added where necessary during
ENUMLOOKUP function calls.
\begin{verbatim}
; example 1
;
; Assumes North American international dialing (011) prefix.
; Look up the first SIP result and send the call there, otherwise
; send the call out a PRI. This is the most simple possible
; ENUM example, but only uses the first SIP reply in the list of
; NAPTR(s).
;
exten => _011.,1,Set(enumresult=${ENUMLOOKUP(+${EXTEN:3})})
exten => _011.,n,Dial(SIP/${enumresult})
exten => _011.,n,Dial(Zap/g1/${EXTEN})
;
; end example 1
; example 2
;
; Assumes North American international dialing (011) prefix.
; Check to see if there are multiple SIP NAPTRs returned by
; the lookup, and dial each in order. If none work (or none
; exist) then send the call out a PRI, group 1.
;
exten => _011.,1,Set(sipcount=${ENUMLOOKUP(${EXTEN:3},sip,c)}|counter=0)
exten => _011.,n,While($["${counter}"<"${sipcount}"])
exten => _011.,n,Set(counter=$[${counter}+1])
exten => _011.,n,Dial(SIP/${ENUMLOOKUP(+${EXTEN:3},sip,,${counter})})
exten => _011.,n,EndWhile
exten => _011.,n,Dial(Zap/g1/${EXTEN})
;
; end example 2
; example 3
;
; This example expects an ${EXTEN} that is an e.164 number (like
; 14102241145 or 437203001721)
; Search through e164.arpa and then also search through e164.org
; to see if there are any valid SIP or IAX termination capabilities.
; If none, send call out via Zap channel 1.
;
; Start first with e164.arpa zone...
;
exten => _X.,1,Set(sipcount=${ENUMLOOKUP(+${EXTEN},sip,c)}|counter=0)
exten => _X.,2,GotoIf($["${counter}"<"${sipcount}"]?3:6)
exten => _X.,3,Set(counter=$[${counter}+1])
exten => _X.,4,Dial(SIP/${ENUMLOOKUP(+${EXTEN},sip,,${counter})})
exten => _X.,5,GotoIf($["${counter}"<"${sipcount}"]?3:6)
;
exten => _X.,6,Set(iaxcount=${ENUMLOOKUP(+${EXTEN},iax2,c)}|counter=0)
exten => _X.,7,GotoIf($["${counter}"<"${iaxcount}"]?8:11)
exten => _X.,8,Set(counter=$[${counter}+1])
exten => _X.,9,Dial(IAX2/${ENUMLOOKUP(+${EXTEN},iax2,,${counter})})
exten => _X.,10,GotoIf($["${counter}"<"${iaxcount}"]?8:11)
;
exten => _X.,11,NoOp("No valid entries in e164.arpa for ${EXTEN} - checking in e164.org")
;
; ...then also try e164.org, and look for SIP and IAX NAPTRs...
;
exten => _X.,12,Set(sipcount=${ENUMLOOKUP(+${EXTEN},sip,c,,e164.org)}|counter=0)
exten => _X.,13,GotoIf($["${counter}"<"${sipcount}"]?14:17)
exten => _X.,14,Set(counter=$[${counter}+1])
exten => _X.,15,Dial(SIP/${ENUMLOOKUP(+${EXTEN},sip,,${counter},e164.org)})
exten => _X.,16,GotoIf($["${counter}"<"${sipcount}"]?14:17)
;
exten => _X.,17,Set(iaxcount=${ENUMLOOKUP(+${EXTEN},iax2,c,,e164.org)}|counter=0)
exten => _X.,18,GotoIf($["${counter}"<"${iaxcount}"]?19:22)
exten => _X.,19,Set(counter=$[${counter}+1])
exten => _X.,20,Dial(IAX2/${ENUMLOOKUP(+${EXTEN},iax2,,${counter},e164.org)})
exten => _X.,21,GotoIf($["${counter}"<"${iaxcount}"]?19:22)
;
; ...then send out PRI.
;
exten => _X.,22,NoOp("No valid entries in e164.org for ${EXTEN} - sending out via Zap")
exten => _X.,23,Dial(Zap/g1/${EXTEN})
;
; end example 3
\end{verbatim}

74
doc/tex/extensions.tex Normal file
View File

@@ -0,0 +1,74 @@
\subsubsection{The Asterisk dialplan}
The Asterisk dialplan is divided into contexts. A context is simply a group
of extensions. For each "line" that should be able to be called, an extension
must be added to a context. Then, you configure the calling "line" to have
access to this context.
If you change the dialplan, you can use the Asterisk CLI command
"extensions reload" to load the new dialplan without disrupting
service in your PBX.
Extensions are routed according to priority and may be based on any set
of characters (a-z), digits, \#, and *. Please note that when matching a
pattern, "N", "X", and "Z" are interpreted as classes of digits.
For each extension, several actions may be listed and must be given a unique
priority. When each action completes, the call continues at the next priority
(except for some modules which use explicitly GOTO's).
When each action completes, it generally moves to the next priority (except for
some modules which use explicitly GOTO's.
Extensions frequently have data they pass to the executing application
(most frequently a string). You can see the available dialplan applications
by entering the "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.
\subsubsection{Example dialplan}
The example dial plan, in the configs/extensions.conf.sample file
is installed as extensions.conf if you run "make samples" after
installation of Asterisk. This file includes many more instructions
and examples than this file, so it's worthwhile to read it.
\subsubsection{Special extensions}
There are some extensions with important meanings:
\begin{itemize}
\item s
\begin{itemize}
\item What to do when an extension context is entered (unless
overridden by the low level channel interface)
This is used in macros, and some special cases.
"s" is not a generic catch-all wildcard extension.
\end{itemize}
\item i
\begin{itemize}
\item What to do if an invalid extension is entered
\end{itemize}
\item h
\begin{itemize}
\item The hangup extension, executed at hangup
\end{itemize}
\item t
\begin{itemize}
\item What to do if nothing is entered in the requisite amount
of time.
\end{itemize}
\item T
\begin{itemize}
\item This is the extension that is executed when the 'absolute'
timeout is reached. See "show function TIMEOUT" for more
information on setting timeouts.
\end{itemize}
\end{itemize}
And finally, the extension context "default" is used when either a) an
extension context is deleted while an extension is in use, or b) a specific
starting extension handler has not been defined (unless overridden by the
low level channel interface).

16
doc/tex/freetds.tex Normal file
View File

@@ -0,0 +1,16 @@
The cdr\_tds module is NOT compatible with version 0.63 of FreeTDS.
The cdr\_tds module is known to work with FreeTDS version 0.62.1;
it should also work with 0.62.2, 0.62.3 and 0.62.4, which are bug
fix releases.
The cdr\_tds module uses the raw "libtds" API of FreeTDS. It appears
that from 0.63 onwards, this is not considered a published API
of FreeTDS and is subject to change without notice.
Between 0.62.x and 0.63 of FreeTDS, many incompatible changes
have been made to the libtds API.
For newer versions of FreeTDS, it is recommended that you use the
ODBC driver.

100
doc/tex/hardware.tex Normal file
View File

@@ -0,0 +1,100 @@
\subsection{Introduction}
A PBX is only really useful if you can get calls into it. Of course, you
can use Asterisk with VoIP calls (SIP, H.323, IAX), but you can also talk
to the real PSTN through various cards.
Supported Hardware is divided into two general groups: Zaptel devices and
non-zaptel devices. The Zaptel compatible hardware supports pseudo-TDM
conferencing and all call features through chan\_zap, whereas non-zaptel
compatible hardware may have different features.
\subsection{Zaptel compatible hardware}
\begin{itemize}
\item Digium, Inc. (Primary Developer of Asterisk)
http://www.digium.com
\begin{itemize}
\item Analog Interfaces
\begin{itemize}
\item TDM400P - The TDM400P is a half-length PCI 2.2-compliant card that supports FXS and FXO station interfaces for connecting analog telephones and analog POTS lines through a PC.
\item TDM800P - The TDM800P is a half-length PCI 2.2-compliant, 8 port card using Digium's VoiceBus technology that supports FXS and FXO station interfaces for connecting analog telephones and analog POTS lines through a PC.
\item TDM2400P - The TDM2400P is a full-length PCI 2.2-compliant card for connecting analog telephones and analog POTS lines through a PC. It supports a combination of up to 6 FXS and/or FXO modules for a total of 24 lines.
\end{itemize}
\item Digital Interfaces
\begin{itemize}
\item TE412P - The TE412P offers an on-board DSP-based echo cancellation module. It supports E1, T1, and J1 environments and is selectable on a per-card or per-port basis.
\item TE410P - The TE410P improves performance and scalability through bus mastering architecture. It supports E1, T1, and J1 environments and is selectable on a per-card or per-port basis.
\item TE407P - The TE407P offers an on-board DSP-based echo cancellation module. It supports E1, T1, and J1 environments and is selectable on a per-card or per-port basis.
\item TE405P - The TE405P improves performance and scalability through bus mastering architecture. It supports both E1, T1, J1 environments and is selectable on a per-card or per-port basis.
\item TE212P - The TE212P offers an on-board DSP-based echo cancellation module. It supports E1, T1, and J1 environments and is selectable on a per-card or per-port basis.
\item TE210P - The TE210P improves performance and scalability through bus mastering architecture. It supports E1, T1, and J1 environments and is selectable on a per-card or per-port basis.
\item TE207P - The TE207P offers an on-board DSP-based echo cancellation module. It supports E1, T1, and J1 environments and is selectable on a per-card or per-port basis.
\item TE205P - The TE205P improves performance and scalability through bus mastering architecture. It supports both E1 and T1/J1 environments and is selectable on a per-card or per-port basis.
\item TE120P - The TE120P is a single span, selectable T1, E1, or J1 card and utilizes Digium's VoiceBus™ technology. It supports both voice and data modes.
\item TE110P - The TE110P brings a high-performance, cost-effective, and flexible single span togglable T1, E1, J1 interface to the Digium line-up of telephony interface devices.
\end{itemize}
\end{itemize}
\end{itemize}
\subsection{Non-zaptel compatible hardware}
\begin{itemize}
\item QuickNet, Inc.
http://www.quicknet.net
\begin{itemize}
\item Internet PhoneJack - Single FXS interface. Supports Linux telephony
interface. DSP compression built-in.
\item Internet LineJack - Single FXS or FXO interface. Supports Linux
telephony interface.
\end{itemize}
\end{itemize}
\subsection{mISDN compatible hardware}
mISDN homepage: http://www.isdn4linux.de/mISDN/
Any adapter with an mISDN driver should be compatible with
chan\_misdn. See the mISDN section for more information.
\begin{itemize}
\item Digium, Inc. (Primary Developer of Asterisk)
http://www.digium.com
\begin{itemize}
\item B410P - 4 Port BRI card (TE/NT)
\end{itemize}
\end{itemize}
\begin{itemize}
\item beroNet
http://www.beronet.com
\begin{itemize}
\item BN4S0 - 4 Port BRI card (TE/NT)
\item BN8S0 - 8 Port BRI card (TE/NT)
\item Billion Card - Single Port BRI card (TE (/NT with crossed cable) )
\end{itemize}
\end{itemize}
\subsection{Miscellaneous other interfaces}
\begin{itemize}
\item Digium, Inc. (Primary Developer of Asterisk)
\begin{itemize}
\item TC400B - The TC400B is a half-length, low-profile PCI 2.2-compliant card for transforming complex VoIP codecs (G.729) into simple codecs.
\end{itemize}
\item ALSA
http://www.alsa-project.org
\begin{itemize}
\item Any ALSA compatible full-duplex sound card
\end{itemize}
\item OSS
http://www.opensound.com
\begin{itemize}
\item Any OSS compatible full-duplex sound card
\end{itemize}
\end{itemize}

7
doc/tex/ices.tex Normal file
View File

@@ -0,0 +1,7 @@
The advent of icecast into Asterisk allows you to do neat things like have
a caller stream right into an ice-cast stream as well as using chan\_local
to place things like conferences, music on hold, etc. into the stream.
You'll need to specify a config file for the ices encoder. An example is
included in contrib/asterisk-ices.xml.

173
doc/tex/imapstorage.tex Normal file
View File

@@ -0,0 +1,173 @@
By enabling IMAP Storage, Asterisk will use native IMAP as the storage
mechanism for voicemail messages instead of using the standard file structure.
Tighter integration of Asterisk voicemail and IMAP email services allows
additional voicemail functionality, including:
\begin{itemize}
\item Listening to a voicemail on the phone will set its state to "read" in
a user's mailbox automatically.
\item Deleting a voicemail on the phone will delete it from the user's
mailbox automatically.
\item Accessing a voicemail recording email message will turn off the message
waiting indicator (MWI) on the user's phone.
\item Deleting a voicemail recording email will also turn off the message
waiting indicator, and delete the message from the voicemail system.
\end{itemize}
\subsection{Installation Notes}
\subsubsection{University of Washington IMAP C-Client}
If you do not have the University of Washington's IMAP c-client
installed on your system, you will need to download the c-client
source distribution (http://www.washington.edu/imap/) and compile it.
Asterisk supports both the 2004 and 2006 versions of c-client, however
mail\_expunge\_full is enabled in the 2006 version.
Note that Asterisk only uses the 'client' portion of the UW IMAP toolkit,
but building it also builds an IMAP server and various other utilities.
Because of this, the build instructions for the IMAP toolkit are somewhat
complicated and can lead to confusion about what is needed.
If you are going to be connecting Asterisk to an existing IMAP server,
then you don't need to care about the server or utilities in the IMAP
toolkit at all. If you want to also install the UW IMAPD server, that
is outside the scope of this document.
Building the c-client library is fairly straightforward; for example, on a
Debian system there are two possibilities:
\begin{verbatim}
1) if you will not be using SSL to connect to the IMAP server:
$ make slx SSLTYPE=none
2) if you will be using SSL to connect to the IMAP server:
$ make slx EXTRACFLAGS="-I/usr/include/openssl"
\end{verbatim}
Once this completes you can proceed with the Asterisk build; there is no
need to run 'make install'.
\subsubsection{Compiling Asterisk}
To use the system c-client library, configure Asterisk with
./configure --with-imap=system. If you downloaded the c-client source
and compiled it according to the above instructions, configure
Asterisk with with ./configure --with-imap=/usr/src/imap or where ever
you built the UWashington IMAP Toolkit. When you run 'make
menuselect', choose 'Voicemail Build Options' and the IMAP\_STORAGE
option should be available for selection.
After selecting the IMAP\_STORAGE option, use the 'x' key to exit
menuselect and save your changes, and the build/install Asterisk
normally.
\subsection{Modify voicemail.conf}
The following directives have been added to voicemail.conf:
\begin{verbatim}
imapserver=<name or IP address of IMAP mail server>
imapport=<IMAP port, defaults to 143>
imapflags=<IMAP flags, "novalidate-cert" for example>
expungeonhangup=<yes or no>
authuser=<username>
authpassword=<password>
\end{verbatim}
The "expungeonhangup" flag is used to determine if the voicemail system should
expunge all messages marked for deletion when the user hangs up the phone.
Each mailbox definition should also have imapuser=<imap username>.
For example:
\begin{verbatim}
4123=>4123,James Rothenberger,jar@onebiztone.com,,attach=yes|imapuser=jar
\end{verbatim}
The directives "authuser" and "authpassword" are not needed when using
Kerberos. They are defined to allow Asterisk to authenticate as a single
user that has access to all mailboxes as an alternative to Kerberos.
\subsection{IMAP Folders}
Besides INBOX, users should create "Old", "Work", "Family" and "Friends"
IMAP folders at the same level of hierarchy as the INBOX. These will be
used as alternate folders for storing voicemail messages to mimic the
behavior of the current (file-based) voicemail system.
\subsection{Separate vs. Shared Email Accounts}
As administrator you will have to decide if you want to send the voicemail
messages to a separate IMAP account or use each user's existing IMAP mailbox
for voicemail storage. The IMAP storage mechanism will work either way.
By implementing a single IMAP mailbox, the user will see voicemail messages
appear in the same INBOX as other messages. The disadvantage of this method
is that if the IMAP server does NOT support UIDPLUS, Asterisk voicemail will
expunge ALL messages marked for deletion when the user exits the voicemail
system, not just the VOICEMAIL messages marked for deletion.
By implementing separate IMAP mailboxes for voicemail and email, voicemail
expunges will not remove regular email flagged for deletion.
\subsection{IMAP Server Implementations}
There are various IMAP server implementations, each supports a potentially
different set of features.
\subsubsection{UW IMAP-2005 or earlier}
UIDPLUS is currently NOT supported on these versions of UW-IMAP. Please note
that without UID\_EXPUNGE, Asterisk voicemail will expunge ALL messages marked
for deletion when a user exits the voicemail system (hangs up the phone).
\subsubsection{UW IMAP-2006 Development Branch}
This version supports UIDPLUS, which allows UID\_EXPUNGE capabilities. This
feature allow the system to expunge ONLY pertinent messages, instead of the
default behavior, which is to expunge ALL messages marked for deletion when
EXPUNGE is called. The IMAP storage mechanism is this version of Asterisk
will check if the UID\_EXPUNGE feature is supported by the server, and use it
if possible.
\subsubsection{Cyrus IMAP}
Cyrus IMAP server v2.3.3 has been tested using a hierarchy delimiter of '/'.
\subsection{Quota Support}
If the IMAP server supports quotas, Asterisk will check the quota when
accessing voicemail. Currently only a warning is given to the user that
their quota is exceeded.
\subsection{Application Notes}
Since the primary storage mechanism is IMAP, all message information that
was previously stored in an associated text file, AND the recording itself,
is now stored in a single email message. This means that the .gsm recording
will ALWAYS be attached to the message (along with the user's preference of
recording format if different - ie. .WAV). The voicemail message information
is stored in the email message headers. These headers include:
\begin{verbatim}
X-Asterisk-VM-Message-Num
X-Asterisk-VM-Server-Name
X-Asterisk-VM-Context
X-Asterisk-VM-Extension
X-Asterisk-VM-Priority
X-Asterisk-VM-Caller-channel
X-Asterisk-VM-Caller-ID-Num
X-Asterisk-VM-Caller-ID-Name
X-Asterisk-VM-Duration
X-Asterisk-VM-Category
X-Asterisk-VM-Orig-date
X-Asterisk-VM-Orig-time
\end{verbatim}

98
doc/tex/jitterbuffer.tex Normal file
View File

@@ -0,0 +1,98 @@
\subsubsection{The new jitterbuffer}
You must add "jitterbuffer=yes" to either the [general] part of
iax.conf, or to a peer or a user. (just like the old jitterbuffer).
Also, you can set "maxjitterbuffer=n", which puts a hard-limit on the size of the
jitterbuffer of "n milliseconds". It is not necessary to have the new jitterbuffer
on both sides of a call; it works on the receive side only.
\subsubsection{PLC}
The new jitterbuffer detects packet loss. PLC is done to try to recreate these
lost packets in the codec decoding stage, as the encoded audio is translated to slinear.
PLC is also used to mask jitterbuffer growth.
This facility is enabled by default in iLBC and speex, as it has no additional cost.
This facility can be enabled in adpcm, alaw, g726, gsm, lpc10, and ulaw by setting
genericplc => true in the [plc] section of codecs.conf.
\subsubsection{Trunktimestamps}
To use this, both sides must be using Asterisk v1.2 or later.
Setting "trunktimestamps=yes" in iax.conf will cause your box to send 16-bit timestamps
for each trunked frame inside of a trunk frame. This will enable you to use jitterbuffer
for an IAX2 trunk, something that was not possible in the old architecture.
The other side must also support this functionality, or else, well, bad things will happen.
If you don't use trunktimestamps, there's lots of ways the jitterbuffer can get confused because
timestamps aren't necessarily sent through the trunk correctly.
\subsubsection{Communication with Asterisk v1.0.x systems}
You can set up communication with v1.0.x systems with the new jitterbuffer, but
you can't use trunks with trunktimestamps in this communication.
If you are connecting to an Asterisk server with earlier versions of the software (1.0.x),
do not enable both jitterbuffer and trunking for the involved peers/users
in order to be able to communicate. Earlier systems will not support trunktimestamps.
You may also compile chan\_iax2.c without the new jitterbuffer, enabling the old
backwards compatible architecture. Look in the source code for instructions.
\subsubsection{Testing and monitoring}
You can test the effectiveness of PLC and the new jitterbuffer's detection of loss by using
the new CLI command "iax2 test losspct <n>". This will simulate n percent packet loss
coming \_in\_ to chan\_iax2. You should find that with PLC and the new JB, 10 percent packet
loss should lead to just a tiny amount of distortion, while without PLC, it would lead to
silent gaps in your audio.
"iax2 show netstats" shows you statistics for each iax2 call you have up.
The columns are "RTT" which is the round-trip time for the last PING, and then a bunch of s
tats for both the local side (what you're receiving), and the remote side (what the other
end is telling us they are seeing). The remote stats may not be complete if the remote
end isn't using the new jitterbuffer.
The stats shown are:
\begin{itemize}
\item Jit: The jitter we have measured (milliseconds)
\item Del: The maximum delay imposed by the jitterbuffer (milliseconds)
\item Lost: The number of packets we've detected as lost.
\item \%: The percentage of packets we've detected as lost recently.
\item Drop: The number of packets we've purposely dropped (to lower latency).
\item OOO: The number of packets we've received out-of-order
\item Kpkts: The number of packets we've received / 1000.
\end{itemize}
\subsubsection{Reporting problems}
There's a couple of things that can make calls sound bad using the jitterbuffer:
\begin{enumerate}
\item The JB and PLC can make your calls sound better, but they can't fix everything.
If you lost 10 frames in a row, it can't possibly fix that. It really can't help much
more than one or two consecutive frames.
\item Bad timestamps: If whatever is generating timestamps to be sent to you generates
nonsensical timestamps, it can confuse the jitterbuffer. In particular, discontinuities
in timestamps will really upset it: Things like timestamps sequences which go 0, 20, 40,
60, 80, 34000, 34020, 34040, 34060... It's going to think you've got about 34 seconds
of jitter in this case, etc..
The right solution to this is to find out what's causing the sender to send us such nonsense,
and fix that. But we should also figure out how to make the receiver more robust in
cases like this.
chan\_iax2 will actually help fix this a bit if it's more than 3 seconds or so, but at
some point we should try to think of a better way to detect this kind of thing and
resynchronize.
Different clock rates are handled very gracefully though; it will actually deal with a
sender sending 20\% faster or slower than you expect just fine.
\item Really strange network delays: If your network "pauses" for like 5 seconds, and then
when it restarts, you are sent some packets that are 5 seconds old, we are going to see
that as a lot of jitter. We already throw away up to the worst 20 frames like this,
though, and the "maxjitterbuffer" parameter should put a limit on what we do in this case.
\end{enumerate}

49
doc/tex/localchannel.tex Normal file
View File

@@ -0,0 +1,49 @@
\subsection{Introduction}
chan\_local is a pseudo-channel. Use of this channel simply loops calls back into the dialplan in a different context. Useful for recursive routing.
\subsection{Syntax}
\begin{verbatim}
Local/extension@context[/n]
\end{verbatim}
Adding "/n" at the end of the string will make the Local channel not do a native transfer (the "n" stands for "n"o release) upon the remote end answering the line. This is an esoteric, but important feature if you expect the Local channel to handle calls exactly like a normal channel. If you do not have the "no release" feature set, then as soon as the destination (inside of the Local channel) answers the line, the variables and dial plan will revert back to that of the original call, and the Local channel will become a zombie and be removed from the active channels list. This is desirable in some circumstances, but can result in unexpected dialplan behavior if you are doing fancy things with variables in your call handling.
\subsection{Purpose}
The Local channel construct can be used to establish dialing into any part of the dialplan.
Imagine you have a TE410P in your box. You want to do something for which you must use a Dial statement (for instance when dropping files in /var/spool/outgoing) but you do want to be able to use your dialplans least-cost-routes or other intelligent stuff. What you could do before we had chan\_local was create a cross-link between two ports of the TE410P and then Dial out one port and in the other. This way you could control where the call was going.
Of course, this was a nasty hack, and to make it more sensible, chan\_local was built.
The "Local" channel driver allows you to convert an arbitrary extension into a channel. It is used in a variety of places, including agents, etc.
This also allows us to hop to contexts like a GoSub routine; See examples below.
\subsection{Examples}
\begin{verbatim}
[inbound] ; here falls all incoming calls
exten => s,1,Answer
exten => s,2,Dial(local/200@internal,30,r)
exten => s,3,Playback(sorrynoanswer)
exten => s,4,Hangup
[internal] ; here where our phones falls for default
exten => 200,1,Dial(sip/blah)
exten => 200,102,VoiceMail(${EXTEN}@default)
exten => 201,1,Dial(zap/1)
exten => 201,102,VoiceMail(${EXTEN}@default)
exten => _0.,1,Dial(Zap/g1/${EXTEN:1}) ; outgoing calls with 0+number
\end{verbatim}
\subsection{Caveats}
If you use chan\_local from a call-file and you want to pass channel variables into your context, make sure you append the '/n', because otherwise chan\_local will 'optimize' itself out of the call-path, and the variables will get lost. i.e.
\begin{verbatim}
Local/00531234567@pbx becomes Local/00531234567@pbx/n
\end{verbatim}

250
doc/tex/manager.tex Normal file
View File

@@ -0,0 +1,250 @@
\section{The Asterisk Manager TCP/IP API}
The manager is a client/server model over TCP. With the manager interface,
you'll be able to control the PBX, originate calls, check mailbox status,
monitor channels and queues as well as execute Asterisk commands.
AMI is the standard management interface into your Asterisk server.
You configure AMI in manager.conf. By default, AMI is available on
TCP port 5038 if you enable it in manager.conf.
AMI receive commands, called "actions". These generate a "response"
from Asterisk. Asterisk will also send "Events" containing various
information messages about changes within Asterisk. Some actions
generate an initial response and data in the form list of events.
This format is created to make sure that extensive reports do not
block the manager interface fully.
Management users are configured in the configuration file manager.conf and are
given permissions for read and write, where write represents their ability
to perform this class of "action", and read represents their ability to
receive this class of "event".
If you develop AMI applications, treat the headers
in Actions, Events and Responses as local to that particular
message. There is no cross-message standardization of headers.
If you develop applications, please try to reuse existing manager
headers and their interpretation. If you are unsure, discuss on
the asterisk-dev mailing list.
\section{Device status reports}
Manager subscribes to extension status reports from all channels,
to be able to generate events when an extension or device changes
state. The level of details in these events may depend on the channel
and device configuration. Please check each channel configuration
file for more information. (in sip.conf, check the section on
subscriptions and call limits)
\section{Command Syntax}
Management communication consists of tags of the form "header: value",
terminated with an empty newline (\\r\\n) in the style of SMTP, HTTP, and
other headers.
The first tag MUST be one of the following:
\begin{itemize}
\item Action: An action requested by the CLIENT to the Asterisk SERVER. Only one "Action" may be outstanding at any time.
\item Response: A response to an action from the Asterisk SERVER to the CLIENT.
\item Event: An event reported by the Asterisk SERVER to the CLIENT
\end{itemize}
\section{Manager commands}
To see all of the available manager commands, use the "manager show commands"
CLI command.
You can get more information about a manager command
with the "manager show command <command>" CLI command in Asterisk.
\section{Examples}
\begin{verbatim}
Login - Log a user into the manager interface.
Action: Login
Username: testuser
Secret: testsecret
Originate - Originate a call from a channel to an extension.
Action: Originate
Channel: sip/12345
Exten: 1234
Context: default
Originate - Originate a call from a channel to an extension without waiting
for call to complete.
Action: Originate
Channel: sip/12345
Exten: 1234
Context: default
Async: yes
Redirect with ExtraChannel:
Attempted goal:
Have a 'robot' program Redirect both ends of an already-connected call
to a meetme room using the ExtraChannel feature through the management interface.
Action: Redirect
Channel: Zap/1-1
ExtraChannel: SIP/3064-7e00 (varies)
Exten: 680
Priority: 1
Where 680 is an extension that sends you to a MeetMe room.
\end{verbatim}
There are a number of GUI tools that use the manager interface, please search
the mailing list archives and the documentation page on the
http://www.asterisk.org web site for more information.
\section{Some standard AMI headers}
\begin{verbatim}
Account: -- Account Code (Status)
AccountCode: -- Account Code (cdr_manager)
ACL: <Y | N> -- Does ACL exist for object ?
Action: <action> -- request or notification of a particular action
Address-IP: -- IPaddress
Address-Port: -- IP port number
Agent: <string> -- Agent name
AMAflags: -- AMA flag (cdr_manager, sippeers)
AnswerTime: -- Time of answer (cdr_manager)
Append: <bool> -- CDR userfield Append flag
Application: -- Application to use
Async: -- Whether or not to use fast setup
AuthType: -- Authentication type (for login or challenge)
"md5"
BillableSeconds: -- Billable seconds for call (cdr_manager)
CallerID: -- Caller id (name and number in Originate & cdr_manager)
CallerID: -- CallerID number
Number or "<unknown>" or "unknown"
(should change to "<unknown>" in app_queue)
CallerID1: -- Channel 1 CallerID (Link event)
CallerID2: -- Channel 2 CallerID (Link event)
CallerIDName: -- CallerID name
Name or "<unknown>" or "unknown"
(should change to "<unknown>" in app_queue)
Callgroup: -- Call group for peer/user
CallsTaken: <num> -- Queue status variable
Cause: <value> -- Event change cause - "Expired"
Cause: <value> -- Hangupcause (channel.c)
CID-CallingPres: -- Caller ID calling presentation
Channel: <channel> -- Channel specifier
Channel: <dialstring> -- Dialstring in Originate
Channel: <tech/[peer/username]> -- Channel in Registry events (SIP, IAX2)
Channel: <tech> -- Technology (SIP/IAX2 etc) in Registry events
ChannelType: -- Tech: SIP, IAX2, ZAP, MGCP etc
Channel1: -- Link channel 1
Channel2: -- Link channel 2
ChanObjectType: -- "peer", "user"
Codecs: -- Codec list
CodecOrder: -- Codec order, separated with comma ","
Command: -- Cli command to run
Context: -- Context
Count: <num> -- Number of callers in queue
Data: -- Application data
Default-addr-IP: -- IP address to use before registration
Default-Username: -- Username part of URI to use before registration
Destination: -- Destination for call (Dialstring ) (dial, cdr_manager)
DestinationContext: -- Destination context (cdr_manager)
DestinationChannel: -- Destination channel (cdr_manager)
DestUniqueID: -- UniqueID of destination (dial event)
Disposition: -- Call disposition (CDR manager)
Domain: <domain> -- DNS domain
Duration: <secs> -- Duration of call (cdr_manager)
Dynamic: <Y | N> -- Device registration supported?
Endtime: -- End time stamp of call (cdr_manager)
EventList: <flag> -- Flag being "Start", "End", "Cancelled" or "ListObject"
Events: <eventmask> -- Eventmask filter ("on", "off", "system", "call", "log")
Exten: -- Extension (Redirect command)
Extension: -- Extension (Status)
Family: <string> -- ASTdb key family
File: <filename> -- Filename (monitor)
Format: <format> -- Format of sound file (monitor)
From: <time> -- Parking time (ParkedCall event)
Hint: -- Extension hint
Incominglimit: -- SIP Peer incoming limit
Key:
Key: -- ASTdb Database key
LastApplication: -- Last application executed (cdr_manager)
LastCall: <num> -- Last call in queue
LastData: -- Data for last application (cdr_manager)
Link: -- (Status)
ListItems: <number> -- Number of items in Eventlist (Optionally sent in "end" packet)
Location: -- Interface (whatever that is -maybe tech/name in app_queue )
Loginchan: -- Login channel for agent
Logintime: <number> -- Login time for agent
Mailbox: -- VM Mailbox (id@vmcontext) (mailboxstatus, mailboxcount)
MD5SecretExist: <Y | N> -- Whether secret exists in MD5 format
Membership: <string> -- "Dynamic" or "static" member in queue
Message: <text> -- Text message in ACKs, errors (explanation)
Mix: <bool> -- Boolean parameter (monitor)
NewMessages: <count> -- Count of new Mailbox messages (mailboxcount)
Newname:
ObjectName: -- Name of object in list
OldName: -- Something in Rename (channel.c)
OldMessages: <count> -- Count of old mailbox messages (mailboxcount)
Outgoinglimit: -- SIP Peer outgoing limit
Paused: <num> -- Queue member paused status
Peer: <tech/name> -- "channel" specifier :-)
PeerStatus: <tech/name> -- Peer status code
"Unregistered", "Registered", "Lagged", "Reachable"
Penalty: <num> -- Queue penalty
Priority: -- Extension priority
Privilege: <privilege> -- AMI authorization class (system, call, log, verbose, command, agent, user)
Pickupgroup: -- Pickup group for peer
Position: <num> -- Position in Queue
Queue: -- Queue name
Reason: -- "Autologoff"
Reason: -- "Chanunavail"
Response: <response> -- response code, like "200 OK"
"Success", "Error", "Follows"
Restart: -- "True", "False"
RegExpire: -- SIP registry expire
RegExpiry: -- SIP registry expiry
Reason: -- Originate reason code
Seconds: -- Seconds (Status)
Secret: <password> -- Authentication secret (for login)
SecretExist: <Y | N> -- Whether secret exists
Shutdown: -- "Uncleanly", "Cleanly"
SIP-AuthInsecure:
SIP-FromDomain: -- Peer FromDomain
SIP-FromUser: -- Peer FromUser
SIP-NatSupport:
SIPLastMsg:
Source: -- Source of call (dial event, cdr_manager)
SrcUniqueID: -- UniqueID of source (dial event)
StartTime: -- Start time of call (cdr_manager)
State: -- Channel state
Status: -- Registration status (Registry events SIP)
Status: -- Extension status (Extensionstate)
Status: -- Peer status (if monitored) ** Will change name **
"unknown", "lagged", "ok"
Status: <num> -- Queue Status
Status: -- DND status (DNDState)
Time: <sec> -- Roundtrip time (latency)
Timeout: -- Parking timeout time
Timeout: -- Timeout for call setup (Originate)
Timeout: <seconds> -- Timeout for call
Uniqueid: -- Channel Unique ID
Uniqueid1: -- Channel 1 Unique ID (Link event)
Uniqueid2: -- Channel 2 Unique ID (Link event)
User: -- Username (SIP registry)
UserField: -- CDR userfield (cdr_manager)
Val: -- Value to set/read in ASTdb
Variable: -- Variable AND value to set (multiple separated with | in Originate)
Variable: <name> -- For channel variables
Value: <value> -- Value to set
VoiceMailbox: -- VM Mailbox in SIPpeers
Waiting: -- Count of mailbox messages (mailboxstatus)
\end{verbatim}
** Please try to re-use existing headers to simplify manager message parsing in clients.
Read the CODING-GUIDELINES if you develop new manager commands or events.

266
doc/tex/misdn.tex Normal file
View File

@@ -0,0 +1,266 @@
\subsection{Introduction}
This package contains the mISDN Channel Driver for the Asterisk PBX. It
supports every mISDN Hardware and provides an interface for asterisk.
\subsection{Features}
\begin{itemize}
\item NT and TE mode
\item PP and PMP mode
\item BRI and PRI (with BNE1 and BN2E1 Cards)
\item Hardware Bridging
\item DTMF Detection in HW+mISDNdsp
\item Display Messages on Phones (on those that support display msg)
\item app\_SendText
\item HOLD/RETRIEVE/TRANSFER on ISDN Phones : )
\item Screen/ Not Screen User Number
\item EchoCancellation
\item Volume Control
\item Crypting with mISDNdsp (Blowfish)
\item Data (HDLC) callthrough
\item Data Calling (with app\_ptyfork +pppd)
\item Echo cancellation
\item CallDeflection
\item Some other
\end{itemize}
\subsection{Fast Installation Guide}
It is easy to install mISDN and mISDNuser. Just fetch the newest head of the
cvs, this can be done by:
\begin{verbatim}
cvs -d:pserver:anonymous:readonly@cvs.isdn4linux.de:/i4ldev co mISDN mISDNuser
\end{verbatim}
then compile and install both with:
\begin{verbatim}
cd mISDN ;
make && make install
\end{verbatim}
(you will need at least your kernel headers to compile mISDN).
\begin{verbatim}
cd mISDNuser ;
make && make install
\end{verbatim}
Now you can compile chan\_misdn, just by making asterisk:
\begin{verbatim}
cd asterisk ;
./configure && make && make install
\end{verbatim}
That's all!
Follow the instructions in the mISDN Package for how to load the Kernel
Modules.
\subsection{Pre-Requisites}
To compile and install this driver, you'll need at least one mISDN Driver and
the mISDNuser package. Chan\_misdn works with both, the current release version
and the development (svn trunk) version of Asterisk. mISDNuser and mISDN must
be fetched from cvs.isdn4linux.de.
You should use Kernels >= 2.6.9
\subsection{Configuration}
First of all you must configure the mISDN drivers, please follow the
instructions in the mISDN package to do that, the main config file and config
script is:
\begin{verbatim}
/etc/init.d/misdn-init and
/etc/misdn-init.conf
\end{verbatim}
Now you will want to configure the misdn.conf file which resides in the
asterisk config directory (normally /etc/asterisk).
\subsubsection{misdn.conf: [general]}
The misdn.conf file contains a "general" subsection, and user subsections which
contain misdn port settings and different Asterisk contexts.
In the general subsection you can set options that are not directly port
related. There is for example the very important debug variable which you can
set from the Asterisk cli (command line interface) or in this configuration
file, bigger numbers will lead to more debug output. There's also a tracefile
option, which takes a path+filename where debug output is written to.
\subsubsection{misdn.conf: [default] subsection}
The default subsection is another special subsection which can contain all the
options available in the user/port subsections. the user/port subsection inherit
their parameters from the default subsection.
\subsubsection{misdn.conf: user/port subsections}
The user subsections have names which are unequal to "general". Those subsections
contain the ports variable which mean the mISDN Ports. Here you can add
multiple ports, comma separated.
Espacially for TE-Mode Ports there is a msns option. This option tells the
chan\_misdn driver to listen for incoming calls with the given msns, you can
insert a '*' as single msn, which leads in getting every incoming call (if you
want to share on PMP TE S0 with a asterisk and a phone or isdn card you should
insert here the msns which you'll like to give the Asterisk). Finally a
context variable resides in the user subsections, which tells chan\_misdn where to
send incoming calls to in the Asterisk dial plan (extension.conf).
\subsubsection{Dial and Options String}
The dial string of chan\_misdn got more complex, because we added more features,
so the generic dial string looks like:
\begin{verbatim}
mISDN/<port>|g:<group>/<extension>[/<OPTIONSSTRING>]
The Optionsstring looks Like:
:<optchar1><OptParam1>:<optchar2><OptParam2>
the ":" character is the delimiter.
The available Optchars are:
d - Send display text on called phone, text is the optparam
n - don't detect dtmf tones on called channel
h - make digital outgoing call
c - make crypted outgoing call, param is keyindex
e - perform echo cancellation on this channel,
takes taps as arguments (32,64,128,256)
s - send Non Inband DTMF as inband
vr - rxgain control
vt - txgain control
\end{verbatim}
chan\_misdn registers a new dial plan application "misdn\_set\_opt" when
loaded. This application takes the Optionsstring as argument. The Syntax is:
\begin{verbatim}
misdn_set_opt(<OPTIONSSTRING>)
\end{verbatim}
When you set options in the dialstring, the options are set in the external
channel. When you set options with misdn\_set\_opt, they are set in the current
incoming channel. So if you like to use static encryption, the scenario looks
as follows:
\begin{verbatim}
Phone1 --> * Box 1 --> PSTN_TE
PSTN_TE --> * Box 2 --> Phone2
\end{verbatim}
The Encryption must be done on the PSTN sides, so the dialplan on the boxes
are:
\begin{verbatim}
* Box 1:
exten => _${CRYPT_PREFIX}X.,1,Dial(mISDN/g:outbound/:c1)
* Box 2:
exten => ${CRYPT_MSN},1,misdn_set_opt(:c1)
exten => ${CRYPT_MSN},2,dial(${PHONE2})
\end{verbatim}
\subsection{mISDN CLI commands}
At the Asterisk cli you can try to type in:
\begin{verbatim}
misdn <tab> <tab>
\end{verbatim}
Now you should see the misdn cli commands:
\begin{verbatim}
- clean
-> pid (cleans a broken call, use with care, leads often
to a segmentation fault)
- send
-> display (sends a Text Message to a Asterisk channel,
this channel must be an misdn channel)
- set
-> debug (sets debug level)
- show
-> config (shows the configuration options)
-> channels (shows the current active misdn channels)
-> channel (shows details about the given misdn channels)
-> stacks (shows the current ports, their protocols and states)
-> fullstacks (shows the current active and inactive misdn channels)
- restart
-> port (restarts given port (L2 Restart) )
- reload (reloads misdn.conf)
\end{verbatim}
You can only use "misdn send display" when an Asterisk channel is created and
isdn is in the correct state. "correct state" means that you have established a
call to another phone (mustn't be isdn though).
Then you use it like this:
misdn send display mISDN/1/101 "Hello World!"
where 1 is the Port of the Card where the phone is plugged in, and 101 is the
msn (callerid) of the Phone to send the text to.
\subsection{mISDN Variables}
mISDN Exports/Imports a few Variables:
\begin{verbatim}
- MISDN_ADDRESS_COMPLETE : Is either set to 1 from the Provider, or you
can set it to 1 to force a sending complete.
\end{verbatim}
\subsection{Debugging and sending bug reports}
If you encounter problems, you should set up the debugging flag, usually
debug=2 should be enough. the messages are divided in asterisk and misdn
parts. Misdn Debug messages begin with an 'I', asterisk messages begin with
an '*', the rest is clear I think.
Please take a trace of the problem and open a report in the Asterisk issue
tracker at http://bugs.digium.com in the "channel drivers" project,
"chan\_misdn" category. Read the bug guidelines to make sure you
provide all the information needed.
\subsection{Examples}
Here are some examples of how to use chan\_misdn in the dialplan
(extensions.conf):
\begin{verbatim}
[globals]
OUT_PORT=1 ; The physical Port of the Card
OUT_GROUP=ExternE1 ; The Group of Ports defined in misdn.conf
[misdnIn]
exten => _X.,1,Dial(mISDN/${OUT_PORT}/${EXTEN})
exten => _0X.,1,Dial(mISDN/g:${OUT_GROUP}/${EXTEN:1})
exten => _1X.,1,Dial(mISDN/g:${OUT_GROUP}/${EXTEN:1}/:dHello)
exten => _1X.,1,Dial(mISDN/g:${OUT_GROUP}/${EXTEN:1}/:dHello Test:n)
\end{verbatim}
On the last line, you will notice the last argument (Hello); this is sent
as Display Message to the Phone.
\subsection{Known Problems}
\begin{verbatim}
* I cannot hear any tone after a successful CONNECT to the other end
-> you forgot to load mISDNdsp, which is now needed by chan\_misdn for switching
and dtmf tone detection
\end{verbatim}

11
doc/tex/mp3.tex Normal file
View File

@@ -0,0 +1,11 @@
\subsubsection{MP3 Music On Hold}
Use of the mpg123 for your music on hold is no longer recommended and is now
officially deprecated. You should now use one of the native formats for your
music on hold selections.
However, if you still need to use mp3 as your music on hold format, a format
driver for reading MP3 audio files is available in the asterisk-addons SVN
repository on svn.digium.com or in the asterisk-addons release at
ftp://ftp.digium.com/pub/telephony/asterisk/.

29
doc/tex/odbcstorage.tex Normal file
View File

@@ -0,0 +1,29 @@
ODBC Storage allows you to store voicemail messages within a database
instead of using a file. This is *not* a full realtime engine and
*only* supports ODBC. The table description for the "voicemessages"
table is as follows:
\begin{verbatim}
+----------------+-------------+------+-----+---------+-------+
| Field | Type | Null | Key | Default | Extra |
+----------------+-------------+------+-----+---------+-------+
| msgnum | int(11) | YES | | NULL | |
| dir | varchar(80) | YES | MUL | NULL | |
| context | varchar(80) | YES | | NULL | |
| macrocontext | varchar(80) | YES | | NULL | |
| callerid | varchar(40) | YES | | NULL | |
| origtime | varchar(40) | YES | | NULL | |
| duration | varchar(20) | YES | | NULL | |
| mailboxuser | varchar(80) | YES | | NULL | |
| mailboxcontext | varchar(80) | YES | | NULL | |
| recording | longblob | YES | | NULL | |
+----------------+-------------+------+-----+---------+-------+
\end{verbatim}
The database name (from /etc/asterisk/res\_odbc.conf) is in the
"odbcstorage" variable in the general section of voicemail.conf.
You may modify the voicemessages table name by using
odbctable=??? in voicemail.conf.

343
doc/tex/privacy.tex Normal file
View File

@@ -0,0 +1,343 @@
So, you want to avoid talking to pesky telemarketers/charity
seekers/poll takers/magazine renewers/etc?
\subsection{First of all}
Try the FTC "Don't call" database, this alone will reduce your
telemarketing call volume considerably. (see:
https://www.donotcall.gov/default.aspx ) But, this list won't protect
from the Charities, previous business relationships, etc.
\subsection{Next, Fight against autodialers!!}
Zapateller detects if callerid is present, and if not, plays the
da-da-da tones that immediately precede messages like, "I'm sorry,
the number you have called is no longer in service."
Most humans, even those with unlisted/callerid-blocked numbers, will
not immediately slam the handset down on the hook the moment they hear
the three tones. But autodialers seem pretty quick to do this.
I just counted 40 hangups in Zapateller over the last year in my
CDR's. So, that is possibly 40 different telemarketers/charities that have
hopefully slashed my back-waters, out-of-the-way, humble home phone
number from their lists.
I highly advise Zapateller for those seeking the nirvana of "privacy".
\subsection{Next, Fight against the empty CALLERID!}
A considerable percentage of the calls you don't want, come from
sites that do not provide CallerID.
Null callerid's are a fact of life, and could be a friend with an
unlisted number, or some charity looking for a handout. The
PrivacyManager application can help here. It will ask the caller to
enter a 10-digit phone number. They get 3 tries(configurable), and this is
configurable, with control being passed to priority+101 if they won't
supply one.
PrivacyManager can't guarantee that the number they supply is any
good, tho, as there is no way to find out, short of hanging up and
calling them back. But some answers are obviously wrong. For instance,
it seems a common practice for telemarketers to use your own number
instead of giving you theirs. A simple test can detect this. More
advanced tests would be to look for -555- numbers, numbers that count
up or down, numbers of all the same digit, etc.
My logs show that 39 have hung up in the PrivacyManager script over
the last year.
(Note: Demanding all unlisted incoming callers to enter their CID may
not always be appropriate for all users. Another option might be to
use call screening. See below.)
\subsection{Next, use a WELCOME MENU !}
Experience has shown that simply presenting incoming callers with
a set of options, no matter how simple, will deter them from calling
you. In the vast majority of situations, a telemarketer will simply
hang up rather than make a choice and press a key.
This will also immediately foil all autodialers that simply belch a
message in your ear and hang up.
\subsubsection{Example usage of Zapateller and PrivacyManager}
\begin{verbatim}
[homeline]
exten => s,1,Answer
exten => s,2,SetVar,repeatcount=0
exten => s,3,Zapateller,nocallerid
exten => s,4,PrivacyManager
exten => s,105,Background(tt-allbusy) ;; do this if they don't enter a number to Privacy Manager
exten => s,106,Background(tt-somethingwrong)
exten => s,107,Background(tt-monkeysintro)
exten => s,108,Background(tt-monkeys)
exten => s,109,Background(tt-weasels)
exten => s,110,Hangup
exten => s,5,GotoIf($[ "${CALLERIDNUM}" = "7773334444" & "${CALLERIDNAME}" : "Privacy Manager" ]?callerid-liar|s|1:s|7)
\end{verbatim}
I suggest using Zapateller at the beginning of the context, before
anything else, on incoming calls.This can be followed by the
PrivacyManager App.
Make sure, if you do the PrivacyManager app, that you take care of the
error condition! or their non-compliance will be rewarded with access
to the system. In the above, if they can't enter a 10-digit number in
3 tries, they get the humorous "I'm sorry, but all household members
are currently helping other telemarketers...", "something is terribly
wrong", "monkeys have carried them away...", various loud monkey
screechings, "weasels have...", and a hangup. There are plenty of
other paths to my torture scripts, I wanted to have some fun.
In nearly all cases now, the telemarketers/charity-seekers that
usually get thru to my main intro, hang up. I guess they can see it's
pointless, or the average telemarketer/charity-seeker is instructed
not to enter options when encountering such systems. Don't know.
\subsection{Next: Torture Them!}
I have developed an elaborate script to torture Telemarketers, and
entertain friends. (See
http://www.voip-info.org/wiki-Asterisk+Telemarketer+Torture )
While mostly those that call in and traverse my teletorture scripts
are those we know, and are doing so out of curiosity, there have been
these others from Jan 1st,2004 thru June 1st, 2004:
(the numbers may or may not be correct.)
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.
That averages out to maybe 1 a month. That puts into question whether
the ratio of the amount of labor it took to make the scripts versus
the benefits of lower call volumes was worth it, but, well, I had fun,
so what the heck.
but, that's about it. Not a whole lot. But I haven't had to say "NO"
or "GO AWAY" to any of these folks for about a year now ...!
\subsection{Using Call Screening}
Another option is to use call screening in the Dial command. It has
two main privacy modes, one that remembers the CID of the caller, and
how the callee wants the call handled, and the other, which does not
have a "memory".
Turning on these modes in the dial command results in this sequence of
events, when someone calls you at an extension:
\begin{enumerate}
\item The caller calls the Asterisk system, and at some point, selects an
option or enters an extension number that would dial your extension.
\item Before ringing your extension, the caller is asked to supply an
introduction. The application asks them: "After the tone, say your
name". They are allowed 4 seconds of introduction.
\item After that, they are told "Hang on, we will attempt to connect you
to your party. Depending on your dial options, they will hear ringing
indications, or get music on hold. I suggest music on hold.
\item Your extension is then dialed. When (and if) you pick up, you are
told that a caller presenting themselves as <their recorded intro is
played> is calling, and you have options, like being connected,
sending them to voicemail, torture, etc.
\item You make your selection, and the call is handled as you chose.
\end{enumerate}
There are some variations, and these will be explained in due course.
To use these options, set your Dial to something like:
\begin{verbatim}
exten => 3,3,Dial(Zap/5r3&Zap/6r3|35|tmPA(beep))
or
exten => 3,3,Dial(Zap/5r3&Zap/6r3|35|tmP(something)A(beep))
or
exten => 3,3,Dial(Zap/5r3&Zap/6r3|35|tmpA(beep))
\end{verbatim}
The 't' allows the dialed party to transfer the call using '\#'. It's
optional.
The 'm' is for music on hold. I suggest it. Otherwise, the calling
party gets to hear all the ringing, and lack thereof. It is generally
better to use Music On Hold. Lots of folks hang up after the 3rd or
4th ring, and you might lose the call before you can enter an option!
The 'P' option alone will database everything using the extension as a
default 'tree'. To get multiple extensions sharing the same database, use
P(some-shared-key). Also, if the same person has multiple extensions,
use P(unique-id) on all their dial commands.
Use little 'p' for screening. Every incoming call will include a
prompt for the callee's choice.
the A(beep), will generate a 'beep' that the callee will hear if they
choose to talk to the caller. It's kind of a prompt to let the callee
know that he has to say 'hi'. It's not required, but I find it
helpful.
When there is no CallerID, P and p options will always record an intro
for the incoming caller. This intro will be stored temporarily in the
/var/lib/asterisk/sounds/priv-callerintros dir, under the name
NOCALLERID\_<extension><channelname> and will be erased after the
callee decides what to do with the call.
Of course, NOCALLERID is not stored in the database. All those with no
CALLERID will be considered "Unknown".
\subsection{The 'N' and 'n' options}
Two other options exist, that act as modifiers to the privacy options
'P' and 'p'. They are 'N' and 'n'. You can enter them as dialing
options, but they only affect things if P or p are also in the
options.
'N' says, "Only screen the call if no CallerID is present". So, if a
callerID were supplied, it will come straight thru to your extension.
'n' says, "Don't save any introductions". Folks will be asked to
supply an introduction ("At the tone, say your name") every time they
call. Their introductions will be removed after the callee makes a
choice on how to handle the call. Whether the P option or the p option
is used, the incoming caller will have to supply their intro every
time they call.
\subsection{Recorded Introductions}
\subsubsection{Philosophical Side Note}
The 'P' option stores the CALLERID in the database, along with the
callee's choice of actions, as a convenience to the CALLEE, whereas
introductions are stored and re-used for the convenience of the CALLER.]
\subsubsection{Introductions}
Unless instructed to not save introductions (see the 'n' option above),
the screening modes will save the recordings of the caller's names in
the directory /var/lib/asterisk/sounds/priv-callerintros, if they have
a CallerID. Just the 10-digit callerid numbers are used as filenames,
with a ".gsm" at the end.
Having these recordings around can be very useful, however...
First of all, if a callerid is supplied, and a recorded intro for that
number is already present, the caller is spared the inconvenience of
having to supply their name, which shortens their call a bit.
Next of all, these intros can be used in voicemail, played over
loudspeakers, and perhaps other nifty things. For instance:
\begin{verbatim}
exten => s,7,System(/usr/bin/play /var/lib/asterisk/sounds/priv-callerintros/${CALLERIDNUM}.gsm&|0)
\end{verbatim}
When a call comes in at the house, the above priority gets executed,
and the callers intro is played over the phone systems speakers. This
gives us a hint who is calling.
(Note: the |0 option at the end of the System command above, is a
local mod I made to the System command. It forces a 0 result code to
be returned, whether the play command successfully completed or
not. Therefore, I don't have to ensure that the file exists or
not. While I've turned this mod into the developers, it hasn't been
incorporated yet. You might want to write an AGI or shell script to
handle it a little more intelligently)
And one other thing. You can easily supply your callers with an option
to listen to, and re-record their introductions. Here's what I did in
the home system's extensions.conf. (assume that a
Goto(home-introduction|s|1) exists somewhere in your main menu as an
option):
\begin{verbatim}
[home-introduction]
exten => s,1,Background,intro-options ;; Script: To hear your Introduction, dial 1.
;; to record a new introduction, dial 2.
;; to return to the main menu, dial 3.
;; to hear what this is all about, dial 4.
exten => 1,1,Playback,priv-callerintros/${CALLERIDNUM}
exten => 1,2,Goto(s,1)
exten => 2,1,Goto(home-introduction-record,s,1)
exten => 3,1,Goto(homeline,s,7)
exten => 4,1,Playback,intro-intro ;; Script:
;; This may seem a little strange, but it really is a neat
;; thing, both for you and for us. I've taped a short introduction
;; for many of the folks who normally call us. Using the Caller ID
;; from each incoming call, the system plays the introduction
;; for that phone number over a speaker, just as the call comes in.
;; This helps the folks
;; here in the house more quickly determine who is calling.
;; and gets the right ones to gravitate to the phone.
;; You can listen to, and record a new intro for your phone number
;; using this menu.
exten => 4,2,Goto(s,1)
exten => t,1,Goto(s,1)
exten => i,1,Background,invalid
exten => i,2,Goto(s,1)
exten => o,1,Goto(s,1)
[home-introduction-record]
exten => s,1,Background,intro-record-choices ;; Script:
;; If you want some advice about recording your
;; introduction, dial 1.
;; otherwise, dial 2, and introduce yourself after
;; the beep.
exten => 1,1,Playback,intro-record
;; Your introduction should be short and sweet and crisp.
;; Your introduction will be limited to 4 seconds.
;; This is NOT meant to be a voice mail message, so
;; please, don't say anything about why you are calling.
;; After we are done making the recording, your introduction
;; will be saved for playback.
;; If you are the only person that would call from this number,
;; please state your name. Otherwise, state your business
;; or residence name instead. For instance, if you are
;; friend of the family, say, Olie McPherson, and both
;; you and your kids might call here a lot, you might
;; say: "This is the distinguished Olie McPherson Residence!"
;; If you are the only person calling, you might say this:
;; "This is the illustrious Kermit McFrog! Pick up the Phone, someone!!"
;; If you are calling from a business, you might pronounce a more sedate introduction,like,
;; "Fritz from McDonalds calling.", or perhaps the more original introduction:
;; "John, from the Park County Morgue. You stab 'em, we slab 'em!".
;; Just one caution: the kids will hear what you record every time
;; you call. So watch your language!
;; I will begin recording after the tone.
;; When you are done, hit the # key. Gather your thoughts and get
;; ready. Remember, the # key will end the recording, and play back
;; your intro. Good Luck, and Thank you!"
exten => 1,2,Goto(2,1)
exten => 2,1,Background,intro-start
;; OK, here we go! After the beep, please give your introduction.
exten => 2,2,Background,beep
exten => 2,3,Record,priv-callerintros/${CALLERIDNUM}:gsm|4
exten => 2,4,Background,priv-callerintros/${CALLERIDNUM}
exten => 2,5,Goto(home-introduction,s,1)
exten => t,1,Goto(s,1)
exten => i,1,Background,invalid
exten => i,2,Goto(s,1)
exten => o,1,Goto(s,1)
\end{verbatim}
In the above, you'd most likely reword the messages to your liking,
and maybe do more advanced things with the 'error' conditions (i,o,t priorities),
but I hope it conveys the idea.

119
doc/tex/qos.tex Normal file
View File

@@ -0,0 +1,119 @@
\subsubsection{Introduction}
Asterisk can set the Type of Service (TOS) byte on outgoing IP packets
for various protocols. The TOS byte is used by the network to provide
some level of Quality of Service (QoS) even if the network is
congested with other traffic.
Also asterisk running on Linux can set 802.1p CoS marks in VLAN packets
for all used VoIP protocols. It is useful when you are working in switched
enviropment. For maping skb->priority and VLAN CoS mark you need to use
command "vconfig set\_egress\_map [vlan-device] [skb-priority] [vlan-qos]".
\subsubsection{SIP}
In sip.conf, there are three parameters that control the TOS settings:
"tos\_sip", "tos\_audio" and "tos\_video". tos\_sip controls what TOS SIP
call signalling packets are set to. tos\_audio controls what TOS RTP audio
packets are set to. tos\_video controls what TOS RTP video packets are
set to.
There are four parameters to control 802.1p CoS: "cos\_sip", "cos\_audio",
"cos\_video" and "cos\_text". It's behavior the same as writen above.
There is a "tos" parameter that is supported for backwards
compatibility. The tos parameter should be avoided in sip.conf
because it sets all three tos settings in sip.conf to the same value.
\subsubsection{IAX2}
In iax.conf, there is a "tos" parameter that sets the global default TOS
for IAX packets generated by chan\_iax2. Since IAX connections combine
signalling, audio, and video into one UDP stream, it is not possible
to set the TOS separately for the different types of traffic.
In iaxprov.conf, there is a "tos" parameter that tells the IAXy what TOS
to set on packets it generates. As with the parameter in iax.conf,
IAX packets generated by an IAXy cannot have different TOS settings
based upon the type of packet. However different IAXy devices can
have different TOS settings.
\subsubsection{H.323}
Also support TOS and CoS.
\subsubsection{MGCP}
Also support TOS and CoS.
\subsubsection{IP TOS values}
The allowable values for any of the tos* parameters are:
CS0, CS1, CS2, CS3, CS4, CS5, CS6, CS7, AF11, AF12, AF13,
AF21, AF22, AF23, AF31, AF32, AF33, AF41, AF42, AF43 and
ef (expedited forwarding),
The tos* parameters also take numeric values.
The lowdelay, throughput, reliability, mincost, and none values are
deprecated because they set the IP TOS using the outdated "IP
precedence" model as defined in RFC 791 and RFC 1349. They still
work in this version of Asterisk, but will be removed in future releases.
\subsubsection{802.1p CoS values}
As 802.1p uses 3 bites from VLAN header, there are parameter can take
integer values from 0 to 7.
\begin{verbatim}
===========================================
Configuration Parameter Recommended
File Setting
-------------------------------------------
sip.conf tos\_sip cs3
sip.conf tos\_audio ef
sip.conf tos\_video af41
sip.conf tos\_text af41
sip.conf cos\_sip 4
sip.conf cos\_audio 6
sip.conf cos\_video 5
sip.conf cos\_text 0
-------------------------------------------
iax.conf tos ef
iax.conf cos 6
-------------------------------------------
iaxprov.conf tos ef
-------------------------------------------
mgcp.conf tos ef
mgcp.conf cos 6
-------------------------------------------
h323.conf tos ef
h323.conf cos 6
===========================================
\end{verbatim}
\subsubsection{Reference}
IEEE 802.1Q Standard:
http://standards.ieee.org/getieee802/download/802.1Q-1998.pdf
Related protocols: IEEE 802.3, 802.2, 802.1D, 802.1Q
RFC 2474 - "Definition of the Differentiated Services Field
(DS field) in the IPv4 and IPv6 Headers", Nichols, K., et al,
December 1998.
IANA Assignments, DSCP registry
Differentiated Services Field Codepoints
http://www.iana.org/assignments/dscp-registry
To get the most out of setting the TOS on packets generated by
Asterisk, you will need to ensure that your network handles packets
with a TOS properly. For Cisco devices, see the previously mentioned
"Enterprise QoS Solution Reference Network Design Guide". For Linux
systems see the "Linux Advanced Routing \& Traffic Control HOWTO" at
<http://www.lartc.org/>.
For more information on Quality of
Service for VoIP networks see the "Enterprise QoS Solution Reference
Network Design Guide" version 3.3 from Cisco at:
<http://www.cisco.com/application/pdf/en/us/guest/netsol/ns432/c649/ccmigration\_09186a008049b062.pdf>

99
doc/tex/queuelog.tex Normal file
View File

@@ -0,0 +1,99 @@
In order to properly manage ACD queues, it is important to be able to
keep track of details of call setups and teardowns in much greater detail
than traditional call detail records provide. In order to support this,
extensive and detailed tracing of every queued call is stored in the
queue log, located (by default) in /var/log/asterisk/queue\_log.
These are the events (and associated information) in the queue log:
ABANDON(position|origposition|waittime)
The caller abandoned their position in the queue. The position is the
caller's position in the queue when they hungup, the origposition is
the original position the caller was when they first entered the
queue, and the waittime is how long the call had been waiting in the
queue at the time of disconnect.
AGENTDUMP
The agent dumped the caller while listening to the queue announcement.
AGENTLOGIN(channel)
The agent logged in. The channel is recorded.
AGENTCALLBACKLOGIN(exten@context)
The callback agent logged in. The login extension and context is recorded.
AGENTLOGOFF(channel|logintime)
The agent logged off. The channel is recorded, along with the total time
the agent was logged in.
AGENTCALLBACKLOGOFF(exten@context|logintime|reason)
The callback agent logged off. The last login extension and context is
recorded, along with the total time the agent was logged in, and the
reason for the logoff if it was not a normal logoff
(e.g., Autologoff, Chanunavail)
COMPLETEAGENT(holdtime|calltime|origposition)
The caller was connected to an agent, and the call was terminated normally
by the *agent*. The caller's hold time and the length of the call are both
recorded. The caller's original position in the queue is recorded in
origposition.
COMPLETECALLER(holdtime|calltime|origposition)
The caller was connected to an agent, and the call was terminated normally
by the *caller*. The caller's hold time and the length of the call are both
recorded. The caller's original position in the queue is recorded in
origposition.
CONFIGRELOAD
The configuration has been reloaded (e.g. with asterisk -rx reload)
CONNECT(holdtime|bridgedchanneluniqueid)
The caller was connected to an agent. Hold time represents the amount
of time the caller was on hold. The bridged channel unique ID contains
the unique ID of the queue member channel that is taking the call. This
is useful when trying to link recording filenames to a particular
call in the queue.
ENTERQUEUE(url|callerid)
A call has entered the queue. URL (if specified) and Caller*ID are placed
in the log.
EXITEMPTY(position|origposition|waittime)
The caller was exited from the queue forcefully because the queue had no
reachable members and it's configured to do that to callers when there
are no reachable members. The position is the caller's position in the
queue when they hungup, the origposition is the original position the
caller was when they first entered the queue, and the waittime is how
long the call had been waiting in the queue at the time of disconnect.
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.
EXITWITHTIMEOUT(position|origposition|waittime)
The caller was on hold too long and the timeout expired. The position in the
queue when the timeout occurred, the entry position, and the amount of time
waited are logged.
QUEUESTART
The queueing system has been started for the first time this session.
RINGNOANSWER(ringtime)
After trying for ringtime ms to connect to the available queue member,
the attempt ended without the member picking up the call. Bad queue
member!
SYSCOMPAT
A call was answered by an agent, but the call was dropped because the
channels were not compatible.
TRANSFER(extension|context|holdtime|calltime)
Caller was transferred to a different extension. Context and extension
are recorded. The caller's hold time and the length of the call are both
recorded. PLEASE remember that transfers performed by SIP UA's by way
of a reinvite may not always be caught by Asterisk and trigger off this
event. The only way to be 100\% sure that you will get this event when
a transfer is performed by a queue member is to use the built-in transfer
functionality of Asterisk.

535
doc/tex/queues-with-callback-members.tex Normal file
View File

@@ -0,0 +1,535 @@
\section{Introduction}
Pardon, but the dialplan in this tutorial will be expressed
in AEL, the new Asterisk Extension Language. If you are
not used to its syntax, we hope you will find it to some
degree intuitive. If not, there are documents explaining
its syntax and constructs.
\section{Configuring Call Queues}
\subsection{queues.conf}
First of all, set up call queues in queue.conf
Here is an example:
\begin{verbatim}
=========== queues.conf ===========
| ; Cool Digium Queues |
| [general] |
| persistentmembers = yes |
| |
| ; General sales queue |
| [sales-general] |
| music=default |
| context=sales |
| strategy=ringall |
| joinempty=strict |
| leavewhenempty=strict |
| |
| ; Customer service queue |
| [customerservice] |
| music=default |
| context=customerservice |
| strategy=ringall |
| joinempty=strict |
| leavewhenempty=strict |
| |
| ; Support dispatch queue |
| [dispatch] |
| music=default |
| context=dispatch |
| strategy=ringall |
| joinempty=strict |
| leavewhenempty=strict |
===================================
\end{verbatim}
In the above, we have defined 3 separate calling queues:
sales-general, customerservice, and dispatch.
Please note that the sales-general queue specifies a
context of "sales", and that customerservice specifies the
context of "customerservice", and the dispatch
queue specifies the context "dispatch". These three
contexts must be defined somewhere in your dialplan.
We will show them after the main menu below.
<verbage explaining options above>
In the [general] section, specifying the persistentmembers=yes,
will cause the agent lists to be stored in astdb, and
recalled on startup.
The strategy=ringall will cause all agents to be dialed
together, the first to answer is then assigned the incoming
call.
"joinempty" set to "strict" will keep incoming callers from
being placed in queues where there are no agents to take calls.
The Queue() application will return, and the dial plan can
determine what to do next.
If there are calls queued, and the last agent logs out, the
remaining incoming callers will immediately be removed from
the queue, and the Queue() call will return, IF the "leavewhenempty" is
set to "strict".
\subsection{Routing incoming Calls to Queues}
Then in extensions.ael, you can do these things:
\subsubsection{The Main Menu}
At Digium, incoming callers are sent to the "mainmenu" context, where they
are greeted, and directed to the numbers they choose...
\begin{verbatim}
context mainmenu {
includes {
digium;
queues-loginout;
}
0 => goto dispatch|s|1;
2 => goto sales|s|1;
3 => goto customerservice|s|1;
4 => goto dispatch|s|1;
s => {
Ringing();
Wait(1);
Set(attempts=0);
Answer();
Wait(1);
Background(digium/ThankYouForCallingDigium);
Background(digium/YourOpenSourceTelecommunicationsSupplier);
WaitExten(0.3);
repeat:
Set(attempts=$[${attempts} + 1]);
Background(digium/IfYouKnowYourPartysExtensionYouMayDialItAtAnyTime);
WaitExten(0.1);
Background(digium/Otherwise);
WaitExten(0.1);
Background(digium/ForSalesPleasePress2);
WaitExten(0.2);
Background(digium/ForCustomerServicePleasePress3);
WaitExten(0.2);
Background(digium/ForAllOtherDepartmentsPleasePress4);
WaitExten(0.2);
Background(digium/ToSpeakWithAnOperatorPleasePress0AtAnyTime);
if( ${attempts} < 2 ) {
WaitExten(0.3);
Background(digium/ToHearTheseOptionsRepeatedPleaseHold);
}
WaitExten(5);
if( ${attempts} < 2 ) goto repeat;
Background(digium/YouHaveMadeNoSelection);
Background(digium/ThisCallWillBeEnded);
Background(goodbye);
Hangup();
}
}
\end{verbatim}
\subsubsection{The Contexts referenced from the queues.conf file}
\begin{verbatim}
context sales {
0 => goto dispatch|s|1;
8 => Voicemail(${SALESVM});
s => {
Ringing();
Wait(2);
Background(digium/ThankYouForContactingTheDigiumSalesDepartment);
WaitExten(0.3);
Background(digium/PleaseHoldAndYourCallWillBeAnsweredByOurNextAvailableSalesRepresentative);
WaitExten(0.3);
Background(digium/AtAnyTimeYouMayPress0ToSpeakWithAnOperatorOr8ToLeaveAMessage);
Set(CALLERID(name)=Sales);
Queue(sales-general|t);
Set(CALLERID(name)=EmptySalQ);
goto dispatch|s|1;
Playback(goodbye);
Hangup();
}
}
\end{verbatim}
Please note that there is only one attempt to queue a call in the sales queue. All sales agents that
are logged in will be rung.
\begin{verbatim}
context customerservice {
0 => {
SetCIDName(CSVTrans);
goto dispatch|s|1;
}
8 => Voicemail(${CUSTSERVVM});
s => {
Ringing();
Wait(2);
Background(digium/ThankYouForCallingDigiumCustomerService);
WaitExten(0.3);
notracking:
Background(digium/PleaseWaitForTheNextAvailableCustomerServiceRepresentative);
WaitExten(0.3);
Background(digium/AtAnyTimeYouMayPress0ToSpeakWithAnOperatorOr8ToLeaveAMessage);
Set(CALLERID(name)=Cust Svc);
Set(QUEUE_MAX_PENALTY=10);
Queue(customerservice|t);
Set(QUEUE_MAX_PENALTY=0);
Queue(customerservice|t);
Set(CALLERID(name)=EmptyCSVQ);
goto dispatch|s|1;
Background(digium/NoCustomerServiceRepresentativesAreAvailableAtThisTime);
Background(digium/PleaseLeaveAMessageInTheCustomerServiceVoiceMailBox);
Voicemail(${CUSTSERVVM});
Playback(goodbye);
Hangup();
}
}
\end{verbatim}
Note that calls coming into customerservice will first be try to queue
calls to those agents with a QUEUE\_MAX\_PENALTY of 10, and if none are available,
then all agents are rung.
\begin{verbatim}
context dispatch
{
s => {
Ringing();
Wait(2);
Background(digium/ThankYouForCallingDigium);
WaitExten(0.3);
Background(digium/YourCallWillBeAnsweredByOurNextAvailableOperator);
Background(digium/PleaseHold);
Set(QUEUE_MAX_PENALTY=10);
Queue(dispatch|t);
Set(QUEUE_MAX_PENALTY=20);
Queue(dispatch|t);
Set(QUEUE_MAX_PENALTY=0);
Queue(dispatch|t);
Background(digium/NoOneIsAvailableToTakeYourCall);
Background(digium/PleaseLeaveAMessageInOurGeneralVoiceMailBox);
Voicemail(${DISPATCHVM});
Playback(goodbye);
Hangup();
}
}
\end{verbatim}
And in the dispatch context, first agents of priority 10 are tried, then
20, and if none are available, all agents are tried.
Notice that a common pattern is followed in each of the three queue contexts:
First, you set QUEUE\_MAX\_PENALTY to a value, then you call
Queue(<queue-name>,option,... (see the documentation for the Queue application));
In the above, note that the "t" option is specified, and this allows the
agent picking up the incoming call the luxury of transferring the call to
other parties.
The purpose of specifying the QUEUE\_MAX\_PENALTY is to develop a set of priorities
amongst agents. By the above usage, agents with lower number priorities will
be given the calls first, and then, if no-one picks up the call, the QUEUE\_MAX\_PENALTY
will be incremented, and the queue tried again. Hopefully, along the line, someone
will pick up the call, and the Queue application will end with a hangup.
The final attempt to queue in most of our examples sets the QUEUE\_MAX\_PENALTY
to zero, which means to try all available agents.
\subsection{Assigning agents to Queues}
In this example dialplan, we want to be able to add and remove agents to
handle incoming calls, as they feel they are available. As they log in,
they are added to the queue's agent list, and as they log out, they are
removed. If no agents are available, the queue command will terminate, and
it is the duty of the dialplan to do something appropriate, be it sending
the incoming caller to voicemail, or trying the queue again with a higher
QUEUE\_MAX\_PENALTY.
Because a single agent can make themselves available to more than one queue,
the process of joining multiple queues can be handled automatically by the
dialplan.
\subsubsection{Agents Log In and Out}
\begin{verbatim}
context queues-loginout
{
6092 => {
Answer();
Read(AGENT_NUMBER,agent-enternum);
VMAuthenticate(${AGENT_NUMBER}@default,s);
Set(queue-announce-success=1);
goto queues-manip,I${AGENT_NUMBER},1;
}
6093 => {
Answer();
Read(AGENT_NUMBER,agent-enternum);
Set(queue-announce-success=1);
goto queues-manip,O${AGENT_NUMBER},1;
}
}
\end{verbatim}
In the above contexts, the agents dial 6092 to log into their queues,
and they dial 6093 to log out of their queues. The agent is prompted
for their agent number, and if they are logging in, their passcode,
and then they are transferred to the proper extension in the
queues-manip context. The queues-manip context does all the
actual work:
\begin{verbatim}
context queues-manip {
// Raquel Squelch
_[IO]6121 => {
&queue-addremove(dispatch,10,${EXTEN});
&queue-success(${EXTEN});
}
// Brittanica Spears
_[IO]6165 => {
&queue-addremove(dispatch,20,${EXTEN});
&queue-success(${EXTEN});
}
// Rock Hudson
_[IO]6170 => {
&queue-addremove(sales-general,10,${EXTEN});
&queue-addremove(customerservice,20,${EXTEN});
&queue-addremove(dispatch,30,${EXTEN});
&queue-success(${EXTEN});
}
// Saline Dye-on
_[IO]6070 => {
&queue-addremove(sales-general,20,${EXTEN});
&queue-addremove(customerservice,30,${EXTEN});
&queue-addremove(dispatch,30,${EXTEN});
&queue-success(${EXTEN});
}
}
\end{verbatim}
In the above extensions, note that the queue-addremove macro is used
to actually add or remove the agent from the applicable queue,
with the applicable priority level. Note that agents with a
priority level of 10 will be called before agents with levels
of 20 or 30.
In the above example, Raquel will be dialed first in the dispatch
queue, if she has logged in. If she is not, then the second call of
Queue() with priority of 20 will dial Brittanica if she is present,
otherwise the third call of Queue() with MAX\_PENALTY of 0 will
dial Rock and Saline simultaneously.
Also note that Rock will be among the first to be called in the sales-general
queue, and among the last in the dispatch queue. As you can see in
main menu, the callerID is set in the main menu so they can tell
which queue incoming calls are coming from.
The call to queue-success() gives some feedback to the agent
as they log in and out, that the process has completed.
\begin{verbatim}
macro queue-success(exten)
{
if( ${queue-announce-success} > 0 )
{
switch(${exten:0:1})
{
case I:
Playback(agent-loginok);
Hangup();
case O:
Playback(agent-loggedoff);
Hangup();
}
}
}
\end{verbatim}
The queue-addremove macro is defined in this manner:
\begin{verbatim}
macro queue-addremove(queuename,penalty,exten)
{
switch(${exten:0:1})
{
case I: // Login
{
AddQueueMember(${queuename},Local/${exten:1}@agents,${penalty});
break;
}
case O: // Logout
{
RemoveQueueMember(${queuename},Local/${exten:1}@agents);
break;
}
case P: // Pause
{
PauseQueueMember(${queuename},Local/${exten:1}@agents);
break;
}
case U: // Unpause
{
UnpauseQueueMember(${queuename},Local/${exten:1}@agents);
break;
}
default: // Invalid
{
Playback(invalid);
}
}
}
\end{verbatim}
Basically, it uses the first character of the exten variable, to determine the
proper actions to take. In the above dial plan code, only the cases I or O are used,
which correspond to the Login and Logout actions.
\subsection{Controlling The Way Queues Call the Agents}
Notice in the above, that the commands to manipulate agents in queues have
"@agents" in their arguments. This is a reference to the agents context:
\begin{verbatim}
context agents
{
// General sales queue
8010 =>
{
Set(QUEUE_MAX_PENALTY=10);
Queue(sales-general|t);
Set(QUEUE_MAX_PENALTY=0);
Queue(sales-general|t);
Set(CALLERID(name)=EmptySalQ);
goto dispatch|s|1;
}
// Customer Service queue
8011 =>
{
Set(QUEUE_MAX_PENALTY=10);
Queue(customerservice|t);
Set(QUEUE_MAX_PENALTY=0);
Queue(customerservice|t);
Set(CALLERID(name)=EMptyCSVQ);
goto dispatch|s|1;
}
8013 =>
{
Dial(iax2/sweatshop/9456@from-ecstacy);
Set(CALLERID(name)=EmptySupQ);
Set(QUEUE_MAX_PENALTY=10);
Queue(support-dispatch,t);
Set(QUEUE_MAX_PENALTY=20);
Queue(support-dispatch,t);
Set(QUEUE_MAX_PENALTY=0); // means no max
Queue(support-dispatch,t);
goto dispatch|s|1;
}
6121 => &callagent(${RAQUEL},${EXTEN});
6165 => &callagent(${SPEARS},${EXTEN});
6170 => &callagent(${ROCK},${EXTEN});
6070 => &callagent(${SALINE},${EXTEN});
}
\end{verbatim}
In the above, the variables \${RAQUEL}, etc stand for
actual devices to ring that person's
phone (like Zap/37).
The 8010, 8011, and 8013 extensions are purely for transferring
incoming callers to queues. For instance, a customer service
agent might want to transfer the caller to talk to sales. The
agent only has to transfer to extension 8010, in this case.
Here is the callagent macro, note that if a person in the
queue is called, but does not answer, then they are automatically
removed from the queue.
\begin{verbatim}
macro callagent(device,exten)
{
if( ${GROUP_COUNT(${exten}@agents)}=0 )
{
Set(OUTBOUND_GROUP=${exten}@agents);
Dial(${device}|300|t);
switch(${DIALSTATUS})
{
case BUSY:
Busy();
break;
case NOANSWER:
Set(queue-announce-success=0);
goto queues-manip|O${exten}|1;
default:
Hangup();
break;
}
}
else
{
Busy();
}
}
\end{verbatim}
In the callagent macro above, the \${exten} will
be 6121, or 6165, etc, which is the extension of the agent.
The use of the GROUP\_COUNT, and OUTBOUND\_GROUP follow this line
of thinking. Incoming calls can be queued to ring all agents in the
current priority. If some of those agents are already talking, they
would get bothersome call-waiting tones. To avoid this inconvenience,
when an agent gets a call, the OUTBOUND\_GROUP assigns that
conversation to the group specified, for instance 6171@agents.
The \${GROUP\_COUNT()} variable on a subsequent call should return
"1" for that group. If GROUP\_COUNT returns 1, then the busy()
is returned without actually trying to dial the agent.
\subsection{Pre Acknowledgement Message}
If you would like to have a pre acknowledge message with option to reject the message
you can use the following dialplan Macro as a base with the 'M' dial argument.
\begin{verbatim}
[macro-screen]
exten=>s,1,Wait(.25)
exten=>s,2,Read(ACCEPT|screen-callee-options|1)
exten=>s,3,Gotoif($[${ACCEPT} = 1] ?50)
exten=>s,4,Gotoif($[${ACCEPT} = 2] ?30)
exten=>s,5,Gotoif($[${ACCEPT} = 3] ?40)
exten=>s,6,Gotoif($[${ACCEPT} = 4] ?30:30)
exten=>s,30,Set(MACRO_RESULT=CONTINUE)
exten=>s,40,Read(TEXTEN|custom/screen-exten|)
exten=>s,41,Gotoif($[${LEN(${TEXTEN})} = 3]?42:45)
exten=>s,42,Set(MACRO_RESULT=GOTO:from-internal^${TEXTEN}^1)
exten=>s,45,Gotoif($[${TEXTEN} = 0] ?46:4)
exten=>s,46,Set(MACRO_RESULT=CONTINUE)
exten=>s,50,Playback(after-the-tone)
exten=>s,51,Playback(connected)
exten=>s,52,Playback(beep)
\end{verbatim}
\subsection{Caveats}
In the above examples, some of the possible error checking has been omitted,
to reduce clutter and make the examples clearer.

130
doc/tex/realtime.tex Normal file
View File

@@ -0,0 +1,130 @@
\subsubsection{Introduction}
The Asterisk Realtime Architecture is a new set of drivers and
functions implemented in Asterisk.
The benefits of this architecture are many, both from a code management
standpoint and from an installation perspective.
Additional information on the configuration of Realtime with Asterisk
can be found in doc/extconfig.txt
The ARA is designed to be independent of storage. Currently, most
drivers are based on SQL, but the architecture should be able to handle
other storage methods in the future, like LDAP.
The main benefit comes in the database support. In Asterisk v1.0 some
functions supported MySQL database, some PostgreSQL and other ODBC.
With the ARA, we have a unified database interface internally in Asterisk,
so if one function supports database integration, all databases that has a
realtime driver will be supported in that function.
Currently there are three realtime database drivers:
\begin{itemize}
\item ODBC: Support for UnixODBC, integrated into Asterisk
The UnixODBC subsystem supports many different databases,
please check www.unixodbc.org for more information.
\item MySQL: Found in the asterisk-addons subversion repository on svn.digium.com
\item PostgreSQL: Native support for Postgres, integrated into Asterisk
\end{itemize}
\subsubsection{Two modes: Static and Realtime}
The ARA realtime mode is used to dynamically load and update objects.
This mode is used in the SIP and IAX2 channels, as well as in the voicemail
system. For SIP and IAX2 this is similar to the v1.0 MYSQL\_FRIENDS
functionality. With the ARA, we now support many more databases for
dynamic configuration of phones.
The ARA static mode is used to load configuration files. For the Asterisk
modules that read configurations, there's no difference between a static
file in the file system, like extensions.conf, and a configuration loaded
from a database.
\subsubsection{Realtime SIP friends}
The SIP realtime objects are users and peers that are loaded in memory
when needed, then deleted. This means that Asterisk currently can't handle
voicemail notification and NAT keepalives for these peers. Other than that,
most of the functionality works the same way for realtime friends as for
the ones in static configuration.
With caching, the device stays in memory for a specified time. More
information about this is to be found in the sip.conf sample file.
\subsubsection{Realtime H.323 friends}
Like SIP realtime friends, H.323 friends also can be configured using
dynamic realtime objects.
\subsubsection{New function in the dial plan: The Realtime Switch}
The realtime switch is more than a port of functionality in v1.0 to the
new architecture, this is a new feature of Asterisk based on the
ARA. The realtime switch lets your Asterisk server do database lookups
of extensions in realtime from your dial plan. You can have many Asterisk
servers sharing a dynamically updated dial plan in real time with this
solution.
Note that this switch does NOT support Caller ID matching, only
extension name or pattern matching.
\subsubsection{Capabilities}
The realtime Architecture lets you store all of your configuration in
databases and reload it whenever you want. You can force a reload over
the AMI, Asterisk Manager Interface or by calling Asterisk from a
shell script with
asterisk -rx "reload"
You may also dynamically add SIP and IAX devices and extensions
and making them available without a reload, by using the realtime
objects and the realtime switch.
\subsubsection{Configuration in extconfig.conf}
You configure the ARA in extconfig.conf (yes, it's a strange name, but
is was defined in the early days of the realtime architecture and kind
of stuck). Please see doc/extconfig.txt for database schemas.
The part of Asterisk that connects to the ARA use a well defined family
name to find the proper database driver. The syntax is easy:
\begin{verbatim}
<family> => <realtime driver>,<db name>[,<table>]
\end{verbatim}
The options following the realtime driver identified depends on the
driver.
Defined well-known family names are:
\begin{itemize}
\item sippeers, sipusers - SIP peers and users
\item iaxpeers, iaxusers - IAX2 peers and users
\item voicemail - Voicemail accounts
\item queues - Queues
\item queue\_members - Queue members
\item extensions - Realtime extensions (switch)
\end{itemize}
There is documentation of the SQL database in the file
doc/extconfig.txt in your Asterisk source code tree.
For voicemail storage with the support of ODBC, there is a
doc/odbcstorage.txt documentation file.
\subsubsection{Limitations}
Currently, realtime extensions do not support realtime hints. There is
a workaround available by using func\_odbc. See the sample func\_odbc.conf
for more information.
\subsubsection{FreeTDS supported with connection pooling}
In order to use a FreeTDS-based database with realtime, you need to turn
connection pooling on in res\_odbc.conf. This is due to a limitation within
the FreeTDS protocol itself. Please note that this includes databases such
as MS SQL Server and Sybase. This support is new in the current release.

76
doc/tex/security.tex Normal file
View File

@@ -0,0 +1,76 @@
\subsection{Introduction}
PLEASE READ THE FOLLOWING IMPORTANT SECURITY RELATED INFORMATION.
IMPROPER CONFIGURATION OF ASTERISK COULD ALLOW UNAUTHORIZED USE OF YOUR
FACILITIES, POTENTIALLY INCURRING SUBSTANTIAL CHARGES.
Asterisk security involves both network security (encryption, authentication)
as well as dialplan security (authorization - who can access services in
your pbx). If you are setting up Asterisk in production use, please make
sure you understand the issues involved.
\subsection{Network Security}
If you install Asterisk and use the "make samples" command to install
a demonstration configuration, Asterisk will open a few ports for accepting
VoIP calls. Check the channel configuration files for the ports and IP addresses.
If you enable the manager interface in manager.conf, please make sure that
you access manager in a safe environment or protect it with SSH or other
VPN solutions.
For all TCP/IP connections in Asterisk, you can set ACL lists that
will permit or deny network access to Asterisk services. Please check
the "permit" and "deny" configuration options in manager.conf and
the VoIP channel configurations - i.e. sip.conf and iax.conf.
The IAX2 protocol supports strong RSA key authentication as well as
AES encryption of voice and signalling. The SIP channel does not
support encryption in this version of Asterisk.
\subsection{Dialplan Security}
First and foremost remember this:
USE THE EXTENSION CONTEXTS TO ISOLATE OUTGOING OR TOLL SERVICES FROM ANY
INCOMING CONNECTIONS.
You should consider that if any channel, incoming line, etc can enter an
extension context that it has the capability of accessing any extension
within that context.
Therefore, you should NOT allow access to outgoing or toll services in
contexts that are accessible (especially without a password) from incoming
channels, be they IAX channels, FX or other trunks, or even untrusted
stations within you network. In particular, never ever put outgoing toll
services in the "default" context. To make things easier, you can include
the "default" context within other private contexts by using:
\begin{verbatim}
include => default
\end{verbatim}
in the appropriate section. A well designed PBX might look like this:
\begin{verbatim}
[longdistance]
exten => _91NXXNXXXXXX,1,Dial(Zap/g2/${EXTEN:1})
include => local
[local]
exten => _9NXXNXXX,1,Dial(Zap/g2/${EXTEN:1})
include => default
[default]
exten => 6123,Dial(Zap/1)
\end{verbatim}
DON'T FORGET TO TAKE THE DEMO CONTEXT OUT OF YOUR DEFAULT CONTEXT. There
isn't really a security reason, it just will keep people from wanting to
play with your Asterisk setup remotely.
\subsection{Log Security}
Please note that the Asterisk log files, as well as information printed to the
Asterisk CLI, may contain sensitive information such as passwords and call
history. Keep this in mind when providing access to these resources.

378
doc/tex/sla.tex Normal file
View File

@@ -0,0 +1,378 @@
%\documentclass[12pt,a4]{article}
%\usepackage{hyperref}
%\author{Russell Bryant \\ Software Engineer \\ Digium, Inc.}
%\title{Shared Line Appearances}
%\begin{document}
%\maketitle
%\tableofcontents
\section{Introduction}
The "SLA" functionality in Asterisk is intended to allow a setup that emulates
a simple key system. It uses the various abstraction layers already built into
Asterisk to emulate key system functionality across various devices, including
IP channels.
\section{Configuration}
\subsection{Summary}
An SLA system is built up of virtual trunks and stations mapped to real
Asterisk devices. The configuration for all of this is done in three
different files: extensions.conf, sla.conf, and the channel specific
configuration file such as sip.conf or zapata.conf.
\subsection{Dialplan}
The SLA implementation can automatically generate the dialplan necessary for
basic operation if the "autocontext" option is set for trunks and stations in
sla.conf. However, for reference, here is an automatically generated dialplan
to help with custom building of the dialplan to include other features, such as
voicemail (\ref{voicemail}).
However, note that there is a little bit of additional configuration needed if
the trunk is an IP channel. This is discussed in the section on trunks (\ref{trunks}).
There are extensions for incoming calls on a specific trunk, which execute the SLATrunk
application, as well as incoming calls from a station, which execute SLAStation.
Note that there are multiple extensions for incoming calls from a station. This is
because the SLA system has to know whether the phone just went off hook, or if the
user pressed a specific line button.
Also note that there is a hint for every line on every station. This lets the SLA
system control each individual light on every phone to ensure that it shows the
correct state of the line. The phones must subscribe to the state of each of their
line appearances.
Please refer to the examples section for full dialplan samples for SLA.
\subsection{Trunks}
\label{trunks}
An SLA trunk is a mapping between a virtual trunk and a real Asterisk device.
This device may be an analog FXO line, or something like a SIP trunk. A trunk
must be configured in two places. First, configure the device itself in the
channel specific configuration file such as zapata.conf or sip.conf. Once the
trunk is configured, then map it to an SLA trunk in sla.conf.
\begin{verbatim}
[line1]
type=trunk
device=Zap/1
\end{verbatim}
Be sure to configure the trunk's context to be the same one that is set for the
"autocontext" option in sla.conf if automatic dialplan configuration is used.
This would be done in the regular device entry in zapata.conf, sip.conf, etc.
Note that the automatic dialplan generation creates the SLATrunk() extension
at extension 's'. This is perfect for Zap channels that are FXO trunks, for
example. However, it may not be good enough for an IP trunk, since the call
coming in over the trunk may specify an actual number.
If the dialplan is being built manually, ensure that calls coming in on a trunk
execute the SLATrunk() application with an argument of the trunk name, as shown
in the dialplan example before.
IP trunks can be used, but they require some additional configuration to work.
For this example, let's say we have a SIP trunk called "mytrunk" that is going
to be used as line4. Furthermore, when calls come in on this trunk, they are
going to say that they are calling the number "12564286000". Also, let's say
that the numbers that are valid for calling out this trunk are NANP numbers,
of the form \_1NXXNXXXXXX.
In sip.conf, there would be an entry for [mytrunk]. For [mytrunk],
set context=line4.
\begin{verbatim}
[line4]
type=trunk
device=Local/disa@line4_outbound
\end{verbatim}
\begin{verbatim}
[line4]
exten => 12564286000,1,SLATrunk(line4)
[line4_outbound]
exten => disa,1,Disa(no-password|line4_outbound)
exten => _1NXXNXXXXXX,1,Dial(SIP/\${EXTEN}@mytrunk)
\end{verbatim}
So, when a station picks up their phone and connects to line 4, they are
connected to the local dialplan. The Disa application plays dialtone to the
phone and collects digits until it matches an extension. In this case, once
the phone dials a number like 12565551212, the call will proceed out the
SIP trunk.
\subsection{Stations}
An SLA station is a mapping between a virtual station and a real Asterisk device.
Currently, the only channel driver that has all of the features necessary to
support an SLA environment is chan\_sip. So, to configure a SIP phone to use
as a station, you must configure sla.conf and sip.conf.
\begin{verbatim}
[station1]
type=station
device=SIP/station1
trunk=line1
trunk=line2
\end{verbatim}
Here are some hints on configuring a SIP phone for use with SLA:
\begin{enumerate}
\item Add the SIP channel as a [station] in sla.conf.
\item Configure the phone in sip.conf. If automatic dialplan configuration was
used by enabling the "autocontext" option in sla.conf, then this entry in
sip.conf should have the same context setting.
\item On the phone itself, there are various things that must be configured to
make everything work correctly:
Let's say this phone is called "station1" in sla.conf, and it uses trunks
named "line1" and line2".
\begin{enumerate}
\item Two line buttons must be configured to subscribe to the state of the
following extensions:
- station1\_line1
- station1\_line2
\item The line appearance buttons should be configured to dial the extensions
that they are subscribed to when they are pressed.
\item If you would like the phone to automatically connect to a trunk when it
is taken off hook, then the phone should be automatically configured to
dial "station1" when it is taken off hook.
\end{enumerate}
\end{enumerate}
\section{Configuration Examples}
\subsection{Basic SLA}
This is an example of the most basic SLA setup. It uses the automatic
dialplan generation so the configuration is minimal.
sla.conf:
\begin{verbatim}
[line1]
type=trunk
device=Zap/1
autocontext=line1
[line2]
type=trunk
device=Zap/2
autocontext=line2
[station](!)
type=station
trunk=line1
trunk=line2
autocontext=sla_stations
[station1](station)
device=SIP/station1
[station2](station)
device=SIP/station2
[station3](station)
device=SIP/station3
\end{verbatim}
With this configuration, the dialplan is generated automatically. The first
zap channel should have its context set to "line1" and the second should be
set to "line2" in zapata.conf. In sip.conf, station1, station2, and station3
should all have their context set to "sla\_stations".
For reference, here is the automatically generated dialplan for this situation:
\begin{verbatim}
[line1]
exten => s,1,SLATrunk(line1)
[line2]
exten => s,2,SLATrunk(line2)
[sla_stations]
exten => station1,1,SLAStation(station1)
exten => station1_line1,hint,SLA:station1_line1
exten => station1_line1,1,SLAStation(station1_line1)
exten => station1_line2,hint,SLA:station1_line2
exten => station1_line2,1,SLAStation(station1_line2)
exten => station2,1,SLAStation(station2)
exten => station2_line1,hint,SLA:station2_line1
exten => station2_line1,1,SLAStation(station2_line1)
exten => station2_line2,hint,SLA:station2_line2
exten => station2_line2,1,SLAStation(station2_line2)
exten => station3,1,SLAStation(station3)
exten => station3_line1,hint,SLA:station3_line1
exten => station3_line1,1,SLAStation(station3_line1)
exten => station3_line2,hint,SLA:station3_line2
exten => station3_line2,1,SLAStation(station3_line2)
\end{verbatim}
\subsection{SLA and Voicemail}
\label{voicemail}
This is an example of how you could set up a single voicemail box for the
phone system. The voicemail box number used in this example is 1234, which
would be configured in voicemail.conf.
For this example, assume that there are 2 trunks and 3 stations. The trunks
are Zap/1 and Zap/2. The stations are SIP/station1, SIP/station2, and
SIP/station3.
In zapata.conf, channel 1 has context=line1 and channel 2 has context=line2.
In sip.conf, all three stations are configured with context=sla\_stations.
When the stations pick up their phones to dial, they are allowed to dial
NANP numbers for outbound calls, or 8500 for checking voicemail.
sla.conf:
\begin{verbatim}
[line1]
type=trunk
device=Local/disa@line1_outbound
[line2]
type=trunk
device=Local/disa@line2_outbound
[station](!)
type=station
trunk=line1
trunk=line2
[station1](station)
device=SIP/station1
[station2](station)
device=SIP/station2
[station3](station)
device=SIP/station3
\end{verbatim}
extensions.conf:
\begin{verbatim}
[macro-slaline]
exten => s,1,SLATrunk(${ARG1})
exten => s,n,Goto(s-${SLATRUNK_STATUS}|1)
exten => s-FAILURE,1,Voicemail(1234|u)
exten => s-UNANSWERED,1,Voicemail(1234|u)
[line1]
exten => s,1,Macro(slaline|line1)
[line2]
exten => s,2,Macro(slaline|line2)
[line1_outbound]
exten => disa,1,Disa(no-password|line1_outbound)
exten => _1NXXNXXXXXX,1,Dial(Zap/1/${EXTEN})
exten => 8500,1,VoicemailMain(1234)
[line2_outbound]
exten => disa,1,Disa(no-password|line2_outbound)
exten => _1NXXNXXXXXX,1,Dial(Zap/2/${EXTEN})
exten => 8500,1,VoicemailMain(1234)
[sla_stations]
exten => station1,1,SLAStation(station1)
exten => station1_line1,hint,SLA:station1_line1
exten => station1_line1,1,SLAStation(station1_line1)
exten => station1_line2,hint,SLA:station1_line2
exten => station1_line2,1,SLAStation(station1_line2)
exten => station2,1,SLAStation(station2)
exten => station2_line1,hint,SLA:station2_line1
exten => station2_line1,1,SLAStation(station2_line1)
exten => station2_line2,hint,SLA:station2_line2
exten => station2_line2,1,SLAStation(station2_line2)
exten => station3,1,SLAStation(station3)
exten => station3_line1,hint,SLA:station3_line1
exten => station3_line1,1,SLAStation(station3_line1)
exten => station3_line2,hint,SLA:station3_line2
exten => station3_line2,1,SLAStation(station3_line2)
\end{verbatim}
\section{Call Handling}
\subsection{Summary}
This section is intended to describe how Asterisk handles calls inside of the
SLA system so that it is clear what behavior is expected.
\subsection{Station goes off hook (not ringing)}
When a station goes off hook, it should initiate a call to Asterisk with the
extension that indicates that the phone went off hook without specifying a
specific line. In the examples in this document, for the station named
"station1", this extension is simply named, "station1".
Asterisk will attempt to connect this station to the first available trunk
that is not in use. Asterisk will check the trunks in the order that they
were specified in the station entry in sla.conf. If all trunks are in use,
the call will be denied.
If Asterisk is able to acquire an idle trunk for this station, then trunk
is connected to the station and the station will hear dialtone. The station
can then proceed to dial a number to call. As soon as a trunk is acquired,
all appearances of this line on stations will show that the line is in use.
\subsection{Station goes off hook (ringing)}
When a station goes off hook while it is ringing, it should simply answer
the call that had been initiated to it to make it ring. Once the station
has answered, Asterisk will figure out which trunk to connect it to. It
will connect it to the highest priority trunk that is currently ringing.
Trunk priority is determined by the order that the trunks are listed in
the station entry in sla.conf.
\subsection{Line button on a station is pressed}
When a line button is pressed on a station, the station should initiate a
call to Asterisk with the extension that indicates which line button was
pressed. In the examples given in this document, for a station named
"station1" and a trunk named "line1", the extension would be "station1\_line1".
If the specified trunk is not in use, then the station will be connected to it and
will hear dialtone. All appearances of this trunk will then show that it
is now in use.
If the specified trunk is on hold by this station, then this station will be
reconnected to the trunk. The line appearance for this trunk on this station
will now show in use. If this was the only station that had the call on hold,
then all appearances of this trunk will now show that it is in use. Otherwise,
all stations that are not currently connected to this trunk will show it
on hold.
If the specified trunk is on hold by a different station, then this station
will be connected to the trunk only if the trunk itself and the station(s) that
have it on hold do not have private hold enabled. If connected, the appeareance
of this trunk on this station will then show in use. All stations that are not
currently connected to this trunk will show it on hold.
%\end{document}