dect
/
asterisk
Archived
13
0
Fork 0
Code Releases Activity

Merged revisions 58931 via svnmerge from 

https://origsvn.digium.com/svn/asterisk/branches/1.4

........
r58931 | russell | 2007-03-15 17:25:12 -0500 (Thu, 15 Mar 2007) | 13 lines

Merge changes from svn/asterisk/team/russell/LaTeX_docs.

* Convert most of the doc directory into a single LaTeX formatted document
  so that we can generate a PDF, HTML, or other formats from this
  information.
* Add a CLI command to dump the application documentation into LaTeX format
  which will only be include if the configure script is run with 
  --enable-dev-mode.
* The PDF turned out to be close to 1 MB, so it is not included.  However, you
  can simply run "make asterisk.pdf" to generate it yourself.  We may include
  it in release tarballs or have automatically generated ones on the web site,
  but that has yet to be decided.

........


git-svn-id: http://svn.digium.com/svn/asterisk/trunk@58932 f38db490-d61c-443f-a65b-d21fe96a405b
This commit is contained in:
russell 2007-03-15 22:29:45 +00:00
parent ddf7ae4539
commit acddd1bef6
59 changed files with 5336 additions and 2665 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

18
Makefile
View File

@ -46,6 +46,7 @@ export AGI_DIR
export ASTCONFPATH
export NOISY_BUILD
export MENUSELECT_CFLAGS
export AST_DEVMODE
export CC
export CXX
export AR
@ -683,4 +684,21 @@ menuselect-tree: $(foreach dir,$(filter-out main,$(MOD_SUBDIRS)),$(wildcard $(di
@echo "Generating input for menuselect ..."
@build_tools/prep_moduledeps > $@
asterisk.pdf: doc/asterisk.pdf
doc/asterisk.pdf:
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 doc/asterisk.pdf. ***"
@echo "**********************************************"
@cd doc && rubber asterisk.tex
endif
.PHONY: menuselect main sounds clean dist-clean distclean all prereqs cleantest uninstall _uninstall uninstall-all dont-optimize $(SUBDIRS_INSTALL) $(SUBDIRS_CLEAN) $(SUBDIRS_UNINSTALL) $(SUBDIRS) $(MOD_SUBDIRS_EMBED_LDSCRIPT) $(MOD_SUBDIRS_EMBED_LDFLAGS) $(MOD_SUBDIRS_EMBED_LIBS)

2
apps/app_voicemail.c
View File

@ -1956,7 +1956,7 @@ static void make_email_file(FILE *p, char *srcemail, struct ast_vm_user *vmu, in
fprintf(p, "Subject: New message %d in mailbox %s" ENDL, msgnum + 1, mailbox);
else
fprintf(p, "Subject: [PBX]: New message %d in mailbox %s" ENDL, msgnum + 1, mailbox);
fprintf(p, "Message-ID: <Asterisk-%d-%d-%s-%d@%s>" ENDL, msgnum, (unsigned int)ast_random(), mailbox, getpid(), host);
fprintf(p, "Message-ID: <Asterisk-%d-%d-%s-%d@%s>" ENDL, msgnum + 1, (unsigned int)ast_random(), mailbox, getpid(), host);
if(imap) {
/* additional information needed for IMAP searching */
fprintf(p, "X-Asterisk-VM-Message-Num: %d" ENDL, msgnum + 1);

6
build_tools/make_buildopts_h
View File

@ -9,5 +9,9 @@ cat << END
END
TMP=`grep MENUSELECT_CFLAGS menuselect.makeopts | sed 's/MENUSELECT_CFLAGS\=//g' | sed 's/-D//g'`
for x in ${TMP}; do
echo "#define ${x} 1"
echo "#define ${x} 1"
done
if grep AST_DEVMODE makeopts | grep -q yes
then
echo "#define AST_DEVMODE 1"
fi

53
configure vendored
View File

@ -1,5 +1,5 @@
#! /bin/sh
# From configure.ac Revision: 58858 .
# From configure.ac Revision: 58866 .
# Guess values for system-dependent variables and create Makefiles.
# Generated by GNU Autoconf 2.60.
#
@ -692,6 +692,7 @@ LN
DOT
STRIP
WGET
RUBBER
FETCH
DOWNLOAD
acx_pthread_config
@ -7432,6 +7433,47 @@ echo "${ECHO_T}no" >&6; }
fi
# Extract the first word of "rubber", so it can be a program name with args.
set dummy rubber; ac_word=$2
{ echo "$as_me:$LINENO: checking for $ac_word" >&5
echo $ECHO_N "checking for $ac_word... $ECHO_C" >&6; }
if test "${ac_cv_path_RUBBER+set}" = set; then
echo $ECHO_N "(cached) $ECHO_C" >&6
else
case $RUBBER in
[\\/]* | ?:[\\/]*)
ac_cv_path_RUBBER="$RUBBER" # Let the user override the test with a path.
;;
*)
as_save_IFS=$IFS; IFS=$PATH_SEPARATOR
for as_dir in $PATH
do
IFS=$as_save_IFS
test -z "$as_dir" && as_dir=.
for ac_exec_ext in '' $ac_executable_extensions; do
if { test -f "$as_dir/$ac_word$ac_exec_ext" && $as_executable_p "$as_dir/$ac_word$ac_exec_ext"; }; then
ac_cv_path_RUBBER="$as_dir/$ac_word$ac_exec_ext"
echo "$as_me:$LINENO: found $as_dir/$ac_word$ac_exec_ext" >&5
break 2
fi
done
done
IFS=$as_save_IFS
test -z "$ac_cv_path_RUBBER" && ac_cv_path_RUBBER=":"
;;
esac
fi
RUBBER=$ac_cv_path_RUBBER
if test -n "$RUBBER"; then
{ echo "$as_me:$LINENO: result: $RUBBER" >&5
echo "${ECHO_T}$RUBBER" >&6; }
else
{ echo "$as_me:$LINENO: result: no" >&5
echo "${ECHO_T}no" >&6; }
fi
if test "${WGET}" != ":" ; then
DOWNLOAD=${WGET}
else
@ -39650,13 +39692,13 @@ LN!$LN$ac_delim
DOT!$DOT$ac_delim
STRIP!$STRIP$ac_delim
WGET!$WGET$ac_delim
RUBBER!$RUBBER$ac_delim
FETCH!$FETCH$ac_delim
DOWNLOAD!$DOWNLOAD$ac_delim
acx_pthread_config!$acx_pthread_config$ac_delim
PTHREAD_CC!$PTHREAD_CC$ac_delim
PTHREAD_LIBS!$PTHREAD_LIBS$ac_delim
PTHREAD_CFLAGS!$PTHREAD_CFLAGS$ac_delim
AST_DEVMODE!$AST_DEVMODE$ac_delim
_ACEOF
if test `sed -n "s/.*$ac_delim\$/X/p" conf$$subs.sed | grep -c X` = 97; then
@ -39698,6 +39740,7 @@ _ACEOF
ac_delim='%!_!# '
for ac_last_try in false false false false false :; do
cat >conf$$subs.sed <<_ACEOF
AST_DEVMODE!$AST_DEVMODE$ac_delim
ALSA_LIB!$ALSA_LIB$ac_delim
ALSA_INCLUDE!$ALSA_INCLUDE$ac_delim
ALSA_DIR!$ALSA_DIR$ac_delim
@ -39794,7 +39837,6 @@ SS7_LIB!$SS7_LIB$ac_delim
SS7_INCLUDE!$SS7_INCLUDE$ac_delim
SS7_DIR!$SS7_DIR$ac_delim
PBX_SS7!$PBX_SS7$ac_delim
PWLIB_LIB!$PWLIB_LIB$ac_delim
_ACEOF
if test `sed -n "s/.*$ac_delim\$/X/p" conf$$subs.sed | grep -c X` = 97; then
@ -39836,6 +39878,7 @@ _ACEOF
ac_delim='%!_!# '
for ac_last_try in false false false false false :; do
cat >conf$$subs.sed <<_ACEOF
PWLIB_LIB!$PWLIB_LIB$ac_delim
PWLIB_INCLUDE!$PWLIB_INCLUDE$ac_delim
PWLIB_DIR!$PWLIB_DIR$ac_delim
PBX_PWLIB!$PBX_PWLIB$ac_delim
@ -39932,7 +39975,6 @@ OPENH323_LIBDIR!$OPENH323_LIBDIR$ac_delim
OPENH323_SUFFIX!$OPENH323_SUFFIX$ac_delim
OPENH323_BUILD!$OPENH323_BUILD$ac_delim
QTMOC!$QTMOC$ac_delim
EDITLINE_LIB!$EDITLINE_LIB$ac_delim
_ACEOF
if test `sed -n "s/.*$ac_delim\$/X/p" conf$$subs.sed | grep -c X` = 97; then
@ -39974,6 +40016,7 @@ _ACEOF
ac_delim='%!_!# '
for ac_last_try in false false false false false :; do
cat >conf$$subs.sed <<_ACEOF
EDITLINE_LIB!$EDITLINE_LIB$ac_delim
PBX_H323!$PBX_H323$ac_delim
PBX_IXJUSER!$PBX_IXJUSER$ac_delim
GTKCONFIG!$GTKCONFIG$ac_delim
@ -39984,7 +40027,7 @@ CURL_CONFIG!$CURL_CONFIG$ac_delim
LTLIBOBJS!$LTLIBOBJS$ac_delim
_ACEOF
if test `sed -n "s/.*$ac_delim\$/X/p" conf$$subs.sed | grep -c X` = 8; then
if test `sed -n "s/.*$ac_delim\$/X/p" conf$$subs.sed | grep -c X` = 9; then
break
elif $ac_last_try; then
{ { echo "$as_me:$LINENO: error: could not make $CONFIG_STATUS" >&5

1
configure.ac
View File

@ -153,6 +153,7 @@ AC_PATH_PROG([LN], [ln], :)
AC_PATH_PROG([DOT], [dot], :)
AC_PATH_PROG([STRIP], [strip], :)
AC_PATH_PROG([WGET], [wget], :)
AC_PATH_PROG([RUBBER], [rubber], :)
if test "${WGET}" != ":" ; then
DOWNLOAD=${WGET}
else

74
doc/00README.1st
View File

@ -1,74 +0,0 @@
Files in the /doc directory:
----------------------------
In addition to these files, there is a lot of documentation of various
configuration options in the sample configuration files, in the /configs
directory of your source code
Start here
----------
security.txt IMPORTANT INFORMATION ABOUT ASTERISK SECURITY
hardware.txt Hardware supported by Asterisk
Configuration
-------------
configuration.txt Features in the configuration parser
extensions.txt Basics about the dialplan
extconfig.txt How to use databases for configuration of Asterisk (ARA)
ip-tos.txt About the IP Type Of Service settings
realtime.txt The Asterisk Realtime Architecture - database support
freetds.txt Information about the FreeTDS support
ael.txt Information about the Asterisk Extension Language
Misc
----
PEERING The General Peering Agreement for Dundi
ajam.txt About the HTTP-based manager interface
app_sms.txt How to configure the SMS application
asterisk.conf.txt Documentation of various options in asterisk.conf
callingpres.txt Settings for Caller ID presentation
billing.txt Call Data Record information
cliprompt.txt How to change the Asterisk CLI prompt
dundi.txt Dundi - a discovery protocol
enum.txt Enum support in Asterisk
ices.txt Integrating ICEcast streaming in Asterisk
jitterbuffer.txt About the IAX2 jitterbuffer implementation
math.txt About the math() application
mp3.txt About MP3 support in Asterisk
musiconhold-fpm.txt Free Music On Hold music
mysql.txt About MYSQL support in Asterisk
odbcstorage.txt Voicemail storage of messages in UnixODBC
privacy.txt Privacy enhancements in Asterisk
queuelog.txt Agent and queue logging
channelvariables.txt Channel variables
cdrdrivers.txt About CDR storage in various databases (needs update)
asterisk-mib.txt SNMP mib for Asterisk (net-snmp)
digium-mib.txt SNMP mib for Asterisk (net-snmp)
Channel drivers
---------------
misdn.txt The mISDN channel driver for ISDN BRI cards
h323.txt How to compile and configure the H.323 channel
chaniax.txt About the IAX2 protocol support in Asterisk
localchannel.txt The local channel is a "gosub" in the dialplan
Portability
-----------
cygwin.txt Compiling Asterisk on CygWin platforms (Windows)
For developers
--------------
See http://www.asterisk.org/developers for more information
manager.txt About the AMI - Asterisk Manager Interface
for third party call control and PBX management
backtrace.txt How to produce a backtrace when Asterisk crashes
CODING-GUIDELINES Guidelines for developers
channels.txt What is a channel?
externalivr.txt Documentation of the protocol used in externalivr()
linkedlists.txt How to develop linked lists in Asterisk (old)
iax.txt About the IAX protocol
apps.txt About application development
model.txt About the call model in Asterisk (old)
modules.txt How Asterisk modules work
datastores.txt About channel data stores
speechrec.txt The Generic Speech Recognition API

4
doc/PEERING
View File

@ -1,3 +1,5 @@
\begin{verbatim}
DIGIUM GENERAL PEERING AGREEMENT (TM)
Version 1.0.0, September 2004
Copyright (C) 2004 Digium, Inc.
@ -497,3 +499,5 @@ member of the Peering System and be able to make Routes available in
accordance with this GPA.
DUNDi, IAX, Asterisk and GPA are trademarks of Digium, Inc.
\end{verbatim}

486
doc/ael.txt → doc/ael.tex
View File

File diff suppressed because it is too large Load Diff

38
doc/ajam.txt → doc/ajam.tex
View File

@ -1,37 +1,38 @@
Asynchronous Javascript Asterisk Manger (AJAM)
==============================================
\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:
Setup the Asterisk HTTP server
------------------------------
\subsection{Setup the Asterisk HTTP server}
1) Uncomment the line "enabled=yes" in /etc/asterisk/http.conf to enable
\begin{enumerate}
\item Uncomment the line "enabled=yes" in /etc/asterisk/http.conf to enable
Asterisk's builtin micro HTTP server.
2) If you want Asterisk to actually deliver simple HTML pages, CSS,
\item If you want Asterisk to actually deliver simple HTML pages, CSS,
javascript, etc. you should uncomment "enablestatic=yes"
3) Adjust your "bindaddr" and "bindport" settings as appropriate for
\item Adjust your "bindaddr" and "bindport" settings as appropriate for
your desired accessibility
4) Adjust your "prefix" if appropriate, which must be the beginning of
\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}
Allow Manager Access via HTTP
-----------------------------
\subsection{Allow Manager Access via HTTP}
1) Make sure you have both "enabled = yes" and "webenabled = yes" setup
\begin{enumerate}
\item Make sure you have both "enabled = yes" and "webenabled = yes" setup
in /etc/asterisk/manager.conf
2) You may also use "httptimeout" to set a default timeout for HTTP
\item You may also use "httptimeout" to set a default timeout for HTTP
connections.
3) Make sure you have a manager username/secret
\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
@ -40,7 +41,7 @@ list can be found by typing "show http" at the Asterisk CLI.
examples:
http://localhost:8088/asterisk/manager?action=login&username=foo&secret=bar
http://localhost:8088/asterisk/manager?action=login\&username=foo\&secret=bar
This logs you into the manager interface's "HTML" view. Once you're
logged in, Asterisk stores a cookie on your browser (valid for the
@ -70,8 +71,7 @@ manager HTML interfaces.
Note that for the demo, there is no need for *any* external web server.
Integration with other web servers
----------------------------------
\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
@ -83,9 +83,3 @@ will likely need to use a more traditional web server like Apache and
link in your Asterisk micro HTTP server with something like this:
ProxyPass /asterisk http://localhost:8088/asterisk
This is a fairly new technology so I'd love to hear if it's useful for
you!
Mark

93
doc/app-sms.txt → doc/app-sms.tex
View File

@ -1,5 +1,4 @@
* Application SMS
\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
@ -9,7 +8,7 @@
locations such as the US, and use of SMS capable phones such as the
Magic Messenger. SMS works using analogue or ISDN lines.
Background
\section{Background}
Short Message Service (SMS), or texting is very popular between mobile
phones. A message can be sent between two phones, and normally
@ -17,11 +16,13 @@ Background
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
@ -34,48 +35,58 @@ Background
before the first ring, so no phones in the house would ring when a
message arrives.
Typical use with Asterisk
\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).
Terminology
\section{Terminology}
SMS
\begin{itemize}
\item SMS -
Short Message Service
i.e. text messages
SMSC
\item SMSC -
Short Message Service Centre
The system responsible for storing and forwarding messages
MO
\item MO -
Mobile Originated
A message on its way from a mobile or landline device to the SMSC
MT
\item MT -
Mobile Terminated
A message on its way from the SMSC to the mobile or landline device
RX
\item RX -
Receive
A message coming in to the Asterisk box
TX
\item TX -
Transmit
A message going out of the Asterisk box
\end{itemize}
Sub address
\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
@ -85,29 +96,22 @@ Sub address
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.
Build / installation
app_sms.c is included in the Asterisk source apps directory and is
included in the object list (app_sms.so) in apps/Makefile.
smsq.c is a stand alone helper application which is used to send SMSs
from the command line. It uses the popt library. A line for your make
file is:-
smsq: smsq.c
cc -O -o smsq smsq.c -lpopt
extensions.conf
\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
@ -152,13 +156,15 @@ exten = _X./_080058752[0-8]0,1,Goto(smsmtrx,${EXTEN}-${CALLERIDNUM:9:1},1)
handling a call from a sip phone is:-
exten = 17094009,1,Goto(smsmorx,${CALLERIDNUM},1)
exten = _1709400[0-8],1,Goto(smsmorx,${CALLERIDNUM}-{EXTEN:7:1},1)
\end{verbatim}
Using smsq
\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
@ -167,15 +173,17 @@ Using smsq
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
@ -310,6 +318,7 @@ Using smsq
* 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
@ -325,6 +334,7 @@ Using smsq
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
@ -335,6 +345,7 @@ Using smsq
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).
@ -344,7 +355,7 @@ Using smsq
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
@ -369,13 +380,15 @@ Using smsq
other
Other fields set using their field name, e.g. mr, pid, dcs, etc. udh
is a hex byte string
\end{verbatim}
File formats
\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
@ -387,11 +400,12 @@ File formats
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
@ -416,7 +430,7 @@ File formats
Present on mobile originated messages, added by default if absent
srr
0 or 1 for status report request
Does not work in UK yet, not implemented in app_sms yet
Does not work in UK yet, not implemented in app\_sms yet
rp
0 or 1 return path
See GSM specs for details
@ -431,34 +445,40 @@ File formats
header must be in the ud field
ud
User data, may be text, or hex, see below
\end{verbatim}
udh is specified as as udh# followed by hex (2 hex digits per byte).
udh is specified as as udh\# followed by hex (2 hex digits per byte).
If present, then the user data header indicator bit is set, and the
length plus the user data header is added to the start of the user
data, with padding if necessary (to septet boundary in 7 bit format).
User data can hold an USC character codes U+0000 to U+FFFF. Any other
characters are coded as U+FEFF
ud can be specified as ud= followed by UTF-8 encoded text if it
contains no control characters, i.e. only (U+0020 to U+FFFF). Any
invalid UTF-8 sequences are treated as is (U+0080-U+00FF).
ud can also be specified as ud# followed by hex (2 hex digits per
ud can also be specified as ud\# followed by hex (2 hex digits per
byte) containing characters U+0000 to U+00FF only.
ud can also be specified as ud## followed by hex (4 hex digits per
ud can also be specified as ud\#\# followed by hex (4 hex digits per
byte) containing UCS-2 characters.
When written by app_sms (e.g. incoming messages), the file is written
When written by app\_sms (e.g. incoming messages), the file is written
with ud= if it can be (no control characters). If it cannot, the a
comment line ;ud= is used to show the user data for human readability
and ud# or ud## is used.
and ud\# or ud\#\# is used.
Delivery reports
\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
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.
@ -468,3 +488,4 @@ Delivery reports
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}

10
doc/apps.txt
View File

@ -1,10 +0,0 @@
Asterisk applications register themselves with ast_application_register.
They should have a short, unique name, and an exec function which takes
as its arguments a channel and some data that might be useful for callback
stuff. Remember to keep track of how many and which channels are using
your application so that should the module need to be unloaded
(particularly force unloaded), you will be able to ast_softhangup all the
channels. An application should *never* call ast_hangup on the channel
that it is running on (although it could conceivably hang up other
channels that it allocates). See app_playback.c as an example of a simple
application.

3225
doc/ast_appdocs.tex Normal file
View File

File diff suppressed because it is too large Load Diff

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

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

85
doc/asterisk-conf.txt
View File

@ -1,85 +0,0 @@
Asterisk Main Configuration File
-----------------------------------------------------
Below is a sample of the main Asterisk configuration file,
asterisk.conf. Note that this file is _not_ provided in
sample form, because the Makefile creates it when needed
and does not touch it when it already exists.
---------------
[directories]
; Make sure these directories have the right permissions if not
; running Asterisk as root
; Where the configuration files (except for this one) are located
astetcdir => /etc/asterisk
; Where the Asterisk loadable modules are located
astmoddir => /usr/lib/asterisk/modules
; Where additional 'library' elements (scripts, etc.) are located
astvarlibdir => /var/lib/asterisk
; Where AGI scripts/programs are located
astagidir => /var/lib/asterisk/agi-bin
; Where spool directories are located
; Voicemail, monitor, dictation and other apps will create files here
; and outgoing call files (used with pbx_spool) must be placed here
astspooldir => /var/spool/asterisk
; Where the Asterisk process ID (pid) file should be created
astrundir => /var/run/asterisk
; Where the Asterisk log files should be created
astlogdir => /var/log/asterisk
[options]
;Under "options" you can enter configuration options
;that you also can set with command line options
verbose = 0 ; Verbosity level for logging (-v)
debug = 3 ; Debug: "No" or value (1-4)
nofork=yes | no ; Background execution disabled (-f)
alwaysfork=yes | no ; Always background, even with -v or -d (-F)
console= yes | no ; Console mode (-c)
highpriority = yes | no ; Execute with high priority (-p)
initcrypto = yes | no ; Initialize crypto at startup (-i)
nocolor = yes | no ; Disable ANSI colors (-n)
dumpcore = yes | no ; Dump core on failure (-g)
quiet = yes | no ; Run quietly (-q)
timestamp = yes | no ; Force timestamping in CLI verbose output (-T)
runuser = asterisk ; User to run asterisk as (-U) NOTE: will require changes to
; directory and device permissions
rungroup = asterisk ; Group to run asterisk as (-G)
internal_timing = yes | no ; Enable internal timing support (-I)
;These options have no command line equivalent
cache_record_files = yes | no ; Cache record() files in another directory until completion
record_cache_dir = <dir>
transcode_via_sln = yes | no ; Build transcode paths via SLINEAR
transmit_silence_during_record = yes | no ; send SLINEAR silence while channel is being recorded
maxload = 1.0 ; The maximum load average we accept calls for
maxcalls = 255 ; The maximum number of concurrent calls you want to allow
execincludes = yes | no ; Allow #exec entries in configuration files
dontwarn = yes | no ; Don't over-inform the Asterisk sysadm, he's a guru
systemname = <a_string> ; System name. Used to prefix CDR uniqueid and to fill ${SYSTEMNAME}
languageprefix = no | yes ; 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)
; NOTE: this option is deprecated, as the default value is now 'yes'
maxlimit = <value> ; Maximum number open files for the Asterisk process
[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

132
doc/asterisk.tex Normal file
View File

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

87
doc/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.

105
doc/billing.txt
View File

@ -1,105 +0,0 @@
Asterisk billing support - Call Detail Records
----------------------------------------------
Asterisk generates Call Detail Records in a database or in a comma
separated text file.
* cdr_csv supports comma separated text file storage, this is the
default driver
* cdr_manager supports CDR information via the AMI, The Asterisk Manager
interface
* cdr_odbc supports UnixODBC databases, see http://www.unixodbc.org
for an updated list of supported databases, from MySQL to MsSQL
and text files.
* cdr_tds supports FreeTDS databases (Among them MS SQL)
NOTE: Please read doc/freetds.txt for information on possible
problems with the FreeTDS driver
* cdr_sqlite supports SQlite
* cdr_pgsql supports PostgreSQL
In the asterisk-addons subversion repository, there's a cdr_mysql driver for
MySQL.
Applications
------------
* SetAccount Set account code for billing
* SetAMAFlags Sets AMA flags
* NoCDR Make sure no CDR is saved for a specific call
* ResetCDR Reset CDR
* ForkCDR Save current CDR and start a new CDR for this call
* Authenticate Authenticates and sets the account code
* SetCDRUserField Set CDR user field
* AppendCDRUserField Append data to CDR User field
For more information, use the "show application" command.
You can set default account codes and AMA flags for devices in
channel configuration files, like sip.conf, iax.conf etc.
Fields of the CDR in Asterisk
-----------------------------
1. accountcode: What account number to use, (string, 20 characters)
2. src: Caller*ID number (string, 80 characters)
3. dst: Destination extension (string, 80 characters)
4. dcontext: Destination context (string, 80 characters)
5. clid: Caller*ID with text (80 characters)
6. channel: Channel used (80 characters)
7. dstchannel: Destination channel if appropriate (80 characters)
8. lastapp: Last application if appropriate (80 characters)
9. lastdata: Last application data (arguments) (80 characters)
10. start: Start of call (date/time)
11. answer: Answer of call (date/time)
12. end: End of call (date/time)
13. duration: Total time in system, in seconds (integer), from dial to hangup
14. billsec: Total time call is up, in seconds (integer), from answer to hangup
15. disposition: What happened to the call: ANSWERED, NO ANSWER, BUSY
16. amaflags: What flags to use: DOCUMENTATION, BILL, IGNORE etc,
specified on a per channel basis like accountcode.
17. user field: A user-defined field, maximum 255 characters
In some cases, uniqueid is appended:
* uniqueid: Unique Channel Identifier (32 characters)
This needs to be enabled in the source code at compile time
NOTE: If you use IAX2 channels for your calls, and allow 'full' transfers
(not media-only transfers), then when the calls is transferred the server
in the middle will no longer be involved in the signaling path, and thus
will not generate accurate CDRs for that call. If you can, use media-only
transfers with IAX2 to avoid this problem, or turn off transfers completely
(although this can result in a media latency increase since the media packets
have to traverse the middle server(s) in the call).
____________________________________
CDR Variables
------------------------------------
If the channel has a cdr, that cdr record has its own set of variables which
can be accessed just like channel variables. The following builtin variables
are available.
${CDR(clid)} Caller ID
${CDR(src)} Source
${CDR(dst)} Destination
${CDR(dcontext)} Destination context
${CDR(channel)} Channel name
${CDR(dstchannel)} Destination channel
${CDR(lastapp)} Last app executed
${CDR(lastdata)} Last app's arguments
${CDR(start)} Time the call started.
${CDR(answer)} Time the call was answered.
${CDR(end)} Time the call ended.
${CDR(duration)} Duration of the call.
${CDR(billsec)} Duration of the call once it was answered.
${CDR(disposition)} ANSWERED, NO ANSWER, BUSY
${CDR(amaflags)} DOCUMENTATION, BILL, IGNORE etc
${CDR(accountcode)} The channel's account code.
${CDR(uniqueid)} The channel's unique id.
${CDR(userfield)} The channels uses specified field.
In addition, you can set your own extra variables by using Set(CDR(name)=value).
These variables can be output into a text-format CDR by using the cdr_custom
CDR driver; see the cdr_custom.conf.sample file in the configs directory for
an example of how to do this.

18
doc/callingpres.txt
View File

@ -1,18 +0,0 @@
Caller ID presentation values
-----------------------------
In some channels it is possible to set Caller ID presentation for a device. It is
also possible to set the presentation for an active channel in the dial plan
with the setcallerpres() application.
Valid values are:
allowed_not_screened : Presentation Allowed, Not Screened
allowed_passed_screen : Presentation Allowed, Passed Screen
allowed_failed_screen : Presentation Allowed, Failed Screen
allowed : Presentation Allowed, Network Number
prohib_not_screened : Presentation Prohibited, Not Screened
prohib_passed_screen : Presentation Prohibited, Passed Screen
prohib_failed_screen : Presentation Prohibited, Failed Screen
prohib : Presentation Prohibited, Network Number
unavailable : Number Unavailable

431
doc/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}

215
doc/cdrdriver.txt
View File

@ -1,215 +0,0 @@
Call data records can be stored in many different databases or even CSV text.
MSSQL: Asterisk can currently store CDRs into an MSSQL database in
two different ways: cdr_odbc.c or cdr_tds.c
Call Data Records can be stored using unixODBC (which requires
the FreeTDS package) [cdr_odbc.c] or directly by using just the
FreeTDS package [cdr_tds.c] The following provide some
examples known to get asterisk working with mssql.
NOTE: Only choose one db connector.
ODBC [cdr_odbc.c]:
Compile, configure, and install the latest unixODBC package:
tar -zxvf unixODBC-2.2.9.tar.gz &&
cd unixODBC-2.2.9 &&
./configure --sysconfdir=/etc --prefix=/usr --disable-gui &&
make &&
make install
Compile, configure, and install the latest FreeTDS package:
tar -zxvf freetds-0.62.4.tar.gz &&
cd freetds-0.62.4 &&
./configure --prefix=/usr --with-tdsver=7.0 \
--with-unixodbc=/usr/lib &&
make &&
make install
Compile, or recompile, asterisk so that it will now add support
for cdr_odbc.c
make clean &&
make update &&
make &&
make install
Setup odbc configuration files. These are working examples
from my system. You will need to modify for your setup.
You are not required to store usernames or passwords here.
/etc/odbcinst.ini
[FreeTDS]
Description = FreeTDS ODBC driver for MSSQL
Driver = /usr/lib/libtdsodbc.so
Setup = /usr/lib/libtdsS.so
FileUsage = 1
/etc/odbc.ini
[MSSQL-asterisk]
description = Asterisk ODBC for MSSQL
driver = FreeTDS
server = 192.168.1.25
port = 1433
database = voipdb
tds_version = 7.0
language = us_english
Only install one database connector. Do not confuse asterisk
by using both ODBC (cdr_odbc.c) and FreeTDS (cdr_tds.c).
This command will erase the contents of cdr_tds.conf
[ -f /etc/asterisk/cdr_tds.conf ] > /etc/asterisk/cdr_tds.conf
NOTE: unixODBC requires the freeTDS package, but asterisk does
not call freeTDS directly.
Setup cdr_odbc configuration files. These are working samples
from my system. You will need to modify for your setup. Define
your usernames and passwords here, secure file as well.
/etc/asterisk/cdr_odbc.conf
[global]
dsn=MSSQL-asterisk
username=voipdbuser
password=voipdbpass
loguniqueid=yes
And finally, create the 'cdr' table in your mssql database.
CREATE TABLE cdr (
[calldate] [datetime] NOT NULL ,
[clid] [varchar] (80) NOT NULL ,
[src] [varchar] (80) NOT NULL ,
[dst] [varchar] (80) NOT NULL ,
[dcontext] [varchar] (80) NOT NULL ,
[channel] [varchar] (80) NOT NULL ,
[dstchannel] [varchar] (80) NOT NULL ,
[lastapp] [varchar] (80) NOT NULL ,
[lastdata] [varchar] (80) NOT NULL ,
[duration] [int] NOT NULL ,
[billsec] [int] NOT NULL ,
[disposition] [varchar] (45) NOT NULL ,
[amaflags] [int] NOT NULL ,
[accountcode] [varchar] (20) NOT NULL ,
[uniqueid] [varchar] (32) NOT NULL ,
[userfield] [varchar] (255) NOT NULL
)
Start asterisk in verbose mode, you should see that asterisk
logs a connection to the database and will now record every
call to the database when it's complete.
TDS [cdr_tds.c]:
Compile, configure, and install the latest FreeTDS package:
tar -zxvf freetds-0.62.4.tar.gz &&
cd freetds-0.62.4 &&
./configure --prefix=/usr --with-tdsver=7.0
make &&
make install
Compile, or recompile, asterisk so that it will now add support
for cdr_tds.c
make clean &&
make update &&
make &&
make install
Only install one database connector. Do not confuse asterisk
by using both ODBC (cdr_odbc.c) and FreeTDS (cdr_tds.c).
This command will erase the contents of cdr_odbc.conf
[ -f /etc/asterisk/cdr_odbc.conf ] > /etc/asterisk/cdr_odbc.conf
Setup cdr_tds configuration files. These are working samples
from my system. You will need to modify for your setup. Define
your usernames and passwords here, secure file as well.
/etc/asterisk/cdr_tds.conf
[global]
hostname=192.168.1.25
port=1433
dbname=voipdb
user=voipdbuser
password=voipdpass
charset=BIG5
And finally, create the 'cdr' table in your mssql database.
CREATE TABLE cdr (
[accountcode] [varchar] (20) NULL ,
[src] [varchar] (80) NULL ,
[dst] [varchar] (80) NULL ,
[dcontext] [varchar] (80) NULL ,
[clid] [varchar] (80) NULL ,
[channel] [varchar] (80) NULL ,
[dstchannel] [varchar] (80) NULL ,
[lastapp] [varchar] (80) NULL ,
[lastdata] [varchar] (80) NULL ,
[start] [datetime] NULL ,
[answer] [datetime] NULL ,
[end] [datetime] NULL ,
[duration] [int] NULL ,
[billsec] [int] NULL ,
[disposition] [varchar] (20) NULL ,
[amaflags] [varchar] (16) NULL ,
[uniqueid] [varchar] (32) NULL
)
Start asterisk in verbose mode, you should see that asterisk
logs a connection to the database and will now record every
call to the database when it's complete.
MYSQL:
PGSQL:
If you want to go directly to postgresql database, and have the cdr_pgsql.so
compiled you can use the following sample setup.
On Debian, before compiling asterisk, just install libpqxx-dev.
Other distros will likely have a similiar package.
Once you have the compile done,
copy the sample cdr_pgsql.conf file or create your own.
Here is a sample:
/etc/asterisk/cdr_pgsql.conf
; Sample Asterisk config file for CDR logging to PostgresSQL
[global]
hostname=localhost
port=5432
dbname=asterisk
password=password
user=postgres
table=cdr
;Now create a table in postgresql for your cdrs
;SQL table where CDRs will be inserted
;Copy and paste this into your postgresql prompt.
CREATE TABLE cdr (
calldate time NOT NULL ,
clid varchar (80) NOT NULL ,
src varchar (80) NOT NULL ,
dst varchar (80) NOT NULL ,
dcontext varchar (80) NOT NULL ,
channel varchar (80) NOT NULL ,
dstchannel varchar (80) NOT NULL ,
lastapp varchar (80) NOT NULL ,
lastdata varchar (80) NOT NULL ,
duration int NOT NULL ,
billsec int NOT NULL ,
disposition varchar (45) NOT NULL ,
amaflags int NOT NULL ,
accountcode varchar (20) NOT NULL ,
uniqueid varchar (32) NOT NULL ,
userfield varchar (255) NOT NULL
);
SQLLITE:
RADIUS: See doc/radius.txt for more information on cdr_radius

84
doc/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.

369
doc/chaniax.txt
View File

@ -1,369 +0,0 @@
Inter-Asterisk eXchange Protocol
================================
INTRODUCTION
------------
This document is intended as an introduction to the Inter-Asterisk
eXchange (or simply IAX) protocol. It provides both a theoretical
background and practical information on its use.
WHY IAX
-------
The first question most people are thinking at this point is "Why do you
need another VoIP protocol? Why didn't you just use SIP or H.323?"
Well, the answer is a fairly complicated one, but in a nutshell it's like
this... Asterisk is intended as a very flexible and powerful
communications tool. As such, the primary feature we need from a VoIP
protocol is the ability to meet our own goals with Asterisk, and one with
enough flexibility that we could use it as a kind of laboratory for
inventing and implementing new concepts in the field. Neither H.323 or
SIP fit the roles we needed, so we developed our own protocol, which,
while not standards based, provides a number of advantages over both SIP
and H.323, some of which are:
* Interoperability with NAT/PAT/Masquerade firewalls
IAX seamlessly interoperates through all sorts of NAT and PAT
and other firewalls, including the ability to place and
receive calls, and transfer calls to other stations.
* High performance, low overhead protocol
When running on low-bandwidth connections, or when running
large numbers of calls, optimized bandwidth utilization is
imperative. IAX uses only 4 bytes of overhead
* Internationalization support
IAX transmits language information, so that remote PBX
content can be delivered in the native language of the
calling party.
* Remote dialplan polling
IAX allows a PBX or IP phone to poll the availability of a
number from a remote server. This allows PBX dialplans to
be centralized.
* Flexible authentication
IAX supports cleartext, md5, and RSA authentication,
providing flexible security models for outgoing calls and
registration services.
* Multimedia protocol
IAX supports the transmission of voice, video, images, text,
HTML, DTMF, and URL's. Voice menus can be presented in both
audibly and visually.
* Call statistic gathering
IAX gathers statistics about network performance (including
latency and jitter, as well as providing end-to-end latency
measurement.
* Call parameter communication
Caller*ID, requested extension, requested context, etc are
all communicated through the call.
* Single socket design
IAX's single socket design allows up to 32768 calls to be
multiplexed.
While we value the importance of standards based (i.e. SIP) call handling,
hopefully this will provide a reasonable explanation of why we developed
IAX rather than starting with SIP.
CONFIG FILE CONVENTIONS
-----------------------
Lines beginning with '>' represent lines which might appear in an actual
configuration file. The '>' is used to help separate them from the
descriptive text and should not actually be included in the file itself.
Lines within []'s by themselves represent section labels within the
configuration file. like this:
> [mysection]
Options are set using the "=" sign, for example
> myoption = value
Sometimes an option will have a number of discrete values which it can
take. In that case, in the documentation, the options will be listed
within square brackets (the "[" and "]" ones) separated by the pipe symbol
("|"). For example:
> myoption = [value1|value2|value3]
means the option "myoption" can be assigned a value of "value1", "value2",
or "value3".
Objects, or pseudo-objects are instantiated using the "=>" construct. For
example:
> myobject => parameter
creates an object called "myobject" with some parameter whose definition
would be specific to that object. Note that the config file parser
considers "=>" and "=" to be equivalent and their use is purely to make
configuration files more readable and easier to "humanly parse".
The comment character in Asterisk configuration files is the semicolon
";". The reason it is not "#" is because the "#" symbol can be used as
parts of extensions and it didn't seem like a good idea to have to escape
it.
IAX CONFIGURATION IN ASTERISK
-----------------------------
Like everything else in Asterisk, IAX's configuration lies in
/etc/asterisk -- specifically /etc/asterisk/iax.conf
The IAX configuration file is a collection of sections, each of which
(with the exception of the "general" section) represents an entity within
the IAX scope.
------------
The first section is typically the "general" section. In this area,
a number of parameters which affect the entire system are configured.
Specifically, the default codecs, port and address, jitter behavior, TOS
bits, and registrations.
The first line of the "general" section is always:
> [general]
Following the first line are a number of other possibilities:
> bindport = <portnum>
This sets the port that IAX will bind to. The default IAX version 1
port number is 5036. For IAX version 2, that is now the default in
Asterisk, the default port is 4569.
It is recommended that this value not be altered in general.
> bindaddr = <ipaddr>
This allows you to bind IAX to a specific local IP address instead of
binding to all addresses. This could be used to enhance security if, for
example, you only wanted IAX to be available to users on your LAN.
> bandwidth = [low|medium|high]
The bandwidth selection initializes the codec selection to appropriate
values for given bandwidths. The "high" selection enables all codecs and
is recommended only for 10Mbps or higher connections. The "medium"
bandwidth eliminates signed linear, Mu-law and A-law codecs, leaving only
the codecs which are 32kbps and smaller (with MP3 as a special case). It
can be used with broadband connections if desired. "low" eliminates ADPCM
and MP3 formats, leaving only the G.723.1, GSM, and LPC10.
> allow = [gsm|lpc10|g723.1|adpcm|ulaw|alaw|mp3|slinear|all]
> disallow = [gsm|lpc10|g723.1|adpcm|ulaw|alaw|mp3|slinear|all]
The "allow" and "disallow" allow you to fine tune the codec selection
beyond the initial bandwidth selection on a codec-by-codec basis.
The recommended configuration is to select "low" bandwidth and then
disallow the LPC10 codec just because it doesn't sound very good.
> jitterbuffer = [yes|no]
> dropcount = <dropamount>
> maxjitterbuffer = <max>
> maxexcessbuffer = <max>
These parameters control the operation of the jitter buffer. The
jitterbuffer should always be enabled unless you expect all your
connections to be over a LAN.
* drop count is the maximum number of voice packets to allow to drop
(out of 100). Useful values are 3-10.
* maxjitterbuffer is the maximum amount of jitter buffer to permit to be
used.
* maxexcessbuffer is the maximum amount of excess jitter buffer
that is permitted before the jitter buffer is slowly shrunk to eliminate
latency.
* minexcessbuffer is the minimum amount of excess jitter buffer
> accountcode = <code>
> amaflags = [default|omit|billing|documentation]
These parameters affect call detail record generation. The first sets the
account code for records received with IAX. The account code can be
overridden on a per-user basis for incoming calls (see below). The
amaflags controls how the record is labeled ("omit" causes no record to be
written. "billing" and "documentation" label the records as billing or
documentation records respectively, and "default" selects the system
default.
> tos = [lowdelay|throughput|reliability|mincost|none]
IAX can optionally set the TOS (Type of Service) bits to specified values
to help improve performance in routing. The recommended value is
"lowdelay", which many routers (including any Linux routers with 2.4
kernels that have not been altered with ip tables) will give priority to
these packets, improving voice quality.
> register => <name>[:<secret>]@<host>[:port]
Any number of registry entries may be instantiated in the general
section. Registration allows Asterisk to notify a remote Asterisk server
(with a fixed address) what our current address is. In order for
registration to work, the remote Asterisk server will need to have a
dynamic peer entry with the same name (and secret if provided).
The name is a required field, and is the remote peer name that we wish to
identify ourselves as. A secret may be provided as well. The secret is
generally a shared password between the local server and the remote
server. However, if the secret is in square brackets ([]'s) then it is
interpreted as the name of a RSA key to use. In that case, the local Asterisk
server must have the *private* key (/var/lib/asterisk/keys/<name>.key) and
the remote server will have to have the corresponding public key.
The "host" is a required field and is the hostname or IP address of the
remote Asterisk server. The port specification is optional and is by
default 4569 for iax2 if not specified.
> notransfer = yes | no
If an IAX phone calls another IAX phone by using a Asterisk server,
Asterisk will transfer the call to go peer to peer. If you do not
want this, turn on notransfer with a "yes". This is also settable
for peers and users.
-------------
The following sections, after "general" define either users, peers or
friends. A "user" is someone who connects to us. A "peer" is someone
that we connect to. A "friend" is simply shorthand for creating a "user"
and "peer" with identical parameters (i.e. someone who can contact us and
who we contact).
> [identifier]
The section begins with the identifier in square brackets. The identifier
should be an alphanumeric string.
> type = [user|peer|friend]
This line tells Asterisk how to interpret this entity. Users are things
that connect to us, while peers are phones we connect to, and a friend is
shorthand for creating a user and a peer with identical information
----------------
User fields:
> context = <context>
One or more context lines may be specified in a user, thus giving the user
access to place calls in the given contexts. Contexts are used by
Asterisk to divide dialing plans into logical units each with the ability
to have numbers interpreted differently, have their own security model,
auxiliary switch handling, and include other contexts. Most users are
given access to the default context. Trusted users could be given access
to the local context for example.
> permit = <ipaddr>/<netmask>
> deny = <ipaddr>/<netmask>
Permit and deny rules may be applied to users, allowing them to connect
from certain IP addresses and not others. The permit and deny rules are
interpreted in sequence and all are evaluated on a given IP address, with
the final result being the decision. For example:
> permit = 0.0.0.0/0.0.0.0
> deny = 192.168.0.0/255.255.255.0
would deny anyone in 192.168.0.0 with a netmask of 24 bits (class C),
whereas:
> deny = 192.168.0.0/24
> permit = 0.0.0.0/0
would not deny anyone since the final rule would permit anyone, thus
overriding the denial.
If no permit/deny rules are listed, it is assumed that someone may connect
from anywhere.
> callerid = <callerid>
You may override the Caller*ID information passed by a user to you (if
they choose to send it) in order that it always be accurate from the
perspective of your server.
> auth = [md5|plaintext|rsa]
You may select which authentication methods are permitted to be used by
the user to authenticate to us. Multiple methods may be specified,
separated by commas. If md5 or plaintext authentication is selected, a
secret must be provided. If RSA authentication is specified, then one or
more key names must be specified with "inkeys"
If no secret is specified and no authentication method is specified, then
no authentication will be required.
> secret = <secret>
The "secret" line specifies the shared secret for md5 and plaintext
authentication methods. It is never suggested to use plaintext except in
some cases for debugging.
> inkeys = key1[:key2...]
The "inkeys" line specifies which keys we can use to authenticate the
remote peer. If the peer's challenge passes with any of the given keys,
then we accept its authentication. The key files live in
/var/lib/asterisk/keys/<name>.pub and are *public keys*. Public keys are
not typically DES3 encrypted and thus do not usually need initialization.
---------------
Peer configuration
> allow = [gsm|lpc10|g723.1|adpcm|ulaw|alaw|mp3|slinear|all]
> disallow = [gsm|lpc10|g723.1|adpcm|ulaw|alaw|mp3|slinear|all]
The "allow" and "disallow" may be used to enable or disable specific codec
support on a per-peer basis.
> host = [<ipaddr>|dynamic]
The host line specifies the hostname or IP address of the remote host, or
may be the word "dynamic" signifying that the host will register with us
(see register => in the general section above).
> defaultip = <ipaddr>
If the host uses dynamic registration, Asterisk may still be given a
default IP address to use when dynamic registration has not been performed
or has timed out.
> peercontext = <context>
Specifies the context name to be passed to the peer for it to use when routing
the call through its dial plan. This entry will be used only if a context
is not included in the IAX2 channel name passed to the Dial command.
> qualify = [yes | no | <value>]
Qualify turns on checking of availability of the remote peer. If the
peer becomes unavailable, no calls are placed to the peer until
it is reachable again. This is also helpful in certain NAT situations.
> jitterbuffer = [yes | no]
Turns on or off the jitterbuffer for this peer
> mailbox = <mailbox>[@mailboxcontext]
Specifies a mailbox to check for voicemail notification.
> permit = <ipaddr>/<netmask>
> deny = <ipaddr>/<netmask>
Permit and deny rules may be applied to users, allowing them to connect
from certain IP addresses and not others. The permit and deny rules are
interpreted in sequence and all are evaluated on a given IP address, with
the final result being the decision. See the user section above
for examples.
----------------------------------------------------------------------
For more examples of a configuration, please see the iax.conf.sample in
your the /configs directory of you source code distribution

44
doc/channels.txt
View File

@ -1,44 +0,0 @@
Implementing a Channel
======================
* What is a channel?
A channel is a unit which brings in a call to the Asterisk PBX. A channel
could be connected to a real telephone (like the Internet Phone Jack) or
to a logical call (like an Internet phone call). Asterisk makes no
distinction between "FXO" and "FXS" style channels (that is, it doesn't
distinguish between telephone lines and telephones).
Every call is placed or received on a distinct channel. Asterisk uses a
channel driver (typically named chan_xxx.so) to support each type of
hardware.
* What do I need to create a channel?
In order to support a new piece of hardware you need to write a channel
driver. The easiest way to do so is to look at an existing channel driver
and model your own code after it.
* What's the general architecture?
Typically, a channel reads a configuration file on startup which tells it
something about the hardware it's going to be servicing. Then, it
launches a thread which monitors all the idle channels (See the chan_modem
or the chan_ixj for an example of this). When a "RING" or equivalent is
detected, the monitoring thread should allocate a channel structure and
assign all the callbacks to it (see ixj_new, for example), and then call
ast_pbx_start on that channel. ast_pbx_start will launch a new thread to
handle the channel as long as the call is up, so once pbx_start has
successfully been run, the monitor should no longer monitor that channel.
The PBX thread will use the channel, reading, writing, calling, etc., and
multiplexing that channel with others using select() on the channel's
file descriptor (if your channel doesn't have an associated file
descriptor, you'll need to emulate one somehow, perhaps along the lines of
what the translator API does with its channel.
When the PBX is finished with the line, it will hang up the line, at which
point it the hardware should again be monitored by the monitoring thread.
---------------
For more information, please consult the Asterisk Developer's Documentation
on http://www.asterisk.org

377
doc/channelvariables.txt → doc/channelvariables.tex
View File

@ -1,89 +1,82 @@
----------------------------
Asterisk dial plan variables
----------------------------
\section{Introduction}
There are two levels of parameter evaluation done in the Asterisk
dial plan in extensions.conf.
* The first, and most frequently used, is the substitution of variable
\begin{enumerate}
\item The first, and most frequently used, is the substitution of variable
references with their values.
* Then there are the evaluations of expressions done in $[ .. ].
\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.
___________________________
PARAMETER QUOTING:
---------------------------
\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 \\).
(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.
___________________________
VARIABLES:
---------------------------
\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)
You can substitute the value of a variable everywhere using ${variablename}.
For example, to stringwise append $lala to $blabla and store result in $koko,
\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
enclose it inside \${}. For example, Set takes as the first argument
(before the =) a variable name, so:
\begin{verbatim}
exten => 1,2,Set(koko=lala)
exten => 1,3,Set(${koko}=blabla)
\end{verbatim}
stores to the variable "koko" the value "lala" and to variable "lala" the
value "blabla".
In fact, everything contained ${here} is just replaced with the value of
In fact, everything contained \${here} is just replaced with the value of
the variable "here".
____________________
VARIABLE INHERITANCE
--------------------
\section{Variable Inheritance}
Variable names which are prefixed by "_" will be inherited to channels
Variable names which are prefixed by "\_" will be inherited to channels
that are created in the process of servicing the original channel in
which the variable was set. When the inheritance takes place, the
prefix will be removed in the channel inheriting the variable. If the
name is prefixed by "__" in the channel, then the variable is
inherited and the "__" will remain intact in the new channel.
name is prefixed by "\_\_" in the channel, then the variable is
inherited and the "\_\_" will remain intact in the new channel.
In the dialplan, all references to these variables refer to the same
variable, regardless of having a prefix or not. Note that setting any
version of the variable removes any other version of the variable,
regardless of prefix.
Example:
\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.
@ -91,24 +84,22 @@ Set(FOO=bar) ; Removes the inherited version and sets a local
However,
NoOp(${__FOO}) is identical to NoOp(${FOO})
\end{verbatim}
___________________________________
SELECTING CHARACTERS FROM VARIABLES
-----------------------------------
\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
@ -118,60 +109,58 @@ 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}
___________________________
EXPRESSIONS:
---------------------------
\section{Expressions}
Everything contained inside a bracket pair prefixed by a $ (like $[this]) is
Everything contained inside a bracket pair prefixed by a \$ (like \$[this]) is
considered as an expression and it is evaluated. Evaluation works similar to
(but is done on a later stage than) variable substitution: the expression
(including the square brackets) is replaced by the result of the expression
evaluation.
For example, after the sequence:
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.
______________________________
SPACES INSIDE VARIABLE VALUES
------------------------------
\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
@ -180,29 +169,35 @@ 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.
_____________________
OPERATORS
---------------------
\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.
@ -272,14 +267,16 @@ with equal precedence are grouped within { } symbols.
will be the result of the "evaluation" of this
expression. expr3 will be the result otherwise. This
operator has the lowest precedence.
\end{verbatim}
Parentheses are used for grouping in the usual manner.
Operator precedence is applied as one would expect in any of the C
or C derived languages.
Examples
\subsection{Examples}
\begin{verbatim}
"One Thousand Five Hundred" =~ "(T[^ ]+)"
returns: Thousand
@ -313,26 +310,27 @@ Examples
(2+8)/2
returns 5, of course.
\begin{verbatim}
Of course, all of the above examples use constants, but would work the
same if any of the numeric or string constants were replaced with a
variable reference ${CALLERIDNUM}, for instance.
variable reference \${CALLERIDNUM}, for instance.
__________________________
NUMBERS VS STRINGS
--------------------------
\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.
___________________________
CONDITIONALS
---------------------------
\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.
@ -342,50 +340,52 @@ 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}
___________________________
PARSE ERRORS
---------------------------
\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
(\&) 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.
___________________________
NULL STRINGS
---------------------------
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.
@ -393,9 +393,7 @@ 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.
___________________________
WARNING
---------------------------
\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
@ -404,9 +402,7 @@ 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.
----------------------------
INCOMPATIBILITIES
----------------------------
\subsection{Incompatabilities}
The asterisk expression parser has undergone some evolution. It is hoped
that the changes will be viewed as positive.
@ -432,7 +428,8 @@ 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:
1. Tokens separated by space(s).
\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'
@ -440,10 +437,10 @@ of possible concern with "legacy" extension.conf files:
To keep such strings from being evaluated, simply wrap them in double
quotes: ' "1+1" '
2. The colon operator. In versions previous to double quoting, the
\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
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,
@ -454,41 +451,40 @@ of possible concern with "legacy" extension.conf files:
and the average regex expression is full of operators that
the scanner will recognize as expression operators. Thus, unless
the pattern is wrapped in double quotes, there will be trouble.
For instance, ${VAR1} : (Who|What*)+
For instance, \${VAR1} : (Who|What*)+
may have have worked before, but unless you wrap the pattern
in double quotes now, look out for trouble! This is better:
"${VAR1}" : "(Who|What*)+"
"\${VAR1}" : "(Who|What*)+"
and should work as previous.
3. Variables and Double Quotes
\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!
4. LE, GE, NE operators removed. The code supported these operators,
\item LE, GE, NE operators removed. The code supported these operators,
but they were not documented. The symbolic operators, <=, >=, and !=
should be used instead.
5. Added the unary '-' operator. So you can 3+ -4 and get -1.
\item Added the unary '-' operator. So you can 3+ -4 and get -1.
6. Added the unary '!' operator, which is a logical complement.
\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.
7. Added the '=~' operator, just in case someone is just looking for
\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.
8. Added the conditional operator 'expr1 ? true_expr :: false_expr'
First, all 3 exprs are evaluated, and if expr1 is false, the 'false_expr'
\item Added the conditional operator 'expr1 ? true\_expr :: false\_expr'
First, all 3 exprs are evaluated, and if expr1 is false, the 'false\_expr'
is returned as the result. See above for details.
9. Unary operators '-' and '!' were made right associative.
\item Unary operators '-' and '!' were made right associative.
\end{enumerate}
--------------------------------------------------------
DEBUGGING HINTS FOR $[ ] EXPRESSIONS
--------------------------------------------------------
\subsection{Debugging Hints}
There are two utilities you can build to help debug the $[ ] in
There are two utilities you can build to help debug the \$[ ] in
your extensions.conf file.
The first, and most simplistic, is to issue the command:
@ -507,7 +503,7 @@ is an example.
And, in the utils directory, you can say:
make check_expr
make check\_expr
and a small program will be built, that will check the file mentioned
in the first command line argument, for any expressions that might be
@ -515,44 +511,43 @@ have problems when you move to flex-2.5.31. It was originally
designed to help spot possible incompatibilities when moving from the
pre-2.5.31 world to the upgraded version of the lexer.
But one more capability has been added to check_expr, that might make
But one more capability has been added to check\_expr, that might make
it more generally useful. It now does a simple minded evaluation of
all variables, and then passes the $[] exprs to the parser. If there
all variables, and then passes the \$[] exprs to the parser. If there
are any parse errors, they will be reported in the log file. You can
use check_expr to do a quick sanity check of the expressions in your
use check\_expr to do a quick sanity check of the expressions in your
extensions.conf file, to see if they pass a crude syntax check.
The "simple-minded" variable substitution replaces ${varname} variable
The "simple-minded" variable substitution replaces \${varname} variable
references with '555'. You can override the 555 for variable values,
by entering in var=val arguments after the filename on the command
line. So...
check_expr /etc/asterisk/extensions.conf CALLERIDNUM=3075551212 DIALSTATUS=TORTURE EXTEN=121
check\_expr /etc/asterisk/extensions.conf CALLERIDNUM=3075551212 DIALSTATUS=TORTURE EXTEN=121
will substitute any ${CALLERIDNUM} variable references with
3075551212, any ${DIALSTATUS} variable references with 'TORTURE', and
any ${EXTEN} references with '121'. If there is any fancy stuff
going on in the reference, like ${EXTEN:2}, then the override will
not work. Everything in the ${...} has to match. So, to substitute
#{EXTEN:2} references, you'd best say:
will substitute any \${CALLERIDNUM} variable references with
3075551212, any \${DIALSTATUS} variable references with 'TORTURE', and
any \${EXTEN} references with '121'. If there is any fancy stuff
going on in the reference, like \${EXTEN:2}, then the override will
not work. Everything in the \${...} has to match. So, to substitute
\${EXTEN:2} references, you'd best say:
check_expr /etc/asterisk/extensions.conf CALLERIDNUM=3075551212 DIALSTATUS=TORTURE EXTEN:2=121
check\_expr /etc/asterisk/extensions.conf CALLERIDNUM=3075551212 DIALSTATUS=TORTURE EXTEN:2=121
on stdout, you will see something like:
OK -- $[ "${DIALSTATUS}" = "TORTURE" | "${DIALSTATUS}" = "DONTCALL" ] at line 416
OK -- \$[ "\${DIALSTATUS}" = "TORTURE" | "\${DIALSTATUS}" = "DONTCALL" ] at line 416
In the expr2_log file that is generated, you will see:
In the expr2\_log file that is generated, you will see:
line 416, evaluation of $[ "TORTURE" = "TORTURE" | "TORTURE" = "DONTCALL" ] result: 1
line 416, evaluation of \$[ "TORTURE" = "TORTURE" | "TORTURE" = "DONTCALL" ] result: 1
check_expr is a very simplistic algorithm, and it is far from being
check\_expr is a very simplistic algorithm, and it is far from being
guaranteed to work in all cases, but it is hoped that it will be
useful.
---------------------------------------------------------
Asterisk standard channel variables
---------------------------------------------------------
\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
@ -562,6 +557,7 @@ 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
@ -591,25 +587,22 @@ ${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)
${MEMBERINTERFACE} * The interface name of the queuemember that was chosen
${MEMBERNAME} * The member name of the queuemember that was chosen
${PRIORITY} * Current priority in the dialplan
${PRIREDIRECTREASON} Reason for redirect on PRI, if a call was directed (also set in SIP)
${SIPREDIRECTREASON} Reason for redirect on SIP (text string)
${PRIREDIRECTREASON} Reason for redirect on PRI, if a call was directed
${RDNIS} * Redirected Dial Number ID Service (Deprecated; use ${CALLERID(rdnis)})
${SIPRDNISDOMAIN} RDNIS domain from a redirect in SIP.
${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}
Application return values
\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()
@ -641,10 +634,10 @@ ${UPQMSTATUS} * unpausequeuemember()
${VMSTATUS} * voicmail()
${VMBOXEXISTSSTATUS} * vmboxexists()
${WAITSTATUS} * waitforsilence()
\end{verbatim}
Various application variables
-----------------------------
\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())
@ -664,18 +657,20 @@ ${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}
The MeetMe Conference Bridge uses the following variables:
----------------------------------------------------------
\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}
The VoiceMail() application uses the following variables:
---------------------------------------------------------
\subsection{The VoiceMail() application}
\begin{verbatim}
${VM_CATEGORY} Sets voicemail category
${VM_NAME} * Full name in voicemail
${VM_DUR} * Voicemail duration
@ -685,25 +680,22 @@ ${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}
The VMAuthenticate() application uses the following variables:
---------------------------------------------------------
\subsection{The VMAuthenticate() application}
\begin{verbatim}
${AUTH_MAILBOX} * Authenticated mailbox
${AUTH_CONTEXT} * Authenticated mailbox context
\end{verbatim}
DUNDiLookup() uses the following variables
---------------------------------------------------------
\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}
The DUNDi dialplan switch uses the following variables
---------------------------------------------------------
${DUNDIDIALARGS} Settings this variable allows you to provide options to be
passed to the Dial application for calls being placed using
the DUNDi switch.
The Zaptel channel sets the following variables:
---------------------------------------------------------
\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)
@ -715,19 +707,22 @@ ${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}
The SIP channel uses the following variables:
---------------------------------------------------------
\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}
The Agent channel uses the following variables:
---------------------------------------------------------
\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
@ -737,9 +732,11 @@ ${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}
The Dial() application uses the following variables:
---------------------------------------------------------
\subsection{The Dial() application}
\begin{verbatim}
${DIALEDPEERNAME} * Dialed peer name
${DIALEDPEERNUMBER} * Dialed peer number
${DIALEDTIME} * Time for the call (seconds)
@ -757,68 +754,38 @@ ${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}
The chanisavail() application sets the following variables:
-----------------------------------------------------------
\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}
When using macros in the dialplan, these variables are available
---------------------------------------------------------
\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}
The ChanSpy() application uses the following variables:
---------------------------------------------------------
\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}
If you compile with OSP support, these variables are used:
---------------------------------------------------------
\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
${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
____________________________________
CDR Variables
------------------------------------
If the channel has a cdr, that cdr record has it's own set of variables which
can be accessed just like channel variables. The following builtin variables
are available.
${CDR(clid)} Caller ID
${CDR(src)} Source
${CDR(dst)} Destination
${CDR(dcontext)} Destination context
${CDR(channel)} Channel name
${CDR(dstchannel)} Destination channel
${CDR(lastapp)} Last app executed
${CDR(lastdata)} Last app's arguments
${CDR(start)} Time the call started.
${CDR(answer)} Time the call was answered.
${CDR(end)} Time the call ended.
${CDR(duration)} Duration of the call.
${CDR(billsec)} Duration of the call once it was answered.
${CDR(disposition)} ANSWERED, NO ANSWER, BUSY
${CDR(amaflags)} DOCUMENTATION, BILL, IGNORE etc
${CDR(accountcode)} The channel's account code.
${CDR(uniqueid)} The channel's unique id.
${CDR(userfield)} The channels uses specified field.
In addition, you can set your own extra variables with a traditional
Set(CDR(var)=val) to anything you want.
Certain functional variables may be accessed with ${foo(<args>)}. A list
of these functional variables may be found by typing "show functions"
at the Asterisk CLI.
\end{verbatim}

19
doc/cliprompt.txt → doc/cliprompt.tex
View File

@ -1,12 +1,12 @@
* Changing the CLI Prompt
-------------------------
\subsubsection{Changing the CLI Prompt}
The CLI prompt is set with the ASTERISK_PROMPT UNIX environment variable that
The CLI prompt is set with the ASTERISK\_PROMPT UNIX environment variable that
you set from the Unix shell before starting Asterisk
You may include the following variables, that will be replaced by
the current value by Asterisk:
\begin{verbatim}
%d Date (year-month-date)
%s Asterisk system name (from asterisk.conf)
%h Full hostname
@ -15,15 +15,16 @@ the current value by Asterisk:
%% Percent sign
%# '#' if Asterisk is run in console mode, '>' if running as remote console
%Cn[;n] Change terminal foreground (and optional background) color to specified
A full list of colors may be found in include/asterisk/term.h
\end{verbatim}
On Linux systems, you may also use
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
-----
04-03-26
\end{verbatim}

72
doc/configuration.txt → doc/configuration.tex
View File

@ -1,8 +1,7 @@
Asterisk Configuration Parser (version 1.1 and later)
-----------------------------------------------------
\subsubsection{Introduction}
The Asterisk configuration parser in the 1.1 development version (1.2
stable) and beyond series has been improved in a number of ways. In
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.
@ -10,17 +9,19 @@ configure phones, voicemail accounts and queues.
These changes are general to the configuration parser, and works in
all configuration files.
General syntax
--------------
\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
@ -29,23 +30,26 @@ is a bit different. In these files the syntax is as follows:
label3 = value3
label2 = value4
object2 => name2
\end{verbatim}
In this syntax, we create objects with the settings defined above the object
creation. Note that settings are inherited from the top, so in the example
above object2 has inherited the setting for "label1" from the first object.
For template configurations, the syntax for defining a section is changed
to
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 "(".
Comments
--------
\subsubsection{Comments}
All lines that starts with semi-colon ";" is treated as comments
and is not parsed.
@ -53,62 +57,71 @@ 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}
Including other files
---------------------
\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.
file with the \#include statement. The content of the other file will be
included at the row that the \#include statement occurred.
\begin{verbatim}
#include myusers.conf
\end{verbatim}
You may also include the output of a program with the #exec directive,
You may also include the output of a program with the \#exec directive,
if you enable it in asterisk.conf
In asterisk.conf, add the execincludes = yes statement in the options
section:
\begin{verbatim}
[options]
execincludes=yes
\end{verbatim}
The exec directive is used like this:
\begin{verbatim}
#exec /usr/local/bin/myasteriskconfigurator.sh
\end{verbatim}
Adding to an existing section
-----------------------------
\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
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.
Defining a template-only section
--------------------------------
\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.
Using templates (or other configuration sections)
-------------------------------------------------
\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
@ -117,6 +130,7 @@ 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
@ -130,10 +144,12 @@ 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
@ -143,12 +159,13 @@ host=jkl
deny=192.168.1.1
permit=192.168.3.1
host=bnm
\end{verbatim}
Additional Examples:
--------------------
\subsubsection{Additional Examples}
(in top-level sip.conf)
\begin{verbatim}
[defaults](!)
type=friend
nat=yes
@ -158,9 +175,11 @@ 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
@ -172,9 +191,8 @@ 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.

9
doc/cygwin.txt
View File

@ -1,9 +0,0 @@
Cygwin support is completely experimental and unsupported at this time. The
current state of cygwin support is that it will compile, and start the cli,
but will not yet take calls properly.
To compile with cygwin, you will need at least a standard base cygwin install plus the following packages:
minires
minires-devel

4
doc/dundi.txt → doc/dundi.tex
View File

@ -1,5 +1,3 @@
Distributed Universal Number Directory (DUNDi) (tm)
===================================================
http://www.dundi.com
Mark Spencer, Digium, Inc.
@ -15,8 +13,6 @@ systems, DUNDi is explicitly designed to preclude any necessity for a
single centralized system which could be a source of fees, regulation,
etc.
You can find the PEERING agreement in the doc directory.
Much less dramatically, DUNDi can also be used within a private
enterprise to share a dialplan efficiently between multiple nodes,
without incurring a risk of a single point of failure. In this way,

137
doc/enum.txt → doc/enum.tex
View File

@ -1,7 +1,4 @@
Enum support in the ENUMLOOKUP dialplan function
------------------------------------------------
2005-09-06
jtodd@loligo.com
\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
@ -26,23 +23,33 @@ 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:
1) post-parsed NAPTR of one method (URI) type
2) count of elements of one method (URI) type
3) count of all method types
4) full URI of method at a particular point in the list of all possible methods
\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}
Arguments:
\subsection{Arguments}
number = telephone number or search string. Only numeric values
within this string are parsed; all other digits are ignored for
search, but are re-written during NAPTR regexp expansion.
\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}
service_type = tel, sip, h323, iax2, mailto, ...[any other string],
\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
@ -52,24 +59,36 @@ service_type = tel, sip, h323, iax2, mailto, ...[any other string],
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}
options = optional specifiers.
c = count. Returns the number of records of this type are returned
\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
service\_type, then a count of all methods will be returned for the
DNS record.
\end{itemize}
\end{itemize}
record# = which record to present if multiple answers are returned
\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
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"
zone_suffix = allows customization of the ENUM zone. Default is e164.arpa.
\end{itemize}
\item zone\_suffix
\begin{itemize}
\item allows customization of the ENUM zone. Default is e164.arpa.
\end{itemize}
\end{itemize}
EXAMPLE USES:
\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
@ -83,62 +102,85 @@ 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.
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!" .
\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}
Usage notes and subtle features:
a) The use of "+" in lookups is confusing, and warrants further
\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
@ -152,12 +194,12 @@ Usage notes and subtle features:
may or may not require a leading "+" - check before using those
trees, as it is possible the parsed NAPTRs will not provide correct
results unless you have the correct dialed string. If you get
console messages like "WARNING[24907]: enum.c:222 parse_naptr: NAPTR
console messages like "WARNING[24907]: enum.c:222 parse\_naptr: NAPTR
Regex match failed." then it is very possible that the returned
NAPTR expects a leading "+" in the search string (or the returned
NAPTR is mis-formed.)
b) If a query is performed of type "c" ("count") and let's say you
\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
@ -171,7 +213,7 @@ Usage notes and subtle features:
given by the remote zone master. Currently, the ENUMLOOKUP function
does not use the dnsmgr method of caching local DNS replies.)
c) If you want strict NAPTR value ordering, then it will be
\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
@ -180,33 +222,33 @@ Usage notes and subtle features:
strict RFC compliance and to comply with the desires of the remote
party who is presenting NAPTRs in a particular order for a reason.
d) Default behavior for the function (even in event of an error) is
\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
their dialplan. This is a change from the old app\_enumlookup method
and it's arbitrary priority jumping based on result type or failure.
e) Anything other than digits will be ignored in lookup strings.
\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.
f) If there exist multiple records with the same weight and order as
\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.
g) Currently, the function ignores the settings in enum.conf as the
\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.
h) The function will digest and return NAPTRs which use older
\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"
i) There is no provision for multi-part methods at this time. If
\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
@ -215,16 +257,16 @@ Usage notes and subtle features:
equal priority/weight (as is often the case) then this will cause no
serious difficulty, but it bears mentioning.
j) ISN (ITAD Subscriber Number) usage: If the search number is of
\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}
==EXAMPLES==
\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.
@ -232,6 +274,7 @@ 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.
@ -306,3 +349,5 @@ exten => _X.,22,NoOp("No valid entries in e164.org for ${EXTEN} - sending out vi
exten => _X.,23,Dial(Zap/g1/${EXTEN})
;
; end example 3
\end{verbatim}

91
doc/extconfig.txt
View File

@ -1,91 +0,0 @@
Asterisk external configuration
===============================
The Asterisk external configuration engine is the result of work by
Anthony Minessale II, Mark Spencer and Constantine Filin.
It is designed to provide a flexible, seamless integration between
Asterisk's internal configuration structure and external SQL other other
databases (maybe even LDAP one day).
The external configuration engine is the basis for the ARA, the
Asterisk Realtime Architecture (see doc/realtime.txt for more
information).
* Configuration
External configuration is configured in /etc/asterisk/extconfig.conf
allowing you to map any configuration file (static mappings) to
be pulled from the database, or to map special runtime entries which
permit the dynamic creation of objects, entities, peers, etc. without
the necessity of a reload.
Generally speaking, the columns in your tables should line up with the
fields you would specify in the given entity declaration. If an entry
would appear more than once, in the column it should be separated by a
semicolon. For example, an entity that looks like:
[foo]
host=dynamic
secret=bar
context=default
context=local
could be stored in a table like this:
+------+--------+-------+--------------+----------+-----+-----------+
| name | host | secret| context | ipaddr | port| regseconds|
+------+--------+-------+--------------+----------+-----+-----------+
| foo | dynamic| bar | default;local| 127.0.0.1| 4569| 1096954152|
+------+--------+-------+--------------+----------+-----+-----------+
Note that for use with IAX or SIP, the table will also need the "name",
"ipaddr", "port", "regseconds" columns. If you wanted to be able to
configure the callerid, you could just add a callerid column to the
table, for example.
A SIP table would look more like this:
+------+--------+-------+----------+-----+------------+----------+
| name | host | secret| ipaddr | port| regseconds | username |
+------+--------+-------+----------+-----+------------+----------+
| foo | dynamic| bar | 127.0.0.1| 4569| 1096954152 | 1234 |
+------+--------+-------+----------+-----+------------+----------+
in order to store appropriate parameters required for SIP.
In addition to this, if you add a field named "regserver" to the
SIP peers table and have the system name set in asterisk.conf,
Asterisk will store the system name that the user registered on in
the database. This can be used to direct calls to go through the server
that holds the registration (for NAT traversal purposes).
A Voicemail table would look more like this:
+----------+---------+----------+----------+-----------+---------------+
| uniqueid | mailbox | context | password |email | fullname |
+----------+---------+----------+----------+-----------+---------------+
| 1 | 1234 | default | 4242 | a@b.com | Joe Schmoe |
+----------+---------+----------+----------+-----------+---------------+
The uniqueid should be unique to each voicemail user and can be
autoincrement. It need not have any relation to the mailbox or context.
An extension table would look more like this:
+----------+---------+----------+-------+-----------+
| context | exten | priority | app | appdata |
+----------+---------+----------+-------+-----------+
| default | 1234 | 1 | Dial | Zap/1 |
+----------+---------+----------+-------+-----------+
In the dialplan you just use the Realtime switch:
[foo]
switch => Realtime
or:
[bar]
switch => Realtime/bar@extensions

48
doc/extensions.txt → doc/extensions.tex
View File

@ -1,5 +1,4 @@
The Asterisk dialplan
=====================
\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
@ -11,7 +10,7 @@ If you change the dialplan, you can use the Asterisk CLI command
service in your PBX.
Extensions are routed according to priority and may be based on any set
of characters (a-z), digits, #, and *. Please note that when matching a
of characters (a-z), digits, \#, and *. Please note that when matching a
pattern, "N", "X", and "Z" are interpreted as classes of digits.
For each extension, several actions may be listed and must be given a unique
@ -29,28 +28,45 @@ 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.
* Example dial plan
\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.
* Special extensions
\subsubsection{Special extensions}
There are some extensions with important meanings:
s: What to do when an extension context is entered (unless
overridden by the low level channel interface)
This is used in macros, and some special cases.
"s" is not a generic catch-all wildcard extension.
i: What to do if an invalid extension is entered
h: The hangup extension, executed at hangup
t: What to do if nothing is entered in the requisite amount
of time.
T: This is the extension that is executed when the 'absolute'
timeout is reached. See "show function TIMEOUT" for more
information on setting timeouts.
\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

8
doc/freetds.txt → doc/freetds.tex
View File

@ -1,12 +1,10 @@
PLEASE NOTE
The cdr\_tds module is NOT compatible with version 0.63 of FreeTDS.
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;
The cdr\_tds module is known to work with FreeTDS version 0.62.1;
it should also work with 0.62.2, 0.62.3 and 0.62.4, which are bug
fix releases.
The cdr_tds module uses the raw "libtds" API of FreeTDS. It appears
The cdr\_tds module uses the raw "libtds" API of FreeTDS. It appears
that from 0.63 onwards, this is not considered a published API
of FreeTDS and is subject to change without notice.

22
doc/h323.txt
View File

@ -1,22 +0,0 @@
The Asterisk PBX supports H.323 via two totally separate
channel drivers.
You can find more information Asterisk's native H.323
support in /path/to/asterisk/channels/h323/README or
you can download a third party driver at
http://www.inaccessnetworks.com/projects/asterisk-oh323
Asterisk's native H.323 is supported and maintained by
Jeremy McNamara (JerJer in irc). Support for the third
party H.323 driver is supplied by inAccessNetworks.
If you have trouble with either driver you should direct
your debug and comments to the appropriate party, making
sure to be specific in exactly which H.323 driver you are
running.
Please, read all supplied documentation before contacting
either party for support. Many issues can be quickly
resolved by simply following the instructions that are
provided.

100
doc/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}

74
doc/hardware.txt
View File

@ -1,74 +0,0 @@
A PBX is only really useful if you can get calls into it. Of course, you
can use Asterisk with VoIP calls (SIP, H.323, IAX), but you can also talk
to the real PSTN through various cards.
Supported Hardware is divided into two general groups: Zaptel devices and
non-zaptel devices. The Zaptel compatible hardware supports pseudo-TDM
conferencing and all call features through chan_zap, whereas non-zaptel
compatible hardware may have different features.
Zaptel compatible hardware
==========================
-- Digium (Primary author of Asterisk)
http://www.digium.com, http://store.digium.com
* Wildcard T400P (obsolete) - Quad T1 interface connects to four T1/PRI
interfaces. Supports RBS and PRI voice and PPP, FR, and HDLC data.
* Wildcard E400P (obsolete)- Quad E1 interface connects to four E1/PRI
(or PRA) interfaces. Supports PRA/PRI, EuroISDN voice and data.
* Wildcard T100P - Single T1 interface connects to a single T1/PRI
interface. Supports RBS and PRI voice and PPP, FR, and HDLC data.
* Wildcard E100P - Single E1 interface connects to a single E1/PRI (or PRA)
interface. Supports PRA/PRI, EuroISDN voice and PPP, FR, HDLC data.
* Wildcard TDM400P - Quad Modular FXS interface connects to standard
analog telephones.
* Wildcard TE410P - Quad T1/E1 switchable interface. Supports PRI and
RBS signalling, as well as PPP, FR, and HDLC data modes.
Non-zaptel compatible hardware
==============================
-- QuickNet, Inc.
http://www.quicknet.net
* Internet PhoneJack - Single FXS interface. Supports Linux telephony
interface. DSP compression built-in.
* Internet LineJack - Single FXS or FXO interface. Supports Linux
telephony interface.
mISDN compatible hardware
=========================
mISDN homepage: http://www.isdn4linux.de/mISDN/
Any adapter with an mISDN driver should be compatible with
chan_misdn. See misdn.txt for information.
-- beroNet
http://www.beronet.com
* BN4S0 - 4 Port BRI card (TE/NT)
* BN8S0 - 8 Port BRI card (TE/NT)
* Billion Card - Single Port BRI card (TE (/NT with crossed cable) )
Miscellaneous other interfaces
==============================
-- ALSA
http://www.alsa-project.org
* Any ALSA compatible full-duplex sound card
-- OSS
http://www.opensound.com
* Any OSS compatible full-duplex sound card

67
doc/iax.txt
View File

@ -1,67 +0,0 @@
Inter-Asterisk eXchange Protocol
================================
Usage:
======
The format for the dialing string on Asterisk is:
IAX/[user@]peer[:exten[@context]]
(Note, []'s denote optional fields). The peer is either an IP address
or a peer as specified in the /etc/asterisk/iax.conf file. Exten is
an optional requested extension (otherwise "s" will be used), and
"context" is an optional context to request. The user is an optional
username specified in the peer's iax.conf. If the user is not specified,
the peer will select one.
The peer uses a score to determine the best user entry to match against if
one is not specified:
1. User entry last specified in iax.conf (this is the baseline).
2. User entry with secret specified and ACL specified.
3. User entry with no secret specified and no ACL specified.
4. User entry with no secret specified and ACL specified.
5. User entry matched via username.
The higher the score the better it is with 5 being an exact match and the maximum
score possible.
Protocol and rationale:
=======================
IAX is a simple, low overhead and low bandwidth VoIP protocol designed to
allow multiple Asterisk PBX's to communicate with one another without
the overhead of more complex protocols like H.323. Payload is sent with
a header overhead of only 4 octets. Control functions (and one payload packet
per minute or so) is sent with a more complex header of 12 octets.
IAX is slightly stateful.
IAX contains two kinds of packets: The full header packet type, which
contains much information about the frame, in addition to its contents,
and the mini header type, which is used only for non-reliable voice
packet delivery.
All packets are immediately transmitted. Packets are received, but not
delivered to the actual channels until a given time quantum has passed, in
order to try to eliminate jitter.
All full header packets must be ackd (except, obviously for the ACK packets
themselves and not so obviously for hangup packets). The "timestamp" field of
ack packets is not the normal offset, but rather a quote of the timestamp as
included with the original packet that you're acking, and likewise the
seqno field is the seqno of the packet you're acking, not your own seqno,
and you do not increment your own sequence number. ACKing is based on the
sequence number.
See iax.h for a description of the frame formats.
IAX internal frames use the AST_FRAME_IAX type. The subclass of these
frames is the IAX control number, as seen in iax.h. The first frame sent
must be an AST_FRAME_IAX with the control AST_IAX_CONTROL_NEW.
The AST_IAX_CONTROL_NEW establishes a new connection.
The first frame sent MUST be an AST_CONTROL_NEW to start a connection.
IAX connnections may require authentication using either simple plaintext
passwords or an md5 challenge/response pair.

9
doc/ices.txt → doc/ices.tex
View File

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

114
doc/imapstorage.txt → doc/imapstorage.tex
View File

@ -1,46 +1,27 @@
======================
IMAP Voicemail Storage
======================
03-01-2006 - James Rothenberger <jar@onebiztone.com>
By enabling IMAP Storage, Asterisk will use native IMAP as the storage
mechanism for voicemail messages instead of using the standard file structure.
Tighter integration of Asterisk voicemail and IMAP email services allows
additional voicemail functionality, including:
- Listening to a voicemail on the phone will set its state to "read" in
\begin{itemize}
\item Listening to a voicemail on the phone will set its state to "read" in
a user's mailbox automatically.
- Deleting a voicemail on the phone will delete it from the user's
\item Deleting a voicemail on the phone will delete it from the user's
mailbox automatically.
- Accessing a voicemail recording email message will turn off the message
\item Accessing a voicemail recording email message will turn off the message
waiting indicator (MWI) on the user's phone.
- Deleting a voicemail recording email will also turn off the message
\item Deleting a voicemail recording email will also turn off the message
waiting indicator, and delete the message from the voicemail system.
\end{itemize}
=====================
Contents of this file
=====================
\subsection{Installation Notes}
- Installation Notes
- Separate vs. Shared Email Accounts
- IMAP Server Implementations
- Quota Support
- Application Notes
- Known Issues
\subsubsection{University of Washington IMAP C-Client}
==================
Installation Notes
==================
--------------------------------------
University of Washington IMAP C-Client
--------------------------------------
You will need a source distribution of University of Washington's IMAP
c-client (http://www.washington.edu/imap/). Asterisk supports both the
2004 and 2006 versions of c-client, however mail_expunge_full is enabled
2004 and 2006 versions of c-client, however mail\_expunge\_full is enabled
in the 2006 version.
Note that Asterisk only uses the 'client' portion of the UW IMAP toolkit,
@ -56,23 +37,23 @@ is outside the scope of this document.
Building the c-client library is fairly straightforward; for example, on a
Debian system there are two possibilities:
\begin{verbatim}
1) if you will not be using SSL to connect to the IMAP server:
$ make slx SSLTYPE=none
2) if you will be using SSL to connect to the IMAP server:
$ make slx EXTRACFLAGS="-I/usr/include/openssl"
\end{verbatim}
Once this completes you can proceed with the Asterisk build; there is no
need to run 'make install'.
------------------
Compiling Asterisk
------------------
\subsubsection{Compiling Asterisk}
Configure with ./configure --with-imap=/usr/src/imap
or where ever you built thfe UWashington IMAP Toolkit. When you run
'make menuselect', choose 'Voicemail Build Options' and the
IMAP_STORAGE option should be available for selection.
IMAP\_STORAGE option should be available for selection.
Note that the --with-imap option will NOT search your system for an
installed copy of the IMAP Toolkit c-client library; the Asterisk
@ -83,17 +64,18 @@ distribution.
After selecting it, use the 'x' key to exit menuselect and save
your changes, and the build/install Asterisk normally.
---------------------
Modify voicemail.conf
---------------------
\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.
@ -101,24 +83,25 @@ 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.
--------------
IMAP Folders
--------------
\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.
==================================
Separate vs. Shared Email Accounts
==================================
\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.
@ -132,46 +115,42 @@ 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.
===========================
IMAP Server Implementations
===========================
\subsection{IMAP Server Implementations}
There are various IMAP server implementations, each supports a potentially
different set of features.
-----------------------
UW IMAP-2005 or earlier
-----------------------
\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
that without UID\_EXPUNGE, Asterisk voicemail will expunge ALL messages marked
for deletion when a user exits the voicemail system (hangs up the phone).
-------------------------------
UW IMAP-2006 Development Branch
-------------------------------
This version supports UIDPLUS, which allows UID_EXPUNGE capabilities. This
\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
will check if the UID\_EXPUNGE feature is supported by the server, and use it
if possible.
----------
Cyrus IMAP
----------
\subsubsection{Cyrus IMAP}
Cyrus IMAP server v2.3.3 has been tested using a hierarchy delimiter of '/'.
=============
Quota Support
=============
\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.
=================
Application Notes
=================
\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
@ -179,6 +158,7 @@ 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
@ -191,12 +171,4 @@ X-Asterisk-VM-Duration
X-Asterisk-VM-Category
X-Asterisk-VM-Orig-date
X-Asterisk-VM-Orig-time
=================
Known Issues
=================
- Forward With Comment advanced option is not currently supported.
This feature will be added in the near future.
- Message Waiting Indicator blinks off and back on when a message arrives.
This should be fixed soon.
\end{verbatim}

43
doc/ip-tos.txt → doc/ip-tos.tex
View File

@ -1,23 +1,25 @@
IP Type of Service settings for VoIP channels
---------------------------------------------
\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.
* SIP
-----
\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
"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.
* IAX2
------
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
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.
@ -34,25 +36,28 @@ ef (expedited forwarding),
The tos* parameters also take numeric values.
The lowdelay, throughput, reliability, mincost, and none values are no
longer supported in this version of Asterisk.
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.
\begin{verbatim}
===========================================
Configuration Parameter Recommended
File Setting
-------------------------------------------
sip.conf tos_sip cs3
sip.conf tos_audio ef
sip.conf tos_video af41
sip.conf tos\_sip cs3
sip.conf tos\_audio ef
sip.conf tos\_video af41
-------------------------------------------
iax.conf tos ef
-------------------------------------------
iaxprov.conf tos ef
===========================================
\end{verbatim}
\subsubsection{Reference}
* REFERENCE
-----------
RFC 2474 - "Definition of the Differentiated Services Field
(DS field) in the IPv4 and IPv6 Headers", Nichols, K., et al,
December 1998.
@ -65,12 +70,12 @@ To get the most out of setting the TOS on packets generated by
Asterisk, you will need to ensure that your network handles packets
with a TOS properly. For Cisco devices, see the previously mentioned
"Enterprise QoS Solution Reference Network Design Guide". For Linux
systems see the "Linux Advanced Routing & Traffic Control HOWTO" at
systems see the "Linux Advanced Routing \& Traffic Control HOWTO" at
<http://www.lartc.org/>.
For more information on Quality of
Service for VoIP networks see the "Enterprise QoS Solution Reference
Network Design Guide" version 3.3 from Cisco at:
<http://www.cisco.com/application/pdf/en/us/guest/netsol/ns432/c649/ccmigration_09186a008049b062.pdf>
<http://www.cisco.com/application/pdf/en/us/guest/netsol/ns432/c649/ccmigration\_09186a008049b062.pdf>

97
doc/jitterbuffer.txt → doc/jitterbuffer.tex
View File

@ -1,28 +1,13 @@
The new Jitterbuffer in Asterisk
--------------------------------
Steve Kann
\subsubsection{The new jitterbuffer}
The new jitterbuffer, PLC, and the IAX2-integration of the new jitterbuffer
have been integrated into Asterisk. The jitterbuffer is generic and work is
going on to implement it in SIP/RTP as well.
Also, we've added a feature called "trunktimestamps", which adds individual
timestamps to trunked frames within a trunk frame.
Here's how to use this stuff:
1) The new jitterbuffer:
------------------------
You must add "jitterbuffer=yes" to either the [general] part of
iax.conf, or to a peer or a user. (just like the old jitterbuffer).
Also, you can set "maxjitterbuffer=n", which puts a hard-limit on the size of the
jitterbuffer of "n milliseconds". It is not necessary to have the new jitterbuffer
on both sides of a call; it works on the receive side only.
2) PLC:
-------
\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.
@ -31,9 +16,9 @@ This facility is enabled by default in iLBC and speex, as it has no additional c
This facility can be enabled in adpcm, alaw, g726, gsm, lpc10, and ulaw by setting
genericplc => true in the [plc] section of codecs.conf.
3) Trunktimestamps:
-------------------
To use this, both sides must be using Asterisk v1.2.
\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.
@ -42,8 +27,8 @@ The other side must also support this functionality, or else, well, bad things w
If you don't use trunktimestamps, there's lots of ways the jitterbuffer can get confused because
timestamps aren't necessarily sent through the trunk correctly.
4) Communication with Asterisk v1.0.x systems
---------------------------------------------
\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.
@ -51,15 +36,15 @@ If you are connecting to an Asterisk server with earlier versions of the softwar
do not enable both jitterbuffer and trunking for the involved peers/users
in order to be able to communicate. Earlier systems will not support trunktimestamps.
You may also compile chan_iax2.c without the new jitterbuffer, enabling the old
You may also compile chan\_iax2.c without the new jitterbuffer, enabling the old
backwards compatible architecture. Look in the source code for instructions.
5) Testing and monitoring:
--------------------------
\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
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.
@ -70,24 +55,26 @@ end is telling us they are seeing). The remote stats may not be complete if the
end isn't using the new jitterbuffer.
The stats shown are:
* Jit: The jitter we have measured (milliseconds)
* Del: The maximum delay imposed by the jitterbuffer (milliseconds)
* Lost: The number of packets we've detected as lost.
* %: The percentage of packets we've detected as lost recently.
* Drop: The number of packets we've purposely dropped (to lower latency).
* OOO: The number of packets we've received out-of-order
* Kpkts: The number of packets we've received / 1000.
\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}
Reporting problems
==================
\subsubsection{Reporting problems}
There's a couple of things that can make calls sound bad using the jitterbuffer:
1) The JB and PLC can make your calls sound better, but they can't fix everything.
\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.
2) Bad timestamps: If whatever is generating timestamps to be sent to you generates
\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
@ -96,42 +83,16 @@ The right solution to this is to find out what's causing the sender to send us s
and fix that. But we should also figure out how to make the receiver more robust in
cases like this.
chan_iax2 will actually help fix this a bit if it's more than 3 seconds or so, but at
chan\_iax2 will actually help fix this a bit if it's more than 3 seconds or so, but at
some point we should try to think of a better way to detect this kind of thing and
resynchronize.
Different clock rates are handled very gracefully though; it will actually deal with a
sender sending 20% faster or slower than you expect just fine.
sender sending 20\% faster or slower than you expect just fine.
3) Really strange network delays: If your network "pauses" for like 5 seconds, and then
\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.
Reporting possible bugs
-----------------------
If you do find bad behaviors, here's the information that will help to diagnose this:
1) Describe
a) the source of the timestamps and frames: i.e. if they're coming from another chan_iax2 box,
a bridged RTP-based channel, an IAX2 softphone, etc..
b) The network between, in brief (i.e. the internet, a local lan, etc).
c) What is the problem you're seeing.
2) Take a look and see what iax2 show netstats is saying about the call, and if it makes sense.
3) a tcpdump of the frames, (or, tethereal output from), so we can see the timestamps and delivery
times of the frames you're receiving. You can make such a tcpdump with:
tcpdump -s 2048 -w /tmp/example.dump udp and port 4569 [and host <other-end>]
Report bugs in the Asterisk bugtracker, http://bugs.digium.com.
Please read the bug guidelines before you post a bug.
Have fun!
-SteveK
\end{enumerate}

30
doc/localchannel.txt → doc/localchannel.tex
View File

@ -1,29 +1,29 @@
The Local channel
-----------------
\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.
* Syntax:
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.
* Purpose:
\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.
Imagine you have a TE410P in your box. You want to do something for which you must use a Dial statement (for instance when dropping files in /var/spool/outgoing) but you do want to be able to use your dialplans least-cost-routes or other intelligent stuff. What you could do before we had chan\_local was create a cross-link between two ports of the TE410P and then Dial out one port and in the other. This way you could control where the call was going.
Of course, this was a nasty hack, and to make it more sensible, chan_local was built.
Of course, this was a nasty hack, and to make it more sensible, chan\_local was built.
The "Local" channel driver allows you to convert an arbitrary extension into a channel. It is used in a variety of places, including agents, etc.
This also allows us to hop to contexts like a GoSub routine; See examples below.
Examples:
---------
\subsection{Examples}
\begin{verbatim}
[inbound] ; here falls all incoming calls
exten => s,1,Answer
exten => s,2,Dial(local/200@internal,30,r)
@ -38,12 +38,12 @@ exten => 201,1,Dial(zap/1)
exten => 201,102,VoiceMail(${EXTEN}@default)
exten => _0.,1,Dial(Zap/g1/${EXTEN:1}) ; outgoing calls with 0+number
\end{verbatim}
\subsection{Caveats}
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.
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
----------
2004-01-17
\end{verbatim}

109
doc/manager.txt → doc/manager.tex
View File

@ -1,5 +1,4 @@
The Asterisk Manager TCP/IP API - AMI
=====================================
\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,
@ -21,9 +20,7 @@ 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".
The Asterisk manager interface in version 1.0.x of Asterisk is
not very well standardized. Work is under way to change this
to Asterisk 1.2. If you develop AMI applications, treat the headers
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.
@ -31,8 +28,8 @@ If you develop applications, please try to reuse existing manager
headers and their interpretation. If you are unsure, discuss on
the asterisk-dev mailing list.
Device status reports
---------------------
\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
@ -41,89 +38,30 @@ file for more information. (in sip.conf, check the section on
subscriptions and call limits)
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.
\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:
* Action: An action requested by the CLIENT to the Asterisk SERVER. Only one "Action" may be outstanding at any time.
* Response: A response to an action from the Asterisk SERVER to the CLIENT.
* Event: An event reported by the Asterisk SERVER to the CLIENT
\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}
Manager commands
----------------
Output from the CLI command 'show manager' command:
To see all of the available manager commands, use the "manager show commands"
CLI command.
* Ping: Ping
* Logoff: Logoff Manager
* Hangup: Hangup Channel
* Status: Status
* Redirect: Redirect
* Originate: Originate Call
* MailboxStatus: Check Mailbox
* Command: Execute Command
* ExtensionState: Check Extension Status
* AbsoluteTimeout: Set Absolute Timeout
* MailboxCount: Check Mailbox Message Count
* Monitor: Monitor a channel
* StopMonitor: Stop monitoring a channel
* ChangeMonitor: Change monitoring filename of a channel
* IAXpeers: List IAX Peers (Defaults to IAX2)
* SIPpeers: List SIP peers
* SIPshowpeer: Show data about one SIP peer
* Queues: Queues
* QueueStatus: Queue Status
You can get more information about a manager command
with the "manager show command <command>" CLI command in Asterisk.
This list depends on the version of Asterisk you are using, as
well as which modules that are loaded.
Command Summary
--------------
Command: Command
Parameters: Command
Command: ExtensionState
Parameters: Exten, Context, ActionID
Command: Hangup
Parameters: Channel
Command: Logoff
Parameters: None
Command: MailboxCount
Parameters: Mailbox, ActionID
Command: MailboxStatus
Parameters: Mailbox, ActionID
Command: Originate
Parameters: Channel, Exten, Context, Priority, Timeout,
CallerID, Variable, Account, Application, Data, Async
Command: Ping
Parameters: None
Command: PlayDTMF
Parameters: Channel, Digit
Command: Redirect
Parameters: Channel, ExtraChannel, Exten, Context, Priority
Command: Timeout
Parameters: Channel, Timeout
You can always get more information about a manager command
with the "show manager command <command>" CLI command in Asterisk.
Examples
--------
\section{Examples}
\begin{verbatim}
Login - Log a user into the manager interface.
Action: Login
@ -159,15 +97,15 @@ Redirect with ExtraChannel:
Priority: 1
Where 680 is an extension that sends you to a MeetMe room.
\end{verbatim}
There are a number of GUI tools that use the manager interface, please search
the mailing list archives and the documentation page on the
http://www.asterisk.org web site for more information.
Some standard AMI headers:
--------------------------
\section{Some standard AMI headers}
\begin{verbatim}
Account: -- Account Code (Status)
AccountCode: -- Account Code (cdr_manager)
ACL: <Y | N> -- Does ACL exist for object ?
@ -305,6 +243,7 @@ Some standard AMI headers:
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.

69
doc/math.txt
View File

@ -1,69 +0,0 @@
Mathematical dialplan function
Yeah, I thought it was a little insane too..
adds:
Sum, Multiply, Divide, Subtract, Modulus, GT, LT, GTE, LTE, EQ functions to Asterisk
All functions follow the same basic pattern for parameters:
parameter 1 = the math expression
parameter 2 = the type of result
Perform calculation on number 1 to number 2. Valid ops are:
+,-,/,*,%,<,>,>=,<=,==
and behave as their C equivalents.
<type_of_result> - wanted type of result:
f, float - float(default)
i, int - integer,
h, hex - hex,
c, char - char
Each math expression is performed as
Action param1 on param2
eg:
Action = Divide
Param1 = 10
Param2 = 2
Results in
Divide 10 by 2
Example dialplan:
exten => 11099,1,Set(RV=${MATH(1+20)})
exten => 11099,n,NOOP(${RV})
exten => 11099,n,Set(RV=${MATH(10*2)})
exten => 11099,n,NOOP(${RV})
exten => 11099,n,Set(RV=${MATH(10*2)})
exten => 11099,n,NOOP(${RV})
exten => 11099,n,Set(RV=${MATH(10-2)})
exten => 11099,n,NOOP(${RV})
exten => 11099,n,Set(RV=${MATH(2%10)})
exten => 11099,n,NOOP(${RV})
exten => 11099,n,Set(RV=${MATH(10/0)})
exten => 11099,n,NOOP(${RV})
exten => 11099,n,Set(RV=${MATH(10-200)})
exten => 11099,n,NOOP(${RV})
exten => 11099,n,Set(RV=${MATH(1-20)})
exten => 11099,n,NOOP(${RV})
exten => 11099,n,Set(RV=${MATH(1<20)})
exten => 11099,n,NOOP(${RV})
exten => 11099,n,Set(RV=${MATH(1>=20)})
exten => 11099,n,NOOP(${RV})
exten => 11099,n,Set(RV=${MATH(101>20)})
exten => 11099,n,NOOP(${RV})
exten => 11099,n,Set(RV=${MATH(1==20)})
exten => 11099,n,NOOP(${RV})
exten => 11099,n,Set(RV=${MATH(20<=20)})
exten => 11099,n,NOOP(${RV})
exten => 11099,n,Set(RV=${MATH(123%16,int)})
exten => 11099,n,NOOP(${RV})

185
doc/misdn.txt → doc/misdn.tex
View File

@ -1,142 +1,126 @@
mISDN Channel Driver for Asterisk PBX
======================================
\subsection{Introduction}
This package contains the mISDN Channel Driver for the Asterisk PBX. It
supports every mISDN Hardware and provides an interface for asterisk.
Features:
---------
\subsection{Features}
* NT and TE mode
* PP and PMP mode
* BRI and PRI (with BNE1 and BN2E1 Cards)
* Hardware Bridging
* DTMF Detection in HW+mISDNdsp
* Display Messages on Phones (on those that support display msg)
* app_SendText
* HOLD/RETRIEVE/TRANSFER on ISDN Phones : )
* Screen/ Not Screen User Number
* EchoCancellation
* Volume Control
* Crypting with mISDNdsp (Blowfish)
* Data (HDLC) callthrough
* Data Calling (with app_ptyfork +pppd)
* Echo cancellation
* CallDeflection
* Some other
\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}
Supported Hardware:
-------------------
chan_misdn supports any mISDN compatible Hardware.
Overview
--------
- Fast Installation Guide
- Pre-Requisites
- Configuration
- Dial and Options String
- misdn cli commands
- mISDN Variables
- Debugging and sending Bugreports
- Examples
- Known Problems
- Changes
Fast Installation Guide
-----------------------
\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}
the compile and install both with:
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:
Now you can compile chan\_misdn, just by making asterisk:
\begin{verbatim}
cd asterisk ;
make && make install
./configure && make && make install
\end{verbatim}
That's all!
Follow the instructions in the mISDN Package for howto loading the Kernel
Follow the instructions in the mISDN Package for how to load the Kernel
Modules.
Pre-Requisites
--------------
\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
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
Configuration
-------------
\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).
- misdn.conf: [general]
The misdn.conf file contains a "general" Section, and user sections which
\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 Section you can set options that are not directly port
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.
- misdn.conf: [default] section
\subsubsection{misdn.conf: [default] subsection}
The default section is another special section which can contain all the
options available in the user/port sections. the user/port section inherit
their parameters from the default section.
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.
- misdn.conf: user/port sections
\subsubsection{misdn.conf: user/port subsections}
The user sections have names which are unequal to "general". Those sections
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
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 sections, which tells chan_misdn where to
context variable resides in the user subsections, which tells chan\_misdn where to
send incoming calls to in the Asterisk dial plan (extension.conf).
Dial and Options String
-----------------------
\subsubsection{Dial and Options String}
The dial string of chan_misdn got more complex, because we added more features,
The dial string of chan\_misdn got more complex, because we added more features,
so the generic dial string looks like:
\begin{verbatim}
mISDN/<port>|g:<group>/<extension>[/<OPTIONSSTRING>]
The Optionsstring looks Like:
@ -154,44 +138,49 @@ The available Optchars are:
s - send Non Inband DTMF as inband
vr - rxgain control
vt - txgain control
\end{verbatim}
chan_misdn registers a new dial plan application "misdn_set_opt" when
chan\_misdn registers a new dial plan application "misdn\_set\_opt" when
loaded. This application takes the Optionsstring as argument. The Syntax is:
\begin{verbatim}
misdn_set_opt(<OPTIONSSTRING>)
\end{verbatim}
When you set options in the dialstring, the options are set in the external
channel. When you set options with misdn_set_opt, they are set in the current
channel. When you set options with misdn\_set\_opt, they are set in the current
incoming channel. So if you like to use static encryption, the scenario looks
as follows:
\begin{verbatim}
Phone1 --> * Box 1 --> PSTN_TE
PSTN_TE --> * Box 2 --> Phone2
\end{verbatim}
The Encryption must be done on the PSTN sides, so the dialplan on the boxes
are:
\begin{verbatim}
* Box 1:
exten => _${CRYPT_PREFIX}X.,1,Dial(mISDN/g:outbound/:c1)
* Box 2:
exten => ${CRYPT_MSN},1,misdn_set_opt(:c1)
exten => ${CRYPT_MSN},2,dial(${PHONE2})
\end{verbatim}
misdn cli commands
------------------
\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)
@ -211,6 +200,7 @@ Now you should see the misdn cli commands:
-> port (restarts given port (L2 Restart) )
- reload (reloads misdn.conf)
\end{verbatim}
You can only use "misdn send display" when an Asterisk channel is created and
isdn is in the correct state. "correct state" means that you have established a
@ -223,19 +213,17 @@ 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.
mISDN Variables
---------------
\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}
Debugging and sending bug reports
---------------------------------
\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
@ -244,17 +232,16 @@ an '*', the rest is clear I think.
Please take a trace of the problem and open a report in the Asterisk issue
tracker at http://bugs.digium.com in the "channel drivers" project,
"chan_misdn" category. Read the bug guidelines to make sure you
"chan\_misdn" category. Read the bug guidelines to make sure you
provide all the information needed.
Examples
--------
\subsection{Examples}
Here are some examples of how to use chan_misdn in the dialplan
Here are some examples of how to use chan\_misdn in the dialplan
(extensions.conf):
\begin{verbatim}
[globals]
OUT_PORT=1 ; The physical Port of the Card
OUT_GROUP=ExternE1 ; The Group of Ports defined in misdn.conf
@ -264,28 +251,16 @@ 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.
Known Problems
--------------
* When I use mISDN->IAX I cannot make Trunk calls
-> You need to use ztdummy as dummy zaptel interface for the iax timing in
trunking mode, simply grab libpri, zaptel and compile them (i think you need
to modify the makefile in zaptel to add ztdummy to the default compiled
modules) then modprobe ztdummy, this resolves the problem.
\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
-> you forgot to load mISDNdsp, which is now needed by chan\_misdn for switching
and dtmf tone detection
Changes
-------
in the Changes File
\end{verbatim}

15
doc/model.txt
View File

@ -1,15 +0,0 @@
Description of call model:
Incoming Call:
Channel backend waits for a RING or equivalent on some sort of
interface. Typically this is done in its own thread. When a RING is
detected, the backend should create a channel structure and then call
ast_pbx_start() on that channel, which will create a thread to monitor
that interface. At this point, the PBX and/or applications it launches
will manage the interface, and it need not be monitored by the
aforementioned thread. When the applications are finished, the requisite
hangup function will be called, at which the channel can be considered to
be no longer valid, and the thread that controls it will imminently be
terminated.

9
doc/mp3.txt → doc/mp3.tex
View File

@ -1,9 +1,8 @@
* Asterisk MP3 Support
======================
\subsubsection{MP3 Music On Hold}
* MP3 Music On Hold
Use of the mpg123 for your music on hold is no longer supported. You should
now use one of the native formats for your music on hold selections.
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

8
doc/musiconhold-fpm.txt
View File

@ -1,8 +0,0 @@
About Hold Music
================
Digium has licensed the music included with
the Asterisk distribution From FreePlayMusic
for use and distribution with Asterisk. It
is licensed ONLY for use as hold music within
an Asterisk based PBX.

15
doc/mysql.txt
View File

@ -1,15 +0,0 @@
MYSQL LICENSING UPDATE
======================
We were recently contacted by MySQL and informed that the MySQL client
libraries are now under GPL license and not LGPL license as before.
Since Asterisk does allow exceptions to GPL, we are removing MySQL support
from standard Asterisk. We will, where appropriate, make it available via
a separate package which will only be usable when Asterisk is used completely
within GPL (i.e. not in conjunction with G.729, OpenH.323, etc). We
apologize for the confusion.
You may find this in the new "asterisk-addons" package.
Mark Spencer
Digium

9
doc/odbcstorage.txt → doc/odbcstorage.tex
View File

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

82
doc/privacy.txt → doc/privacy.tex
View File

@ -1,26 +1,14 @@
Title: Everything About The Privacy Options In The Dial Command That
You Never Wanted To Know, And Even A Little More On Zapateller and
PrivacyManager:
by Steve Murphy
So, you want to avoid talking to pesky telemarketers/charity
seekers/poll takers/magazine renewers/etc?
=============
First of all:
=============
\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.
=================================
Next, Fight against autodialers!!
=================================
\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,
@ -38,9 +26,7 @@ number from their lists.
I highly advise Zapateller for those seeking the nirvana of "privacy".
=======================================
Next, Fight against the empty CALLERID!
=======================================
\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.
@ -67,9 +53,8 @@ the last year.
not always be appropriate for all users. Another option might be to
use call screening. See below.)
==========================
Next, use a WELCOME MENU !
==========================
\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
@ -79,11 +64,8 @@ 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.
----------------------------------------------
Example usage of Zapateller and PrivacyManager:
----------------------------------------------
\subsubsection{Example usage of Zapateller and PrivacyManager}
\begin{verbatim}
[homeline]
exten => s,1,Answer
exten => s,2,SetVar,repeatcount=0
@ -96,6 +78,7 @@ 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
@ -115,9 +98,8 @@ 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.
===================
Next: Torture Them!
===================
\subsection{Next: Torture Them!}
I have developed an elaborate script to torture Telemarketers, and
entertain friends. (See
@ -145,9 +127,7 @@ 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 ...!
========================================
Using Call Screening
=======================================
\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
@ -157,30 +137,31 @@ have a "memory".
Turning on these modes in the dial command results in this sequence of
events, when someone calls you at an extension:
1. The caller calls the Asterisk system, and at some point, selects an
\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.
2. Before ringing your extension, the caller is asked to supply an
\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.
3. After that, they are told "Hang on, we will attempt to connect you
\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.
4. Your extension is then dialed. When (and if) you pick up, you are
\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.
5. You make your selection, and the call is handled as you chose.
\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
@ -190,9 +171,9 @@ exten => 3,3,Dial(Zap/5r3&Zap/6r3|35|tmP(something)A(beep))
or
exten => 3,3,Dial(Zap/5r3&Zap/6r3|35|tmpA(beep))
\end{verbatim}
The 't' allows the dialed party to transfer the call using '#'. It's
The 't' allows the dialed party to transfer the call using '\#'. It's
optional.
The 'm' is for music on hold. I suggest it. Otherwise, the calling
@ -216,15 +197,13 @@ helpful.
When there is no CallerID, P and p options will always record an intro
for the incoming caller. This intro will be stored temporarily in the
/var/lib/asterisk/sounds/priv-callerintros dir, under the name
NOCALLERID_<extension><channelname> and will be erased after the
NOCALLERID\_<extension><channelname> and will be erased after the
callee decides what to do with the call.
Of course, NOCALLERID is not stored in the database. All those with no
CALLERID will be considered "Unknown".
========================
The 'N' and 'n' options
========================
\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
@ -241,15 +220,15 @@ choice on how to handle the call. Whether the P option or the p option
is used, the incoming caller will have to supply their intro every
time they call.
=======================
Recorded Introductions
=======================
[Philosophical Side Note:
\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
@ -265,7 +244,9 @@ 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
@ -285,6 +266,7 @@ 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.
@ -352,10 +334,10 @@ exten => t,1,Goto(s,1)
exten => i,1,Background,invalid
exten => i,2,Goto(s,1)
exten => o,1,Goto(s,1)
\end{verbatim}
In the above, you'd most likely reword the messages to your liking,
and maybe do more advanced things with the 'error' conditions (i,o,t priorities),
but I hope it conveys the idea...
but I hope it conveys the idea.

7
doc/queuelog.txt → doc/queuelog.tex
View File

@ -1,11 +1,8 @@
Queue Log Information
=====================
In order to properly manage ACD queues, it is important to be able to
keep track of details of call setups and teardowns in much greater detail
than traditional call detail records provide. In order to support this,
extensive and detailed tracing of every queued call is stored in the
queue log, located (by default) in /var/log/asterisk/queue_log.
queue log, located (by default) in /var/log/asterisk/queue\_log.
These are the events (and associated information) in the queue log:
@ -93,7 +90,7 @@ Caller was transferred to a different extension. Context and extension
are recorded. The caller's hold time and the length of the call are both
recorded. PLEASE remember that transfers performed by SIP UA's by way
of a reinvite may not always be caught by Asterisk and trigger off this
event. The only way to be 100% sure that you will get this event when
event. The only way to be 100\% sure that you will get this event when
a transfer is performed by a queue member is to use the built-in transfer
functionality of Asterisk.

91
doc/queues-with-callback-members.txt → doc/queues-with-callback-members.tex
View File

@ -1,5 +1,5 @@
Setting up Call Queues -- A Tutorial
\section{Introduction}
Pardon, but the dialplan in this tutorial will be expressed
in AEL, the new Asterisk Extension Language. If you are
@ -8,12 +8,14 @@ degree intuitive. If not, there are documents explaining
its syntax and constructs.
====== Configuring Call Queues
\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] |
@ -43,6 +45,7 @@ Here is an example:
| joinempty=strict |
| leavewhenempty=strict |
===================================
\end{verbatim}
In the above, we have defined 3 separate calling queues:
sales-general, customerservice, and support-dispatch.
@ -73,19 +76,17 @@ remaining incoming callers will immediately be removed from
the queue, and the Queue() call will return, IF the "leavewhenempty" is
set to "strict".
=====================================
| Routing incoming Calls to Queues |
=====================================
\subsection{Routing incoming Calls to Queues}
Then in extensions.ael, you can do these things:
================ The Main Menu
\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 {
@ -132,12 +133,11 @@ context mainmenu {
Hangup();
}
}
\end{verbatim}
\subsubsection{The Contexts referenced from the queues.conf file}
============= The Contexts referenced from the queues.conf file
\begin{verbatim}
context sales {
0 => goto dispatch|s|1;
@ -159,11 +159,12 @@ context sales {
Hangup();
}
}
\end{verbatim}
Please note that there is only one attempt to queue a call in the sales queue. All sales agents that
are logged in will be rung.
\begin{verbatim}
context customerservice {
0 => {
@ -195,12 +196,13 @@ context customerservice {
Hangup();
}
}
\end{verbatim}
Note that calls coming into customerservice will first be try to queue
calls to those agents with a QUEUE_MAX_PENALTY of 10, and if none are available,
calls to those agents with a QUEUE\_MAX\_PENALTY of 10, and if none are available,
then all agents are rung.
\begin{verbatim}
context dispatch
{
@ -224,32 +226,31 @@ context dispatch
Hangup();
}
}
\end{verbatim}
And in the dispatch context, first agents of priority 10 are tried, then
20, and if none are available, all agents are tried.
Notice that a common pattern is followed in each of the three queue contexts:
First, you set QUEUE_MAX_PENALTY to a value, then you call
First, you set QUEUE\_MAX\_PENALTY to a value, then you call
Queue(<queue-name>,option,... (see the documentation for the Queue application));
In the above, note that the "t" option is specified, and this allows the
agent picking up the incoming call the luxury of transferring the call to
other parties.
The purpose of specifying the QUEUE_MAX_PENALTY is to develop a set of priorities
The purpose of specifying the QUEUE\_MAX\_PENALTY is to develop a set of priorities
amongst agents. By the above usage, agents with lower number priorities will
be given the calls first, and then, if no-one picks up the call, the QUEUE_MAX_PENALTY
be given the calls first, and then, if no-one picks up the call, the QUEUE\_MAX\_PENALTY
will be incremented, and the queue tried again. Hopefully, along the line, someone
will pick up the call, and the Queue application will end with a hangup.
The final attempt to queue in most of our examples sets the QUEUE_MAX_PENALTY
The final attempt to queue in most of our examples sets the QUEUE\_MAX\_PENALTY
to zero, which means to try all available agents.
=========================================
| Assigning agents to Queues |
=========================================
\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,
@ -257,16 +258,15 @@ they are added to the queue's agent list, and as they log out, they are
removed. If no agents are available, the queue command will terminate, and
it is the duty of the dialplan to do something appropriate, be it sending
the incoming caller to voicemail, or trying the queue again with a higher
QUEUE_MAX_PENALTY.
QUEUE\_MAX\_PENALTY.
Because a single agent can make themselves available to more than one queue,
the process of joining multiple queues can be handled automatically by the
dialplan.
\subsubsection{Agents Log In and Out}
================= Agents Log In and Out
\begin{verbatim}
context queues-loginout
{
6092 => {
@ -284,7 +284,7 @@ context queues-loginout
goto queues-manip,O${AGENT_NUMBER},1;
}
}
\end{verbatim}
In the above contexts, the agents dial 6092 to log into their queues,
and they dial 6093 to log out of their queues. The agent is prompted
@ -293,7 +293,7 @@ and then they are transferred to the proper extension in the
queues-manip context. The queues-manip context does all the
actual work:
\begin{verbatim}
context queues-manip {
// Raquel Squelch
@ -324,6 +324,7 @@ context queues-manip {
&queue-success();
}
}
\end{verbatim}
In the above extensions, note that the queue-addremove macro is used
to actually add or remove the agent from the applicable queue,
@ -334,7 +335,7 @@ of 20 or 30.
In the above example, Raquel will be dialed first in the dispatch
queue, if she has logged in. If she is not, then the second call of
Queue() with priority of 20 will dial Brittanica if she is present,
otherwise the third call of Queue() with MAX_PENALTY of 0 will
otherwise the third call of Queue() with MAX\_PENALTY of 0 will
dial Rock and Saline simultaneously.
Also note that Rock will be among the first to be called in the sales-general
@ -345,6 +346,7 @@ which queue incoming calls are coming from.
The call to queue-success() gives some feedback to the agent
as they log in and out, that the process has completed.
\begin{verbatim}
macro queue-success()
{
if( ${queue-announce-success} > 0 )
@ -360,10 +362,11 @@ macro queue-success()
}
}
}
\end{verbatim}
The queue-addremove macro is defined in this manner:
\begin{verbatim}
macro queue-addremove(queuename,penalty)
{
switch(${MACRO_EXTEN:0:1})
@ -390,19 +393,19 @@ macro queue-addremove(queuename,penalty)
}
}
}
\end{verbatim}
Basically, it uses the first character of the MACRO_EXTEN variable, to determine the
Basically, it uses the first character of the MACRO\_EXTEN variable, to determine the
proper actions to take. In the above dial plan code, only the cases I or O are used,
which correspond to the Login and Logout actions.
=======================================================
| Controlling The Way Queues Call the Agents |
=======================================================
\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
@ -443,8 +446,9 @@ context agents
6170 => &callagent(${ROCK});
6070 => &callagent(${SALINE});
}
\end{verbatim}
In the above, the variables ${RAQUEL}, etc stand for
In the above, the variables \${RAQUEL}, etc stand for
actual devices to ring that person's
phone (like Zap/37).
@ -457,6 +461,7 @@ Here is the callagent macro, note that if a person in the
queue is called, but does not answer, then they are automatically
removed from the queue.
\begin{verbatim}
macro callagent(device)
{
if( ${GROUP_COUNT(${MACRO_EXTEN}@agents)}=0 )
@ -481,25 +486,27 @@ macro callagent(device)
Busy();
}
}
\end{verbatim}
In the callagent macro above, the ${MACRO_EXTEN} will
In the callagent macro above, the \${MACRO\_EXTEN} will
be 6121, or 6165, etc, which is the extension of the agent.
The use of the GROUP_COUNT, and OUTBOUND_GROUP follow this line
The use of the GROUP\_COUNT, and OUTBOUND\_GROUP follow this line
of thinking. Incoming calls can be queued to ring all agents in the
current priority. If some of those agents are already talking, they
would get bothersome call-waiting tones. To avoid this inconvenience,
when an agent gets a call, the OUTBOUND_GROUP assigns that
when an agent gets a call, the OUTBOUND\_GROUP assigns that
conversation to the group specified, for instance 6171@agents.
The ${GROUP_COUNT()} variable on a subsequent call should return
"1" for that group. If GROUP_COUNT returns 1, then the busy()
The \${GROUP\_COUNT()} variable on a subsequent call should return
"1" for that group. If GROUP\_COUNT returns 1, then the busy()
is returned without actually trying to dial the agent.
================ Pre Acknowledgement Message
\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)
@ -516,9 +523,9 @@ exten=>s,46,Set(MACRO_RESULT=CONTINUE)
exten=>s,50,Playback(after-the-tone)
exten=>s,51,Playback(connected)
exten=>s,52,Playback(beep)
\end{verbatim}
================ Caveats
\subsection{Caveats}
In the above examples, some of the possible error checking has been omitted,
to reduce clutter and make the examples clearer.

203
doc/radius.txt
View File

@ -1,203 +0,0 @@
Call Detail Recording to RADIUS Server
======================================
Configuration of Asterisk to send CDRs to (Free)RADIUS servers.
A. What is needed :
* FreeRADIUS server
* Radiusclient-ng library
* Asterisk PBX
+--------------------+
| Asterisk PBX |
| |
|********************|
| | +---------------+
| RADIUS client |------->| RADIUS server |
| |<-------| (FreeRADIUS) |
+--------------------+ +---------------+
B. Steps to follow in order to have RADIUS support:
1.Radiusclient library
1.a Installation
Download the sources from:
http://developer.berlios.de/projects/radiusclient-ng/
Untar the source tarball.
root@localhost:/usr/local/src# tar xvfz radiusclient-ng-0.5.2.tar.gz
Compile and install the library.
root@localhost:/usr/local/src# cd radiusclient-ng-0.5.2
root@localhost:/usr/local/src/radiusclient-ng-0.5.2# ./configure
root@localhost:/usr/local/src/radiusclient-ng-0.5.2# make
root@localhost:/usr/local/src/radiusclient-ng-0.5.2# make install
1.b Configuration
By default all the configuration files of the radiusclient library will
be in /usr/local/etc/radiusclient-ng directory.
File "radiusclient.conf"
Open the file and find lines containing the following:
authserver localhost
This is the hostname or IP address of the RADIUS server used for
authentication. You will have to change this unless the server is
running on the same host as your Asterisk PBX.
acctserver localhost
This is the hostname or IP address of the RADIUS server used for
accounting. You will have to change this unless the server is running
on the same host as your Asterisk PBX.
File "servers"
RADIUS protocol uses simple access control mechanism based on shared
secrets that allows RADIUS servers to limit access from RADIUS clients.
A RADIUS server is configured with a secret string and only RADIUS
clients that have the same secret will be accepted.
You need to configure a shared secret for each server you have
configured in radiusclient.conf file in the previous step. The shared
secrets are stored in /usr/local/etc/radiusclient-ng/servers file.
Each line contains hostname of a RADIUS server and shared secret
used in communication with that server. The two values are separated
by white spaces. Configure shared secrets for every RADIUS server you
are going to use.
File "dictionary"
Asterisk uses some attributes that are not included in the
dictionary of radiusclient library, therefore it is necessary to add
them. A file called dictionary.digium (kept in the contrib dir)
was created to list all new attributes used by Asterisk.
Add to the end of the main dictionary file
/usr/local/etc/radiusclient-ng/dictionary
the line:
$INCLUDE /path/to/dictionary.digium
2.FreeRADIUS Server (Version 1.1.1)
2.a Installation
Download sources tarball from:
http://freeradius.org/
Untar, configure, build, and install the server:
root@localhost:/usr/local/src# tar xvfz freeradius-1.1.1.tar.gz
root@localhost:/usr/local/src# cd freeradius-1.1.1
root@localhost"/usr/local/src/freeradius-1.1.1# ./configure
root@localhost"/usr/local/src/freeradius-1.1.1# make
root@localhost"/usr/local/src/freeradius-1.1.1# make install
All the configuration files of FreeRADIUS server will be in
/usr/local/etc/raddb directory.
2.b Configuration
There are several file that have to be modified to configure the
RADIUS server. These are presented next.
File "clients.conf"
File /usr/local/etc/raddb/clients.conf contains description of
RADIUS clients that are allowed to use the server. For each of the
clients you need to specify its hostname or IP address and also a
shared secret. The shared secret must be the same string you configured
in radiusclient library.
Example:
client myhost {
secret = mysecret
shortname = foo
}
This fragment allows access from RADIUS clients on "myhost" if they use
"mysecret" as the shared secret.
The file already contains an entry for localhost (127.0.0.1), so if you
are running the RADIUS server on the same host as your Asterisk server,
then modify the existing entry instead, replacing the default password.
File "dictionary"
Note : as of version 1.1.2, the dictionary.digium file ships with FreeRADIUS.
The following procedure brings the dictionary.digium file to previous versions
of FreeRADIUS.
File /usr/local/etc/raddb/dictionary contains the dictionary of
FreeRADIUS server. You have to add the same dictionary file
(dictionary.digium), which you added to the dictionary of radiusclient-ng
library. You can include it into the main file, adding the following line at the
end of file '/usr/local/etc/raddb/dictionary':
$INCLUDE /path/to/dictionary.digium
That will include the same new attribute definitions that are used
in radiusclient-ng library so the client and server will understand each
other.
3. Asterisk Accounting Configuration
Compilation and installation:
The module will be compiled as long as the radiusclient-ng
library has been detected on your system.
By default FreeRADIUS server will log all accounting requests into
/usr/local/var/log/radius/radacct directory in form of plain text files.
The server will create one file for each hostname in the directory. The
following example shows how the log files look like.
Asterisk now generates Call Detail Records. See /include/asterisk/cdr.h
for all the fields which are recorded. By default, records in comma
separated values will be created in /var/log/asterisk/cdr-csv.
The configuration file for cdr_radius.so module is :
/etc/asterisk/cdr.conf
This is where you can set CDR related parameters as well as the path to
the radiusclient-ng library configuration file.
4. Logged Values
"Asterisk-Acc-Code", The account name of detail records
"Asterisk-Src",
"Asterisk-Dst",
"Asterisk-Dst-Ctx", The destination context
"Asterisk-Clid",
"Asterisk-Chan", The channel
"Asterisk-Dst-Chan", (if applicable)
"Asterisk-Last-App", Last application run on the channel
"Asterisk-Last-Data", Argument to the last channel
"Asterisk-Start-Time",
"Asterisk-Answer-Time",
"Asterisk-End-Time",
"Asterisk-Duration", Duration is the whole length that the entire
call lasted. ie. call rx'd to hangup
"end time" minus "start time"
"Asterisk-Bill-Sec", The duration that a call was up after other
end answered which will be <= to duration
"end time" minus "answer time"
"Asterisk-Disposition", ANSWERED, NO ANSWER, BUSY
"Asterisk-AMA-Flags", DOCUMENTATION, BILL, IGNORE etc, specified on
a per channel basis like accountcode.
"Asterisk-Unique-ID", Unique call identifier
"Asterisk-User-Field" User field set via SetCDRUserField

75
doc/realtime.txt → doc/realtime.tex
View File

@ -1,5 +1,4 @@
The Asterisk Realtime Architecture
----------------------------------
\subsubsection{Introduction}
The Asterisk Realtime Architecture is a new set of drivers and
functions implemented in Asterisk.
@ -22,17 +21,19 @@ realtime driver will be supported in that function.
Currently there are three realtime database drivers:
* ODBC: Support for UnixODBC, integrated into Asterisk
The UnixODBC subsystem supports many different databases,
please check www.unixodbc.org for more information.
* MySQL: Found in the asterisk-addons subversion repository on svn.digium.com
* PostgreSQL: Native support for Postgres, integrated into Asterisk
\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}
* Two modes: Static and Realtime
--------------------------------
The ARA realtime mode is used to dynamically load and update objects.
This mode is used in the SIP and IAX2 channels, as well as in the voicemail
system. For SIP and IAX2 this is similar to the v1.0 MYSQL_FRIENDS
system. For SIP and IAX2 this is similar to the v1.0 MYSQL\_FRIENDS
functionality. With the ARA, we now support many more databases for
dynamic configuration of phones.
@ -41,8 +42,8 @@ modules that read configurations, there's no difference between a static
file in the file system, like extensions.conf, and a configuration loaded
from a database.
* Realtime SIP friends
----------------------
\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,
@ -52,16 +53,13 @@ the ones in static configuration.
With caching, the device stays in memory for a specified time. More
information about this is to be found in the sip.conf sample file.
If you specify a separate family called "sipregs" SIP registration
data will be stored in that table and not in the "sippeers" table.
\subsubsection{Realtime H.323 friends}
* Realtime H.323 friends
------------------------
Like SIP realtime friends, H.323 friends also can be configured using
dynamic realtime objects.
* New function in the dial plan: The Realtime Switch
----------------------------------------------------
\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
@ -69,43 +67,48 @@ 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/pattern matching.
Note that this switch does NOT support Caller ID matching, only
extension name or pattern matching.
\subsubsection{Capabilities}
* So what can you do?
---------------------
The realtime Architecture lets you store all of your configuration in
databases and reload it whenever you want. You can force a reload over
the AMI, Asterisk Manager Interface or by calling Asterisk from a
shell script with
asterisk -rx "reload"
You may also dynamically add SIP and IAX devices and extensions
and making them available without a reload, by using the realtime
objects and the realtime switch.
\subsubsection{Configuration in extconfig.conf}
* Configuration in extconfig.conf
---------------------------------
You configure the ARA in extconfig.conf (yes, it's a strange name, but
is was defined in the early days of the realtime architecture and kind
of stuck). Please see doc/extconfig.txt for database schemas.
The part of Asterisk that connects to the ARA use a well defined family
name to find the proper database driver. The syntax is easy:
<family> => <realtime driver>,<db name>[,<table>]
\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:
* sippeers, sipusers SIP peers and users
* iaxpeers, iaxusers IAX2 peers and users
* voicemail Voicemail accounts
* queues Queues
* queue_members Queue members
* extensions Realtime extensions (switch)
\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.
@ -113,17 +116,15 @@ doc/extconfig.txt in your Asterisk source code tree.
For voicemail storage with the support of ODBC, there is a
doc/odbcstorage.txt documentation file.
\subsubsection{Limitations}
* Limitations
-------------
Currently, realtime extensions do not support realtime hints. There is
a workaround available by using func_odbc. See the sample func_odbc.conf
a workaround available by using func\_odbc. See the sample func\_odbc.conf
for more information.
\subsubsection{FreeTDS supported with connection pooling}
* FreeTDS supported with connection pooling
-------------------------------------------
In order to use a FreeTDS-based database with realtime, you need to turn
connection pooling on in res_odbc.conf. This is due to a limitation within
connection pooling on in res\_odbc.conf. This is due to a limitation within
the FreeTDS protocol itself. Please note that this includes databases such
as MS SQL Server and Sybase. This support is new in the current release.

20
doc/security.txt → doc/security.tex
View File

@ -1,4 +1,4 @@
==== Security Notes with Asterisk ====
\subsection{Introduction}
PLEASE READ THE FOLLOWING IMPORTANT SECURITY RELATED INFORMATION.
IMPROPER CONFIGURATION OF ASTERISK COULD ALLOW UNAUTHORIZED USE OF YOUR
@ -9,7 +9,7 @@ as well as dialplan security (authorization - who can access services in
your pbx). If you are setting up Asterisk in production use, please make
sure you understand the issues involved.
* NETWORK SECURITY
\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
@ -28,14 +28,7 @@ The IAX2 protocol supports strong RSA key authentication as well as
AES encryption of voice and signalling. The SIP channel does not
support encryption in this version of Asterisk.
By default, if you have libcap available, Asterisk will try to retain the
CAP_NET_ADMIN capability when running as a non-root user. If you do not need
that capability you may want to configure Asterisk with --without-cap; however,
this will prevent Asterisk from being able to mark high ToS bits under Linux.
More information on CAP_NET_ADMIN is available at:
http://www.lids.org/lids-howto/node48.html
* DIALPLAN SECURITY
\subsection{Dialplan Security}
First and foremost remember this:
@ -53,10 +46,13 @@ 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
@ -67,13 +63,13 @@ include => default
[default]
exten => 6123,Dial(Zap/1)
\end{verbatim}
DON'T FORGET TO TAKE THE DEMO CONTEXT OUT OF YOUR DEFAULT CONTEXT. There
isn't really a security reason, it just will keep people from wanting to
play with your Asterisk setup remotely.
* LOG SECURITY
\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

BIN
doc/sla.pdf
View File

Binary file not shown.

16
doc/sla.tex
View File

@ -1,13 +1,13 @@
\documentclass[12pt,a4]{article}
\usepackage{hyperref}
%\documentclass[12pt,a4]{article}
%\usepackage{hyperref}
\author{Russell Bryant \\ Software Engineer \\ Digium, Inc.}
\title{Shared Line Appearances}
%\author{Russell Bryant \\ Software Engineer \\ Digium, Inc.}
%\title{Shared Line Appearances}
\begin{document}
\maketitle
%\begin{document}
%\maketitle
\tableofcontents
%\tableofcontents
\section{Introduction}
@ -375,4 +375,4 @@ have it on hold do not have private hold enabled. If connected, the appeareance
of this trunk on this station will then show in use. All stations that are not
currently connected to this trunk will show it on hold.
\end{document}
%\end{document}

56
main/pbx.c
View File

@ -3056,6 +3056,56 @@ static int handle_show_application(int fd, int argc, char *argv[])
return RESULT_SUCCESS;
}
#ifdef AST_DEVMODE
static char core_dumpappdocs_help[] =
"Usage: core dumpappdocs [application]\n"
" Dump Application documentation to \\tmp\\ast_appdocs.tex.\n";
static int handle_core_dumpappdocs(int fd, int argc, char *argv[])
{
struct ast_app *app;
FILE *f;
char *appname = NULL;
const char *fn = "/tmp/ast_appdocs.tex";
if (argc > 3)
appname = argv[3];
if (!(f = fopen(fn, "w+"))) {
ast_cli(fd, "Unable to open %s for writing!\n", fn);
return RESULT_FAILURE;
}
fprintf(f, "%% This file is automatically generated. Any manual edits will be lost.\n");
AST_LIST_LOCK(&apps);
AST_LIST_TRAVERSE(&apps, app, list) {
if (appname && strcasecmp(app->name, appname))
continue;
fprintf(f, "\\section{%s}\n"
"\\subsection{Synopsis}\n"
"\\begin{verbatim}\n"
"%s\n"
"\\end{verbatim}\n"
"\\subsection{Description}\n"
"\\begin{verbatim}\n"
"%s\n"
"\\end{verbatim}\n\n\n", app->name, app->synopsis, app->description);
if (appname)
break;
}
AST_LIST_UNLOCK(&apps);
fclose(f);
ast_cli(fd, "Documentation has been dumped to %s\n", fn);
return RESULT_SUCCESS;
}
#endif
/*! \brief handle_show_hints: CLI support for listing registered dial plan hints */
static int handle_show_hints(int fd, int argc, char *argv[])
{
@ -3730,6 +3780,12 @@ static struct ast_cli_entry pbx_cli[] = {
handle_show_application, "Describe a specific dialplan application",
show_application_help, complete_show_application },
#ifdef AST_DEVMODE
{ { "core", "dumpappdocs", NULL },
handle_core_dumpappdocs, "Dump App docs in LaTeX format",
core_dumpappdocs_help, NULL },
#endif
{ { "core", "set", "global", NULL },
handle_set_global, "Set global dialplan variable",
set_global_help },

1
makeopts.in
View File

@ -22,6 +22,7 @@ STRIP=@STRIP@
WGET=@WGET@
FETCH=@FETCH@
DOWNLOAD=@DOWNLOAD@
RUBBER=@RUBBER@
BUILD_PLATFORM=@BUILD_PLATFORM@
BUILD_CPU=@BUILD_CPU@