From 286a521e1135aaa655577646bfcfd7a98f2fb2dc Mon Sep 17 00:00:00 2001 From: Olle Johansson Date: Wed, 1 Feb 2006 17:49:02 +0000 Subject: - Removing the "README." from the name of the README files. git-svn-id: https://origsvn.digium.com/svn/asterisk/trunk@9047 65c4cc65-6c06-0410-ace0-fbb531ad65f3 --- doc/00README.1st | 72 ++-- doc/README.ael | 273 ---------------- doc/README.app_sms | 470 -------------------------- doc/README.asterisk.conf | 76 ----- doc/README.backtrace | 187 ----------- doc/README.callingpres | 18 - doc/README.cdr | 120 ------- doc/README.channels | 44 --- doc/README.cliprompt | 28 -- doc/README.configuration | 180 ---------- doc/README.cygwin | 7 - doc/README.dundi | 26 -- doc/README.enum | 306 ----------------- doc/README.extconfig | 85 ----- doc/README.extensions | 58 ---- doc/README.externalivr | 109 ------- doc/README.h323 | 23 -- doc/README.hardware | 70 ---- doc/README.iax | 369 --------------------- doc/README.ices | 12 - doc/README.jitterbuffer | 137 -------- doc/README.linkedlists | 98 ------ doc/README.localchannel | 49 --- doc/README.manager | 298 ----------------- doc/README.math | 69 ---- doc/README.misdn | 342 ------------------- doc/README.mp3 | 19 -- doc/README.musiconhold-fpm | 8 - doc/README.mysql | 15 - doc/README.odbcstorage | 33 -- doc/README.privacy | 361 -------------------- doc/README.queuelog | 78 ----- doc/README.realtime | 111 ------- doc/README.security | 67 ---- doc/README.sms | 147 --------- doc/README.tds | 18 - doc/README.variables | 796 --------------------------------------------- doc/ael.txt | 273 ++++++++++++++++ doc/app-sms.txt | 470 ++++++++++++++++++++++++++ doc/asterisk-conf.txt | 76 +++++ doc/backtrace.txt | 187 +++++++++++ doc/billing.txt | 120 +++++++ doc/callingpres.txt | 18 + doc/cdr.txt | 171 ---------- doc/cdrdriver.txt | 171 ++++++++++ doc/chaniax.txt | 369 +++++++++++++++++++++ doc/channels.txt | 44 +++ doc/channelvariables.txt | 796 +++++++++++++++++++++++++++++++++++++++++++++ doc/cliprompt.txt | 28 ++ doc/configuration.txt | 180 ++++++++++ doc/cygwin.txt | 7 + doc/dundi.txt | 26 ++ doc/enum.txt | 306 +++++++++++++++++ doc/extconfig.txt | 85 +++++ doc/extensions.txt | 58 ++++ doc/externalivr.txt | 109 +++++++ doc/freetds.txt | 18 + doc/h323.txt | 22 ++ doc/hardware.txt | 70 ++++ doc/ices.txt | 12 + doc/jitterbuffer.txt | 137 ++++++++ doc/linkedlists.txt | 98 ++++++ doc/localchannel.txt | 49 +++ doc/manager.txt | 298 +++++++++++++++++ doc/math.txt | 69 ++++ doc/misdn.txt | 342 +++++++++++++++++++ doc/mp3.txt | 19 ++ doc/musiconhold-fpm.txt | 8 + doc/mysql.txt | 15 + doc/odbcstorage.txt | 33 ++ doc/privacy.txt | 361 ++++++++++++++++++++ doc/queuelog.txt | 78 +++++ doc/realtime.txt | 111 +++++++ doc/security.txt | 67 ++++ doc/sms.txt | 147 +++++++++ 75 files changed, 5313 insertions(+), 5314 deletions(-) delete mode 100644 doc/README.ael delete mode 100644 doc/README.app_sms delete mode 100644 doc/README.asterisk.conf delete mode 100644 doc/README.backtrace delete mode 100644 doc/README.callingpres delete mode 100644 doc/README.cdr delete mode 100644 doc/README.channels delete mode 100644 doc/README.cliprompt delete mode 100644 doc/README.configuration delete mode 100644 doc/README.cygwin delete mode 100644 doc/README.dundi delete mode 100644 doc/README.enum delete mode 100644 doc/README.extconfig delete mode 100644 doc/README.extensions delete mode 100644 doc/README.externalivr delete mode 100644 doc/README.h323 delete mode 100644 doc/README.hardware delete mode 100644 doc/README.iax delete mode 100644 doc/README.ices delete mode 100644 doc/README.jitterbuffer delete mode 100644 doc/README.linkedlists delete mode 100644 doc/README.localchannel delete mode 100644 doc/README.manager delete mode 100644 doc/README.math delete mode 100644 doc/README.misdn delete mode 100644 doc/README.mp3 delete mode 100644 doc/README.musiconhold-fpm delete mode 100644 doc/README.mysql delete mode 100644 doc/README.odbcstorage delete mode 100644 doc/README.privacy delete mode 100644 doc/README.queuelog delete mode 100644 doc/README.realtime delete mode 100644 doc/README.security delete mode 100644 doc/README.sms delete mode 100644 doc/README.tds delete mode 100644 doc/README.variables create mode 100644 doc/ael.txt create mode 100644 doc/app-sms.txt create mode 100644 doc/asterisk-conf.txt create mode 100644 doc/backtrace.txt create mode 100644 doc/billing.txt create mode 100644 doc/callingpres.txt delete mode 100644 doc/cdr.txt create mode 100644 doc/cdrdriver.txt create mode 100644 doc/chaniax.txt create mode 100644 doc/channels.txt create mode 100644 doc/channelvariables.txt create mode 100644 doc/cliprompt.txt create mode 100644 doc/configuration.txt create mode 100644 doc/cygwin.txt create mode 100644 doc/dundi.txt create mode 100644 doc/enum.txt create mode 100644 doc/extconfig.txt create mode 100644 doc/extensions.txt create mode 100644 doc/externalivr.txt create mode 100644 doc/freetds.txt create mode 100644 doc/h323.txt create mode 100644 doc/hardware.txt create mode 100644 doc/ices.txt create mode 100644 doc/jitterbuffer.txt create mode 100644 doc/linkedlists.txt create mode 100644 doc/localchannel.txt create mode 100644 doc/manager.txt create mode 100644 doc/math.txt create mode 100644 doc/misdn.txt create mode 100644 doc/mp3.txt create mode 100644 doc/musiconhold-fpm.txt create mode 100644 doc/mysql.txt create mode 100644 doc/odbcstorage.txt create mode 100644 doc/privacy.txt create mode 100644 doc/queuelog.txt create mode 100644 doc/realtime.txt create mode 100644 doc/security.txt create mode 100644 doc/sms.txt diff --git a/doc/00README.1st b/doc/00README.1st index a530922e6..04dba7cb2 100644 --- a/doc/00README.1st +++ b/doc/00README.1st @@ -6,62 +6,62 @@ directory of your source code Start here ---------- -README.security IMPORTANT INFORMATION ABOUT ASTERISK SECURITY -README.hardware Hardware supported by Asterisk +security.txt IMPORTANT INFORMATION ABOUT ASTERISK SECURITY +hardware.txt Hardware supported by Asterisk Configuration ------------- -README.configuration Features in the configuration parser -README.extensions Basics about the dialplan -README.extconfig How to use databases for configuration of Asterisk (ARA) -README.realtime The Asterisk Realtime Architecture - database support -README.tds Information about the FreeTDS support -README.ael Information about the Asterisk Extension Language +configuration.txt Features in the configuration parser +extensions.txt Basics about the dialplan +extconfig.txt How to use databases for configuration of Asterisk (ARA) +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 -README.app_sms How to configure the SMS application -README.asterisk.conf Documentation of various options in asterisk.conf -README.callingpres Settings for Caller ID presentation -README.cdr Call Data Record information -README.cliprompt How to change the Asterisk CLI prompt -README.dundi Dundi - a discovery protocol -README.enum Enum support in Asterisk -README.ices Integrating ICEcast streaming in Asterisk -README.jitterbuffer About the IAX2 jitterbuffer implementation -README.math About the math() application -README.mp3 About MP3 support in Asterisk -README.musiconhold-fpm Free Music On Hold music -README.mysql About MYSQL support in Asterisk -README.odbcstorage Voicemail storage of messages in UnixODBC -README.privacy Privacy enhancements in Asterisk -README.queuelog Agent and queue logging -README.variables Channel variables -cdr.txt About CDR storage in various databases (needs update) +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) Channel drivers --------------- -README.misdn -README.h323 How to compile and configure the H.323 channel -README.iax About the IAX2 protocol support in Asterisk -README.localchannel The local channel is a "gosub" in the dialplan +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 ----------- -README.cygwin Compiling Asterisk on CygWin platforms (Windows) +cygwin.txt Compiling Asterisk on CygWin platforms (Windows) For developers -------------- See http://www.asterisk.org/developers for more information -README.manager About the AMI - Asterisk Manager Interface +manager.txt About the AMI - Asterisk Manager Interface for third party call control and PBX management -README.backtrace How to produce a backtrace when Asterisk crashes +backtrace.txt How to produce a backtrace when Asterisk crashes CODING-GUIDELINES Guidelines for developers -README.channels What is a channel? -README.externalivr Documentation of the protocol used in externalivr() -README.linkedlists How to develop linked lists in Asterisk (old) +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) diff --git a/doc/README.ael b/doc/README.ael deleted file mode 100644 index e2014a4e1..000000000 --- a/doc/README.ael +++ /dev/null @@ -1,273 +0,0 @@ -The Asterisk Extension Language -=================================== - -Over time, people have been pushing to add features to extensions.conf to make -it more like a programming language. AEL is intended to provide an actual -programming language that can be used to write an Asterisk dialplan. - -Getting Started -------------------------- -The AEL parser (pbx_ael.so) is completely separate from the module -that parses extensions.conf (pbx_config.so). To use AEL, the only thing that -has to be done is the module pbx_ael.so must be loaded by Asterisk. This will -be done automatically if using 'autoload=yes' in /etc/asterisk/modules.conf. -When the module is loaded, it will look for 'extensions.ael' in /etc/asterisk/. -Both extensions.conf and extensions.ael can be used in conjunction with each -other if that is what is desired. Some users may want to keep extensions.conf -for the features that are configured in the 'general' section of -extensions.conf. - - -Reloading extensions.ael -------------------------- -To reload extensions.ael, the following command can be issued at the CLI. - - *CLI> reload pbx_ael.so - - -Contexts -------------------------- -Contexts in AEL represent a set of extensions in the same way that they do -in extensions.conf. - -context default { - -}; - - -Extensions -------------------------- -To specify an extension in a context, the following syntax is used. If more -than one application is be called in an extension, they can be listed in order -inside of a block. - -context default { - 1234 => Playback(tt-monkeys); - 8000 => { - NoOp(one); - NoOp(two); - NoOp(three); - }; - _5XXX => NoOp(it's a pattern!); -}; - - -Includes -------------------------- -Contexts can be included in other contexts. All included contexts are listed -within a single block. - -context default { - includes { - local; - longdistance; - international; - }; -}; - - -Dialplan Switches -------------------------- -Switches are listed in their own block within a context. - -context default { - switches { - DUNDi/e164; - IAX2/box5; - }; - eswitches { - IAX2/context@${CURSERVER}; - }; -}; - - -Ignorepat -------------------------- -ignorepat can be used to instruct channel drivers to not cancel dialtone upon -receipt of a particular pattern. The most commonly used example is '9'. - -context outgoing { - ignorepat => 9; -}; - - -Variables -------------------------- -Variables in Asterisk do not have a type, so to define a variable, it just has -to be specified with a value. - -Global variables are set in their own block. - -globals { - CONSOLE=Console/dsp; - TRUNK=Zap/g2; -}; - -Variables can be set within extensions as well. - -context foo { - 555 => { - x=5; - y=blah; - NoOp(x is ${x} and y is ${y} !); - }; -}; - -Writing to a dialplan function is treated the same as writing to a variable. - -context blah { - s => { - CALLERID(name)=ChickenMan; - NoOp(My name is ${CALLERID(name)} !); - }; -}; - - -Loops -------------------------- -AEL has implementations of 'for' and 'while' loops. - -context loops { - 1 => { - for (x=0; ${x} < 3; x=${x} + 1) { - Verbose(x is ${x} !); - }; - }; - 2 => { - y=10; - while (${y} >= 0) { - Verbose(y is ${y} !); - y=${y}-1; - }; - }; -}; - - -Conditionals -------------------------- -AEL supports if and switch statements. Note that if you have an else -clause, you MUST place braces around the non-else portion of the if -statement. - -context conditional { - _8XXX => { - Dial(SIP/${EXTEN}); - if (${DIALSTATUS} = "BUSY") { - Voicemail(${EXTEN}|b); - } else - Voicemail(${EXTEN}|u); - }; - _777X => { - switch (${EXTEN}) { - case 7771: - NoOp(You called 7771!); - break; - case 7772: - NoOp(You called 7772!); - break; - case 7773: - NoOp(You called 7773!); - // fall through - default: - NoOp(In the default clause!); - }; - }; -}; - - -goto and labels -------------------------- -This is an example of how to do a goto in AEL. - -context gotoexample { - s => { -begin: - NoOp(Infinite Loop! yay!); - Wait(1); - goto begin; - }; -}; - - -Macros -------------------------- -A macro is defined in its own block like this. The arguments to the macro are -specified with the name of the macro. They are then reffered to by that same -name. A catch block can be specified to catch special extensions. - -macro std-exten( ext , dev ) { - Dial(${dev}/${ext},20); - switch(${DIALSTATUS) { - case BUSY: - Voicemail(b${ext}); - break; - default: - Voicemail(u${ext}); - }; - catch a { - VoiceMailMain(${ext}); - return; - }; -}; - -A macro is then called by preceeding the macro name with an ampersand. - -context example { - _5XXX => &std-exten(${EXTEN}, "IAX2"); -}; - - -Examples ------------------------- - -context demo { - s => { - Wait(1); - Answer(); - TIMEOUT(digit)=5; - TIMEOUT(response)=10; -restart: - Background(demo-congrats); -instructions: - for (x=0; ${x} < 3; x=${x} + 1) { - Background(demo-instruct); - WaitExten(); - }; - }; - 2 => { - Background(demo-moreinfo); - goto s|instructions; - }; - 3 => { - LANGUAGE()=fr; - goto s|restart; - }; - 500 => { - Playback(demo-abouttotry); - Dial(IAX2/guest@misery.digium.com); - Playback(demo-nogo); - goto s|instructions; - }; - 600 => { - Playback(demo-echotest); - Echo(); - Playback(demo-echodone); - goto s|instructions; - }; - # => { -hangup: - Playback(demo-thanks); - Hangup(); - }; - t => goto #|hangup; - i => Playback(invalid); -}; - - -Syntax Note ------------------------- -Please note that all opening {'s are on the same line as the keyword. For -the time being, that syntax is mandatory. We are looking at ways to allow -other syntax in the future for flexibility, but for now, that is the way -you must write AEL clauses. - diff --git a/doc/README.app_sms b/doc/README.app_sms deleted file mode 100644 index 22ca3fdf9..000000000 --- a/doc/README.app_sms +++ /dev/null @@ -1,470 +0,0 @@ - - * Application SMS - - The SMS module for Asterisk was developed by Adrian Kennard, and is an - implementation of the ETSI specification for landline SMS, ETSI ES 201 - 912, which is available from www.etsi.org. Landline SMS is starting to - be available in various parts of Europe, and is available from BT in - the UK. However, Asterisk would allow gateways to be created in other - locations such as the US, and use of SMS capable phones such as the - Magic Messenger. SMS works using analogue or ISDN lines. - -Background - - Short Message Service (SMS), or texting is very popular between mobile - phones. A message can be sent between two phones, and normally - contains 160 characters. There are ways in which various types of data - can be encoded in a text message such as ring tones, and small - graphic, etc. Text messaging is being used for voting and - competitions, and also SPAM... - Sending a message involves the mobile phone contacting a message - centre (SMSC) and passing the message to it. The message centre then - contacts the destination mobile to deliver the message. The SMSC is - responsible for storing the message and trying to send it until the - destination mobile is available, or a timeout. - Landline SMS works in basically the same way. You would normally have - a suitable text capable landline phone, or a separate texting box such - as a Magic Messenger on your phone line. This sends a message to a - message centre your telco provides by making a normal call and sending - the data using 1200 Baud FSK signaling according to the ETSI spec. To - receive a message the message centre calls the line with a specific - calling number, and the text capable phone answers the call and - receives the data using 1200 Baud FSK signaling. This works - particularly well in the UK as the calling line identity is sent - before the first ring, so no phones in the house would ring when a - message arrives. - -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 - - SMS - Short Message Service - i.e. text messages - SMSC - Short Message Service Centre - The system responsible for storing and forwarding messages - MO - Mobile Originated - A message on its way from a mobile or landline device to the SMSC - MT - Mobile Terminated - A message on its way from the SMSC to the mobile or landline device - RX - Receive - A message coming in to the Asterisk box - TX - Transmit - A message going out of the Asterisk box - -Sub address - - When sending a message to a landline, you simply send to the landline - number. In the UK, all of the mobile operators (bar one) understand - sending messages to landlines and pass the messages to the BTText - system for delivery to the landline. - The specification for landline SMS allows for the possibility of more - than one device on a single landline. These can be configured with Sub - addresses which are a single digit. To send a message to a specific - device the message is sent to the landline number with an extra digit - appended to the end. The telco can define a default sub address (9 in - the UK) which is used when the extra digit is not appended to the end. - When the call comes in, part of the calling line ID is the sub - address, so that only one device on the line answers the call and - receives the message. - Sub addresses also work for outgoing messages. Part of the number - called by the device to send a message is its sub address. Sending - from the default sub address (9 in the UK) means the message is - delivered with the sender being the normal landline number. Sending - from any other sub address makes the sender the landline number with - an extra digit on the end. - Using Asterisk, you can make use of the sub addresses for sending and - receiving messages. Using DDI (DID, i.e. multiple numbers on the line - on ISDN) you can also make use of many different numbers for SMS. - -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 - - The following contexts are recommended. -; Mobile Terminated, RX. This is used when an incoming call from the SMS arrive -s, with the queue (called number and sub address) in ${EXTEN} -; Running an app after receipt of the text allows the app to find all messages -in the queue and handle them, e.g. email them. -; The app may be something like smsq --process=somecommand --queue=${EXTEN} -to run a command for each received message -; See below for usage -[smsmtrx] -exten = _X.,1, SMS(${EXTEN}|a) -exten = _X.,2,System("someapptohandleincomingsms ${EXTEN}") -exten = _X.,3,Hangup -; Mobile originated, RX. This is receiving a message from a device, e.g. a Magi -c Messenger on a sip extension -; Running an app after receipt of the text allows the app to find all messages -in the queue and handle then, e.g. sending them to the public SMSC -; The app may be something like smsq --process=somecommand --queue=${EXTEN} -to run a command for each received message -; See below for example usage -[smsmorx] -exten = _X.,1, SMS(${EXTEN}|sa) -exten = _X.,2,System("someapptohandlelocalsms ${EXTEN}") -exten = _X.,3,Hangup - - smsmtrx is normally accessed by an incoming call from the SMSC. In the - UK this call is from a CLI of 080058752X0 where X is the sub address. - As such a typical usage in the extensions.conf at the point of - handling an incoming call is:- -exten = _X./8005875290,1,Goto(smsmtrx,${EXTEN},1) -exten = _X./_80058752[0-8]0,1,Goto(smsmtrx,${EXTEN}-${CALLERIDNUM:8:1},1) - - Alternatively, if you have the correct national prefix on incoming - CLI, e.g. using zaphfc, you might use:- -exten = _X./08005875290,1,Goto(smsmtrx,${EXTEN},1) -exten = _X./_080058752[0-8]0,1,Goto(smsmtrx,${EXTEN}-${CALLERIDNUM:9:1},1) - - smsmorx is normally accessed by a call from a local sip device - connected to a Magic Messenger. It could however by that you are - operating Asterisk as a message centre for calls from outside. Either - way, you look at the called number and goto smsmorx. In the UK, the - SMSC number that would be dialed is 1709400X where X is the caller sub - address. As such typical usage in extension.config at the point of - handling a call from a sip phone is:- -exten = 17094009,1,Goto(smsmorx,${CALLERIDNUM},1) -exten = _1709400[0-8],1,Goto(smsmorx,${CALLERIDNUM}-{EXTEN:7:1},1) - -Using smsq - - smsq is a simple helper application designed to make it easy to send - messages from a command line. it is intended to run on the Asterisk - box and have direct access to the queue directories for SMS and for - Asterisk. - In its simplest form you can send an SMS by a command such as - smsq 0123456789 This is a test to 0123456789 - This would create a queue file for a mobile originated TX message in - queue 0 to send the text "This is a test to 0123456789" to 0123456789. - It would then place a file in the /var/spool/asterisk/outgoing - directory to initiate a call to 17094009 (the default message centre - in smsq) attached to application SMS with argument of the queue name - (0). - Normally smsq will queue a message ready to send, and will then create - a file in the Asterisk outgoing directory causing Asterisk to actually - connect to the message centre or device and actually send the pending - message(s). - Using --process, smsq can however be used on received queues to run a - command for each file (matching the queue if specified) with various - environment variables set based on the message (see below); - smsq options:- - - --help - Show help text - --usage - Show usage - --queue - -q - Specify a specific queue - In no specified, messages are queued under queue "0" - --da - -d - Specify destination address - --oa - -o - Specify originating address - This also implies that we are generating a mobile terminated message - --ud - -m - Specify the actual message - --ud-file - -f - Specify a file to be read for the context of the message - A blank filename (e.g. --ud-file= on its own) means read stdin. Very - useful when using via ssh where command line parsing could mess up the - message. - --mt - -t - Mobile terminated message to be generated - --mo - Mobile originated message to be generated - Default - --tx - Transmit message - Default - --rx - -r - Generate a message in the receive queue - --UTF-8 - Treat the file as UTF-8 encoded (default) - --UCS-1 - Treat the file as raw 8 bit UCS-1 data, not UTF-8 encoded - --UCS-2 - Treat the file as raw 16 bit bigendian USC-2 data - --process - Specific a command to process for each file in the queue - Implies --rx and --mt if not otherwise specified. - Sets environment variables for every possible variable, and also ud, - ud8 (USC-1 hex), and ud16 (USC-2 hex) for each call. Removes files. - --motx-channel - Specify the channel for motx calls - May contain X to use sub address based on queue name or may be full - number - Default is Local/1709400X - --motx-callerid - Specify the caller ID for motx calls - The default is the queue name without -X suffix - --motx-wait - Wait time for motx call - Default 10 - --motx-delay - Retry time for motx call - Default 1 - --motx-retries - Retries for motx call - Default 10 - --mttx-channel - Specify the channel for mttx calls - Default is Local/ and the queue name without -X suffix - --mtttx-callerid - Specify the callerid for mttx calls - May include X to use sub address based on queue name or may be full - number - Default is 080058752X0 - --mttx-wait - Wait time for mttx call - Default 10 - --mttx-delay - Retry time for mttx call - Default 30 - --mttx-retries - Retries for mttx call - Default 100 - --default-sub-address - The default sub address assumed (e.g. for X in CLI and dialled numbers - as above) when none added (-X) to queue - Default 9 - --no-dial - -x - Create queue, but do not dial to send message - --no-wait - Do not wait if a call appears to be in progress - This could have a small window where a mesdsage is queued but not - sent, so regular calls to smsq should be done to pick up any missed - messages - --concurrent - How many concurrent calls to allow (per queue), default 1 - --mr - -n - Message reference - --pid - -p - Protocol ID - --dcs - Data coding scheme - --udh - Specific hex string of user data header specified (not including the - initial length byte) - May be a blank string to indicate header is included in the user data - already but user data header indication to be set. - --srr - Status report requested - --rp - Return path requested - --vp - Specify validity period (seconds) - --scts - Specify timestamp (YYYY-MM-DDTHH:MM:SS) - --spool-dir - Spool dir (in which sms and outgoing are found) - Default /var/spool/asterisk - - Other arguments starting '-' or '--' are invalid and will cause an - error. Any trailing arguments are processed as follows:- - * If the message is mobile originating and no destination address - has been specified, then the first argument is assumed to be a - destination address - * If the message is mobile terminating and no destination address - has been specified, then the first argument is assumed to be the - queue name - * If there is no user data, or user data file specified, then any - following arguments are assumed to be the message, which are - concatenated. - * If no user data is specified, then no message is sent. However, - unless --no-dial is specified, smsq checks for pending messages - and generates an outgoing anyway - - Note that when smsq attempts to make a file in - /var/spool/asterisk/outgoing, it checks if there is already a call - queued for that queue. It will try several filenames, up to the - --concorrent setting. If these files exists, then this means Asterisk - is already queued to send all messages for that queue, and so Asterisk - should pick up the message just queued. However, this alone could - create a race condition, so if the files exist then smsq will wait up - to 3 seconds to confirm it still exists or if the queued messages have - been sent already. The --no-wait turns off this behaviour. Basically, - this means that if you have a lot of messages to send all at once, - Asterisk will not make unlimited concurrent calls to the same message - centre or device for the same queue. This is because it is generally - more efficient to make one call and send all of the messages one after - the other. - smsq can be used with no arguments, or with a queue name only, and it - will check for any pending messages and cause an outgoing if there are - any. It only sets up one outgoing call at a time based on the first - queued message it finds. A outgoing call will normally send all queued - messages for that queue. One way to use smsq would be to run with no - queue name (so any queue) every minute or every few seconds to send - pending message. This is not normally necessary unless --no-dial is - selected. Note that smsq does only check motx or mttx depending on the - options selected, so it would need to be called twice as a general - check. - UTF-8 is used to parse command line arguments for user data, and is - the default when reading a file. If an invalid UTF-8 sequence is - found, it is treated as UCS-1 data (i.e, as is). - The --process option causes smsq to scan the specified queue (default - is mtrx) for messages (matching the queue specified, or any if queue - not specified) and run a command and delete the file. The command is - run with a number of environment variables set as follows. Note that - these are unset if not needed and not just taken from the calling - environment. This allows simple processing of incoming messages - - $queue - Set if a queue specified - $?srr - srr is set (to blank) if srr defined and has value 1. - $?rp - rp is set (to blank) if rp defined and has value 1. - $ud - User data, UTF-8 encoding, including any control characters, but with - nulls stripped out - Useful for the content of emails, for example, as it includes any - newlines, etc. - $ude - User data, escaped UTF-8, including all characters, but control - characters \n, \r, \t, \f, \xxx and \ is escaped as \\ - Useful fGuaranteed one line printable text, so useful in Subject lines - of emails, etc - $ud8 - Hex UCS-1 coding of user data (2 hex digits per character) - Present only if all user data is in range U+0000 to U+00FF - $ud16 - Hex UCS-2 coding of user data (4 hex digits per chartacter) - other - Other fields set using their field name, e.g. mr, pid, dcs, etc. udh - is a hex byte string - -File formats - - By default all queues are held in a director /var/spool/asterisk/sms. - Within this directory are sub directories mtrx, mttx, morx, motx which - hold the received messages and the messages ready to send. Also, - /var/log/asterisk/sms is a log file of all messages handled. - The file name in each queue directory starts with the queue parameter - to SMS which is normally the CLI used for an outgoing message or the - called number on an incoming message, and may have -X (X being sub - address) appended. If no queue ID is known, then 0 is used by smsq by - default. After this is a dot, and then any text. Files are scanned for - matching queue ID and a dot at the start. This means temporary files - being created can be given a different name not starting with a queue - (we recommend a . on the start of the file name for temp files). - Files in these queues are in the form of a simple text file where each - line starts with a keyword and an = and then data. udh and ud have - options for hex encoding, see below. - UTF-8. The user data (ud) field is treated as being UTF-8 encoded - unless the DCS is specified indicating 8 bit formart. If 8 bit format - is specified then the user data is sent as is. - The keywords are as follows:- - - oa Originating address - The phone number from which the message came - Present on mobile terminated messages and is the CLI for morx messages - da - Destination Address - The phone number to which the message is sent - Present on mobile originated messages - scts - The service centre time stamp - Format YYYY-MM-DDTHH:MM:SS - Present on mobile terminated messages - pid - One byte decimal protocol ID - See GSM specs for more details - Normally 0 or absent - dcs - One byte decimal data coding scheme - If omitted, a sensible default is used (see below) - See GSM specs for more details - mr - One byte decimal message reference - Present on mobile originated messages, added by default if absent - srr - 0 or 1 for status report request - Does not work in UK yet, not implemented in app_sms yet - rp - 0 or 1 return path - See GSM specs for details - vp - Validity period in seconds - Does not work in UK yet - udh - Hex string of user data header prepended to the SMS contents, - excluding initial length byte. - Consistent with ud, this is specified as udh# rather than udh= - If blank, this means that the udhi flag will be set but any user data - header must be in the ud field - ud - User data, may be text, or hex, see below - - udh is specified as as udh# followed by hex (2 hex digits per byte). - If present, then the user data header indicator bit is set, and the - length plus the user data header is added to the start of the user - data, with padding if necessary (to septet boundary in 7 bit format). - User data can hold an USC character codes U+0000 to U+FFFF. Any other - characters are coded as U+FEFF - ud can be specified as ud= followed by UTF-8 encoded text if it - contains no control characters, i.e. only (U+0020 to U+FFFF). Any - invalid UTF-8 sequences are treated as is (U+0080-U+00FF). - ud can also be specified as ud# followed by hex (2 hex digits per - byte) containing characters U+0000 to U+00FF only. - ud can also be specified as ud## followed by hex (4 hex digits per - byte) containing UCS-2 characters. - When written by app_sms (e.g. incoming messages), the file is written - with ud= if it can be (no control characters). If it cannot, the a - comment line ;ud= is used to show the user data for human readability - and ud# or ud## is used. - -Delivery reports - - The SMS specification allows for delivery reports. These are requested - using the srr bit. However, as these do not work in the UK yet they - are not fully implemented in this application. If anyone has a telco - that does implement these, please let me know. BT in the UK have a non - standard way to do this by starting the message with *0#, and so this - application may have a UK specific bodge in the near future to handle - these. - The main changes that are proposed for delivery report handling are :- - * New queues for sent messages, one file for each destination - address and message reference. - * New field in message format, user reference, allowing applications - to tie up their original message with a report. - * Handling of the delivery confirmation/rejection and connecting to - the outgoing message - the received message file would then have - fields for the original outgoing message and user reference - allowing applications to handle confirmations better. diff --git a/doc/README.asterisk.conf b/doc/README.asterisk.conf deleted file mode 100644 index 4e210aacd..000000000 --- a/doc/README.asterisk.conf +++ /dev/null @@ -1,76 +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 directoriess 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) -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 on log entries to console (-T) -runuser = asterisk ; User to run asterisk as (-U) NOTE: will require changes to - ; directory and device permisions -rungroup = asterisk ; Group to run asterisk as (-G) - -;These options have no command line equivalent -cache_record_files = yes | no ; Cache record() files in another directory until completion -record_cache_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 - -[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 diff --git a/doc/README.backtrace b/doc/README.backtrace deleted file mode 100644 index 64d30a357..000000000 --- a/doc/README.backtrace +++ /dev/null @@ -1,187 +0,0 @@ -This document is to provide information on how to obtain the -backtraces required on the asterisk bug tracker, available at -http://bugs.digium.com. The information is required by developers to -help fix problem with bugs of any kind. Backtraces provide information -about what was wrong when a program crashed; in our case, -Asterisk. There are two kind of backtraces (aka 'bt'), which are -useful: bt and bt full. - -First of all, when you start Asterisk, you MUST start it with option --g (this tells Asterisk to produce a core file if it crashes). - -If you start Asterisk with the safe_asterisk script, it automatically -starts using the option -g. - -If you're not sure if Asterisk is running with the -g option, type the -following command in your shell: - -debian:/tmp# ps aux | grep asterisk -root 17832 0.0 1.2 2348 788 pts/1 S Aug12 0:00 /bin/sh /usr/sbin/safe_asterisk -root 26686 0.0 2.8 15544 1744 pts/1 S Aug13 0:02 asterisk -vvvg -c -[...] - -The interesting information is located in the last column. - -Second, your copy of Asterisk must have been built without -optimization or the backtrace will be (nearly) unusable. This can be -done by using 'make dont-optimize' intead of 'make install' to build -and install the Asterisk binary and modules. - -After Asterisk crashes, a core file will be "dumped" in your /tmp/ -directory. To make sure it's really there, you can just type the -following command in your shell: - -debian:/tmp# ls -l /tmp/core.* --rw------- 1 root root 10592256 Aug 12 19:40 /tmp/core.26252 --rw------- 1 root root 9924608 Aug 12 20:12 /tmp/core.26340 --rw------- 1 root root 10862592 Aug 12 20:14 /tmp/core.26374 --rw------- 1 root root 9105408 Aug 12 20:19 /tmp/core.26426 --rw------- 1 root root 9441280 Aug 12 20:20 /tmp/core.26462 --rw------- 1 root root 8331264 Aug 13 00:32 /tmp/core.26647 -debian:/tmp# - -Now that we've verified the core file has been written to disk, the -final part is to extract 'bt' from the core file. Core files are -pretty big, don't be scared, it's normal. - -*** NOTE: Don't attach core files on the bug tracker, we only need the bt and bt full. *** - -For extraction, we use a really nice tool, called gdb. To verify that -you have gdb installed on your system: - -debian:/tmp# gdb -v -GNU gdb 6.3-debian -Copyright 2004 Free Software Foundation, Inc. -GDB is free software, covered by the GNU General Public License, and you are -welcome to change it and/or distribute copies of it under certain conditions. -Type "show copying" to see the conditions. -There is absolutely no warranty for GDB. Type "show warranty" for details. -This GDB was configured as "i386-linux". -debian:/tmp# - -Which is great, we can continue. If you don't have gdb installed, go install gdb. - -Now load the core file in gdb, as follows: - -debian:/tmp# gdb -se "asterisk" -c /tmp/core.26252 -[...] -(You would see a lot of output here.) -[...] -Reading symbols from /usr/lib/asterisk/modules/app_externalivr.so...done. -Loaded symbols for /usr/lib/asterisk/modules/app_externalivr.so -#0 0x29b45d7e in ?? () -(gdb) - -Now at the gdb prompt, type: bt -You would see output similar to: -(gdb) bt -#0 0x29b45d7e in ?? () -#1 0x08180bf8 in ?? () -#2 0xbcdffa58 in ?? () -#3 0x08180bf8 in ?? () -#4 0xbcdffa60 in ?? () -#5 0x08180bf8 in ?? () -#6 0x180bf894 in ?? () -#7 0x0bf80008 in ?? () -#8 0x180b0818 in ?? () -#9 0x08068008 in ast_stopstream (tmp=0x40758d38) at file.c:180 -#10 0x000000a0 in ?? () -#11 0x000000a0 in ?? () -#12 0x00000000 in ?? () -#13 0x407513c3 in confcall_careful_stream (conf=0x8180bf8, filename=0x8181de8 "Zap/pseudo-1324221520") at app_meetme.c:262 -#14 0x40751332 in streamconfthread (args=0x8180bf8) at app_meetme.c:1965 -#15 0xbcdffbe0 in ?? () -#16 0x40028e51 in pthread_start_thread () from /lib/libpthread.so.0 -#17 0x401ec92a in clone () from /lib/libc.so.6 -(gdb) - - -The bt's output is the information that we need on the bug tracker. - -Now do a bt full as follows: -(gdb) bt full -#0 0x29b45d7e in ?? () -No symbol table info available. -#1 0x08180bf8 in ?? () -No symbol table info available. -#2 0xbcdffa58 in ?? () -No symbol table info available. -#3 0x08180bf8 in ?? () -No symbol table info available. -#4 0xbcdffa60 in ?? () -No symbol table info available. -#5 0x08180bf8 in ?? () -No symbol table info available. -#6 0x180bf894 in ?? () -No symbol table info available. -#7 0x0bf80008 in ?? () -No symbol table info available. -#8 0x180b0818 in ?? () -No symbol table info available. -#9 0x08068008 in ast_stopstream (tmp=0x40758d38) at file.c:180 -No locals. -#10 0x000000a0 in ?? () -No symbol table info available. -#11 0x000000a0 in ?? () -No symbol table info available. -#12 0x00000000 in ?? () -No symbol table info available. -#13 0x407513c3 in confcall_careful_stream (conf=0x8180bf8, filename=0x8181de8 "Zap/pseudo-1324221520") at app_meetme.c:262 - f = (struct ast_frame *) 0x8180bf8 - trans = (struct ast_trans_pvt *) 0x0 -#14 0x40751332 in streamconfthread (args=0x8180bf8) at app_meetme.c:1965 -No locals. -#15 0xbcdffbe0 in ?? () -No symbol table info available. -#16 0x40028e51 in pthread_start_thread () from /lib/libpthread.so.0 -No symbol table info available. -#17 0x401ec92a in clone () from /lib/libc.so.6 -No symbol table info available. -(gdb) - -We also need gdb's output. That output gives more details compared to -the simple "bt". So we recommend that you use bt full instead of bt. -But, if you could include both, we appreciate that. - -The final "extraction" would the to know all traces by all -threads. Even if asterisk runs on the same thread for each calls, it -could have some new threads created. - -To make sure we have the correct informations, just do: -(gdb) thread apply all bt - -Thread 1 (process 26252): -#0 0x29b45d7e in ?? () -#1 0x08180bf8 in ?? () -#2 0xbcdffa58 in ?? () -#3 0x08180bf8 in ?? () -#4 0xbcdffa60 in ?? () -#5 0x08180bf8 in ?? () -#6 0x180bf894 in ?? () -#7 0x0bf80008 in ?? () -#8 0x180b0818 in ?? () -#9 0x08068008 in ast_stopstream (tmp=0x40758d38) at file.c:180 -#10 0x000000a0 in ?? () -#11 0x000000a0 in ?? () -#12 0x00000000 in ?? () -#13 0x407513c3 in confcall_careful_stream (conf=0x8180bf8, filename=0x8181de8 "Zap/pseudo-1324221520") at app_meetme.c:262 -#14 0x40751332 in streamconfthread (args=0x8180bf8) at app_meetme.c:1965 -#15 0xbcdffbe0 in ?? () -#16 0x40028e51 in pthread_start_thread () from /lib/libpthread.so.0 -#17 0x401ec92a in clone () from /lib/libc.so.6 -(gdb) - - -That output tell us crucial informations for threads. - -Now, just create a output.txt and dump your "bt full" (and/or "bt") -AND with "thread apply all bt". - -Note: Please ATTACH your output, DO NOT paste it as a note. - -And you're ready for upload on bug tracker. - - -Questions or comments regarding this documentation, feel free to pass -by #asterisk-bugs on FreeNode. - diff --git a/doc/README.callingpres b/doc/README.callingpres deleted file mode 100644 index 0fa1ff469..000000000 --- a/doc/README.callingpres +++ /dev/null @@ -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 diff --git a/doc/README.cdr b/doc/README.cdr deleted file mode 100644 index b3f60a733..000000000 --- a/doc/README.cdr +++ /dev/null @@ -1,120 +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 README.tds 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 - - -ONE IMPORTANT NOTE: If you are trying to collect records on IAX to IAX calls -you need to be aware that by default, IAX will attempt to transfer calls -in this situation (if DTMF is not required). When the transfer is completed -the call is dumped from the middle machine and thus the call detail records -will report a short call time. If you want detailed records you must -turn off IAX transfer, but unless your servers are very close together, you -will definitely get a latency hit from doing so. - -____________________________________ -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). - -______________________________ -cdr_csv2 ------------------------------- - -This module is an experimental new cdr module to demonstrate the cdr vars. -usage( - -*) Create a file called cdr.conf and place it in your /etc/asterisk (or wherever your config files are) in the [cdr_csv2] section. -*) Add an entry called format to indicate any format you want for the output. - -The following format string will emulate the regular cdr file format: -[cdr_csv2] - -format => "${CDR(clid)}","${CDR(src)}","${CDR(dst)}","${CDR(dcontext)}","${CDR(channel)}","${CDR(dstchannel)}","${CDR(lastapp)}","${CDR(lastdata)}","${CDR(start)}","${CDR(answer)}","${CDR(end)}","${CDR(duration)}","${CDR(billsec)}","${CDR(disposition)}","${CDR(amaflags)}","${CDR(accountcode)}","${CDR(uniqueid)}","${CDR(userfield)}" - -You can put anything you want as the value of format incuding new cdr vars you make up or any global variables. - diff --git a/doc/README.channels b/doc/README.channels deleted file mode 100644 index b907a92aa..000000000 --- a/doc/README.channels +++ /dev/null @@ -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 diff --git a/doc/README.cliprompt b/doc/README.cliprompt deleted file mode 100644 index 281d3df5f..000000000 --- a/doc/README.cliprompt +++ /dev/null @@ -1,28 +0,0 @@ -* Changing the CLI Prompt -------------------------- - -The CLI prompt is set with the ASTERISK_PROMPT UNIX environment variable that -you set from the Unix shell before starting Asterisk - -You may include the following variables, that will be replaced by -the current value by Asterisk: - -%d Date (year-month-date) -%h Full hostname -%H Short hostname -%t Time -%% Percent sign -%# '#' if Asterisk is run in console mode, '>' if running as remote console -%Cn[;n] Change terminal foreground (and optional background) color to specified - A full list of colors may be found in include/asterisk/term.h - -On Linux systems, you may also use -%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 diff --git a/doc/README.configuration b/doc/README.configuration deleted file mode 100644 index 60a077a32..000000000 --- a/doc/README.configuration +++ /dev/null @@ -1,180 +0,0 @@ -Asterisk Configuration Parser (version 1.1 and later) ------------------------------------------------------ - -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 -addition to the realtime architecture, we now have the ability to create -templates in configuration files, and use these as templates when we -configure phones, voicemail accounts and queues. - -These changes are general to the configuration parser, and works in -all configuration files. - -General syntax --------------- -Asterisk configuration files are defined as follows: - - [section] - label = value - label2 = value - -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: - - [section] - label1 = value1 - label2 = value2 - object => name - - label3 = value3 - label2 = value4 - object2 => name2 - -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 - [section](options) - label = value - -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 --------- -All lines that starts with semi-colon ";" is treated as comments -and is not parsed. - -The ";--" is a marker for a multi-line comment. Everything after -that marker will be treated as a comment until the end-marker "--;" -is found. Parsing begins directly after the end-marker. - - ;This is a comment - label = value - ;-- This is - a comment --; - - ;-- Comment --; exten=> 1000,1,dial(SIP/lisa) - -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 occured. - - #include myusers.conf - -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: - [options] - execincludes=yes - -The exec directive is used like this: - - #exec /usr/local/bin/myasteriskconfigurator.sh - -Adding to an existing section ------------------------------ - - [section] - label = value - - [section](+) - label2 = value2 - -In this case, the plus sign indicates that the second section (with the -same name) is an addition to the first section. The second section can -be in another file (by using the #include statement). If the section -name referred to before the plus is missing, the configuration will fail -to load. - -Defining a template-only section --------------------------------- - [section](!) - label = value - -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) -------------------------------------------------- - [section](name[,name]) - label = value - -The name within the parenthesis refers to other sections, either -templates or standard sections. The referred sections are included -before the configuration engine parses the local settings within the -section as though their entire contents (and anything they were -previously based upon) were included in the new section. For example -consider the following: - -[foo] -permit=192.168.0.2 -host=asdf -deny=192.168.0.1 - -[bar] -permit=192.168.1.2 -host=jkl -deny=192.168.1.1 - -[baz](foo,bar) -permit=192.168.3.1 -host=bnm - -The [baz] section will be processed as though it had been written in the -following way: - -[baz] -permit=192.168.0.2 -host=asdf -deny=192.168.0.1 -permit=192.168.1.2 -host=jkl -deny=192.168.1.1 -permit=192.168.3.1 -host=bnm - -Additional Examples: --------------------- - -(in top-level sip.conf) - -[defaults](!) -type=friend -nat=yes -qualify=on -dtmfmode=rfc2833 -disallow=all -allow=alaw - -#include accounts/*/sip.conf - -(in accounts/customer1/sip.conf) - -[def-customer1](!,defaults) -secret=this_is_not_secret -context=from-customer1 -callerid=Customer 1 <300> -accountcode=0001 - -[phone1](def-customer1) -mailbox=phone1@customer1 - -[phone2](def-customer1) -mailbox=phone2@customer1 - -This example defines two phones - phone1 and phone2 with settings -inherited from "def-customer1". The "def-customer1" is a template that -inherits from "defaults", which also is a template. - - diff --git a/doc/README.cygwin b/doc/README.cygwin deleted file mode 100644 index fa1f7845d..000000000 --- a/doc/README.cygwin +++ /dev/null @@ -1,7 +0,0 @@ -Cygwin support is completely experimental and usupported 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 - diff --git a/doc/README.dundi b/doc/README.dundi deleted file mode 100644 index 89c8d24a1..000000000 --- a/doc/README.dundi +++ /dev/null @@ -1,26 +0,0 @@ -Distributed Universal Number Directory (DUNDi) (tm) -=================================================== -http://www.dundi.com -Mark Spencer, Digium, Inc. - -DUNDi is essentially a trusted, peer-to-peer system for being able to -call any phone number from the Internet. DUNDi works by creating a -network of nodes called the "DUNDi E.164 Trust Group" which are bound by -a common peering agreement known as the General Peering Agreement or -GPA. The GPA legally binds the members of the Trust Group to provide -good-faith accurate information to the other nodes on the network, and -provides standards by which the community can insure the integrity of -the information on the nodes themselves. Unlike ENUM or similar -systems, DUNDi is explicitly designed to preclude any necessity for a -single centralized system which could be a source of fees, regulation, -etc. - -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 incuring a risk of a single point of failure. In this way, -administrators can locally add extensions which become immediately -available to the other nodes in the system. - -For more information visit http://www.dundi.com diff --git a/doc/README.enum b/doc/README.enum deleted file mode 100644 index ba8484749..000000000 --- a/doc/README.enum +++ /dev/null @@ -1,306 +0,0 @@ -README.enum - -2005-09-06 -jtodd@loligo.com - -The ENUMLOOKUP function is more complex than it first may appear, and -this guide is to give a general overview and set of examples that may -be well-suited for the advanced user to evaluate in their -consideration of ENUM or ENUM-like lookup strategies. This document -assumes a familiarity with ENUM (RFC3761) or ENUM-like methods, as -well as familiarity with NAPTR DNS records (RFC2915, RFC3401-3404). -For an overview of NAPTR records, and the use of NAPTRs in the ENUM -global phone-number-to-DNS mapping scheme, please see -http://www.voip-info.org/tiki-index.php?page=ENUM for more detail. - -Using ENUM within Asterisk can be simple or complex, depending on how -many failover methods and redundancy procedures you wish to utilize. -Implementation of ENUM paths is supposedly defined by the person -creating the NAPTR records, but the local administrator may choose to -ignore certain NAPTR response methods (URI types) or prefer some over -others, which is in contradiction to the RFC. The ENUMLOOKUP method -simply provides administrators a method for determining NAPTR results -in either the globally unique ENUM (e164.arpa) DNS tree, or in other -ENUM-like DNS trees which are not globally unique. The methods to -actually create channels ("dial") results given by the ENUMLOOKUP -function is then up to the administrator to implement in a way that -best suits their environment. - -Function: ENUMLOOKUP([,pointer_type[,options[,zone_suffix]]]) - - Performs an ENUM tree lookup on the specified number, method type, - and (optionally) ordinal 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 - -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. - -service_type = tel, sip, h323, iax2, mailto, ...[any other string], - ALL. Default type is "sip". - Special name of "ALL" will create a list of method types across - all NAPTR records for the search number, and then put the results - in an ordinal list starting with 1. The position - specified will then be returned, starting with 1 as the first - record (lowest value) in the list. The service types are not - hardcoded in Asterisk except for the default (sip) if no other - service type specified; any method type string (IANA-approved or - not) may be used except for the string "ALL". - -options = optional specifiers. - c = count. Returns the number of records of this type are returned - (regardless of order or priority.) If "ALL" is the specified - service_type, then a count of all methods will be returned for the - DNS record. - = The record in priority/order sequence based on the - total count of records passed back by the query. If a service_type - is specified, all entries of that type will be sorted into an - ordinal list starting with 1 (by order first, then priority). - The default of is "1" - -zone_suffix = allows customization of the ENUM zone. Default is e164.arpa. - - -EXAMPLE USES: - -Let's use this ENUM list as an example (note that these examples exist -in the DNS, and will hopefully remain in place as example -destinations, but they may change or become invalid over time. The -end result URIs are not guaranteed to actually work, since some of -these hostnames or SIP proxies are imaginary. Of course, the tel: -replies go to directory assistance for New York City and San -Francisco...) Also note that the complex SIP NAPTR at weight 30 will -strip off the leading "+" from the dialed string if it exists. This -is probably a better NAPTR than hard-coding the number into the NAPTR, -and it is included as a more complex regexp example, though other -simpler NAPTRs will work just as well. - - -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!" . - -Example 1: Simplest case, using first SIP return (use all defaults -except for domain name) -exten => 100,1,Set(foo=${ENUMLOOKUP(+13015611020,,,loligo.com)}) - returns: ${foo}="2203@sip.fox-den.com" - -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) -exten => 100,1,Set(foo=${ENUMLOOKUP(+13015611020,tel,,loligo.com)}) - returns: ${foo}="+12125551212" - -Example 3: How many "sip" pointer type entries are there for this number? -exten => 100,1,Set(foo=${ENUMLOOKUP(+13015611020,sip,c,loligo.com)}) - returns: ${foo}=3 - -Example 4: For all the "tel" pointer type entries, what is the second -one in the list? (after sorting by preference) -exten => 100,1,Set(foo=${ENUMLOOKUP(+13015611020,tel,2,loligo.com)}) - returns: ${foo}="+14155551212" - -Example 5: How many NAPTRs (tel, sip, mailto, etc.) are in the list for this number? -exten => 100,1,Set(foo=${ENUMLOOKUP(+13015611020,ALL,c,loligo.com)}) - returns: ${foo}=6 - -Example 6: Give back the second full URI in the sorted list of all NAPTR URIs: -exten => 100,1,Set(foo=${ENUMLOOKUP(+13015611020,ALL,2,loligo.com)}) - returns: ${foo}="tel:+14155551212" [note the "tel:" prefix in the string] - -Example 7: Look up first SIP entry for the number in the e164.arpa zone (all defaults) -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] - - -Example 8: Look up the ISN mapping in freenum.org alpha test zone -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] - -Example 9: Give back the first SIP pointer for a number in the -enum.yoydynelabs.com zone (invalid lookup) -exten => 100,1,Set(foo=${ENUMLOOKUP(1234567890,sip,1,enum.yoyodynelabs.com)}) - returns: ${foo}="" - - -Usage notes and subtle features: - - a) The use of "+" in lookups is confusing, and warrants further - explanation. All E.164 numbers ("global phone numbers") by - definition need a leading "+" during ENUM lookup. If you neglect to - add a leading "+", you may discover that numbers that seem to exist - in the DNS aren't getting matched by the system or are returned with - a null string result. This is due to the NAPTR reply requiring a - "+" in the regular expression matching sequence. Older versions of - Asterisk add a "+" from within the code, which may confuse - administrators converting to the new function. Please ensure that - all ENUM (e164.arpa) lookups contain a leading "+" before lookup, so - ensure your lookup includes the leading plus sign. Other DNS trees - may or may not require a leading "+" - check before using those - trees, as it is possible the parsed NAPTRs will not provide correct - results unless you have the correct dialed string. If you get - console messages like "WARNING[24907]: enum.c:222 parse_naptr: NAPTR - Regex match failed." then it is very possible that the returned - NAPTR expects a leading "+" in the search string (or the returned - NAPTR is mis-formed.) - - b) If a query is performed of type "c" ("count") and let's say you - get back 5 records and then some seconds later a query is made - against record 5 in the list, it may not be the case that the DNS - resolver has the same answers as it did a second or two ago - maybe - there are only 4 records in the list in the newest query. The - resolver should be the canonical storage location for DNS records, - since that is the intent of ENUM. However, some obscure future - cases may have wildly changing NAPTR records within several seconds. - This is a corner case, and probably only worth noting as a very rare - circumstance. (note: I do not object to Asterisk's dnsmgr method of - locally caching DNS replies, but this method needs to honor the TTL - given by the remote zone master. Currently, the ENUMLOOKUP function - does not use the dnsmgr method of caching local DNS replies.) - - c) If you want strict NAPTR value ordering, then it will be - necessary to use the "ALL" method to incrementally step through the - different returned NAPTR pointers. You will need to use string - manipulation to strip off the returned method types, since the - results will look like "sip:12125551212" in the returned value. - This is a non-trivial task, though it is required in order to have - strict RFC compliance and to comply with the desires of the remote - party who is presenting NAPTRs in a particular order for a reason. - - d) Default behavior for the function (even in event of an error) is - to move to the next priority, and the result is a null value. Most - ENUM lookups are going to be failures, and it is the responsibility - of the dialplan administrator to manage error conditions within - their dialplan. This is a change from the old app_enumlookup method - and it's arbitrary priority jumping based on result type or failure. - - e) 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 - 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 - 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 - (depricated) 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 - there are multiple NAPTRs with (as an example) a method of - "E2U+voice:sip" and then another NAPTR in the same DNS record with a - method of ""E2U+sip", the system will treat these both as method - "sip" and they will be separate records from the perspective of the - function. Of course, if both records point to the same URI and have - equal priority/weight (as is often the case) then this will cause no - serious difficulty, but it bears mentioning. - - j) 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. - - -==EXAMPLES== - -All examples below except where noted use "e164.arpa" as the -referenced domain, which is the default domain name for ENUMLOOKUP. -All numbers are assumed to not have a leading "+" as dialed by the -inbound channel, so that character is added where necessary during -ENUMLOOKUP function calls. - -; example 1 -; -; Assumes North American international dialing (011) prefix. -; Look up the first SIP result and send the call there, otherwise -; send the call out a PRI. This is the most simple possible -; ENUM example, but only uses the first SIP reply in the list of -; NAPTR(s). -; -exten => _011.,1,Set(enumresult=${ENUMLOOKUP(+${EXTEN:3})}) -exten => _011.,n,Dial(SIP/${enumlookup}) -exten => _011.,n,Dial(Zap/g1/${EXTEN}) -; -; end example 1 - -; example 2 -; -; Assumes North American international dialing (011) prefix. -; Check to see if there are multiple SIP NAPTRs returned by -; the lookup, and dial each in order. If none work (or none -; exist) then send the call out a PRI, group 1. -; -exten => _011.,1,Set(sipcount=${ENUMLOOKUP(${EXTEN:3},sip,c)}|counter=0) -exten => _011.,n,While($["${counter}"<"${sipcount}"]) -exten => _011.,n,Set(counter=$[${counter}+1]) -exten => _011.,n,Dial(SIP/${ENUMLOOKUP(+${EXTEN:3},sip,${counter})}) -exten => _011.,n,EndWhile -exten => _011.,n,Dial(Zap/g1/${EXTEN}) -; -; end example 2 - -; example 3 -; -; This example expects an ${EXTEN} that is an e.164 number (like -; 14102241145 or 437203001721) -; Search through e164.arpa and then also search through e164.org -; to see if there are any valid SIP or IAX termination capabilities. -; If none, send call out via Zap channel 1. -; -; Start first with e164.arpa zone... -; -exten => _X.,1,Set(sipcount=${ENUMLOOKUP(+${EXTEN},sip,c)}|counter=0) -exten => _X.,2,GotoIf($["${counter}"<"${sipcount}"]?3:6) -exten => _X.,3,Set(counter=$[${counter}+1]) -exten => _X.,4,Dial(SIP/${ENUMLOOKUP(+${EXTEN},sip,${counter})}) -exten => _X.,5,GotoIf($["${counter}"<"${sipcount}"]?3:6) -; -exten => _X.,6,Set(iaxcount=${ENUMLOOKUP(+${EXTEN},iax2,c)}|counter=0) -exten => _X.,7,GotoIf($["${counter}"<"${iaxcount}"]?8:11) -exten => _X.,8,Set(counter=$[${counter}+1]) -exten => _X.,9,Dial(IAX2/${ENUMLOOKUP(+${EXTEN},iax2,${counter})}) -exten => _X.,10,GotoIf($["${counter}"<"${iaxcount}"]?8:11) -; -exten => _X.,11,NoOp("No valid entries in e164.arpa for ${EXTEN} - checking in e164.org") -; -; ...then also try e164.org, and look for SIP and IAX NAPTRs... -; -exten => _X.,12,Set(sipcount=${ENUMLOOKUP(+${EXTEN},sip,c,e164.org)}|counter=0) -exten => _X.,13,GotoIf($["${counter}"<"${sipcount}"]?14:17) -exten => _X.,14,Set(counter=$[${counter}+1]) -exten => _X.,15,Dial(SIP/${ENUMLOOKUP(+${EXTEN},sip,${counter},e164.org)}) -exten => _X.,16,GotoIf($["${counter}"<"${sipcount}"]?14:17) -; -exten => _X.,17,Set(iaxcount=${ENUMLOOKUP(+${EXTEN},iax2,c,e164.org)}|counter=0) -exten => _X.,18,GotoIf($["${counter}"<"${iaxcount}"]?19:22) -exten => _X.,19,Set(counter=$[${counter}+1]) -exten => _X.,20,Dial(IAX2/${ENUMLOOKUP(+${EXTEN},iax2,${counter},e164.org)}) -exten => _X.,21,GotoIf($["${counter}"<"${iaxcount}"]?19:22) -; -; ...then send out PRI. -; -exten => _X.,22,NoOp("No valid entries in e164.org for ${EXTEN} - sending out via Zap") -exten => _X.,23,Dial(Zap/g1/${EXTEN}) -; -; end example 3 diff --git a/doc/README.extconfig b/doc/README.extconfig deleted file mode 100644 index 6b147e573..000000000 --- a/doc/README.extconfig +++ /dev/null @@ -1,85 +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 README.realtime 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. - -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 - diff --git a/doc/README.extensions b/doc/README.extensions deleted file mode 100644 index bab08d319..000000000 --- a/doc/README.extensions +++ /dev/null @@ -1,58 +0,0 @@ -The Asterisk dialplan -===================== - -The Asterisk dialplan is divided into contexts. A context is simply a group -of extensions. For each "line" that should be able to be called, an extension -must be added to a context. Then, you configure the calling "line" to have -access to this context. - -If you change the dialplan, you can use the Asterisk CLI command -"extensions reload" to load the new dialplan without disrupting -service in your PBX. - -Extensions are routed according to priority and may be based on any set -of characters (a-z), digits, #, and *. Please note that when matching a -pattern, "N", "X", and "Z" are interpreted as classes of digits. - -For each extension, several actions may be listed and must be given a unique -priority. When each action completes, the call continunes at the next priority -(except for some modules which use explicitly GOTO's). - -When each action completes, it generally moves to the next priority (except for -some modules which use explicitly GOTO's. - -Extensions frequently have data they pass to the executing application -(most frequently a string). You can see the available dialplan applications -by entering the "show applications" command in the CLI. - -In this version of Asterisk, dialplan functions are added. These can -be used as arguments to any application. For a list of the installed -functions in your Asterisk, use the "show functions" command. - -* Example dial plan - -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 worthwile to read it. - -* 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. - -And finally, the extension context "default" is used when either a) an -extension context is deleted while an extension is in use, or b) a specific -starting extension handler has not been defined (unless overridden by the -low level channel interface). diff --git a/doc/README.externalivr b/doc/README.externalivr deleted file mode 100644 index a1d4757e7..000000000 --- a/doc/README.externalivr +++ /dev/null @@ -1,109 +0,0 @@ -Asterisk External IVR Interface -------------------------------- - -If you load app_externalivr.so in your Asterisk instance, you will -have an ExternalIVR() application available in your dialplan. This -application implements a simple protocol for bidirectional -communication with an external process, while simultaneous playing -audio files to the connected channel (without interruption or -blocking). - -The arguments to ExternalIVR() consist of the command to execute and -any arguments to pass to it, the same as the System() application -accepts. The external command will be executed in a child process, -with its standard file handles connected to the Asterisk process as -follows: - -stdin (0) - DTMF and hangup events will be received on this handle -stdout (1) - Playback and hangup commands can be sent on this handle -stderr (2) - Error messages can be sent on this handle - -The application will also create an audio generator to play audio to -the channel, and will start playing silence. When your application -wants to send audio to the channel, it can send a command (see below) -to add file(s) to the generator's playlist. The generator will then -work its way through the list, playing each file in turn until it -either runs out of files to play, the channel is hung up, or a command -is received to clear the list and start with a new file. At any time, -more files can be added to the list and the generator will play them -in sequence. - -While the generator is playing audio (or silence), any DTMF events -received on the channel will be sent to the child process (see -below). Note that this can happen at any time, since the generator, -the child process and the channel thread are all executing -independently. It is very important that your external application be -ready to receive events from Asterisk at all times (without blocking), -or you could cause the channel to become non-responsive. - -If the child process dies, ExternalIVR() will notice this and hang up -the channel immediately (and also send a message to the log). - -DTMF (and other) events ------------------------ - -All events will be newline-terminated strings. - -Events send to the child's stdin will be in the following format: - -tag,timestamp[,data] - -The tag can be one of the following characters: - -0-9: DTMF event for keys 0 through 9 -A-D: DTMF event for keys A through D -*: DTMF event for key * -#: DTMF event for key # -H: the channel was hung up by the connected party -Z: the previous command was unable to be executed (file does not -exist, etc.) -T: the play list was interrupted (see below) -D: a file was dropped from the play list due to interruption (the -data element will be the dropped file name) -F: a file has finished playing (the data element will be the file -name) - -The timestamp will be 10 digits long, and will be a decimal -representation of a standard Unix epoch-based timestamp. - -Commands --------- - -All commands must be newline-terminated strings. - -The child process can send commands on stdout in the following formats: - -S,filename -A,filename -H,message -O,option - -The 'S' command checks to see if there is a playable audio file with -the specified name, and if so, clear's the generator's playlist and -places the file onto the list. Note that the playability check does -not take into account transcoding requirements, so it is possible for -the file to not be played even though it was found. If the file cannot -be found, a 'Z' event (see above) will be sent to the child. If the -generator is not currently playing silence, then T and D events will -be sent to the child to signal the playlist interruption and notify -it of the files that will not be played. - -The 'A' command checks to see if there is a playable audio file with -the specified name, and if so, adds it to the generator's -playlist. The same playability and exception rules apply as for the -'S' command. - -The 'H' command stops the generator and hangs up the channel, and logs -the supplied message to the Asterisk log. - -The 'O' command allows the child to set/clear options in the -ExternalIVR() application. The supported options are: - autoclear/noautoclear: - Automatically interrupt and clear the playlist upon reception - of DTMF input. - -Errors ------- - -Any newline-terminated output generated by the child process on its -stderr handle will be copied into the Asterisk log. diff --git a/doc/README.h323 b/doc/README.h323 deleted file mode 100644 index 9951f6353..000000000 --- a/doc/README.h323 +++ /dev/null @@ -1,23 +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. - - diff --git a/doc/README.hardware b/doc/README.hardware deleted file mode 100644 index 86b28bef7..000000000 --- a/doc/README.hardware +++ /dev/null @@ -1,70 +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.yahoo.com/asteriskpbx - - * Wildcard X100P - Single FXO interface connects to Loopstart phone - line - - * 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 S100U - Single FXS interface connects to a standard analog - telephone. - - * 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. - - -Miscellaneous other interfaces -============================== - --- ISDN4Linux - http://www.isdn4linux.de/ - - * Any ISDN terminal adapter supported by isdn4linux should provide - connectivity. - --- 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 diff --git a/doc/README.iax b/doc/README.iax deleted file mode 100644 index 1a35d6b15..000000000 --- a/doc/README.iax +++ /dev/null @@ -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 = - -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 = - -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 = -> maxjitterbuffer = -> maxexcessbuffer = - -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 amout of excess jitter buffer - -> accountcode = -> 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 => [:]@[: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/.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 = - -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 = / -> deny = / - -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 = - -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 = - -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/.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 = [|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 = - -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 = - -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 | ] - -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 = [@mailboxcontext] - -Specifies a mailbox to check for voicemail notification. - -> permit = / -> deny = / - -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 diff --git a/doc/README.ices b/doc/README.ices deleted file mode 100644 index d75236357..000000000 --- a/doc/README.ices +++ /dev/null @@ -1,12 +0,0 @@ -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 -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 - -Anyway hope you like it. - -Mark diff --git a/doc/README.jitterbuffer b/doc/README.jitterbuffer deleted file mode 100644 index e5cd81ce0..000000000 --- a/doc/README.jitterbuffer +++ /dev/null @@ -1,137 +0,0 @@ -The new Jitterbuffer in Asterisk --------------------------------- -Steve Kann - - - -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: -------- -The new jitterbuffer detects packet loss. PLC is done to try to recreate these -lost packets in the codec decoding stage, as the encoded audio is translated to slinear. -PLC is also used to mask jitterbuffer growth. - -This facility is enabled by default in iLBC and speex, as it has no additional cost. -This facility can be enabled in adpcm, alaw, g726, gsm, lpc10, and ulaw by setting -genericplc => true in the [plc] section of codecs.conf. - -3) Trunktimestamps: -------------------- -To use this, both sides must be using Asterisk v1.2. -Setting "trunktimestamps=yes" in iax.conf will cause your box to send 16-bit timestamps -for each trunked frame inside of a trunk frame. This will enable you to use jitterbuffer -for an IAX2 trunk, something that was not possible in the old architecture. - -The other side must also support this functionality, or else, well, bad things will happen. -If you don't use trunktimestamps, there's lots of ways the jitterbuffer can get confused because -timestamps aren't necessarily sent through the trunk correctly. - -4) Communication with Asterisk v1.0.x systems ---------------------------------------------- -You can set up communication with v1.0.x systems with the new jitterbuffer, but -you can't use trunks with trunktimestamps in this communication. - -If you are connecting to an Asterisk server with earlier versions of the software (1.0.x), -do not enable both jitterbuffer and trunking for the involved peers/users -in order to be able to communicate. Earlier systems will not support trunktimestamps. - -You may also compile chan_iax2.c without the new jitterbuffer, enabling the old -backwards compatible architecture. Look in the source code for instructions. - - -5) 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 ". This will simulate n percent packet loss -coming _in_ to chan_iax2. You should find that with PLC and the new JB, 10 percent packet -loss should lead to just a tiny amount of distortion, while without PLC, it would lead to -silent gaps in your audio. - -"iax2 show netstats" shows you statistics for each iax2 call you have up. -The columns are "RTT" which is the round-trip time for the last PING, and then a bunch of s -tats for both the local side (what you're receiving), and the remote side (what the other -end is telling us they are seeing). The remote stats may not be complete if the remote -end isn't using the new jitterbuffer. - -The stats shown are: -* 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. - -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. -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 -nonsensical timestamps, it can confuse the jitterbuffer. In particular, discontinuities -in timestamps will really upset it: Things like timestamps sequences which go 0, 20, 40, -60, 80, 34000, 34020, 34040, 34060... It's going to think you've got about 34 seconds -of jitter in this case, etc.. -The right solution to this is to find out what's causing the sender to send us such nonsense, -and fix that. But we should also figure out how to make the receiver more robust in -cases like this. - -chan_iax2 will actually help fix this a bit if it's more than 3 seconds or so, but at -some point we should try to think of a better way to detect this kind of thing and -resynchronize. - -Different clock rates are handled very gracefully though; it will actually deal with a -sender sending 20% faster or slower than you expect just fine. - -3) 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 ] - -Report bugs in the Asterisk bugtracker, http://bugs.digium.com. -Please read the bug guidelines before you post a bug. - -Have fun! - --SteveK diff --git a/doc/README.linkedlists b/doc/README.linkedlists deleted file mode 100644 index 340933548..000000000 --- a/doc/README.linkedlists +++ /dev/null @@ -1,98 +0,0 @@ -As of 2004-12-23, this documentation is no longer maintained. The doxygen documentation -generated from linkedlists.h should be referred to in its place, as it is more complete -and better maintained. - -2nd version, implemented as macros. - - include - -AST_LIST_ENTRY declares pointers inside the object structure : - - struct ast_var_t { - char *name; - char *value; - AST_LIST_ENTRY(ast_var_t) listpointers; - }; - -AST_LIST_HEAD declares a head structure, which is initialized -to AST_LIST_HEAD_NULL : - - AST_LIST_HEAD(head, ast_var_t) head - -Next, we declare a pointer to this structure : - - struct headtype *headp = head; - -AST_LIST_INIT initializes the head pointer to a null value - - AST_LIST_INIT(headp); - -AST_LIST_INSERT_HEAD inserts an element to the head of the list : - - struct ast_var_t *node; - - node=malloc(sizeof(struct ast_var_t)); - (...we fill data in struct....) - data->name=malloc(100); - strcpy(data->name,"lalalalaa"); - etc etc - - (then we insert the node in the head of the list :) - - AST_LIST_INSERT_HEAD(headp,node,listpointers); - -AST_LIST_INSERT_HEAD_AFTER inserts an element after another : - - struct ast_var_t *node1; - ... - AST_LIST_INSERT_AFTER(node,node1,listpointers); - -AST_LIST_REMOVE removes an arbitrary element from the head: - - AST_LIST_REMOVE(headp,node1,ast_var_t,listpointers); - -AST_LIST_REMOVE_HEAD removes the entry at the head of the list and -returns a pointer to the removed entry: - - AST_LIST_REMOVE_HEAD(headp,node,listpointers); - -AST_LIST_FIRST returns a pointer to the first element of the list; - - struct ast_var_t *firstnode; - firstnode=AST_LIST_FIRST(headp); - -AST_LIST_NEXT returns a pointer to the next element : - - struct ast_var_t *nextnode; - nextnode=AST_LIST_NEXT(firstnode,listpointers); - -AST_LIST_TRAVERSE traverses all elements of the list : - - struct ast_var_t *node; - - AST_LIST_TRAVERSE(headp,node,listpointers) { - printf("%s\n",node->name); - } - -AST_LIST_EMPTY evaluates to a true condition if there are no elements on -the list. - -To completely delete a list : - - struct ast_var_t *vardata; - - while (!AST_LIST_EMPTY(headp)) { /* List Deletion. */ - vardata = AST_LIST_REMOVE_HEAD(head, ast_var_t, listpointers); - free(vardata->name); - free(vardata->value); - } - -AST_LIST_LOCK returns true if it can lock the list, AST_LIST_UNLOCK unlocks -the list : - -if (AST_LIST_LOCK(headp)) { - ...do all list operations here... - AST_LIST_UNLOCK(headp); -} else { - ast_log(LOG_WARNING,"List locked bla bla bla\n"); -} diff --git a/doc/README.localchannel b/doc/README.localchannel deleted file mode 100644 index f96ea15ec..000000000 --- a/doc/README.localchannel +++ /dev/null @@ -1,49 +0,0 @@ -The Local channel ------------------ - -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: - - Local/extension@context[/n] - -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: - -The Local channel construct can be used to establish dialing into any part of the dialplan. - -Imagine you have a TE410P in your box. You want to do something for which you must use a Dial statement (for instance when dropping files in /var/spool/outgoing) but you do want to be able to use your dialplans least-cost-routes or other intelligent stuff. What you could do before we had chan_local was create a cross-link between two ports of the TE410P and then Dial out one port and in the other. This way you could control where the call was going. - -Of course, this was a nasty hack, and to make it more sensible, chan_local was built. - -The "Local" channel driver allows you to convert an arbitrary extension into a channel. It is used in a variety of places, including agents, etc. - -This also allows us to hop to contexts like a GoSub routine; See examples below. - -Examples: ---------- - -[inbound] ; here falls all incoming calls -exten => s,1,Answer -exten => s,2,Dial(local/200@internal,30,r) -exten => s,3,Playback(sorrynoanswer) -exten => s,4,Hangup - -[internal] ; here where our phones falls for default -exten => 200,1,Dial(sip/blah) -exten => 200,102,VoiceMail(${EXTEN}@default) - -exten => 201,1,Dial(zap/1) -exten => 201,102,VoiceMail(${EXTEN}@default) - -exten => _0.,1,Dial(Zap/g1/${EXTEN:1}) ; outgoing calls with 0+number - - -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. - - Local/00531234567@pbx becomes Local/00531234567@pbx/n - ----------- -2004-01-17 diff --git a/doc/README.manager b/doc/README.manager deleted file mode 100644 index 065d70a21..000000000 --- a/doc/README.manager +++ /dev/null @@ -1,298 +0,0 @@ -The Asterisk Manager TCP/IP API - AMI -===================================== - -The manager is a client/server model over TCP. With the manager interface, -you'll be able to control the PBX, originate calls, check mailbox status, -monitor channels and queues as well as execute Asterisk commands. - -AMI is the standard management interface into your Asterisk server. -You configure AMI in manager.conf. By default, AMI is available on -TCP port 5038 if you enable it in manager.conf. - -AMI receive commands, called "actions". These generate a "response" -from Asterisk. Asterisk will also send "Events" containing various -information messages about changes within Asterisk. Some actions -generate an initial response and data in the form list of events. -This format is created to make sure that extensive reports do not -block the manager interface fully. - -Management users are configured in the configuration file manager.conf and are -given permissions for read and write, where write represents their ability -to perform this class of "action", and read represents their ability to -receive this class of "event". - -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 -in Actions, Events and Responses as local to that particular -message. There is no cross-message standardization of headers. - -If you develop applications, please try to reuse existing manager -headers and their interpretation. If you are unsure, discuss on -the asterisk-dev mailing list. - - -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 - - -Manager commands ----------------- -Output from the CLI command 'show manager' 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 - -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: 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 " CLI command in Asterisk. - -Examples --------- -Login - Log a user into the manager interface. - - Action: Login - Username: testuser - Secret: testsecret - -Originate - Originate a call from a channel to an extension. - - Action: Originate - Channel: sip/12345 - Exten: 1234 - Context: default - -Originate - Originate a call from a channel to an extension without waiting -for call to complete. - - Action: Originate - Channel: sip/12345 - Exten: 1234 - Context: default - Async: yes - - -Redirect with ExtraChannel: - Attempted goal: - Have a 'robot' program Redirect both ends of an already-connected call - to a meetme room using the ExtraChannel feature through the management interface. - - Action: Redirect - Channel: Zap/1-1 - ExtraChannel: SIP/3064-7e00 (varies) - Exten: 680 - Priority: 1 - -Where 680 is an extension that sends you to a MeetMe room. - -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: --------------------------- - - Account: -- Account Code (Status) - AccountCode: -- Account Code (cdr_manager) - ACL: -- Does ACL exist for object ? - Action: -- request or notification of a particular action - Address-IP: -- IPaddress - Address-Port: -- IP port number - Agent: -- Agent name - AMAflags: -- AMA flag (cdr_manager, sippeers) - AnswerTime: -- Time of answer (cdr_manager) - Append: -- CDR userfield Append flag - Application: -- Application to use - Async: -- Whether or not to use fast setup - AuthType: -- Authentication type (for login or challenge) - "md5" - BillableSeconds: -- Billable seconds for call (cdr_manager) - CallerID: -- Caller id (name and number in Originate & cdr_manager) - CallerID: -- CallerID number - Number or "" or "unknown" - (should change to "" in app_queue) - CallerID1: -- Channel 1 CallerID (Link event) - CallerID2: -- Channel 2 CallerID (Link event) - CallerIDName: -- CallerID name - Name or "" or "unknown" - (should change to "" in app_queue) - Callgroup: -- Call group for peer/user - CallsTaken: -- Queue status variable - Cause: -- Event change cause - "Expired" - Cause: -- Hangupcause (channel.c) - CID-CallingPres: -- Caller ID calling presentation - Channel: -- Channel specifier - Channel: -- Dialstring in Originate - Channel: -- Channel in Registry events (SIP, IAX2) - Channel: -- Technology (SIP/IAX2 etc) in Registry events - ChannelType: -- Tech: SIP, IAX2, ZAP, MGCP etc - Channel1: -- Link channel 1 - Channel2: -- Link channel 2 - ChanObjectType: -- "peer", "user" - Codecs: -- Codec list - CodecOrder: -- Codec order, separated with comma "," - Command: -- Cli command to run - Context: -- Context - Count: -- Number of callers in queue - Data: -- Application data - Default-addr-IP: -- IP address to use before registration - Default-Username: -- Username part of URI to use before registration - Destination: -- Destination for call (Dialstring ) (dial, cdr_manager) - DestinationContext: -- Destination context (cdr_manager) - DestinationChannel: -- Destination channel (cdr_manager) - DestUniqueID: -- UniqueID of destination (dial event) - Disposition: -- Call disposition (CDR manager) - Domain: -- DNS domain - Duration: -- Duration of call (cdr_manager) - Dynamic: -- Device registration supported? - Endtime: -- End time stamp of call (cdr_manager) - EventList: -- Flag being "Start", "End", "Cancelled" or "ListObject" - Events: -- Eventmask filter ("on", "off", "system", "call", "log") - Exten: -- Extension (Redirect command) - Extension: -- Extension (Status) - Family: -- ASTdb key family - File: -- Filename (monitor) - Format: -- Format of sound file (monitor) - From: