diff options
Diffstat (limited to '1.4.23-rc4/doc')
71 files changed, 12391 insertions, 0 deletions
diff --git a/1.4.23-rc4/doc/00README.1st b/1.4.23-rc4/doc/00README.1st new file mode 100644 index 000000000..ef4b326a7 --- /dev/null +++ b/1.4.23-rc4/doc/00README.1st @@ -0,0 +1,75 @@ +Files in the /doc directory: +---------------------------- +In addition to these files, there is a lot of documentation of various +configuration options in the sample configuration files, in the /configs +directory of your source code + +Start here +---------- +security.txt IMPORTANT INFORMATION ABOUT ASTERISK SECURITY +hardware.txt Hardware supported by Asterisk +cli.txt Information on using the Asterisk console + +Configuration +------------- +configuration.txt Features in the configuration parser +extensions.txt Basics about the dialplan +extconfig.txt How to use databases for configuration of Asterisk (ARA) +ip-tos.txt About the IP Type Of Service settings +realtime.txt The Asterisk Realtime Architecture - database support +freetds.txt Information about the FreeTDS support +ael.txt Information about the Asterisk Extension Language + +Misc +---- +PEERING The General Peering Agreement for Dundi +ajam.txt About the HTTP-based manager interface +app_sms.txt How to configure the SMS application +asterisk.conf.txt Documentation of various options in asterisk.conf +callingpres.txt Settings for Caller ID presentation +billing.txt Call Data Record information +cliprompt.txt How to change the Asterisk CLI prompt +dundi.txt Dundi - a discovery protocol +enum.txt Enum support in Asterisk +ices.txt Integrating ICEcast streaming in Asterisk +jitterbuffer.txt About the IAX2 jitterbuffer implementation +math.txt About the math() application +mp3.txt About MP3 support in Asterisk +musiconhold-fpm.txt Free Music On Hold music +mysql.txt About MYSQL support in Asterisk +odbcstorage.txt Voicemail storage of messages in UnixODBC +privacy.txt Privacy enhancements in Asterisk +queuelog.txt Agent and queue logging +channelvariables.txt Channel variables +cdrdrivers.txt About CDR storage in various databases (needs update) +asterisk-mib.txt SNMP mib for Asterisk (net-snmp) +digium-mib.txt SNMP mib for Asterisk (net-snmp) + +Channel drivers +--------------- +misdn.txt The mISDN channel driver for ISDN BRI cards +h323.txt How to compile and configure the H.323 channel +chaniax.txt About the IAX2 protocol support in Asterisk +localchannel.txt The local channel is a "gosub" in the dialplan + +Portability +----------- +cygwin.txt Compiling Asterisk on CygWin platforms (Windows) + +For developers +-------------- +See http://www.asterisk.org/developers for more information + +manager.txt About the AMI - Asterisk Manager Interface + for third party call control and PBX management +backtrace.txt How to produce a backtrace when Asterisk crashes +CODING-GUIDELINES Guidelines for developers +channels.txt What is a channel? +externalivr.txt Documentation of the protocol used in externalivr() +linkedlists.txt How to develop linked lists in Asterisk (old) +iax.txt About the IAX protocol +apps.txt About application development +model.txt About the call model in Asterisk (old) +modules.txt How Asterisk modules work +datastores.txt About channel data stores +speechrec.txt The Generic Speech Recognition API diff --git a/1.4.23-rc4/doc/CODING-GUIDELINES b/1.4.23-rc4/doc/CODING-GUIDELINES new file mode 100644 index 000000000..c3ffacd3c --- /dev/null +++ b/1.4.23-rc4/doc/CODING-GUIDELINES @@ -0,0 +1,543 @@ +== Asterisk Patch/Coding Guidelines == +-------------------------------------- + +We are looking forward to your contributions to Asterisk - the +Open Source PBX! As Asterisk is a large and in some parts very +time-sensitive application, the code base needs to conform to +a common set of coding rules so that many developers can enhance +and maintain the code. Code also needs to be reviewed and tested +so that it works and follows the general architecture and guide- +lines, and is well documented. + +Asterisk is published under a dual-licensing scheme by Digium. +To be accepted into the codebase, all non-trivial changes must be +disclaimed to Digium or placed in the public domain. For more information +see http://bugs.digium.com + +Patches should be in the form of a unified (-u) diff, made from a checkout +from subversion. + +/usr/src/asterisk$ svn diff > mypatch + +If you would like to only include changes to certain files in the patch, you +can list them in the "svn diff" command: + +/usr/src/asterisk$ svn diff somefile.c someotherfile.c > mypatch + +* General rules +--------------- + +- All code, filenames, function names and comments must be in ENGLISH. + +- Don't annotate your changes with comments like "/* JMG 4/20/04 */"; + Comments should explain what the code does, not when something was changed + or who changed it. If you have done a larger contribution, make sure + that you are added to the CREDITS file. + +- Don't make unnecessary whitespace changes throughout the code. + If you make changes, submit them to the tracker as separate patches + that only include whitespace and formatting changes. + +- Don't use C++ type (//) comments. + +- Try to match the existing formatting of the file you are working on. + +- Use spaces instead of tabs when aligning in-line comments or #defines (this makes + your comments aligned even if the code is viewed with another tabsize) + +* Declaration of functions and variables +---------------------------------------- + +- Do not declare variables mid-block (e.g. like recent GNU compilers support) + since it is harder to read and not portable to GCC 2.95 and others. + +- Functions and variables that are not intended to be used outside the module + must be declared static. + +- When reading integer numeric input with scanf (or variants), do _NOT_ use '%i' + unless you specifically want to allow non-base-10 input; '%d' is always a better + choice, since it will not silently turn numbers with leading zeros into base-8. + +- Strings that are coming from input should not be used as a first argument to + a formatted *printf function. + +* Use the internal API +---------------------- + +- Make sure you are aware of the string and data handling functions that exist + within Asterisk to enhance portability and in some cases to produce more + secure and thread-safe code. Check utils.c/utils.h for these. + + +* Code formatting +----------------- + +Roughly, Asterisk code formatting guidelines are generally equivalent to the +following: + +# indent -i4 -ts4 -br -brs -cdw -lp -ce -nbfda -npcs -nprs -npsl -nbbo -saf -sai -saw -cs -l90 foo.c + +this means in verbose: + -i4: indent level 4 + -ts4: tab size 4 + -br: braces on if line + -brs: braces on struct decl line + -cdw: cuddle do while + -lp: line up continuation below parenthesis + -ce: cuddle else + -nbfda: dont break function decl args + -npcs: no space after function call names + -nprs: no space after parentheses + -npsl: dont break procedure type + -saf: space after for + -sai: space after if + -saw: space after while + -cs: space after cast + -ln90: line length 90 columns + +Function calls and arguments should be spaced in a consistent way across +the codebase. + GOOD: foo(arg1, arg2); + GOOD: foo(arg1,arg2); /* Acceptable but not preferred */ + BAD: foo (arg1, arg2); + BAD: foo( arg1, arg2 ); + BAD: foo(arg1, arg2,arg3); + +Don't treat keywords (if, while, do, return) as if they were functions; +leave space between the keyword and the expression used (if any). For 'return', +don't even put parentheses around the expression, since they are not +required. + +There is no shortage of whitespace characters :-) Use them when they make +the code easier to read. For example: + + for (str=foo;str;str=str->next) + +is harder to read than + + for (str = foo; str; str = str->next) + +Following are examples of how code should be formatted. + +- Functions: +int foo(int a, char *s) +{ + return 0; +} + +- If statements: +if (foo) { + bar(); +} else { + blah(); +} + +- Case statements: +switch (foo) { +case BAR: + blah(); + break; +case OTHER: + other(); + break; +} + +- No nested statements without braces, e.g.: + +for (x = 0; x < 5; x++) + if (foo) + if (bar) + baz(); + +instead do: +for (x = 0; x < 5; x++) { + if (foo) { + if (bar) + baz(); + } +} + +- Don't build code like this: + +if (foo) { + /* .... 50 lines of code ... */ +} else { + result = 0; + return; +} + +Instead, try to minimize the number of lines of code that need to be +indented, by only indenting the shortest case of the 'if' +statement, like so: + +if (!foo) { + result = 0; + return; +} + +.... 50 lines of code .... + +When this technique is used properly, it makes functions much easier to read +and follow, especially those with more than one or two 'setup' operations +that must succeed for the rest of the function to be able to execute. + +- Labels/goto are acceptable +Proper use of this technique may occasionally result in the need for a +label/goto combination so that error/failure conditions can exit the +function while still performing proper cleanup. This is not a bad thing! +Use of goto in this situation is encouraged, since it removes the need +for excess code indenting without requiring duplication of cleanup code. + +- Never use an uninitialized variable +Make sure you never use an uninitialized variable. The compiler will +usually warn you if you do so. However, do not go too far the other way, +and needlessly initialize variables that do not require it. If the first +time you use a variable in a function is to store a value there, then +initializing it at declaration is pointless, and will generate extra +object code and data in the resulting binary with no purpose. When in doubt, +trust the compiler to tell you when you need to initialize a variable; +if it does not warn you, initialization is not needed. + +- Do not cast 'void *' +Do not explicitly cast 'void *' into any other type, nor should you cast any +other type into 'void *'. Implicit casts to/from 'void *' are explicitly +allowed by the C specification. This means the results of malloc(), calloc(), +alloca(), and similar functions do not _ever_ need to be cast to a specific +type, and when you are passing a pointer to (for example) a callback function +that accepts a 'void *' you do not need to cast into that type. + +* Variable naming +----------------- + +- Global variables +Name global variables (or local variables when you have a lot of them or +are in a long function) something that will make sense to aliens who +find your code in 100 years. All variable names should be in lower +case, except when following external APIs or specifications that normally +use upper- or mixed-case variable names; in that situation, it is +preferable to follow the external API/specification for ease of +understanding. + +Make some indication in the name of global variables which represent +options that they are in fact intended to be global. + e.g.: static char global_something[80] + +- Don't use un-necessary typedef's +Don't use 'typedef' just to shorten the amount of typing; there is no substantial +benefit in this: + +struct foo { + int bar; +}; +typedef struct foo foo_t; + +In fact, don't use 'variable type' suffixes at all; it's much preferable to +just type 'struct foo' rather than 'foo_s'. + +- Use enums instead of #define where possible +Use enums rather than long lists of #define-d numeric constants when possible; +this allows structure members, local variables and function arguments to +be declared as using the enum's type. For example: + +enum option { + OPT_FOO = 1 + OPT_BAR = 2 + OPT_BAZ = 4 +}; + +static enum option global_option; + +static handle_option(const enum option opt) +{ + ... +} + +Note: The compiler will _not_ force you to pass an entry from the enum +as an argument to this function; this recommendation serves only to make +the code clearer and somewhat self-documenting. In addition, when using +switch/case blocks that switch on enum values, the compiler will warn +you if you forget to handle one or more of the enum values, which can be +handy. + +* String handling +----------------- + +Don't use strncpy for copying whole strings; it does not guarantee that the +output buffer will be null-terminated. Use ast_copy_string instead, which +is also slightly more efficient (and allows passing the actual buffer +size, which makes the code clearer). + +Don't use ast_copy_string (or any length-limited copy function) for copying +fixed (known at compile time) strings into buffers, if the buffer is something +that has been allocated in the function doing the copying. In that case, you +know at the time you are writing the code whether the buffer is large enough +for the fixed string or not, and if it's not, your code won't work anyway! +Use strcpy() for this operation, or directly set the first two characters +of the buffer if you are just trying to store a one-character string in the +buffer. If you are trying to 'empty' the buffer, just store a single +NULL character ('\0') in the first byte of the buffer; nothing else is +needed, and any other method is wasteful. + +In addition, if the previous operations in the function have already +determined that the buffer in use is adequately sized to hold the string +you wish to put into it (even if you did not allocate the buffer yourself), +use a direct strcpy(), as it can be inlined and optimized to simple +processor operations, unlike ast_copy_string(). + +* Use of functions +------------------ + +When making applications, always ast_strdupa(data) to a local pointer if +you intend to parse the incoming data string. + + if (data) + mydata = ast_strdupa(data); + + +- Separating arguments to dialplan applications and functions +Use ast_app_separate_args() to separate the arguments to your application +once you have made a local copy of the string. + +- Parsing strings with strsep +Use strsep() for parsing strings when possible; there is no worry about +'re-entrancy' as with strtok(), and even though it modifies the original +string (which the man page warns about), in many cases that is exactly +what you want! + +- Create generic code! +If you do the same or a similar operation more than one time, make it a +function or macro. + +Make sure you are not duplicating any functionality already found in an +API call somewhere. If you are duplicating functionality found in +another static function, consider the value of creating a new API call +which can be shared. + +* Handling of pointers and allocations +-------------------------------------- + +- Dereference or localize pointers +Always dereference or localize pointers to things that are not yours like +channel members in a channel that is not associated with the current +thread and for which you do not have a lock. + channame = ast_strdupa(otherchan->name); + +- Use const on pointer arguments if possible +Use const on pointer arguments which your function will not be modifying, as this +allows the compiler to make certain optimizations. In general, use 'const' +on any argument that you have no direct intention of modifying, as it can +catch logic/typing errors in your code when you use the argument variable +in a way that you did not intend. + +- Do not create your own linked list code - reuse! +As a common example of this point, make an effort to use the lockable +linked-list macros found in include/asterisk/linkedlists.h. They are +efficient, easy to use and provide every operation that should be +necessary for managing a singly-linked list (if something is missing, +let us know!). Just because you see other open-coded list implementations +in the source tree is no reason to continue making new copies of +that code... There are also a number of common string manipulation +and timeval manipulation functions in asterisk/strings.h and asterisk/time.h; +use them when possible. + +- Avoid needless allocations! +Avoid needless malloc(), strdup() calls. If you only need the value in +the scope of your function try ast_strdupa() or declare structs on the +stack and pass a pointer to them. However, be careful to _never_ call +alloca(), ast_strdupa() or similar functions in the argument list +of a function you are calling; this can cause very strange stack +arrangements and produce unexpected behavior. + +-Allocations for structures +When allocating/zeroing memory for a structure, use code like this: + +struct foo *tmp; + +... + +tmp = ast_calloc(1, sizeof(*tmp)); + +Avoid the combination of ast_malloc() and memset(). Instead, always use +ast_calloc(). This will allocate and zero the memory in a single operation. +In the case that uninitialized memory is acceptable, there should be a comment +in the code that states why this is the case. + +Using sizeof(*tmp) instead of sizeof(struct foo) eliminates duplication of the +'struct foo' identifier, which makes the code easier to read and also ensures +that if it is copy-and-pasted it won't require as much editing. + +The ast_* family of functions for memory allocation are functionally the same. +They just add an Asterisk log error message in the case that the allocation +fails for some reason. This eliminates the need to generate custom messages +throughout the code to log that this has occurred. + +-String Duplications + +The functions strdup and strndup can *not* accept a NULL argument. This results +in having code like this: + + if (str) + newstr = strdup(str); + else + newstr = NULL; + +However, the ast_strdup and ast_strdup functions will happily accept a NULL +argument without generating an error. The same code can be written as: + + newstr = ast_strdup(str); + +Furthermore, it is unnecessary to have code that malloc/calloc's for the length +of a string (+1 for the terminating '\0') and then using strncpy to copy the +copy the string into the resulting buffer. This is the exact same thing as +using ast_strdup. + +* CLI Commands +-------------- + +New CLI commands should be named using the module's name, followed by a verb +and then any parameters that the command needs. For example: + +*CLI> iax2 show peer <peername> + +not + +*CLI> show iax2 peer <peername> + +* New dialplan applications/functions +------------------------------------- + +There are two methods of adding functionality to the Asterisk +dialplan: applications and functions. Applications (found generally in +the apps/ directory) should be collections of code that interact with +a channel and/or user in some significant way. Functions (which can be +provided by any type of module) are used when the provided +functionality is simple... getting/retrieving a value, for +example. Functions should also be used when the operation is in no way +related to a channel (a computation or string operation, for example). + +Applications are registered and invoked using the +ast_register_application function; see the apps/app_skel.c file for an +example. + +Functions are registered using 'struct ast_custom_function' +structures and the ast_custom_function_register function. + +* Doxygen API Documentation Guidelines +-------------------------------------- + +When writing Asterisk API documentation the following format should be +followed. Do not use the javadoc style. + +/*! + * \brief Do interesting stuff. + * \param thing1 interesting parameter 1. + * \param thing2 interesting parameter 2. + * + * This function does some interesting stuff. + * + * \return zero on success, -1 on error. + */ +int ast_interesting_stuff(int thing1, int thing2) +{ + return 0; +} + +Notice the use of the \param, \brief, and \return constructs. These should be +used to describe the corresponding pieces of the function being documented. +Also notice the blank line after the last \param directive. All doxygen +comments must be in one /*! */ block. If the function or struct does not need +an extended description it can be left out. + +Please make sure to review the doxygen manual and make liberal use of the \a, +\code, \c, \b, \note, \li and \e modifiers as appropriate. + +When documenting a 'static' function or an internal structure in a module, +use the \internal modifier to ensure that the resulting documentation +explicitly says 'for internal use only'. + +Structures should be documented as follows. + +/*! + * \brief A very interesting structure. + */ +struct interesting_struct +{ + /*! \brief A data member. */ + int member1; + + int member2; /*!< \brief Another data member. */ +} + +Note that /*! */ blocks document the construct immediately following them +unless they are written, /*!< */, in which case they document the construct +preceding them. + +* Finishing up before you submit your code +------------------------------------------ + +- Look at the code once more +When you achieve your desired functionality, make another few refactor +passes over the code to optimize it. + +- Read the patch +Before submitting a patch, *read* the actual patch file to be sure that +all the changes you expect to be there are, and that there are no +surprising changes you did not expect. During your development, that +part of Asterisk may have changed, so make sure you compare with the +latest CVS. + +- Listen to advice +If you are asked to make changes to your patch, there is a good chance +the changes will introduce bugs, check it even more at this stage. +Also remember that the bug marshal or co-developer that adds comments +is only human, they may be in error :-) + +- Optimize, optimize, optimize +If you are going to reuse a computed value, save it in a variable +instead of recomputing it over and over. This can prevent you from +making a mistake in subsequent computations, making it easier to correct +if the formula has an error and may or may not help optimization but +will at least help readability. + +Just an example (so don't over analyze it, that'd be a shame): + +const char *prefix = "pre"; +const char *postfix = "post"; +char *newname; +char *name = "data"; + +if (name && (newname = alloca(strlen(name) + strlen(prefix) + strlen(postfix) + 3))) + snprintf(newname, strlen(name) + strlen(prefix) + strlen(postfix) + 3, "%s/%s/%s", prefix, name, postfix); + +...vs this alternative: + +const char *prefix = "pre"; +const char *postfix = "post"; +char *newname; +char *name = "data"; +int len = 0; + +if (name && (len = strlen(name) + strlen(prefix) + strlen(postfix) + 3) && (newname = alloca(len))) + snprintf(newname, len, "%s/%s/%s", prefix, name, postfix); + +* Creating new manager events? +------------------------------ +If you create new AMI events, please read manager.txt. Do not re-use +existing headers for new purposes, but please re-use existing headers +for the same type of data. + +Manager events that signal a status are required to have one +event name, with a status header that shows the status. +The old style, with one event named "ThisEventOn" and another named +"ThisEventOff", is no longer approved. + +Check manager.txt for more information on manager and existing +headers. Please update this file if you add new headers. + +----------------------------------------------- +Welcome to the Asterisk development community! +Meet you on the asterisk-dev mailing list. +Subscribe at http://lists.digium.com! + +Mark Spencer, Kevin P. Fleming and +the Asterisk.org Development Team diff --git a/1.4.23-rc4/doc/PEERING b/1.4.23-rc4/doc/PEERING new file mode 100644 index 000000000..253009221 --- /dev/null +++ b/1.4.23-rc4/doc/PEERING @@ -0,0 +1,499 @@ + DIGIUM GENERAL PEERING AGREEMENT (TM) + Version 1.0.0, September 2004 + Copyright (C) 2004 Digium, Inc. + 445 Jan Davis Drive, Huntsville, AL 35806 USA + + Everyone is permitted to copy and distribute complete verbatim copies + of this General Peering Agreement provided it is not modified in any + manner. + + ------------------------------------------------------ + + DIGIUM GENERAL PEERING AGREEMENT + + PREAMBLE + + For most of the history of telecommunications, the power of being able +to locate and communicate with another person in a system, be it across +a hall or around the world, has always centered around a centralized +authority -- from a local PBX administrator to regional and national +RBOCs, generally requiring fees, taxes or regulation. By contrast, +DUNDi is a technology developed to provide users the freedom to +communicate with each other without the necessity of any centralized +authority. This General Peering Agreement ("GPA") is used by individual +parties (each, a "Participant") to allow them to build the E164 trust +group for the DUNDi protocol. + + To protect the usefulness of the E164 trust group for those who use +it, while keeping the system wholly decentralized, it is necessary to +replace many of the responsibilities generally afforded to a company or +government agency, with a set of responsibilities implemented by the +parties who use the system, themselves. It is the goal of this document +to provide all the protections necessary to keep the DUNDi E164 trust +group useful and reliable. + + The Participants wish to protect competition, promote innovation and +value added services and make this service valuable both commercially +and non-commercially. To that end, this GPA provides special terms and +conditions outlining some permissible and non-permissible revenue +sources. + + This GPA is independent of any software license or other license +agreement for a program or technology employing the DUNDi protocol. For +example, the implementation of DUNDi used by Asterisk is covered under a +separate license. Each Participant is responsible for compliance with +any licenses or other agreements governing use of such program or +technology that they use to peer. + + You do not have to execute this GPA to use a program or technology +employing the DUNDi protocol, however if you do not execute this GPA, +you will not be able to peer using DUNDi and the E164 context with +anyone who is a member of the trust group by virtue of their having +executed this GPA with another member. + +The parties to this GPA agree as follows: + + 0. DEFINITIONS. As used herein, certain terms shall be defined as +follows: + + (a) The term "DUNDi" means the DUNDi protocol as published by + Digium, Inc. or its successor in interest with respect to the + DUNDi protocol specification. + + (b) The terms "E.164" and "E164" mean ITU-T specification E.164 as + published by the International Telecommunications Union (ITU) in + May, 1997. + + (c) The term "Service" refers to any communication facility (e.g., + telephone, fax, modem, etc.), identified by an E.164-compatible + number, and assigned by the appropriate authority in that + jurisdiction. + + (d) The term "Egress Gateway" refers an Internet facility that + provides a communications path to a Service or Services that may + not be directly addressable via the Internet. + + (e) The term "Route" refers to an Internet address, policies, and + other characteristics defined by the DUNDi protocol and + associated with the Service, or the Egress Gateway which + provides access to the specified Service. + + (f) The term "Propagate" means to accept or transmit Service and/or + Egress Gateway Routes only using the DUNDi protocol and the + DUNDi context "e164" without regard to case, and does not apply + to the exchange of information using any other protocol or + context. + + (g) The term "Peering System" means the network of systems that + Propagate Routes. + + (h) The term "Subscriber" means the owner of, or someone who + contracts to receive, the services identified by an E.164 + number. + + (i) The term "Authorizing Individual" means the Subscriber to a + number who has authorized a Participant to provide Routes + regarding their services via this Peering System. + + (j) The term "Route Authority" refers to a Participant that provides + an original source of said Route within the Peering System. + Routes are propagated from the Route Authorities through the + Peering System and may be cached at intermediate points. There + may be multiple Route Authorities for any Service. + + (k) The term "Participant" (introduced above) refers to any member + of the Peering System. + + (l) The term "Service Provider" refers to the carrier (e.g., + exchange carrier, Internet Telephony Service Provider, or other + reseller) that provides communication facilities for a + particular Service to a Subscriber, Customer or other End User. + + (m) The term "Weight" refers to a numeric quality assigned to a + Route as per the DUNDi protocol specification. The current + Weight definitions are shown in Exhibit A. + + 1. PEERING. The undersigned Participants agree to Propagate Routes +with each other and any other member of the Peering System and further +agree not to Propagate DUNDi Routes with a third party unless they have +first have executed this GPA (in its unmodified form) with such third +party. The Participants further agree only to Propagate Routes with +Participants whom they reasonably believe to be honoring the terms of +the GPA. Participants may not insert, remove, amend, or otherwise +modify any of the terms of the GPA. + + 2. ACCEPTABLE USE POLICY. The DUNDi protocol contains information +that reflect a Subscriber's or Egress Gateway's decisions to receive +calls. In addition to the terms and conditions set forth in this GPA, +the Participants agree to honor the intent of restrictions encoded in +the DUNDi protocol. To that end, Participants agree to the following: + + (a) A Participant may not utilize or permit the utilization of + Routes for which the Subscriber or Egress Gateway provider has + indicated that they do not wish to receive "Unsolicited Calls" + for the purpose of making an unsolicited phone call on behalf of + any party or organization. + + (b) A Participant may not utilize or permit the utilization of + Routes which have indicated that they do not wish to receive + "Unsolicited Commercial Calls" for the purpose of making an + unsolicited phone call on behalf of a commercial organization. + + (c) A Participant may never utilize or permit the utilization of any + DUNDi route for the purpose of making harassing phone calls. + + (d) A Party may not utilize or permit the utilization of DUNDi + provided Routes for any systematic or random calling of numbers + (e.g., for the purpose of locating facsimile, modem services, or + systematic telemarketing). + + (e) Initial control signaling for all communication sessions that + utilize Routes obtained from the Peering System must be sent + from a member of the Peering System to the Service or Egress + Gateway identified in the selected Route. For example, 'SIP + INVITES' and IAX2 "NEW" commands must be sent from the + requesting DUNDi node to the terminating Service. + + (f) A Participant may not disclose any specific Route, Service or + Participant contact information obtained from the Peering System + to any party outside of the Peering System except as a + by-product of facilitating communication in accordance with + section 2e (e.g., phone books or other databases may not be + published, but the Internet addresses of the Egress Gateway or + Service does not need to be obfuscated.) + + (g) The DUNDi Protocol requires that each Participant include valid + contact information about itself (including information about + nodes connected to each Participant). Participants may use or + disclose the contact information only to ensure enforcement of + legal furtherance of this Agreement. + + 3. ROUTES. The Participants shall only propagate valid Routes, as +defined herein, through the Peering System, regardless of the original +source. The Participants may only provide Routes as set forth below, +and then only if such Participant has no good faith reason to believe +such Route to be invalid or unauthorized. + + (a) A Participant may provide Routes if each Route has as its + original source another member of the Peering System who has + duly executed the GPA and such Routes are provided in accordance + with this Agreement; provided that the Routes are not modified + (e.g., with regards to existence, destination, technology or + Weight); or + + (b) A Participant may provide Routes for Services with any Weight + for which it is the Subscriber; or + + (c) A Participant may provide Routes for those Services whose + Subscriber has authorized the Participant to do so, provided + that the Participant is able to confirm that the Authorizing + Individual is the Subscriber through: + + i. a written statement of ownership from the Authorizing + Individual, which the Participant believes in good faith + to be accurate (e.g., a phone bill with the name of the + Authorizing Individual and the number in question); or + + ii. the Participant's own direct personal knowledge that the + Authorizing Individual is the Subscriber. + + (d) A Participant may provide Routes for Services, with Weight in + accordance with the Current DUNDi Specification, if it can in + good faith provide an Egress Gateway to that Service on the + traditional telephone network without cost to the calling party. + + 4. REVOCATION. A Participant must provide a free, easily accessible +mechanism by which a Subscriber may revoke permission to act as a Route +Authority for his Service. A Participant must stop acting as a Route +Authority for that Service within 7 days after: + + (a) receipt of a revocation request; + + (b) receiving other notice that the Service is no longer valid; or + + (c) determination that the Subscriber's information is no longer + accurate (including that the Subscriber is no longer the service + owner or the service owner's authorized delegate). + + 5. SERVICE FEES. A Participant may charge a fee to act as a Route +Authority for a Service, with any Weight, provided that no Participant +may charge a fee to propagate the Route received through the Peering +System. + + 6. TOLL SERVICES. No Participant may provide Routes for any Services +that require payment from the calling party or their customer for +communication with the Service. Nothing in this section shall prohibit +a Participant from providing routes for Services where the calling party +may later enter into a financial transaction with the called party +(e.g., a Participant may provide Routes for calling cards services). + + 7. QUALITY. A Participant may not intentionally impair communication +using a Route provided to the Peering System (e.g. by adding delay, +advertisements, reduced quality). If for any reason a Participant is +unable to deliver a call via a Route provided to the Peering System, +that Participant shall return out-of-band Network Congestion +notification (e.g. "503 Service Unavailable" with SIP protocol or +"CONGESTION" with IAX protocol). + + 8. PROTOCOL COMPLIANCE. Participants agree to Propagate Routes in +strict compliance with current DUNDi protocol specifications. + + 9. ADMINISTRATIVE FEES. A Participant may charge (but is not required +to charge) another Participant a reasonable fee to cover administrative +expenses incurred in the execution of this Agreement. A Participant may +not charge any fee to continue the relationship or to provide Routes to +another Participant in the Peering System. + + 10. CALLER IDENTIFICATION. A Participant will make a good faith effort +to ensure the accuracy and appropriate nature of any caller +identification that it transmits via any Route obtained from the Peering +System. Caller identification shall at least be provided as a valid +E.164 number. + + 11. COMPLIANCE WITH LAWS. The Participants are solely responsible for +determining to what extent, if any, the obligations set forth in this +GPA conflict with any laws or regulations their region. A Participant +may not provide any service or otherwise use DUNDi under this GPA if +doing so is prohibited by law or regulation, or if any law or regulation +imposes requirements on the Participant that are inconsistent with the +terms of this GPA or the Acceptable Use Policy. + + 12. WARRANTY. EACH PARTICIPANT WARRANTS TO THE OTHER PARTICIPANTS THAT +IT MADE, AND WILL CONTINUE TO MAKE, A GOOD FAITH EFFORT TO AUTHENTICATE +OTHERS IN THE PEERING SYSTEM AND TO PROVIDE ACCURATE INFORMATION IN +ACCORDANCE WITH THE TERMS OF THIS GPA. THIS WARRANTY IS MADE BETWEEN +THE PARTICIPANTS, AND THE PARTICIPANTS MAY NOT EXTEND THIS WARRANTY TO +ANY NON-PARTICIPANT INCLUDING END-USERS. + + 13. DISCLAIMER OF WARRANTIES. THE PARTICIPANTS UNDERSTAND AND AGREE +THAT ANY SERVICE PROVIDED AS A RESULT OF THIS GPA IS "AS IS." EXCEPT FOR +THOSE WARRANTIES OTHERWISE EXPRESSLY SET FORTH HEREIN, THE PARTICIPANTS +DISCLAIM ANY REPRESENTATIONS OR WARRANTIES OF ANY KIND OR NATURE, +EXPRESS OR IMPLIED, AS TO THE CONDITION, VALUE OR QUALITIES OF THE +SERVICES PROVIDED HEREUNDER, AND SPECIFICALLY DISCLAIM ANY +REPRESENTATION OR WARRANTY OF MERCHANTABILITY, SUITABILITY OR FITNESS +FOR A PARTICULAR PURPOSE OR AS TO THE CONDITION OR WORKMANSHIP THEREOF, +OR THE ABSENCE OF ANY DEFECTS THEREIN, WHETHER LATENT OR PATENT, +INCLUDING ANY WARRANTIES ARISING FROM A COURSE OF DEALING, USAGE OR +TRADE PRACTICE. EXCEPT AS EXPRESSLY PROVIDED HEREIN, THE PARTICIPANTS +EXPRESSLY DISCLAIM ANY REPRESENTATIONS OR WARRANTIES THAT THE PEERING +SERVICE WILL BE CONTINUOUS, UNINTERRUPTED OR ERROR-FREE, THAT ANY DATA +SHARED OR OTHERWISE MADE AVAILABLE WILL BE ACCURATE OR COMPLETE OR +OTHERWISE COMPLETELY SECURE FROM UNAUTHORIZED ACCESS. + + 14. LIMITATION OF LIABILITIES. NO PARTICIPANT SHALL BE LIABLE TO ANY +OTHER PARTICIPANT FOR INCIDENTAL, INDIRECT, CONSEQUENTIAL, SPECIAL, +PUNITIVE OR EXEMPLARY DAMAGES OF ANY KIND (INCLUDING LOST REVENUES OR +PROFITS, LOSS OF BUSINESS OR LOSS OF DATA) IN ANY WAY RELATED TO THIS +GPA, WHETHER IN CONTRACT OR IN TORT, REGARDLESS OF WHETHER SUCH +PARTICIPANT WAS ADVISED OF THE POSSIBILITY THEREOF. + + 15. END-USER AGREEMENTS. The Participants may independently enter +into agreements with end-users to provide certain services (e.g., fees +to a Subscriber to originate Routes for that Service). To the extent +that provision of these services employs the Peering System, the Parties +will include in their agreements with their end-users terms and +conditions consistent with the terms of this GPA with respect to the +exclusion of warranties, limitation of liability and Acceptable Use +Policy. In no event may a Participant extend the warranty described in +Section 12 in this GPA to any end-users. + + 16. INDEMNIFICATION. Each Participant agrees to defend, indemnify and +hold harmless the other Participant or third-party beneficiaries to this +GPA (including their affiliates, successors, assigns, agents and +representatives and their respective officers, directors and employees) +from and against any and all actions, suits, proceedings, +investigations, demands, claims, judgments, liabilities, obligations, +liens, losses, damages, expenses (including, without limitation, +attorneys' fees) and any other fees arising out of or relating to (i) +personal injury or property damage caused by that Participant, its +employees, agents, servants, or other representatives; (ii) any act or +omission by the Participant, its employees, agents, servants or other +representatives, including, but not limited to, unauthorized +representations or warranties made by the Participant; or (iii) any +breach by the Participant of any of the terms or conditions of this GPA. + + 17. THIRD PARTY BENEFICIARIES. This GPA is intended to benefit those +Participants who have executed the GPA and who are in the Peering +System. It is the intent of the Parties to this GPA to give to those +Participants who are in the Peering System standing to bring any +necessary legal action to enforce the terms of this GPA. + + 18. TERMINATION. Any Participant may terminate this GPA at any time, +with or without cause. A Participant that terminates must immediately +cease to Propagate. + + 19. CHOICE OF LAW. This GPA and the rights and duties of the Parties +hereto shall be construed and determined in accordance with the internal +laws of the State of New York, United States of America, without regard +to its conflict of laws principles and without application of the United +Nations Convention on Contracts for the International Sale of Goods. + + 20. DISPUTE RESOLUTION. Unless otherwise agreed in writing, the +exclusive procedure for handling disputes shall be as set forth herein. +Notwithstanding such procedures, any Participant may, at any time, seek +injunctive relief in addition to the process described below. + + (a) Prior to mediation or arbitration the disputing Participants + shall seek informal resolution of disputes. The process shall be + initiated with written notice of one Participant to the other + describing the dispute with reasonable particularity followed + with a written response within ten (10) days of receipt of + notice. Each Participant shall promptly designate an executive + with requisite authority to resolve the dispute. The informal + procedure shall commence within ten (10) days of the date of + response. All reasonable requests for non-privileged information + reasonably related to the dispute shall be honored. If the + dispute is not resolved within thirty (30) days of commencement + of the procedure either Participant may proceed to mediation or + arbitration pursuant to the rules set forth in (b) or (c) below. + + (b) If the dispute has not been resolved pursuant to (a) above or, + if the disputing Participants fail to commence informal dispute + resolution pursuant to (a) above, either Participant may, in + writing and within twenty (20) days of the response date noted + in (a) above, ask the other Participant to participate in a one + (1) day mediation with an impartial mediator, and the other + Participant shall do so. Each Participant will bear its own + expenses and an equal share of the fees of the mediator. If the + mediation is not successful the Participants may proceed with + arbitration pursuant to (c) below. + + (c) If the dispute has not been resolved pursuant to (a) or (b) + above, the dispute shall be promptly referred, no later than one + (1) year from the date of original notice and subject to + applicable statute of limitations, to binding arbitration in + accordance with the UNCITRAL Arbitration Rules in effect on the + date of this contract. The appointing authority shall be the + International Centre for Dispute Resolution. The case shall be + administered by the International Centre for Dispute Resolution + under its Procedures for Cases under the UNCITRAL Arbitration + Rules. Each Participant shall bear its own expenses and shall + share equally in fees of the arbitrator. All arbitrators shall + have substantial experience in information technology and/or in + the telecommunications business and shall be selected by the + disputing participants in accordance with UNCITRAL Arbitration + Rules. If any arbitrator, once selected is unable or unwilling + to continue for any reason, replacement shall be filled via the + process described above and a re-hearing shall be conducted. The + disputing Participants will provide each other with all + requested documents and records reasonably related to the + dispute in a manner that will minimize the expense and + inconvenience of both parties. Discovery will not include + depositions or interrogatories except as the arbitrators + expressly allow upon a showing of need. If disputes arise + concerning discovery requests, the arbitrators shall have sole + and complete discretion to resolve the disputes. The parties and + arbitrator shall be guided in resolving discovery disputes by + the Federal Rules of Civil Procedure. The Participants agree + that time of the essence principles shall guide the hearing and + that the arbitrator shall have the right and authority to issue + monetary sanctions in the event of unreasonable delay. The + arbitrator shall deliver a written opinion setting forth + findings of fact and the rationale for the award within thirty + (30) days following conclusion of the hearing. The award of the + arbitrator, which may include legal and equitable relief, but + which may not include punitive damages, will be final and + binding upon the disputing Participants, and judgment may be + entered upon it in accordance with applicable law in any court + having jurisdiction thereof. In addition to award the + arbitrator shall have the discretion to award the prevailing + Participant all or part of its attorneys' fees and costs, + including fees associated with arbitrator, if the arbitrator + determines that the positions taken by the other Participant on + material issues of the dispute were without substantial + foundation. Any conflict between the UNCITRAL Arbitration Rules + and the provisions of this GPA shall be controlled by this GPA. + + 21. INTEGRATED AGREEMENT. This GPA, constitutes the complete +integrated agreement between the parties concerning the subject matter +hereof. All prior and contemporaneous agreements, understandings, +negotiations or representations, whether oral or in writing, relating to +the subject matter of this GPA are superseded and canceled in their +entirety. + + 22. WAIVER. No waiver of any of the provisions of this GPA shall be +deemed or shall constitute a waiver of any other provision of this GPA, +whether or not similar, nor shall such waiver constitute a continuing +waiver unless otherwise expressly so provided in writing. The failure +of either party to enforce at any time any of the provisions of this +GPA, or the failure to require at any time performance by either party +of any of the provisions of this GPA, shall in no way be construed to be +a present or future waiver of such provisions, nor in any way affect the +ability of a Participant to enforce each and every such provision +thereafter. + + 23. INDEPENDENT CONTRACTORS. Nothing in this GPA shall make the +Parties partners, joint venturers, or otherwise associated in or with +the business of the other. Parties are, and shall always remain, +independent contractors. No Participant shall be liable for any debts, +accounts, obligations, or other liabilities of the other Participant, +its agents or employees. No party is authorized to incur debts or other +obligations of any kind on the part of or as agent for the other. This +GPA is not a franchise agreement and does not create a franchise +relationship between the parties, and if any provision of this GPA is +deemed to create a franchise between the parties, then this GPA shall +automatically terminate. + + 24. CAPTIONS AND HEADINGS. The captions and headings used in this GPA +are used for convenience only and are not to be given any legal effect. + + 25. EXECUTION. This GPA may be executed in counterparts, each of which +so executed will be deemed to be an original and such counterparts +together will constitute one and the same Agreement. The Parties shall +transmit to each other a signed copy of the GPA by any means that +faithfully reproduces the GPA along with the Signature. For purposes of +this GPA, the term "signature" shall include digital signatures as +defined by the jurisdiction of the Participant signing the GPA. + + Exhibit A + +Weight Range Requirements + +0-99 May only be used under authorization of Owner + +100-199 May only be used by the Owner's service + provider, regardless of authorization. + +200-299 Reserved -- do not use for e164 context. + +300-399 May only be used by the owner of the code under + which the Owner's number is a part of. + +400-499 May be used by any entity providing access via + direct connectivity to the Public Switched + Telephone Network. + +500-599 May be used by any entity providing access via + indirect connectivity to the Public Switched + Telephone Network (e.g. Via another VoIP + provider) + +600- Reserved-- do not use for e164 context. + + Participant Participant + +Company: + +Address: + +Email: + + + _________________________ _________________________ + Authorized Signature Authorized Signature + +Name: + + +END OF GENERAL PEERING AGREEMENT + +------------------------------------------------ + +How to Peer using this GPA If you wish to exchange routing information +with parties using the e164 DUNDi context, all you must do is execute +this GPA with any member of the Peering System and you will become a +member of the Peering System and be able to make Routes available in +accordance with this GPA. + +DUNDi, IAX, Asterisk and GPA are trademarks of Digium, Inc. diff --git a/1.4.23-rc4/doc/ael.txt b/1.4.23-rc4/doc/ael.txt new file mode 100644 index 000000000..7c7829ae9 --- /dev/null +++ b/1.4.23-rc4/doc/ael.txt @@ -0,0 +1,1260 @@ +The Asterisk Extension Language - v 2 +===================================== + +AEL is a specialized language intended purely for +describing Asterisk dial plans. + +The current version was written by Steve Murphy, and is a rewrite of +the original version. + +This new version further extends AEL, and +provides more flexible syntax, better error messages, and some missing +functionality. + +AEL is really the merger of 4 different 'languages', or syntaxes: + + * The first and most obvious is the AEL syntax itself. A BNF is + provided near the end of this document. + + * The second syntax is the Expression Syntax, which is normally + handled by Asterisk extension engine, as expressions enclosed in + $[...]. The right hand side of assignments are wrapped in $[ ... ] + by AEL, and so are the if and while expressions, among others. + + * The third syntax is the Variable Reference Syntax, the stuff + enclosed in ${..} curly braces. It's a bit more involved than just + putting a variable name in there. You can include one of dozens of + 'functions', and their arguments, and there are even some string + manipulation notation in there. + + * The last syntax that underlies AEL, and is not used + directly in AEL, is the Extension Language Syntax. The + extension language is what you see in extensions.conf, and AEL + compiles the higher level AEL language into extensions and + priorities, and passes them via function calls into + Asterisk. Embedded in this language is the Application/AGI + commands, of which one application call per step, or priority + can be made. You can think of this as a "macro assembler" + language, that AEL will compile into. + + +Any programmer of AEL should be familiar with it's syntax, of course, +as well as the Expression syntax, and the Variable syntax. + +************************** +* Asterisk in a Nutshell * +************************** + +Asterisk acts as a server. Devices involved in telephony, like Zapata +cards, or Voip phones, all indicate some context that should be +activated in their behalf. See the config file formats for IAX, SIP, +chan_dahdi.conf, etc. They all help describe a device, and they all +specify a context to activate when somebody picks up a phone, or a +call comes in from the phone company, or a voip phone, etc. + +Contexts +-------- + +Contexts are a grouping of extensions. + +Contexts can also include other contexts. Think of it as a sort of +merge operation at runtime, whereby the included context's extensions +are added to the contexts making the inclusion. + +Extensions and priorities +------------------------- + +A Context contains zero or more Extensions. There are several +predefined extensions. The "s" extension is the "start" extension, and +when a device activates a context the "s" extension is the one that is +going to be run. Other extensions are the timeout "t" extension, the +invalid response, or "i" extension, and there's a "fax" extension. For +instance, a normal call will activate the "s" extension, but an +incoming FAX call will come into the "fax" extension, if it +exists. (BTW, asterisk can tell it's a fax call by the little "beep" +that the calling fax machine emits every so many seconds.). + +Extensions contain several priorities, which are individual +instructions to perform. Some are as simple as setting a variable to a +value. Others are as complex as initiating the Voicemail application, +for instance. Priorities are executed in order. + +When the 's" extension completes, asterisk waits until the timeout for +a response. If the response matches an extension's pattern in the +context, then control is transferred to that extension. Usually the +responses are tones emitted when a user presses a button on their +phone. For instance, a context associated with a desk phone might not +have any "s" extension. It just plays a dialtone until someone starts +hitting numbers on the keypad, gather the number, find a matching +extension, and begin executing it. That extension might Dial out over +a connected telephone line for the user, and then connect the two +lines together. + +The extensions can also contain "goto" or "jump" commands to skip to +extensions in other contexts. Conditionals provide the ability to +react to different stimuli, and there you have it. + +Macros +------ + +Think of a macro as a combination of a context with one nameless +extension, and a subroutine. It has arguments like a subroutine +might. A macro call can be made within an extension, and the +individual statements there are executed until it ends. At this point, +execution returns to the next statement after the macro call. Macros +can call other macros. And they work just like function calls. + +Applications +------------ + +Application calls, like "Dial()", or "Hangup()", or "Answer()", are +available for users to use to accomplish the work of the +dialplan. There are over 145 of them at the moment this was written, +and the list grows as new needs and wants are uncovered. Some +applications do fairly simple things, some provide amazingly complex +services. + +Hopefully, the above objects will allow you do anything you need to in +the Asterisk environment! + + +******************* +* 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/. extensions.conf and +extensions.ael can be used in conjunction with +each other if that is what is desired. Some users may want to keep +extensions.conf for the features that are configured in the 'general' +section of extensions.conf. + +------------------------------ +- Reloading extensions.ael - +------------------------------ + +To reload extensions.ael, the following command can be issued at the +CLI: + + *CLI> ael reload + + + +************* +* Debugging * +************* + +Right at this moment, the following commands are available, but do +nothing: + +Enable AEL contexts debug + *CLI> ael debug contexts + +Enable AEL macros debug + *CLI> ael debug macros + +Enable AEL read debug + *CLI> ael debug read + +Enable AEL tokens debug + *CLI> ael debug tokens + +Disable AEL debug messages + *CLI> ael no debug + +If things are going wrong in your dialplan, you can use the following +facilities to debug your file: + +1. The messages log in /var/log/asterisk. (from the checks done at load time). +2. the "show dialplan" command in asterisk +3. the standalone executable, "aelparse" built in the utils/ dir in the source. + + +***************************** +* About "aelparse" * +***************************** + +You can use the "aelparse" program to check your extensions.ael +file before feeding it to asterisk. Wouldn't it be nice to eliminate +most errors before giving the file to asterisk? + +aelparse is compiled in the utils directory of the asterisk release. +It isn't installed anywhere (yet). You can copy it to your favorite +spot in your PATH. + +aelparse has two optional arguments: + +-d - Override the normal location of the config file dir, (usually + /etc/asterisk), and use the current directory instead as the + config file dir. Aelparse will then expect to find the file + "./extensions.ael" in the current directory, and any included + files in the current directory as well. + +-n - don't show all the function calls to set priorities and contexts + within asterisk. It will just show the errors and warnings from + the parsing and semantic checking phases. + + +****************************** +* General Notes about Syntax * +****************************** + +Note that the syntax and style are now a little more free-form. The +opening '{' (curly-braces) do not have to be on the same line as the +keyword that precedes them. Statements can be split across lines, as +long as tokens are not broken by doing so. More than one statement can +be included on a single line. Whatever you think is best! + +You can just as easily say, + +if(${x}=1) { NoOp(hello!); goto s|3; } else { NoOp(Goodbye!); goto s|12; } + +as you can say: + +if(${x}=1) +{ + NoOp(hello!); + goto s|3; +} +else +{ + NoOp(Goodbye!); + goto s|12; +} + +or: + +if(${x}=1) { + NoOp(hello!); + goto s|3; +} else { + NoOp(Goodbye!); + goto s|12; +} + +or: + +if (${x}=1) { + NoOp(hello!); goto s|3; +} else { + NoOp(Goodbye!); goto s|12; +} + +or even: + +if +(${x}=1) +{ +NoOp(hello!); +goto s|3; +} +else +{ +NoOp(Goodbye!); +goto s|12; +} + + +************ +* Keywords * +************ + +The AEL keywords are case-sensitive. If an application name and a +keyword overlap, there is probably good reason, and you should +consider replacing the application call with an AEL statement. If you +do not wish to do so, you can still use the application, by using a +capitalized letter somewhere in its name. In the Asterisk extension +language, application names are NOT case-sensitive. + +The following are keywords in the AEL language: + + * abstract + * context + * macro + * globals + * ignorepat + * switch + * if + * ifTime + * else + * random + * goto + * jump + * return + * break + * continue + * regexten + * hint + * for + * while + * case + * pattern + * default NOTE: the "default" keyword can be used as a context name, + for those who would like to do so. + * catch + * switches + * eswitches + * includes + + + + + +Procedural Interface and Internals +================================== + +AEL first parses the extensions.ael file into a memory structure representing the file. +The entire file is represented by a tree of "pval" structures linked together. + +This tree is then handed to the semantic check routine. + +Then the tree is handed to the compiler. + +After that, it is freed from memory. + +A program could be written that could build a tree of pval structures, and +a pretty printing function is provided, that would dump the data to a file, +or the tree could be handed to the compiler to merge the data into the +asterisk dialplan. The modularity of the design offers several opportunities +for developers to simplify apps to generate dialplan data. + + + +========================= + AEL version 2 BNF +========================= + + + +(hopefully, something close to bnf). + +First, some basic objects + +------------------------ + +<word> a lexical token consisting of characters matching this pattern: [-a-zA-Z0-9"_/.\<\>\*\+!$#\[\]][-a-zA-Z0-9"_/.!\*\+\<\>\{\}$#\[\]]* + +<word3-list> a concatenation of up to 3 <word>s. + +<collected-word> all characters encountered until the character that follows the <collected-word> in the grammar. + +------------------------- + +<file> :== <objects> + +<objects> :== <object> + | <objects> <object> + + +<object> :== <context> + | <macro> + | <globals> + | ';' + + +<context> :== 'context' <word> '{' <elements> '}' + | 'context' <word> '{' '}' + | 'context' 'default' '{' <elements> '}' + | 'context' 'default' '{' '}' + | 'abstract' 'context' <word> '{' <elements> '}' + | 'abstract' 'context' <word> '{' '}' + | 'abstract' 'context' 'default' '{' <elements> '}' + | 'abstract' 'context' 'default' '{' '}' + + +<macro> :== 'macro' <word> '(' <arglist> ')' '{' <macro_statements> '}' + | 'macro' <word> '(' <arglist> ')' '{' '}' + | 'macro' <word> '(' ')' '{' <macro_statements> '}' + | 'macro' <word> '(' ')' '{' '}' + + +<globals> :== 'globals' '{' <global_statements> '}' + | 'globals' '{' '}' + + +<global_statements> :== <global_statement> + | <global_statements> <global_statement> + + +<global_statement> :== <word> '=' <collected-word> ';' + + +<arglist> :== <word> + | <arglist> ',' <word> + + +<elements> :== <element> + | <elements> <element> + + +<element> :== <extension> + | <includes> + | <switches> + | <eswitches> + | <ignorepat> + | <word> '=' <collected-word> ';' + | ';' + + +<ignorepat> :== 'ignorepat' '=>' <word> ';' + + +<extension> :== <word> '=>' <statement> + | 'regexten' <word> '=>' <statement> + | 'hint' '(' <word3-list> ')' <word> '=>' <statement> + | 'regexten' 'hint' '(' <word3-list> ')' <word> '=>' <statement> + + +<statements> :== <statement> + | <statements> <statement> + +<if_head> :== 'if' '(' <collected-word> ')' + +<random_head> :== 'random' '(' <collected-word> ')' + +<ifTime_head> :== 'ifTime' '(' <word3-list> ':' <word3-list> ':' <word3-list> '|' <word3-list> '|' <word3-list> '|' <word3-list> ')' + | 'ifTime' '(' <word> '|' <word3-list> '|' <word3-list> '|' <word3-list> ')' + + +<word3-list> :== <word> + | <word> <word> + | <word> <word> <word> + +<switch_head> :== 'switch' '(' <collected-word> ')' '{' + + +<statement> :== '{' <statements> '}' + | <word> '=' <collected-word> ';' + | 'goto' <target> ';' + | 'jump' <jumptarget> ';' + | <word> ':' + | 'for' '(' <collected-word> ';' <collected-word> ';' <collected-word> ')' <statement> + | 'while' '(' <collected-word> ')' <statement> + | <switch_head> '}' + | <switch_head> <case_statements> '}' + | '&' macro_call ';' + | <application_call> ';' + | <application_call> '=' <collected-word> ';' + | 'break' ';' + | 'return' ';' + | 'continue' ';' + | <random_head> <statement> + | <random_head> <statement> 'else' <statement> + | <if_head> <statement> + | <if_head> <statement> 'else' <statement> + | <ifTime_head> <statement> + | <ifTime_head> <statement> 'else' <statement> + | ';' + +<target> :== <word> + | <word> '|' <word> + | <word> '|' <word> '|' <word> + | 'default' '|' <word> '|' <word> + | <word> ',' <word> + | <word> ',' <word> ',' <word> + | 'default' ',' <word> ',' <word> + +<jumptarget> :== <word> + | <word> ',' <word> + | <word> ',' <word> '@' <word> + | <word> '@' <word> + | <word> ',' <word> '@' 'default' + | <word> '@' 'default' + +<macro_call> :== <word> '(' <eval_arglist> ')' + | <word> '(' ')' + +<application_call_head> :== <word> '(' + +<application_call> :== <application_call_head> <eval_arglist> ')' + | <application_call_head> ')' + +<eval_arglist> :== <collected-word> + | <eval_arglist> ',' <collected-word> + | /* nothing */ + | <eval_arglist> ',' /* nothing */ + +<case_statements> :== <case_statement> + | <case_statements> <case_statement> + + +<case_statement> :== 'case' <word> ':' <statements> + | 'default' ':' <statements> + | 'pattern' <word> ':' <statements> + | 'case' <word> ':' + | 'default' ':' + | 'pattern' <word> ':' + +<macro_statements> :== <macro_statement> + | <macro_statements> <macro_statement> + +<macro_statement> :== <statement> + | 'catch' <word> '{' <statements> '}' + +<switches> :== 'switches' '{' <switchlist> '}' + | 'switches' '{' '}' + +<eswitches> :== 'eswitches' '{' <switchlist> '}' + | 'eswitches' '{' '}' + +<switchlist> :== <word> ';' + | <switchlist> <word> ';' + +<includeslist> :== <includedname> ';' + | <includedname> '|' <word3-list> ':' <word3-list> ':' <word3-list> '|' <word3-list> '|' <word3-list> '|' <word3-list> ';' + | <includedname> '|' <word> '|' <word3-list> '|' <word3-list> '|' <word3-list> ';' + | <includeslist> <includedname> ';' + | <includeslist> <includedname> '|' <word3-list> ':' <word3-list> ':' <word3-list> '|' <word3-list> '|' <word3-list> '|' <word3-list> ';' + | <includeslist> <includedname> '|' <word> '|' <word3-list> '|' <word3-list> '|' <word3-list> ';' + +<includedname> :== <word> + | 'default' + +<includes> :== 'includes' '{' <includeslist> '}' + | 'includes' '{' '}' + + +************************** +* AEL Example USAGE ***** +************************** + +Comments +======== + +Comments begin with // and end with the end of the line. + +Comments are removed by the lexical scanner, and will not be +recognized in places where it is busy gathering expressions to wrap in +$[] , or inside application call argument lists. The safest place to put +comments is after terminating semicolons, or on otherwise empty lines. + + +Context +======= + +Contexts in AEL represent a set of extensions in the same way that +they do in extensions.conf. + + +context default { + +} + + +A context can be declared to be "abstract", in which case, this +declaration expresses the intent of the writer, that this context will +only be included by another context, and not "stand on its own". The +current effect of this keyword is to prevent "goto " statements from +being checked. + + +abstract context longdist { + _1NXXNXXXXXX => NoOp(generic long distance dialing actions in the US); +} + + + +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!); +} + + +Two optional items have been added to the AEL syntax, that allow the +specification of hints, and a keyword, regexten, that will force the +numbering of priorities to start at 2. + +The ability to make extensions match by CID is preserved in +AEL; just use '/' and the CID number in the specification. See below. + + +context default { + + regexten _5XXX => NoOp(it's a pattern!); +} + + + +context default { + + hint(Sip/1) _5XXX => NoOp(it's a pattern!); +} + + + +context default { + + regexten hint(Sip/1) _5XXX => NoOp(it's a pattern!); +} + + +The regexten must come before the hint if they are both present. + +CID matching is done as with the extensions.conf file. Follow the extension +name/number with a slash (/) and the number to match against the Caller ID: + +context zoombo +{ + 819/7079953345 => { NoOp(hello, 3345); } +} + +In the above, the 819/7079953345 extension will only be matched if the +CallerID is 7079953345, and the dialed number is 819. Hopefully you have +another 819 extension defined for all those who wish 819, that are not so lucky +as to have 7079953345 as their CallerID! + + +Includes +======== + +Contexts can be included in other contexts. All included contexts are +listed within a single block. + + +context default { + includes { + local; + longdistance; + international; + } +} + + +Time-limited inclusions can be specified, as in extensions.conf +format, with the fields described in the wiki page Asterisk cmd +GotoIfTime. + + +context default { + includes { + local; + longdistance|16:00-23:59|mon-fri|*|*; + international; + } +} + + +#include +======== + +You can include other files with the #include "filepath" construct. + + + #include "/etc/asterisk/testfor.ael" + + +An interesting property of the #include, is that you can use it almost +anywhere in the .ael file. It is possible to include the contents of +a file in a macro, context, or even extension. The #include does not +have to occur at the beginning of a line. Included files can include +other files, up to 50 levels deep. If the path provided in quotes is a +relative path, the parser looks in the config file directory for the +file (usually /etc/asterisk). + + + +Dialplan Switches +================= + +Switches are listed in their own block within a context. For clues as +to what these are used for, see Asterisk - dual servers, and Asterisk +config extensions.conf. + + +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; + divexample=10/2 + NoOp(x is ${x} and y is ${y} !); + } +} + + +NOTE: AEL wraps the right hand side of an assignment with $[ ] to allow +expressions to be used If this is unwanted, you can protect the right hand +side from being wrapped by using the Set() application. +Read the README.variables about the requirements and behavior +of $[ ] expressions. + +NOTE: These things are wrapped up in a $[ ] expression: The while() test; +the if() test; the middle expression in the for( x; y; z) statement +(the y expression); Assignments - the right hand side, so a = b -> Set(a=$[b]) + +Writing to a dialplan function is treated the same as writing to a variable. + + +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; + } + } +} + + +NOTE: The conditional expression (the "${y} >= 0" above) is wrapped in + $[ ] so it can be evaluated. NOTE: The for loop test expression + (the "${x} < 3" above) is wrapped in $[ ] so it can be evaluated. + + + +Conditionals +============ + +AEL supports if and switch statements, like AEL, but adds ifTime, and +random. Unlike the original AEL, though, you do NOT need to put curly +braces around a single statement in the "true" branch of an if(), the +random(), or an ifTime() statement. The if(), ifTime(), and random() +statements allow optional else clause. + + +context conditional { + _8XXX => { + Dial(SIP/${EXTEN}); + if ("${DIALSTATUS}" = "BUSY") + { + NoOp(yessir); + Voicemail(${EXTEN}|b); + } + else + Voicemail(${EXTEN}|u); + ifTime (14:00-25:00|sat-sun|*|*) + Voicemail(${EXTEN}|b); + else + { + Voicemail(${EXTEN}|u); + NoOp(hi, there!); + } + random(51) NoOp(This should appear 51% of the time); + + random( 60 ) + { + NoOp( This should appear 60% of the time ); + } + else + { + random(75) + { + NoOp( This should appear 30% of the time! ); + } + else + { + NoOp( This should appear 10% of the time! ); + } + } + } + _777X => { + switch (${EXTEN}) { + case 7771: + NoOp(You called 7771!); + break; + case 7772: + NoOp(You called 7772!); + break; + case 7773: + NoOp(You called 7773!); + // fall thru- + pattern 777[4-9]: + NoOp(You called 777 something!); + default: + NoOp(In the default clause!); + } + } +} + + +NOTE: The conditional expression in if() statements (the + "${DIALSTATUS}" = "BUSY" above) is wrapped by the compiler in + $[] for evaluation. + +NOTE: Neither the switch nor case values are wrapped in $[ ]; they can + be constants, or ${var} type references only. + +NOTE: AEL generates each case as a separate extension. case clauses + with no terminating 'break', or 'goto', have a goto inserted, to + the next clause, which creates a 'fall thru' effect. + +NOTE: AEL introduces the ifTime keyword/statement, which works just + like the if() statement, but the expression is a time value, + exactly like that used by the application GotoIfTime(). See + Asterisk cmd GotoIfTime + +NOTE: The pattern statement makes sure the new extension that is + created has an '_' preceding it to make sure asterisk recognizes + the extension name as a pattern. + +NOTE: Every character enclosed by the switch expression's parenthesis + are included verbatim in the labels generated. So watch out for + spaces! + +NOTE: NEW: Previous to version 0.13, the random statement used the + "Random()" application, which has been deprecated. It now uses + the RAND() function instead, in the GotoIf application. + + +Break, Continue, and Return +=========================== + + +Three keywords, break, continue, and return, are included in the +syntax to provide flow of control to loops, and switches. + +The break can be used in switches and loops, to jump to the end of the +loop or switch. + +The continue can be used in loops (while and for) to immediately jump +to the end of the loop. In the case of a for loop, the increment and +test will then be performed. In the case of the while loop, the +continue will jump to the test at the top of the loop. + +The return keyword will cause an immediate jump to the end of the +context, or macro, and can be used anywhere. + + + +goto, jump, 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; // go to label in same extension + } + 3 => { + goto s|begin; // go to label in different extension + } + 4 => { + goto gotoexample|s|begin; // overkill go to label in same context + } +} + +context gotoexample2 { + s => { + end: + goto gotoexample|s|begin; // go to label in different context + } +} + +You can use the special label of "1" in the goto and jump +statements. It means the "first" statement in the extension. I would +not advise trying to use numeric labels other than "1" in goto's or +jumps, nor would I advise declaring a "1" label anywhere! As a matter +of fact, it would be bad form to declare a numeric label, and it might +conflict with the priority numbers used internally by asterisk. + +The syntax of the jump statement is: jump +extension[,priority][@context] If priority is absent, it defaults to +"1". If context is not present, it is assumed to be the same as that +which contains the "jump". + + +context gotoexample { + s => { +begin: + NoOp(Infinite Loop! yay!); + Wait(1); + jump s; // go to first extension in same extension + } + 3 => { + jump s,begin; // go to label in different extension + } + 4 => { + jump s,begin@gotoexample; // overkill go to label in same context + } +} + +context gotoexample2 { + s => { + end: + jump s@gotoexample; // go to label in different context + } +} + +NOTE: goto labels follow the same requirements as the Goto() + application, except the last value has to be a label. If the + label does not exist, you will have run-time errors. If the + label exists, but in a different extension, you have to specify + both the extension name and label in the goto, as in: goto s|z; + if the label is in a different context, you specify + context|extension|label. There is a note about using goto's in a + switch statement below... + +NOTE AEL introduces the special label "1", which is the beginning + context number for most extensions. + +NOTE: A NEW addition to AEL: you can now use ',' instead of '|' to + separate the items in the target address. You can't have a mix, + though, of '|' and ',' in the target. It's either one, or the other. + + + + +Macros +====== + +A macro is defined in its own block like this. The arguments to the +macro are specified with the name of the macro. They are then referred +to by that same name. A catch block can be specified to catch special +extensions. + + +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 preceding the macro name with an +ampersand. Empty arguments can be passed simply with nothing between +comments(0.11). + + +context example { + _5XXX => &std-exten(${EXTEN}, "IAX2"); + _6XXX => &std-exten(, "IAX2"); + _7XXX => &std-exten(${EXTEN},); + _8XXX => &std-exten(,); +} + + + +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); +} + + +Semantic Checks +=============== + + +AEL, after parsing, but before compiling, traverses the dialplan +tree, and makes several checks: + + * Macro calls to non-existent macros. + * Macro calls to contexts. + * Macro calls with argument count not matching the definition. + * application call to macro. (missing the '&') + * application calls to "GotoIf", "GotoIfTime", "while", + "endwhile", "Random", and "execIf", will generate a message to + consider converting the call to AEL goto, while, etc. constructs. + * goto a label in an empty extension. + * goto a non-existent label, either a within-extension, + within-context, or in a different context, or in any included + contexts. Will even check "sister" context references. + * All the checks done on the time values in the dial plan, are + done on the time values in the ifTime() and includes times: + o the time range has to have two times separated by a dash; + o the times have to be in range of 0 to 24 hours. + o The weekdays have to match the internal list, if they are provided; + o the day of the month, if provided, must be in range of 1 to 31; + o the month name or names have to match those in the internal list. + * (0.5) If an expression is wrapped in $[ ... ], and the compiler + will wrap it again, a warning is issued. + * (0.5) If an expression had operators (you know, + +,-,*,/,%,!,etc), but no ${ } variables, a warning is + issued. Maybe someone forgot to wrap a variable name? + * (0.12) check for duplicate context names. + * (0.12) check for abstract contexts that are not included by any context. + * (0.13) Issue a warning if a label is a numeric value. + +There are a subset of checks that have been removed until the proposed +AAL (Asterisk Argument Language) is developed and incorporated into Asterisk. +These checks will be: + + * (if the application argument analyzer is working: the presence + of the 'j' option is reported as error. + * if options are specified, that are not available in an + application. + * if you specify too many arguments to an application. + * a required argument is not present in an application call. + * Switch-case using "known" variables that applications set, that + does not cover all the possible values. (a "default" case will + solve this problem. Each "unhandled" value is listed. + * a Switch construct is used, which is uses a known variable, and + the application that would set that variable is not called in + the same extension. This is a warning only... + * Calls to applications not in the "applist" database (installed + in /var/lib/asterisk/applist" on most systems). + * In an assignment statement, if the assignment is to a function, + the function name used is checked to see if it one of the + currently known functions. A warning is issued if it is not. + + + +Differences with the original version of AEL +============================================ + + 1. The $[...] expressions have been enhanced to include the ==, ||, + and && operators. These operators are exactly equivalent to the + =, |, and & operators, respectively. Why? So the C, Java, C++ + hackers feel at home here. + 2. It is more free-form. The newline character means very little, + and is pulled out of the white-space only for line numbers in + error messages. + 3. It generates more error messages -- by this I mean that any + difference between the input and the grammar are reported, by + file, line number, and column. + 4. It checks the contents of $[ ] expressions (or what will end up + being $[ ] expressions!) for syntax errors. It also does + matching paren/bracket counts. + 5. It runs several semantic checks after the parsing is over, but + before the compiling begins, see the list above. + 6. It handles #include "filepath" directives. -- ALMOST + anywhere, in fact. You could easily include a file in a context, + in an extension, or at the root level. Files can be included in + files that are included in files, down to 50 levels of hierarchy... + 7. Local Goto's inside Switch statements automatically have the + extension of the location of the switch statement appended to them. + 8. A pretty printer function is available within pbx_ael.so. + 9. In the utils directory, two standalone programs are supplied for + debugging AEL files. One is called "aelparse", and it reads in + the /etc/asterisk/extensions.ael file, and shows the results of + syntax and semantic checking on stdout, and also shows the + results of compilation to stdout. The other is "aelparse1", + which uses the original ael compiler to do the same work, + reading in "/etc/asterisk/extensions.ael", using the original + 'pbx_ael.so' instead. + 10. AEL supports the "jump" statement, and the "pattern" statement + in switch constructs. Hopefully these will be documented in the + AEL README. + 11. Added the "return" keyword, which will jump to the end of an + extension/Macro. + 12. Added the ifTime (<time range>|<days of week>|<days of + month>|<months> ) {} [else {}] construct, which executes much + like an if () statement, but the decision is based on the + current time, and the time spec provided in the ifTime. See the + example above. (Note: all the other time-dependent Applications + can be used via ifTime) + 13. Added the optional time spec to the contexts in the includes + construct. See examples above. + 14. You don't have to wrap a single "true" statement in curly + braces, as in the original AEL. An "else" is attached to the + closest if. As usual, be careful about nested if statements! + When in doubt, use curlies! + 15. Added the syntax [regexten] [hint(channel)] to precede an + extension declaration. See examples above, under + "Extension". The regexten keyword will cause the priorities in + the extension to begin with 2 instead of 1. The hint keyword + will cause its arguments to be inserted in the extension under + the hint priority. They are both optional, of course, but the + order is fixed at the moment-- the regexten must come before the + hint, if they are both present. + 16. Empty case/default/pattern statements will "fall thru" as + expected. (0.6) + 17. A trailing label in an extension, will automatically have a + NoOp() added, to make sure the label exists in the extension on + Asterisk. (0.6) + 18. (0.9) the semicolon is no longer required after a closing brace! + (i.e. "];" ===> "}". You can have them there if you like, but + they are not necessary. Someday they may be rejected as a syntax + error, maybe. + 19. (0.9) the // comments are not recognized and removed in the + spots where expressions are gathered, nor in application call + arguments. You may have to move a comment if you get errors in + existing files. + 20. (0.10) the random statement has been added. Syntax: random ( + <expr> ) <lucky-statement> [ else <unlucky-statement> ]. The + probability of the lucky-statement getting executed is <expr>, + which should evaluate to an integer between 0 and 100. If the + <lucky-statement> isn't so lucky this time around, then the + <unlucky-statement> gets executed, if it is present. + + + +Hints and Bugs +============== + + * The safest way to check for a null strings is to say $[ "${x}" = + "" ] The old way would do as shell scripts often do, and append + something on both sides, like this: $[ ${x}foo = foo ]. The + trouble with the old way, is that, if x contains any spaces, then + problems occur, usually syntax errors. It is better practice and + safer wrap all such tests with double quotes! Also, there are now + some functions that can be used in a variable reference, + ISNULL(), and LEN(), that can be used to test for an empty string: + ${ISNULL(${x})} or $[ ${LEN(${x}) = 0 ]. + + * Assignment vs. Set(). Keep in mind that setting a variable to + value can be done two different ways. If you choose say 'x=y;', + keep in mind that AEL will wrap the right-hand-side with + $[]. So, when compiled into extension language format, the end + result will be 'Set(x=$[y])'. If you don't want this effect, + then say "Set(x=y);" instead. + + +The Full Power of AEL +============================== + +A newcomer to Asterisk will look at the above constructs and +descriptions, and ask, "Where's the string manipulation functions?", +"Where's all the cool operators that other languages have to offer?", +etc. + +The answer is that the rich capabilities of Asterisk are made +available through AEL, via: + + * Applications: See Asterisk - documentation of application + commands + + * Functions: Functions were implemented inside ${ .. } variable + references, and supply many useful capabilities. + + * Expressions: An expression evaluation engine handles items + wrapped inside $[...]. This includes some string manipulation + facilities, arithmetic expressions, etc. + + * Application Gateway Interface: Asterisk can fork external + processes that communicate via pipe. AGI applications can be + written in any language. Very powerful applications can be added + this way. + + * Variables: Channels of communication have variables associated + with them, and asterisk provides some global variables. These can be + manipulated and/or consulted by the above mechanisms. + diff --git a/1.4.23-rc4/doc/ajam.txt b/1.4.23-rc4/doc/ajam.txt new file mode 100644 index 000000000..d3babd0c2 --- /dev/null +++ b/1.4.23-rc4/doc/ajam.txt @@ -0,0 +1,91 @@ +Asynchronous Javascript Asterisk Manger (AJAM) +============================================== + +AJAM is a new technology which allows web browsers or other HTTP enabled +applications and web pages to directly access the Asterisk Manger +Interface (AMI) via HTTP. Setting up your server to process AJAM +involves a few steps: + +Setup the Asterisk HTTP server +------------------------------ + +1) Uncomment the line "enabled=yes" in /etc/asterisk/http.conf to enable + Asterisk's builtin micro HTTP server. + +2) If you want Asterisk to actually deliver simple HTML pages, CSS, + javascript, etc. you should uncomment "enablestatic=yes" + +3) Adjust your "bindaddr" and "bindport" settings as appropriate for + your desired accessibility + +4) Adjust your "prefix" if appropriate, which must be the beginning of + any URI on the server to match. The default is "asterisk" and the + rest of these instructions assume that value. + +Allow Manager Access via HTTP +----------------------------- + +1) Make sure you have both "enabled = yes" and "webenabled = yes" setup + in /etc/asterisk/manager.conf + +2) You may also use "httptimeout" to set a default timeout for HTTP + connections. + +3) Make sure you have a manager username/secret + +Once those configurations are complete you can reload or restart +Asterisk and you should be able to point your web browser to specific +URI's which will allow you to access various web functions. A complete +list can be found by typing "show http" at the Asterisk CLI. + +examples: + +http://localhost:8088/asterisk/manager?action=login&username=foo&secret=bar + +This logs you into the manager interface's "HTML" view. Once you're +logged in, Asterisk stores a cookie on your browser (valid for the +length of httptimeout) which is used to connect to the same session. + +http://localhost:8088/asterisk/rawman?action=status + +Assuming you've already logged into manager, this URI will give you a +"raw" manager output for the "status" command. + +http://localhost:8088/asterisk/mxml?action=status + +This will give you the same status view but represented as AJAX data, +theoretically compatible with RICO (http://www.openrico.org). + +http://localhost:8088/asterisk/static/ajamdemo.html + +If you have enabled static content support and have done a make install, +Asterisk will serve up a demo page which presents a live, but very +basic, "astman" like interface. You can login with your username/secret +for manager and have a basic view of channels as well as transfer and +hangup calls. It's only tested in Firefox, but could probably be made +to run in other browsers as well. + +A sample library (astman.js) is included to help ease the creation of +manager HTML interfaces. + +Note that for the demo, there is no need for *any* external web server. + +Integration with other web servers +---------------------------------- + +Asterisk's micro HTTP server is *not* designed to replace a general +purpose web server and it is intentionally created to provide only the +minimal interfaces required. Even without the addition of an external +web server, one can use Asterisk's interfaces to implement screen pops +and similar tools pulling data from other web servers using iframes, +div's etc. If you want to integrate CGI's, databases, PHP, etc. you +will likely need to use a more traditional web server like Apache and +link in your Asterisk micro HTTP server with something like this: + +ProxyPass /asterisk http://localhost:8088/asterisk + +This is a fairly new technology so I'd love to hear if it's useful for +you! + +Mark + diff --git a/1.4.23-rc4/doc/app-sms.txt b/1.4.23-rc4/doc/app-sms.txt new file mode 100644 index 000000000..308376e46 --- /dev/null +++ b/1.4.23-rc4/doc/app-sms.txt @@ -0,0 +1,470 @@ + + * 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 message is queued but not + sent, so regular calls to smsq should be done to pick up any missed + messages + --concurrent + How many concurrent calls to allow (per queue), default 1 + --mr + -n + Message reference + --pid + -p + Protocol ID + --dcs + Data coding scheme + --udh + Specific hex string of user data header specified (not including the + initial length byte) + May be a blank string to indicate header is included in the user data + already but user data header indication to be set. + --srr + Status report requested + --rp + Return path requested + --vp + Specify validity period (seconds) + --scts + Specify timestamp (YYYY-MM-DDTHH:MM:SS) + --spool-dir + Spool dir (in which sms and outgoing are found) + Default /var/spool/asterisk + + Other arguments starting '-' or '--' are invalid and will cause an + error. Any trailing arguments are processed as follows:- + * If the message is mobile originating and no destination address + has been specified, then the first argument is assumed to be a + destination address + * If the message is mobile terminating and no destination address + has been specified, then the first argument is assumed to be the + queue name + * If there is no user data, or user data file specified, then any + following arguments are assumed to be the message, which are + concatenated. + * If no user data is specified, then no message is sent. However, + unless --no-dial is specified, smsq checks for pending messages + and generates an outgoing anyway + + Note that when smsq attempts to make a file in + /var/spool/asterisk/outgoing, it checks if there is already a call + queued for that queue. It will try several filenames, up to the + --concurrent setting. If these files exist, then this means Asterisk + is already queued to send all messages for that queue, and so Asterisk + should pick up the message just queued. However, this alone could + create a race condition, so if the files exist then smsq will wait up + to 3 seconds to confirm it still exists or if the queued messages have + been sent already. The --no-wait turns off this behaviour. Basically, + this means that if you have a lot of messages to send all at once, + Asterisk will not make unlimited concurrent calls to the same message + centre or device for the same queue. This is because it is generally + more efficient to make one call and send all of the messages one after + the other. + smsq can be used with no arguments, or with a queue name only, and it + will check for any pending messages and cause an outgoing if there are + any. It only sets up one outgoing call at a time based on the first + queued message it finds. A outgoing call will normally send all queued + messages for that queue. One way to use smsq would be to run with no + queue name (so any queue) every minute or every few seconds to send + pending message. This is not normally necessary unless --no-dial is + selected. Note that smsq does only check motx or mttx depending on the + options selected, so it would need to be called twice as a general + check. + UTF-8 is used to parse command line arguments for user data, and is + the default when reading a file. If an invalid UTF-8 sequence is + found, it is treated as UCS-1 data (i.e, as is). + The --process option causes smsq to scan the specified queue (default + is mtrx) for messages (matching the queue specified, or any if queue + not specified) and run a command and delete the file. The command is + run with a number of environment variables set as follows. Note that + these are unset if not needed and not just taken from the calling + environment. This allows simple processing of incoming messages + + $queue + Set if a queue specified + $?srr + srr is set (to blank) if srr defined and has value 1. + $?rp + rp is set (to blank) if rp defined and has value 1. + $ud + User data, UTF-8 encoding, including any control characters, but with + nulls stripped out + Useful for the content of emails, for example, as it includes any + newlines, etc. + $ude + User data, escaped UTF-8, including all characters, but control + characters \n, \r, \t, \f, \xxx and \ is escaped as \\ + Useful guaranteed one line printable text, so useful in Subject lines + of emails, etc + $ud8 + Hex UCS-1 coding of user data (2 hex digits per character) + Present only if all user data is in range U+0000 to U+00FF + $ud16 + Hex UCS-2 coding of user data (4 hex digits per character) + other + Other fields set using their field name, e.g. mr, pid, dcs, etc. udh + is a hex byte string + +File formats + + By default all queues are held in a director /var/spool/asterisk/sms. + Within this directory are sub directories mtrx, mttx, morx, motx which + hold the received messages and the messages ready to send. Also, + /var/log/asterisk/sms is a log file of all messages handled. + The file name in each queue directory starts with the queue parameter + to SMS which is normally the CLI used for an outgoing message or the + called number on an incoming message, and may have -X (X being sub + address) appended. If no queue ID is known, then 0 is used by smsq by + default. After this is a dot, and then any text. Files are scanned for + matching queue ID and a dot at the start. This means temporary files + being created can be given a different name not starting with a queue + (we recommend a . on the start of the file name for temp files). + Files in these queues are in the form of a simple text file where each + line starts with a keyword and an = and then data. udh and ud have + options for hex encoding, see below. + UTF-8. The user data (ud) field is treated as being UTF-8 encoded + unless the DCS is specified indicating 8 bit format. If 8 bit format + is specified then the user data is sent as is. + The keywords are as follows:- + + 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/1.4.23-rc4/doc/apps.txt b/1.4.23-rc4/doc/apps.txt new file mode 100644 index 000000000..c9696a1a5 --- /dev/null +++ b/1.4.23-rc4/doc/apps.txt @@ -0,0 +1,10 @@ +Asterisk applications register themselves with ast_application_register. +They should have a short, unique name, and an exec function which takes +as its arguments a channel and some data that might be useful for callback +stuff. Remember to keep track of how many and which channels are using +your application so that should the module need to be unloaded +(particularly force unloaded), you will be able to ast_softhangup all the +channels. An application should *never* call ast_hangup on the channel +that it is running on (although it could conceivably hang up other +channels that it allocates). See app_playback.c as an example of a simple +application. diff --git a/1.4.23-rc4/doc/asterisk-conf.txt b/1.4.23-rc4/doc/asterisk-conf.txt new file mode 100644 index 000000000..93c92d680 --- /dev/null +++ b/1.4.23-rc4/doc/asterisk-conf.txt @@ -0,0 +1,89 @@ +Asterisk Main Configuration File +----------------------------------------------------- +Below is a sample of the main Asterisk configuration file, +asterisk.conf. Note that this file is _not_ provided in +sample form, because the Makefile creates it when needed +and does not touch it when it already exists. + +--------------- + +[directories] +; Make sure these directories have the right permissions if not +; running Asterisk as root + +; Where the configuration files (except for this one) are located +astetcdir => /etc/asterisk + +; Where the Asterisk loadable modules are located +astmoddir => /usr/lib/asterisk/modules + +; Where additional 'library' elements (scripts, etc.) are located +astvarlibdir => /var/lib/asterisk + +; Where AGI scripts/programs are located +astagidir => /var/lib/asterisk/agi-bin + +; Where spool directories are located +; Voicemail, monitor, dictation and other apps will create files here +; and outgoing call files (used with pbx_spool) must be placed here +astspooldir => /var/spool/asterisk + +; Where the Asterisk process ID (pid) file should be created +astrundir => /var/run/asterisk + +; Where the Asterisk log files should be created +astlogdir => /var/log/asterisk + + +[options] +;Under "options" you can enter configuration options +;that you also can set with command line options + +verbose = 0 ; Verbosity level for logging (-v) +debug = 3 ; Debug: "No" or value (1-4) +nofork=yes | no ; Background execution disabled (-f) +alwaysfork=yes | no ; Always background, even with -v or -d (-F) +console= yes | no ; Console mode (-c) +highpriority = yes | no ; Execute with high priority (-p) +initcrypto = yes | no ; Initialize crypto at startup (-i) +nocolor = yes | no ; Disable ANSI colors (-n) +dumpcore = yes | no ; Dump core on failure (-g) +quiet = yes | no ; Run quietly (-q) +timestamp = yes | no ; Force timestamping in CLI verbose output (-T) +runuser = asterisk ; User to run asterisk as (-U) NOTE: will require changes to + ; directory and device permissions +rungroup = asterisk ; Group to run asterisk as (-G) +internal_timing = yes | no ; Enable internal timing support (-I) + +;These options have no command line equivalent +cache_record_files = yes | no ; Cache record() files in another directory until completion +record_cache_dir = <dir> +transcode_via_sln = yes | no ; Build transcode paths via SLINEAR +transmit_silence_during_record = yes | no ; send SLINEAR silence while channel is being recorded +maxload = 1.0 ; The maximum load average we accept calls for +maxcalls = 255 ; The maximum number of concurrent calls you want to allow +execincludes = yes | no ; Allow #exec entries in configuration files +dontwarn = yes | no ; Don't over-inform the Asterisk sysadm, he's a guru +systemname = <a_string> ; System name. Used to prefix CDR uniqueid and to fill ${SYSTEMNAME} +languageprefix = yes | no ; Should language code be last component of sound file name or first? + ; when off, sound files are searched as <path>/<lang>/<file> + ; when on, sound files are search as <lang>/<path>/<file> + ; (only affects + relative paths for + sound files) +dahdichanname = yes | no ; Should channels created by chan_dahdi be called 'DAHDI' or 'Zap'; + ; defaults to 'DAHDI' if built against DAHDI, and 'Zap' if built + ; against Zaptel; also used by other applications so that they will + ; know what channel name to expect + +[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/1.4.23-rc4/doc/asterisk-mib.txt b/1.4.23-rc4/doc/asterisk-mib.txt new file mode 100644 index 000000000..a635347b1 --- /dev/null +++ b/1.4.23-rc4/doc/asterisk-mib.txt @@ -0,0 +1,748 @@ +ASTERISK-MIB DEFINITIONS ::= BEGIN + +IMPORTS + OBJECT-TYPE, MODULE-IDENTITY, Integer32, Counter32, TimeTicks, + Unsigned32, Gauge32 + FROM SNMPv2-SMI + + TEXTUAL-CONVENTION, DisplayString, TruthValue + FROM SNMPv2-TC + + digium + FROM DIGIUM-MIB; + +asterisk MODULE-IDENTITY + LAST-UPDATED "200806202025Z" + ORGANIZATION "Digium, Inc." + CONTACT-INFO + "Mark A. Spencer + Postal: Digium, Inc. + 445 Jan Davis Drive + Huntsville, AL 35806 + USA + Tel: +1 256 428 6000 + Email: markster@digium.com + + Thorsten Lockert + Postal: Voop AS + Boehmergaten 42 + NO-5057 Bergen + Norway + Tel: +47 5598 7200 + Email: tholo@voop.no" + DESCRIPTION + "Asterisk is an Open Source PBX. This MIB defined + objects for managing Asterisk instances." + REVISION "200806202025Z" + DESCRIPTION + "smilint police -- + Add missing imports; fix initial capitalization + of enumeration elements; add missing range + restrictions for Integer32 indices, correct + spelling of astChanCidANI in its definition. + Addresses bug 12905. - jeffg@opennms.org" + REVISION "200603061840Z" + DESCRIPTION + "Change audio codec identification from 3kAudio to + Audio3k to conform better with specification. + + Expand on contact information." + REVISION "200602041900Z" + DESCRIPTION + "Initial published revision." + ::= { digium 1 } + +asteriskVersion OBJECT IDENTIFIER ::= { asterisk 1 } +asteriskConfiguration OBJECT IDENTIFIER ::= { asterisk 2 } +asteriskModules OBJECT IDENTIFIER ::= { asterisk 3 } +asteriskIndications OBJECT IDENTIFIER ::= { asterisk 4 } +asteriskChannels OBJECT IDENTIFIER ::= { asterisk 5 } + +-- asteriskVersion + +astVersionString OBJECT-TYPE + SYNTAX DisplayString + MAX-ACCESS read-only + STATUS current + DESCRIPTION + "Text version string of the version of Asterisk that + the SNMP Agent was compiled to run against." + ::= { asteriskVersion 1 } + +astVersionTag OBJECT-TYPE + SYNTAX Unsigned32 + MAX-ACCESS read-only + STATUS current + DESCRIPTION + "SubVersion revision of the version of Asterisk that + the SNMP Agent was compiled to run against -- this is + typically 0 for release-versions of Asterisk." + ::= { asteriskVersion 2 } + +-- asteriskConfiguration + +astConfigUpTime OBJECT-TYPE + SYNTAX TimeTicks + MAX-ACCESS read-only + STATUS current + DESCRIPTION + "Time ticks since Asterisk was started." + ::= { asteriskConfiguration 1 } + +astConfigReloadTime OBJECT-TYPE + SYNTAX TimeTicks + MAX-ACCESS read-only + STATUS current + DESCRIPTION + "Time ticks since Asterisk was last reloaded." + ::= { asteriskConfiguration 2 } + +astConfigPid OBJECT-TYPE + SYNTAX Integer32 + MAX-ACCESS read-only + STATUS current + DESCRIPTION + "The process id of the running Asterisk process." + ::= { asteriskConfiguration 3 } + +astConfigSocket OBJECT-TYPE + SYNTAX DisplayString + MAX-ACCESS read-only + STATUS current + DESCRIPTION + "The control socket for giving Asterisk commands." + ::= { asteriskConfiguration 4 } + +-- asteriskModules + +astNumModules OBJECT-TYPE + SYNTAX Integer32 + MAX-ACCESS read-only + STATUS current + DESCRIPTION + "Number of modules currently loaded into Asterisk." + ::= { asteriskModules 1 } + +-- asteriskIndications + +astNumIndications OBJECT-TYPE + SYNTAX Integer32 + MAX-ACCESS read-only + STATUS current + DESCRIPTION + "Number of indications currently defined in Asterisk." + ::= { asteriskIndications 1 } + +astCurrentIndication OBJECT-TYPE + SYNTAX DisplayString + MAX-ACCESS read-only + STATUS current + DESCRIPTION + "Default indication zone to use." + ::= { asteriskIndications 2 } + +astIndicationsTable OBJECT-TYPE + SYNTAX SEQUENCE OF AstIndicationsEntry + MAX-ACCESS not-accessible + STATUS current + DESCRIPTION + "Table with all the indication zones currently know to + the running Asterisk instance." + ::= { asteriskIndications 3 } + +astIndicationsEntry OBJECT-TYPE + SYNTAX AstIndicationsEntry + MAX-ACCESS not-accessible + STATUS current + DESCRIPTION + "Information about a single indication zone." + INDEX { astIndIndex } + ::= { astIndicationsTable 1 } + +AstIndicationsEntry ::= SEQUENCE { + astIndIndex Integer32, + astIndCountry DisplayString, + astIndAlias DisplayString, + astIndDescription DisplayString +} + +astIndIndex OBJECT-TYPE + SYNTAX Integer32 (1 .. 2147483647) + MAX-ACCESS read-only + STATUS current + DESCRIPTION + "Numerical index into the table of indication zones." + ::= { astIndicationsEntry 1 } + +astIndCountry OBJECT-TYPE + SYNTAX DisplayString + MAX-ACCESS read-only + STATUS current + DESCRIPTION + "Country for which the indication zone is valid, + typically this is the ISO 2-letter code of the country." + ::= { astIndicationsEntry 2 } + +astIndAlias OBJECT-TYPE + SYNTAX DisplayString + MAX-ACCESS read-only + STATUS current + DESCRIPTION + "" + ::= { astIndicationsEntry 3 } + +astIndDescription OBJECT-TYPE + SYNTAX DisplayString + MAX-ACCESS read-only + STATUS current + DESCRIPTION + "Description of the indication zone, usually the full + name of the country it is valid for." + ::= { astIndicationsEntry 4 } + +-- asteriskChannels + +astNumChannels OBJECT-TYPE + SYNTAX Integer32 + MAX-ACCESS read-only + STATUS current + DESCRIPTION + "Current number of active channels." + ::= { asteriskChannels 1 } + +astChanTable OBJECT-TYPE + SYNTAX SEQUENCE OF AstChanEntry + MAX-ACCESS not-accessible + STATUS current + DESCRIPTION + "Table with details of the currently active channels + in the Asterisk instance." + ::= { asteriskChannels 2 } + +astChanEntry OBJECT-TYPE + SYNTAX AstChanEntry + MAX-ACCESS not-accessible + STATUS current + DESCRIPTION + "Details of a single channel." + INDEX { astChanIndex } + ::= { astChanTable 1 } + +AstChanEntry ::= SEQUENCE { + astChanIndex Integer32, + astChanName DisplayString, + astChanLanguage DisplayString, + astChanType DisplayString, + astChanMusicClass DisplayString, + astChanBridge DisplayString, + astChanMasq DisplayString, + astChanMasqr DisplayString, + astChanWhenHangup TimeTicks, + astChanApp DisplayString, + astChanData DisplayString, + astChanContext DisplayString, + astChanMacroContext DisplayString, + astChanMacroExten DisplayString, + astChanMacroPri Integer32, + astChanExten DisplayString, + astChanPri Integer32, + astChanAccountCode DisplayString, + astChanForwardTo DisplayString, + astChanUniqueId DisplayString, + astChanCallGroup Unsigned32, + astChanPickupGroup Unsigned32, + astChanState INTEGER, + astChanMuted TruthValue, + astChanRings Integer32, + astChanCidDNID DisplayString, + astChanCidNum DisplayString, + astChanCidName DisplayString, + astChanCidANI DisplayString, + astChanCidRDNIS DisplayString, + astChanCidPresentation DisplayString, + astChanCidANI2 Integer32, + astChanCidTON Integer32, + astChanCidTNS Integer32, + astChanAMAFlags INTEGER, + astChanADSI INTEGER, + astChanToneZone DisplayString, + astChanHangupCause INTEGER, + astChanVariables DisplayString, + astChanFlags BITS, + astChanTransferCap INTEGER +} + +astChanIndex OBJECT-TYPE + SYNTAX Integer32 (1 .. 2147483647) + MAX-ACCESS read-only + STATUS current + DESCRIPTION + "Index into the channel table." + ::= { astChanEntry 1 } + +astChanName OBJECT-TYPE + SYNTAX DisplayString + MAX-ACCESS read-only + STATUS current + DESCRIPTION + "Name of the current channel." + ::= { astChanEntry 2 } + +astChanLanguage OBJECT-TYPE + SYNTAX DisplayString + MAX-ACCESS read-only + STATUS current + DESCRIPTION + "Which language the current channel is configured to + use -- used mainly for prompts." + ::= { astChanEntry 3 } + +astChanType OBJECT-TYPE + SYNTAX DisplayString + MAX-ACCESS read-only + STATUS current + DESCRIPTION + "Underlying technology for the current channel." + ::= { astChanEntry 4 } + +astChanMusicClass OBJECT-TYPE + SYNTAX DisplayString + MAX-ACCESS read-only + STATUS current + DESCRIPTION + "Music class to be used for Music on Hold for this + channel." + ::= { astChanEntry 5 } + +astChanBridge OBJECT-TYPE + SYNTAX DisplayString + MAX-ACCESS read-only + STATUS current + DESCRIPTION + "Which channel this channel is currently bridged (in a + conversation) with." + ::= { astChanEntry 6 } + +astChanMasq OBJECT-TYPE + SYNTAX DisplayString + MAX-ACCESS read-only + STATUS current + DESCRIPTION + "Channel masquerading for us." + ::= { astChanEntry 7 } + +astChanMasqr OBJECT-TYPE + SYNTAX DisplayString + MAX-ACCESS read-only + STATUS current + DESCRIPTION + "Channel we are masquerading for." + ::= { astChanEntry 8 } + +astChanWhenHangup OBJECT-TYPE + SYNTAX TimeTicks + MAX-ACCESS read-only + STATUS current + DESCRIPTION + "How long until this channel will be hung up." + ::= { astChanEntry 9 } + +astChanApp OBJECT-TYPE + SYNTAX DisplayString + MAX-ACCESS read-only + STATUS current + DESCRIPTION + "Current application for the channel." + ::= { astChanEntry 10 } + +astChanData OBJECT-TYPE + SYNTAX DisplayString + MAX-ACCESS read-only + STATUS current + DESCRIPTION + "Arguments passed to the current application." + ::= { astChanEntry 11 } + +astChanContext OBJECT-TYPE + SYNTAX DisplayString + MAX-ACCESS read-only + STATUS current + DESCRIPTION + "Current extension context." + ::= { astChanEntry 12 } + +astChanMacroContext OBJECT-TYPE + SYNTAX DisplayString + MAX-ACCESS read-only + STATUS current + DESCRIPTION + "Current macro context." + ::= { astChanEntry 13 } + +astChanMacroExten OBJECT-TYPE + SYNTAX DisplayString + MAX-ACCESS read-only + STATUS current + DESCRIPTION + "Current macro extension." + ::= { astChanEntry 14 } + +astChanMacroPri OBJECT-TYPE + SYNTAX Integer32 + MAX-ACCESS read-only + STATUS current + DESCRIPTION + "Current macro priority." + ::= { astChanEntry 15 } + +astChanExten OBJECT-TYPE + SYNTAX DisplayString + MAX-ACCESS read-only + STATUS current + DESCRIPTION + "Current extension." + ::= { astChanEntry 16 } + +astChanPri OBJECT-TYPE + SYNTAX Integer32 + MAX-ACCESS read-only + STATUS current + DESCRIPTION + "Current priority." + ::= { astChanEntry 17 } + +astChanAccountCode OBJECT-TYPE + SYNTAX DisplayString + MAX-ACCESS read-only + STATUS current + DESCRIPTION + "Account Code for billing." + ::= { astChanEntry 18 } + +astChanForwardTo OBJECT-TYPE + SYNTAX DisplayString + MAX-ACCESS read-only + STATUS current + DESCRIPTION + "Where to forward to if asked to dial on this + interface." + ::= { astChanEntry 19 } + +astChanUniqueId OBJECT-TYPE + SYNTAX DisplayString + MAX-ACCESS read-only + STATUS current + DESCRIPTION + "Unique Channel Identifier." + ::= { astChanEntry 20 } + +astChanCallGroup OBJECT-TYPE + SYNTAX Unsigned32 + MAX-ACCESS read-only + STATUS current + DESCRIPTION + "Call Group." + ::= { astChanEntry 21 } + +astChanPickupGroup OBJECT-TYPE + SYNTAX Unsigned32 + MAX-ACCESS read-only + STATUS current + DESCRIPTION + "Pickup Group." + ::= { astChanEntry 22 } + +astChanState OBJECT-TYPE + SYNTAX INTEGER { + stateDown(0), + stateReserved(1), + stateOffHook(2), + stateDialing(3), + stateRing(4), + stateRinging(5), + stateUp(6), + stateBusy(7), + stateDialingOffHook(8), + statePreRing(9) + } + MAX-ACCESS read-only + STATUS current + DESCRIPTION + "Channel state." + ::= { astChanEntry 23 } + +astChanMuted OBJECT-TYPE + SYNTAX TruthValue + MAX-ACCESS read-only + STATUS current + DESCRIPTION + "Transmission of voice data has been muted." + ::= { astChanEntry 24 } + +astChanRings OBJECT-TYPE + SYNTAX Integer32 + MAX-ACCESS read-only + STATUS current + DESCRIPTION + "Number of rings so far." + ::= { astChanEntry 25 } + +astChanCidDNID OBJECT-TYPE + SYNTAX DisplayString + MAX-ACCESS read-only + STATUS current + DESCRIPTION + "Dialled Number ID." + ::= { astChanEntry 26 } + +astChanCidNum OBJECT-TYPE + SYNTAX DisplayString + MAX-ACCESS read-only + STATUS current + DESCRIPTION + "Caller Number." + ::= { astChanEntry 27 } + +astChanCidName OBJECT-TYPE + SYNTAX DisplayString + MAX-ACCESS read-only + STATUS current + DESCRIPTION + "Caller Name." + ::= { astChanEntry 28 } + +astChanCidANI OBJECT-TYPE + SYNTAX DisplayString + MAX-ACCESS read-only + STATUS current + DESCRIPTION + "ANI" + ::= { astChanEntry 29 } + +astChanCidRDNIS OBJECT-TYPE + SYNTAX DisplayString + MAX-ACCESS read-only + STATUS current + DESCRIPTION + "Redirected Dialled Number Service." + ::= { astChanEntry 30 } + +astChanCidPresentation OBJECT-TYPE + SYNTAX DisplayString + MAX-ACCESS read-only + STATUS current + DESCRIPTION + "Number Presentation/Screening." + ::= { astChanEntry 31 } + +astChanCidANI2 OBJECT-TYPE + SYNTAX Integer32 + MAX-ACCESS read-only + STATUS current + DESCRIPTION + "ANI 2 (info digit)." + ::= { astChanEntry 32 } + +astChanCidTON OBJECT-TYPE + SYNTAX Integer32 + MAX-ACCESS read-only + STATUS current + DESCRIPTION + "Type of Number." + ::= { astChanEntry 33 } + +astChanCidTNS OBJECT-TYPE + SYNTAX Integer32 + MAX-ACCESS read-only + STATUS current + DESCRIPTION + "Transit Network Select." + ::= { astChanEntry 34 } + +astChanAMAFlags OBJECT-TYPE + SYNTAX INTEGER { + default(0), + omit(1), + billing(2), + documentation(3) + } + MAX-ACCESS read-only + STATUS current + DESCRIPTION + "AMA Flags." + ::= { astChanEntry 35 } + +astChanADSI OBJECT-TYPE + SYNTAX INTEGER { + unknown(0), + available(1), + unavailable(2), + offHookOnly(3) + } + MAX-ACCESS read-only + STATUS current + DESCRIPTION + "Whether or not ADSI is detected on CPE." + ::= { astChanEntry 36 } + +astChanToneZone OBJECT-TYPE + SYNTAX DisplayString + MAX-ACCESS read-only + STATUS current + DESCRIPTION + "Indication zone to use for channel." + ::= { astChanEntry 37 } + +astChanHangupCause OBJECT-TYPE + SYNTAX INTEGER { + notDefined(0), + unregistered(3), + normal(16), + busy(17), + noAnswer(19), + congestion(34), + failure(38), + noSuchDriver(66) + } + MAX-ACCESS read-only + STATUS current + DESCRIPTION + "Why is the channel hung up." + ::= { astChanEntry 38 } + +astChanVariables OBJECT-TYPE + SYNTAX DisplayString + MAX-ACCESS read-only + STATUS current + DESCRIPTION + "Channel Variables defined for this channel." + ::= { astChanEntry 39 } + +astChanFlags OBJECT-TYPE + SYNTAX BITS { + wantsJitter(0), + deferDTMF(1), + writeInterrupt(2), + blocking(3), + zombie(4), + exception(5), + musicOnHold(6), + spying(7), + nativeBridge(8), + autoIncrementingLoop(9) + } + MAX-ACCESS read-only + STATUS current + DESCRIPTION + "Flags set on this channel." + ::= { astChanEntry 40 } + +astChanTransferCap OBJECT-TYPE + SYNTAX INTEGER { + speech(0), + digital(8), + restrictedDigital(9), + audio3k(16), + digitalWithTones(17), + video(24) + } + MAX-ACCESS read-only + STATUS current + DESCRIPTION + "Transfer Capabilities for this channel." + ::= { astChanEntry 41 } + +astNumChanTypes OBJECT-TYPE + SYNTAX Integer32 + MAX-ACCESS read-only + STATUS current + DESCRIPTION + "Number of channel types (technologies) supported." + ::= { asteriskChannels 3 } + +astChanTypeTable OBJECT-TYPE + SYNTAX SEQUENCE OF AstChanTypeEntry + MAX-ACCESS not-accessible + STATUS current + DESCRIPTION + "Table with details of the supported channel types." + ::= { asteriskChannels 4 } + +astChanTypeEntry OBJECT-TYPE + SYNTAX AstChanTypeEntry + MAX-ACCESS not-accessible + STATUS current + DESCRIPTION + "Information about a technology we support, including + how many channels are currently using this technology." + INDEX { astChanTypeIndex } + ::= { astChanTypeTable 1 } + +AstChanTypeEntry ::= SEQUENCE { + astChanTypeIndex Integer32, + astChanTypeName DisplayString, + astChanTypeDesc DisplayString, + astChanTypeDeviceState Integer32, + astChanTypeIndications Integer32, + astChanTypeTransfer Integer32, + astChanTypeChannels Gauge32 +} + +astChanTypeIndex OBJECT-TYPE + SYNTAX Integer32 (1 .. 2147483647) + MAX-ACCESS read-only + STATUS current + DESCRIPTION + "Index into the table of channel types." + ::= { astChanTypeEntry 1 } + +astChanTypeName OBJECT-TYPE + SYNTAX DisplayString + MAX-ACCESS read-only + STATUS current + DESCRIPTION + "Unique name of the technology we are describing." + ::= { astChanTypeEntry 2 } + +astChanTypeDesc OBJECT-TYPE + SYNTAX DisplayString + MAX-ACCESS read-only + STATUS current + DESCRIPTION + "Description of the channel type (technology)." + ::= { astChanTypeEntry 3 } + +astChanTypeDeviceState OBJECT-TYPE + SYNTAX TruthValue + MAX-ACCESS read-only + STATUS current + DESCRIPTION + "Whether the current technology can hold device states." + ::= { astChanTypeEntry 4 } + +astChanTypeIndications OBJECT-TYPE + SYNTAX TruthValue + MAX-ACCESS read-only + STATUS current + DESCRIPTION + "Whether the current technology supports progress indication." + ::= { astChanTypeEntry 5 } + +astChanTypeTransfer OBJECT-TYPE + SYNTAX TruthValue + MAX-ACCESS read-only + STATUS current + DESCRIPTION + "Whether the current technology supports transfers, where + Asterisk can get out from inbetween two bridged channels." + ::= { astChanTypeEntry 6 } + +astChanTypeChannels OBJECT-TYPE + SYNTAX Gauge32 + MAX-ACCESS read-only + STATUS current + DESCRIPTION + "Number of active channels using the current technology." + ::= { astChanTypeEntry 7 } + +END diff --git a/1.4.23-rc4/doc/asterisk.8 b/1.4.23-rc4/doc/asterisk.8 new file mode 100644 index 000000000..9e0e6880f --- /dev/null +++ b/1.4.23-rc4/doc/asterisk.8 @@ -0,0 +1,195 @@ +.\" This manpage has been automatically generated by docbook2man +.\" from a DocBook document. This tool can be found at: +.\" <http://shell.ipoline.com/~elmert/comp/docbook2X/> +.\" Please send any bug reports, improvements, comments, patches, +.\" etc. to Steve Cheng <steve@ggi-project.org>. +.TH "ASTERISK" "8" "25 October 2005" "asterisk 1.2" "" + +.SH NAME +asterisk \- All-purpose telephony server. +.SH SYNOPSIS + +\fBasterisk\fR [ \fB-tThfdvVqpRgciIn\fR ] [ \fB-C \fIfile\fB\fR ] [ \fB-U \fIuser\fB\fR ] [ \fB-G \fIgroup\fB\fR ] [ \fB-x \fIcommand\fB\fR ] [ \fB-M \fIvalue\fB\fR ] + + +\fBasterisk -r\fR [ \fB-v\fR ] [ \fB-x \fIcommand\fB\fR ] + +.SH "DESCRIPTION" +.PP +\fBasterisk\fR is a full-featured telephony server which +provides Private Branch eXchange (PBX), Interactive Voice Response (IVR), +Automated Call Distribution (ACD), Voice over IP (VoIP) gatewaying, +Conferencing, and a plethora of other telephony applications to a broad +range of telephony devices including packet voice (SIP, IAX2, MGCP, Skinny, +H.323) devices (both endpoints and proxies), as well as traditional TDM +hardware including T1, E1, ISDN PRI, GR-303, RBS, Loopstart, Groundstart, +ISDN BRI, and many more. +.PP +At start, Asterisk reads the /etc/asterisk/asterisk.conf main configuration +file and locates the rest of the configuration files from the configuration +in that file. The -C option specifies an alternate main configuration file. +Virtually all aspects of the operation of asterisk's configuration files +can be found in the sample configuration files. The format for those files +is generally beyond the scope of this man page. +.PP +When running with \fB-c\fR, \fB-r\fR or \fB-R\fR +options, Asterisk supplies a powerful command line, including command +completion, which may be used to monitors its status, perform a variety +of administrative actions and even explore the applications that are +currently loaded into the system. +.PP +Asterisk is a trademark of Digium, Inc. +.SH "OPTIONS" +.TP +\fB-C \fIfile\fB\fR +Use \fIfile\fR as master configuration file +instead of the default, /etc/asterisk/asterisk.conf +.TP +\fB-c\fR +Provide a control console on the calling terminal. +Specifying this option implies \fB-f\fR and will cause +asterisk to no longer fork or detach from the controlling terminal. +.TP +\fB-d\fR +Enable extra debugging statements. + +Note: This always sets the debug level in the asterisk process, +even if it is running in the background. This will affect the size +of your log files. +.TP +\fB-f\fR +Do not fork or detach from controlling terminal. +.TP +\fB-g\fR +Remove resource limit on core size, thus forcing Asterisk to dump +core in the unlikely event of a segmentation fault or abort signal. +\fBNOTE:\fR in some cases this may be incompatible +with the \fB-U\fR or \fB-G\fR flags. +.TP +\fB-G \fIgroup\fB\fR +Run as group \fIgroup\fR instead of the +calling group. \fBNOTE:\fR this requires substantial work +to be sure that Asterisk's environment has permission to write +the files required for its operation, including logs, its comm +socket, the asterisk database, etc. +.TP +\fB-h\fR +Provide brief summary of command line arguments and terminate. +.TP +\fB-i\fR +Prompt user to initialize any encrypted private keys for IAX2 +secure authentication during startup. +.TP +\fB-L \fIloadaverage\fB\fR +Limits the maximum load average before rejecting new calls. This can +be useful to prevent a system from being brought down by terminating +too many simultaneous calls. +.TP +\fB-m\fR +Disable log and verbose output to remote (-r) consoles. +.TP +\fB-M \fIvalue\fB\fR +Limits the maximum number of calls to the specified value. This can +be useful to prevent a system from being brought down by terminating +too many simultaneous calls. +.TP +\fB-n\fR +Disable ANSI colors even on terminals capable of displaying them. +.TP +\fB-p\fR +If supported by the operating system (and executing as root), +attempt to run with realtime priority for increased performance and +responsiveness within the Asterisk process, at the expense of other +programs running on the same machine. +.TP +\fB-q\fR +Reduce default console output when running in conjunction with +console mode (\fB-c\fR). +.TP +\fB-r\fR +Instead of running a new Asterisk process, attempt to connect +to a running Asterisk process and provide a console interface +for controlling it. +.TP +\fB-R\fR +Much like \fB-r\fR\&. Instead of running a new Asterisk process, attempt to connect +to a running Asterisk process and provide a console interface +for controlling it. Additionally, if connection to the Asterisk +process is lost, attempt to reconnect for as long as 30 seconds. +.TP +\fB-I\fR +Enable internal timing if Zaptel timer is available +The default behaviour is that outbound packets are phase locked +to inbound packets. Enabling this switch causes them to be +locked to the internal Zaptel timer instead. +.TP +\fB-t\fR +When recording files, write them first into a temporary holding directory, +then move them into the final location when done. +.TP +\fB-T\fR +Add timestamp to all non-command related output going to the console +when running with verbose and/or logging to the console. +.TP +\fB-U \fIuser\fB\fR +Run as user \fIuser\fR instead of the +calling user. \fBNOTE:\fR this requires substantial work +to be sure that Asterisk's environment has permission to write +the files required for its operation, including logs, its comm +socket, the asterisk database, etc. +.TP +\fB-v\fR +Increase the level of verboseness on the console. The more times +\fB-v\fR is specified, the more verbose the output is. +Specifying this option implies \fB-f\fR and will cause +asterisk to no longer fork or detach from the controlling terminal. +This option may also be used in conjunction with \fB-r\fR +and \fB-R\fR\&. + +Note: This always sets the verbose level in the asterisk process, +even if it is running in the background. This will affect the size +of your log files. +.TP +\fB-V\fR +Display version information and exit immediately. +.TP +\fB-x \fIcommand\fB\fR +Connect to a running Asterisk process and execute a command on +a command line, passing any output through to standard out and +then terminating when the command execution completes. Implies +\fB-r\fR when \fB-R\fR is not explicitly +supplied. +.SH "EXAMPLES" +.PP +\fBasterisk\fR - Begin Asterisk as a daemon +.PP +\fBasterisk -vvvgc\fR - Run on controlling terminal +.PP +\fBasterisk -rx "core show channels"\fR - Display channels on running server +.SH "BUGS" +.PP +Bug reports and feature requests may be filed at http://bugs.digium.com +.SH "SEE ALSO" +.PP +*CLI> \fBhelp\fR - Help on Asterisk CLI +.PP +*CLI> \fBcore show applications\fR - Show loaded dialplan applications +.PP +*CLI> \fBcore show functions\fR - Show loaded dialplan functions +.PP +*CLI> \fBdialplan show\fR - Show current dialplan +.PP +http://www.asterisk.org - The Asterisk Home Page +.PP +http://www.asteriskdocs.org - The Asterisk Documentation Project +.PP +http://www.voip-info.org/wiki-Asterisk - The Asterisk Wiki +.PP +http://www.digium.com/ - Asterisk sponsor and hardware supplier +.PP +http://www.markocam.com/ - Asterisk author's web cam +.SH "AUTHOR" +.PP +Mark Spencer <markster@digium.com> +.PP +Countless other contributors, see CREDITS with distribution for more information diff --git a/1.4.23-rc4/doc/asterisk.sgml b/1.4.23-rc4/doc/asterisk.sgml new file mode 100644 index 000000000..ff257ff67 --- /dev/null +++ b/1.4.23-rc4/doc/asterisk.sgml @@ -0,0 +1,364 @@ +<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook V4.1//EN"> +<refentry> +<refentryinfo> + <date>2005-10-18</date> +</refentryinfo> +<refmeta> + <refentrytitle> + <application>asterisk</application> + </refentrytitle> + <manvolnum>8</manvolnum> + <refmiscinfo>asterisk 1.2</refmiscinfo> +</refmeta> +<refnamediv> + <refname> + <application>asterisk</application> + </refname> + <refpurpose> + All-purpose telephony server. + </refpurpose> +</refnamediv> +<refsynopsisdiv> + <cmdsynopsis> + <command>asterisk</command> +<arg><option>-tThfdvVqpRgciIn</option></arg> +<arg><option>-C </option><replaceable class="parameter">file</replaceable></arg> +<arg><option>-U </option><replaceable class="parameter">user</replaceable></arg> +<arg><option>-G </option><replaceable class="parameter">group</replaceable></arg> +<arg><option>-x </option><replaceable class="parameter">command</replaceable></arg> +<arg><option>-M </option><replaceable class="parameter">value</replaceable></arg> +<arg><option>-L </option><replaceable class="parameter">loadaverage</replaceable></arg> + </cmdsynopsis> + <cmdsynopsis> + + <command>asterisk -r</command> + <arg><option>-v</option></arg> +<arg><option>-x </option><replaceable class="parameter">command</replaceable></arg> + </cmdsynopsis> +</refsynopsisdiv> +<refsect1> + <refsect1info> + <date>2006-03-29</date> + </refsect1info> + <title>DESCRIPTION</title> + <para> + <command>asterisk</command> is a full-featured telephony server which + provides Private Branch eXchange (PBX), Interactive Voice Response (IVR), + Automated Call Distribution (ACD), Voice over IP (VoIP) gatewaying, + Conferencing, and a plethora of other telephony applications to a broad + range of telephony devices including packet voice (SIP, IAX2, MGCP, Skinny, + H.323) devices (both endpoints and proxies), as well as traditional TDM + hardware including T1, E1, ISDN PRI, GR-303, RBS, Loopstart, Groundstart, + ISDN BRI, and many more. + </para> + <para> + At start, Asterisk reads the /etc/asterisk/asterisk.conf main configuration + file and locates the rest of the configuration files from the configuration + in that file. The -C option specifies an alternate main configuration file. + Virtually all aspects of the operation of asterisk's configuration files + can be found in the sample configuration files. The format for those files + is generally beyond the scope of this man page. + </para> + <para> + When running with <command>-c</command>, <command>-r</command> or <command>-R</command> + options, Asterisk supplies a powerful command line, including command + completion, which may be used to monitors its status, perform a variety + of administrative actions and even explore the applications that are + currently loaded into the system. + </para> + <para> + Asterisk is a trademark of Digium, Inc. + </para> +</refsect1> +<refsect1> + <title>OPTIONS</title> + <variablelist> + <varlistentry> + <term>-C <replaceable class="parameter">file</replaceable></term> + <listitem> + <para> + Use <filename>file</filename> as master configuration file + instead of the default, /etc/asterisk/asterisk.conf + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>-c</term> + <listitem> + <para> + Provide a control console on the calling terminal. + Specifying this option implies <command>-f</command> and will cause + asterisk to no longer fork or detach from the controlling terminal. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>-d</term> + <listitem> + <para> + Enable extra debugging statements. + </para> + <para> + Note: This always sets the debug level in the asterisk process, + even if it is running in the background. This will affect the size + of your log files. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>-f</term> + <listitem> + <para> + Do not fork or detach from controlling terminal. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>-g</term> + <listitem> + <para> + Remove resource limit on core size, thus forcing Asterisk to dump + core in the unlikely event of a segmentation fault or abort signal. + <command>NOTE:</command> in some cases this may be incompatible + with the <command>-U</command> or <command>-G</command> flags. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>-G <replaceable class="parameter">group</replaceable></term> + <listitem> + <para> + Run as group <replaceable>group</replaceable> instead of the + calling group. <command>NOTE:</command> this requires substantial work + to be sure that Asterisk's environment has permission to write + the files required for its operation, including logs, its comm + socket, the asterisk database, etc. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>-h</term> + <listitem> + <para> + Provide brief summary of command line arguments and terminate. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>-i</term> + <listitem> + <para> + Prompt user to intialize any encrypted private keys for IAX2 + secure authentication during startup. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>-I</term> + <listitem> + <para> + Enable internal timing if Zaptel timing is available. + The default behaviour is that outbound packets are phase locked + to inbound packets. Enabling this switch causes them to be + locked to the internal Zaptel timer instead. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>-L <replaceable class="parameter">loadaverage</replaceable></term> + <listitem> + <para> + Limits the maximum load average before rejecting new calls. This can + be useful to prevent a system from being brought down by terminating + too many simultaneous calls. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>-M <replaceable class="parameter">value</replaceable></term> + <listitem> + <para> + Limits the maximum number of calls to the specified value. This can + be useful to prevent a system from being brought down by terminating + too many simultaneous calls. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>-n</term> + <listitem> + <para> + Disable ANSI colors even on terminals capable of displaying them. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>-p</term> + <listitem> + <para> + If supported by the operating system (and executing as root), + attempt to run with realtime priority for increased performance and + responsiveness within the Asterisk process, at the expense of other + programs running on the same machine. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>-q</term> + <listitem> + <para> + Reduce default console output when running in conjunction with + console mode (<command>-c</command>). + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>-r</term> + <listitem> + <para> + Instead of running a new Asterisk process, attempt to connect + to a running Asterisk process and provide a console interface + for controlling it. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>-R</term> + <listitem> + <para> + Much like <command>-r</command>. Instead of running a new Asterisk process, attempt to connect + to a running Asterisk process and provide a console interface + for controlling it. Additionally, if connection to the Asterisk + process is lost, attempt to reconnect for as long as 30 seconds. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>-t</term> + <listitem> + <para> + When recording files, write them first into a temporary holding directory, + then move them into the final location when done. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>-T</term> + <listitem> + <para> + Add timestamp to all non-command related output going to the console + when running with verbose and/or logging to the console. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>-U <replaceable class="parameter">user</replaceable></term> + <listitem> + <para> + Run as user <replaceable>user</replaceable> instead of the + calling user. <command>NOTE:</command> this requires substantial work + to be sure that Asterisk's environment has permission to write + the files required for its operation, including logs, its comm + socket, the asterisk database, etc. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>-v</term> + <listitem> + <para> + Increase the level of verboseness on the console. The more times + <command>-v</command> is specified, the more verbose the output is. + Specifying this option implies <command>-f</command> and will cause + asterisk to no longer fork or detach from the controlling terminal. + This option may also be used in conjunction with <command>-r</command> + and <command>-R</command>. + </para> + <para> + Note: This always sets the verbose level in the asterisk process, + even if it is running in the background. This will affect the size + of your log files. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>-V</term> + <listitem> + <para> + Display version information and exit immediately. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>-x <replaceable class="parameter">command</replaceable></term> + <listitem> + <para> + Connect to a running Asterisk process and execute a command on + a command line, passing any output through to standard out and + then terminating when the command execution completes. Implies + <command>-r</command> when <command>-R</command> is not explicitly + supplied. + </para> + </listitem> + </varlistentry> + </variablelist> +</refsect1> +<refsect1> + <title>EXAMPLES</title> + <para> + <command>asterisk</command> - Begin Asterisk as a daemon + </para> + <para> + <command>asterisk -vvvgc</command> - Run on controlling terminal + </para> + <para> + <command>asterisk -rx "show channels"</command> - Display channels on running server + </para> +</refsect1> +<refsect1> + <title>BUGS</title> + <para> + Bug reports and feature requests may be filed at http://bugs.digium.com + </para> +</refsect1> +<refsect1> + <title>SEE ALSO</title> + <para> + *CLI> <command>help</command> - Help on Asterisk CLI + </para> + <para> + *CLI> <command>show applications</command> - Show loaded dialplan applications + </para> + <para> + *CLI> <command>show functions</command> - Show loaded dialplan functions + </para> + <para> + http://www.asterisk.org - The Asterisk Home Page + </para> + <para> + http://www.asteriskdocs.org - The Asterisk Documentation Project + </para> + <para> + http://www.voip-info.org/wiki-Asterisk - The Asterisk Wiki + </para> + <para> + http://www.digium.com/ - Asterisk sponsor and hardware supplier + </para> + <para> + http://www.markocam.com/ - Asterisk author's web cam + </para> +</refsect1> +<refsect1> + <title>AUTHOR</title> + <para> + <author> + <firstname>Mark Spencer <markster@digium.com></firstname> + </author> + </para> + <para> + <author> + <firstname>Countless other contributers, see CREDITS with distribution for more information</firstname> + </author> + </para> +</refsect1> +</refentry> diff --git a/1.4.23-rc4/doc/backtrace.txt b/1.4.23-rc4/doc/backtrace.txt new file mode 100644 index 000000000..ce39b0a3e --- /dev/null +++ b/1.4.23-rc4/doc/backtrace.txt @@ -0,0 +1,197 @@ +This document is intended 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 selecting the 'DONT_OPTIMIZE' option in the Compiler Flags +submenu in the 'make menuselect' tree before building Asterisk. + +After Asterisk crashes, a core file will be "dumped" in your /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# + +In the event that there are multiple core files present (as in the +above example), it is important to look at the file timestamps in +order to determine which one you really intend to look at. + +Now that we've verified the core file has been written to disk, the +final part is to extract 'bt' from the core file. Core files are +pretty big, don't be scared, it's normal. + +*** 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 asterisk /tmp/core.26252 +[...] +(You would see a lot of output here.) +[...] +Reading symbols from /usr/lib/asterisk/modules/app_externalivr.so...done. +Loaded symbols for /usr/lib/asterisk/modules/app_externalivr.so +#0 0x29b45d7e in ?? () +(gdb) + +In order to make extracting the gdb output easier, you may wish to +turn on logging using "set logging on". This command will save all +output to the default file of gdb.txt, which in the end can be +uploaded as an attachment to the bug tracker. + +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 be to know all traces by all +threads. Even if asterisk runs on the same thread for each call, it +could have created some new threads. + +To make sure we have the correct information, just do: +(gdb) thread apply all bt + +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 tells us crucial information about each thread. + +Now, if you turned on logging upload your gdb.txt file. Otherwise, +create an output.txt file and dump your "bt full" (and/or "bt") +ALONG WITH "thread apply all bt" into it. + +Note: Please ATTACH your output, DO NOT paste it as a note. + +And you're ready for upload on the bug tracker. + + +If you have questions or comments regarding this documentation, feel +free to pass by the #asterisk-bugs channel on irc.freenode.net. + diff --git a/1.4.23-rc4/doc/billing.txt b/1.4.23-rc4/doc/billing.txt new file mode 100644 index 000000000..bca6b8fba --- /dev/null +++ b/1.4.23-rc4/doc/billing.txt @@ -0,0 +1,105 @@ +Asterisk billing support - Call Detail Records +---------------------------------------------- +Asterisk generates Call Detail Records in a database or in a comma +separated text file. + + * cdr_csv supports comma separated text file storage, this is the + default driver + * cdr_manager supports CDR information via the AMI, The Asterisk Manager + interface + * cdr_odbc supports UnixODBC databases, see http://www.unixodbc.org + for an updated list of supported databases, from MySQL to MsSQL + and text files. + * cdr_tds supports FreeTDS databases (Among them MS SQL) + NOTE: Please read doc/freetds.txt for information on possible + problems with the FreeTDS driver + * cdr_sqlite supports SQlite + * cdr_pgsql supports PostgreSQL + +In the asterisk-addons subversion repository, there's a cdr_mysql driver for +MySQL. + +Applications +------------ + + * SetAccount Set account code for billing + * SetAMAFlags Sets AMA flags + * NoCDR Make sure no CDR is saved for a specific call + * ResetCDR Reset CDR + * ForkCDR Save current CDR and start a new CDR for this call + * Authenticate Authenticates and sets the account code + * SetCDRUserField Set CDR user field + * AppendCDRUserField Append data to CDR User field + +For more information, use the "show application" command. +You can set default account codes and AMA flags for devices in +channel configuration files, like sip.conf, iax.conf etc. + + +Fields of the CDR in Asterisk +----------------------------- + + 1. accountcode: What account number to use, (string, 20 characters) + 2. src: Caller*ID number (string, 80 characters) + 3. dst: Destination extension (string, 80 characters) + 4. dcontext: Destination context (string, 80 characters) + 5. clid: Caller*ID with text (80 characters) + 6. channel: Channel used (80 characters) + 7. dstchannel: Destination channel if appropriate (80 characters) + 8. lastapp: Last application if appropriate (80 characters) + 9. lastdata: Last application data (arguments) (80 characters) + 10. start: Start of call (date/time) + 11. answer: Answer of call (date/time) + 12. end: End of call (date/time) + 13. duration: Total time in system, in seconds (integer), from dial to hangup + 14. billsec: Total time call is up, in seconds (integer), from answer to hangup + 15. disposition: What happened to the call: ANSWERED, NO ANSWER, BUSY + 16. amaflags: What flags to use: DOCUMENTATION, BILL, IGNORE etc, + specified on a per channel basis like accountcode. + 17. user field: A user-defined field, maximum 255 characters + +In some cases, uniqueid is appended: + + * uniqueid: Unique Channel Identifier (32 characters) + This needs to be enabled in the source code at compile time + + +NOTE: If you use IAX2 channels for your calls, and allow 'full' transfers +(not media-only transfers), then when the calls is transferred the server +in the middle will no longer be involved in the signaling path, and thus +will not generate accurate CDRs for that call. If you can, use media-only +transfers with IAX2 to avoid this problem, or turn off transfers completely +(although this can result in a media latency increase since the media packets +have to traverse the middle server(s) in the call). + +____________________________________ +CDR Variables +------------------------------------ + +If the channel has a cdr, that cdr record has its own set of variables which +can be accessed just like channel variables. The following builtin variables +are available. + +${CDR(clid)} Caller ID +${CDR(src)} Source +${CDR(dst)} Destination +${CDR(dcontext)} Destination context +${CDR(channel)} Channel name +${CDR(dstchannel)} Destination channel +${CDR(lastapp)} Last app executed +${CDR(lastdata)} Last app's arguments +${CDR(start)} Time the call started. +${CDR(answer)} Time the call was answered. +${CDR(end)} Time the call ended. +${CDR(duration)} Duration of the call. +${CDR(billsec)} Duration of the call once it was answered. +${CDR(disposition)} ANSWERED, NO ANSWER, BUSY +${CDR(amaflags)} DOCUMENTATION, BILL, IGNORE etc +${CDR(accountcode)} The channel's account code. +${CDR(uniqueid)} The channel's unique id. +${CDR(userfield)} The channels uses specified field. + +In addition, you can set your own extra variables by using Set(CDR(name)=value). +These variables can be output into a text-format CDR by using the cdr_custom +CDR driver; see the cdr_custom.conf.sample file in the configs directory for +an example of how to do this. diff --git a/1.4.23-rc4/doc/callfiles.txt b/1.4.23-rc4/doc/callfiles.txt new file mode 100644 index 000000000..3fe6cb09e --- /dev/null +++ b/1.4.23-rc4/doc/callfiles.txt @@ -0,0 +1,139 @@ +Asterisk call files +=================== + +Asterisk has the ability to initiate a call from outside of the normal +methods such as the dialplan, manager interface, or spooling interface. + +Using the call file method, you must give Asterisk the following information: + +* How to perform the call, similar to the Dial() application +* What to do when the call is answered + +With call files you submit this information simply by creating a file with +the required syntax and placing it in the outgoing spooling directory, located +by default in /var/spool/asterisk/outgoing/ (configurable in asterisk.conf). + +The pbx_spool module aggressively examines the directory contents every second, +creating a new call for every call file it finds. Do NOT write or create +the call file directly in the outgoing directory, but always create the file +in another directory of the same filesystem and then move the file to the +/var/spool/asterisk/outgoing directory, or Asterisk may read just a partial +file. + + +The call file syntax +==================== + +The call file consists of <Key>: <value> pairs; one per line. + +Comments are indicated by a '#' character that begins a line, or follows a space +or tab character. To be consistent with the configuration files in Asterisk, +comments can also be indicated by a semicolon. However, the multiline comments +(;-- --;) used in Asterisk configuration files are not supported. Semicolons can +be escaped by a backslash. + + +The following keys-value pairs are used to specify how setup a call: + +Channel: <channel> the channel to use for the new call, in the form + technology/resource as in the Dial application. This + value is required. + +Callerid: <callerid> the caller id to use. + +WaitTime: <number> how many seconds to wait for an answer before the call + fails (ring cycle). Default 45 seconds. + +Maxretries: <number> number of retries before failing, not including the + initial attempt. Default = 0 e.g. don't retry if fails. + +RetryTime: <number> how many seconds to wait before retry. The default is + 300 (5 minutes). + +Account: <account> the account code for the call. This value will be + assigned to CDR(accountcode) + + + +When the call answers there are two choices: +* Execute a single application, or +* Execute the dialplan at the specified context/extension/priority. + + +To execute an application: +-------------------------- + +Application: <appname> the application to execute + +Data: <args> the application arguments + + +To start executing applications in the dialplan: +------------------------------------------------ + +Context: <context> the context in the dialplan + +Extension: <exten> the extension in the specified context + +Priority: <priority> the priority of the specified extension + (numeric or label) + + + +Setvar: <var=value> you may also assign values to variables that will be + available to the channel, as if you had performed a + Set(var=value) in the dialplan. More than one Setvar: + maybe specified. + + +The processing of the call file ends when the call is answered and terminated; when +the call was not answered in the initial attempt and subsequent retries; or if +the call file can't be successfully read and parsed. + +To specify what to do with the call file at the end of processing: + +Archive: <yes|no> if "no" the call file is deleted. If set to "yes" the + call file is moved to the "outgoing_done" subdirectory + of the Asterisk spool directory. The default is to + delete the call file. + + +If the call file is archived, Asterisk will append to the call file: + +Status: <exitstatus> can be "Expired", "Completed" or "Failed" + + + +Other lines generated by Asterisk: + +Asterisk keep track of how many retries the call has already attempted, +appending to the call file the following key-pairs in the form: + +StartRetry: <pid> <retrycount> (<time>) +EndRetry: <pid> <retrycount> (<time>) + +With the main process ID (pid) of the Asterisk process, the retry number, and +the attempts start and end times in time_t format. + + + +Directory locations +=================== + +<astspooldir>/outgoing the outgoing dir, where call files are put + for processing + +<astspooldir>/outgoing_done the archive dir + + +<astspooldir> is specified in asterisk.conf, usually /var/spool/asterisk + + + +How to schedule a call +====================== + +Call files that have the time of the last modification in the future are ignored +by Asterisk. This makes it possible to modify the time of a call file to the +wanted time, move to the outgoing directory, and Asterisk will attempt to +create the call at that time. diff --git a/1.4.23-rc4/doc/callingpres.txt b/1.4.23-rc4/doc/callingpres.txt new file mode 100644 index 000000000..0fa1ff469 --- /dev/null +++ b/1.4.23-rc4/doc/callingpres.txt @@ -0,0 +1,18 @@ +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/1.4.23-rc4/doc/cdrdriver.txt b/1.4.23-rc4/doc/cdrdriver.txt new file mode 100644 index 000000000..809245c77 --- /dev/null +++ b/1.4.23-rc4/doc/cdrdriver.txt @@ -0,0 +1,216 @@ +Call data records can be stored in many different databases or even CSV text. + +MSSQL: Asterisk can currently store CDRs into an MSSQL database in + two different ways: cdr_odbc.c or cdr_tds.c + + Call Data Records can be stored using unixODBC (which requires + the FreeTDS package) [cdr_odbc.c] or directly by using just the + FreeTDS package [cdr_tds.c] The following provide some + examples known to get asterisk working with mssql. + NOTE: Only choose one db connector. + + ODBC [cdr_odbc.c]: + Compile, configure, and install the latest unixODBC package: + tar -zxvf unixODBC-2.2.9.tar.gz && + cd unixODBC-2.2.9 && + ./configure --sysconfdir=/etc --prefix=/usr --disable-gui && + make && + make install + + Compile, configure, and install the latest FreeTDS package: + tar -zxvf freetds-0.62.4.tar.gz && + cd freetds-0.62.4 && + ./configure --prefix=/usr --with-tdsver=7.0 \ + --with-unixodbc=/usr/lib && + make && + make install + + Compile, or recompile, asterisk so that it will now add support + for cdr_odbc.c + + make clean && + make update && + make && + make install + + Setup odbc configuration files. These are working examples + from my system. You will need to modify for your setup. + You are not required to store usernames or passwords here. + + /etc/odbcinst.ini + [FreeTDS] + Description = FreeTDS ODBC driver for MSSQL + Driver = /usr/lib/libtdsodbc.so + Setup = /usr/lib/libtdsS.so + FileUsage = 1 + + /etc/odbc.ini + [MSSQL-asterisk] + description = Asterisk ODBC for MSSQL + driver = FreeTDS + server = 192.168.1.25 + port = 1433 + database = voipdb + tds_version = 7.0 + language = us_english + + Only install one database connector. Do not confuse asterisk + by using both ODBC (cdr_odbc.c) and FreeTDS (cdr_tds.c). + This command will erase the contents of cdr_tds.conf + + [ -f /etc/asterisk/cdr_tds.conf ] > /etc/asterisk/cdr_tds.conf + + NOTE: unixODBC requires the freeTDS package, but asterisk does + not call freeTDS directly. + + Setup cdr_odbc configuration files. These are working samples + from my system. You will need to modify for your setup. Define + your usernames and passwords here, secure file as well. + + /etc/asterisk/cdr_odbc.conf + [global] + dsn=MSSQL-asterisk + username=voipdbuser + password=voipdbpass + loguniqueid=yes + + And finally, create the 'cdr' table in your mssql database. + + CREATE TABLE cdr ( + [calldate] [datetime] NOT NULL , + [clid] [varchar] (80) NOT NULL , + [src] [varchar] (80) NOT NULL , + [dst] [varchar] (80) NOT NULL , + [dcontext] [varchar] (80) NOT NULL , + [channel] [varchar] (80) NOT NULL , + [dstchannel] [varchar] (80) NOT NULL , + [lastapp] [varchar] (80) NOT NULL , + [lastdata] [varchar] (80) NOT NULL , + [duration] [int] NOT NULL , + [billsec] [int] NOT NULL , + [disposition] [varchar] (45) NOT NULL , + [amaflags] [int] NOT NULL , + [accountcode] [varchar] (20) NOT NULL , + [uniqueid] [varchar] (32) NOT NULL , + [userfield] [varchar] (255) NOT NULL + ) + + Start asterisk in verbose mode, you should see that asterisk + logs a connection to the database and will now record every + call to the database when it's complete. + + TDS [cdr_tds.c]: + Compile, configure, and install the latest FreeTDS package: + tar -zxvf freetds-0.62.4.tar.gz && + cd freetds-0.62.4 && + ./configure --prefix=/usr --with-tdsver=7.0 + make && + make install + + Compile, or recompile, asterisk so that it will now add support + for cdr_tds.c + + make clean && + make update && + make && + make install + + Only install one database connector. Do not confuse asterisk + by using both ODBC (cdr_odbc.c) and FreeTDS (cdr_tds.c). + This command will erase the contents of cdr_odbc.conf + + [ -f /etc/asterisk/cdr_odbc.conf ] > /etc/asterisk/cdr_odbc.conf + + Setup cdr_tds configuration files. These are working samples + from my system. You will need to modify for your setup. Define + your usernames and passwords here, secure file as well. + + /etc/asterisk/cdr_tds.conf + [global] + hostname=192.168.1.25 + port=1433 + dbname=voipdb + user=voipdbuser + password=voipdpass + charset=BIG5 + + And finally, create the 'cdr' table in your mssql database. + + CREATE TABLE cdr ( + [accountcode] [varchar] (20) NULL , + [src] [varchar] (80) NULL , + [dst] [varchar] (80) NULL , + [dcontext] [varchar] (80) NULL , + [clid] [varchar] (80) NULL , + [channel] [varchar] (80) NULL , + [dstchannel] [varchar] (80) NULL , + [lastapp] [varchar] (80) NULL , + [lastdata] [varchar] (80) NULL , + [start] [datetime] NULL , + [answer] [datetime] NULL , + [end] [datetime] NULL , + [duration] [int] NULL , + [billsec] [int] NULL , + [disposition] [varchar] (20) NULL , + [amaflags] [varchar] (16) NULL , + [uniqueid] [varchar] (32) NULL , + [userfield] [varchar] (256) NULL + ) + + Start asterisk in verbose mode, you should see that asterisk + logs a connection to the database and will now record every + call to the database when it's complete. + + +MYSQL: + + +PGSQL: + If you want to go directly to postgresql database, and have the cdr_pgsql.so + compiled you can use the following sample setup. + On Debian, before compiling asterisk, just install libpqxx-dev. + Other distros will likely have a similiar package. + + Once you have the compile done, + copy the sample cdr_pgsql.conf file or create your own. + + Here is a sample: + + /etc/asterisk/cdr_pgsql.conf + ; Sample Asterisk config file for CDR logging to PostgresSQL + [global] + hostname=localhost + port=5432 + dbname=asterisk + password=password + user=postgres + table=cdr + + ;Now create a table in postgresql for your cdrs + + ;SQL table where CDRs will be inserted + ;Copy and paste this into your postgresql prompt. + CREATE TABLE cdr ( + calldate time NOT NULL , + clid varchar (80) NOT NULL , + src varchar (80) NOT NULL , + dst varchar (80) NOT NULL , + dcontext varchar (80) NOT NULL , + channel varchar (80) NOT NULL , + dstchannel varchar (80) NOT NULL , + lastapp varchar (80) NOT NULL , + lastdata varchar (80) NOT NULL , + duration int NOT NULL , + billsec int NOT NULL , + disposition varchar (45) NOT NULL , + amaflags int NOT NULL , + accountcode varchar (20) NOT NULL , + uniqueid varchar (32) NOT NULL , + userfield varchar (255) NOT NULL + ); + + +SQLLITE: + + +RADIUS: See doc/radius.txt for more information on cdr_radius diff --git a/1.4.23-rc4/doc/chaniax.txt b/1.4.23-rc4/doc/chaniax.txt new file mode 100644 index 000000000..0bac3046f --- /dev/null +++ b/1.4.23-rc4/doc/chaniax.txt @@ -0,0 +1,369 @@ +Inter-Asterisk eXchange Protocol +================================ + +INTRODUCTION +------------ + +This document is intended as an introduction to the Inter-Asterisk +eXchange (or simply IAX) protocol. It provides both a theoretical +background and practical information on its use. + +WHY IAX +------- +The first question most people are thinking at this point is "Why do you +need another VoIP protocol? Why didn't you just use SIP or H.323?" + +Well, the answer is a fairly complicated one, but in a nutshell it's like +this... Asterisk is intended as a very flexible and powerful +communications tool. As such, the primary feature we need from a VoIP +protocol is the ability to meet our own goals with Asterisk, and one with +enough flexibility that we could use it as a kind of laboratory for +inventing and implementing new concepts in the field. Neither H.323 or +SIP fit the roles we needed, so we developed our own protocol, which, +while not standards based, provides a number of advantages over both SIP +and H.323, some of which are: + + * Interoperability with NAT/PAT/Masquerade firewalls + IAX seamlessly interoperates through all sorts of NAT and PAT + and other firewalls, including the ability to place and + receive calls, and transfer calls to other stations. + + * High performance, low overhead protocol + When running on low-bandwidth connections, or when running + large numbers of calls, optimized bandwidth utilization is + imperative. IAX uses only 4 bytes of overhead + + * Internationalization support + IAX transmits language information, so that remote PBX + content can be delivered in the native language of the + calling party. + + * Remote dialplan polling + IAX allows a PBX or IP phone to poll the availability of a + number from a remote server. This allows PBX dialplans to + be centralized. + + * Flexible authentication + IAX supports cleartext, md5, and RSA authentication, + providing flexible security models for outgoing calls and + registration services. + + * Multimedia protocol + IAX supports the transmission of voice, video, images, text, + HTML, DTMF, and URL's. Voice menus can be presented in both + audibly and visually. + + * Call statistic gathering + IAX gathers statistics about network performance (including + latency and jitter, as well as providing end-to-end latency + measurement. + + * Call parameter communication + Caller*ID, requested extension, requested context, etc are + all communicated through the call. + + * Single socket design + IAX's single socket design allows up to 32768 calls to be + multiplexed. + +While we value the importance of standards based (i.e. SIP) call handling, +hopefully this will provide a reasonable explanation of why we developed +IAX rather than starting with SIP. + +CONFIG FILE CONVENTIONS +----------------------- +Lines beginning with '>' represent lines which might appear in an actual +configuration file. The '>' is used to help separate them from the +descriptive text and should not actually be included in the file itself. + +Lines within []'s by themselves represent section labels within the +configuration file. like this: + +> [mysection] + +Options are set using the "=" sign, for example + +> myoption = value + +Sometimes an option will have a number of discrete values which it can +take. In that case, in the documentation, the options will be listed +within square brackets (the "[" and "]" ones) separated by the pipe symbol +("|"). For example: + +> myoption = [value1|value2|value3] + +means the option "myoption" can be assigned a value of "value1", "value2", +or "value3". + +Objects, or pseudo-objects are instantiated using the "=>" construct. For +example: + +> myobject => parameter + +creates an object called "myobject" with some parameter whose definition +would be specific to that object. Note that the config file parser +considers "=>" and "=" to be equivalent and their use is purely to make +configuration files more readable and easier to "humanly parse". + +The comment character in Asterisk configuration files is the semicolon +";". The reason it is not "#" is because the "#" symbol can be used as +parts of extensions and it didn't seem like a good idea to have to escape +it. + +IAX CONFIGURATION IN ASTERISK +----------------------------- + +Like everything else in Asterisk, IAX's configuration lies in +/etc/asterisk -- specifically /etc/asterisk/iax.conf + +The IAX configuration file is a collection of sections, each of which +(with the exception of the "general" section) represents an entity within +the IAX scope. + +------------ + +The first section is typically the "general" section. In this area, +a number of parameters which affect the entire system are configured. +Specifically, the default codecs, port and address, jitter behavior, TOS +bits, and registrations. + +The first line of the "general" section is always: + +> [general] + +Following the first line are a number of other possibilities: + +> bindport = <portnum> + +This sets the port that IAX will bind to. The default IAX version 1 +port number is 5036. For IAX version 2, that is now the default in +Asterisk, the default port is 4569. +It is recommended that this value not be altered in general. + +> bindaddr = <ipaddr> + +This allows you to bind IAX to a specific local IP address instead of +binding to all addresses. This could be used to enhance security if, for +example, you only wanted IAX to be available to users on your LAN. + +> bandwidth = [low|medium|high] + +The bandwidth selection initializes the codec selection to appropriate +values for given bandwidths. The "high" selection enables all codecs and +is recommended only for 10Mbps or higher connections. The "medium" +bandwidth eliminates signed linear, Mu-law and A-law codecs, leaving only +the codecs which are 32kbps and smaller (with MP3 as a special case). It +can be used with broadband connections if desired. "low" eliminates ADPCM +and MP3 formats, leaving only the G.723.1, GSM, and LPC10. + +> allow = [gsm|lpc10|g723.1|adpcm|ulaw|alaw|mp3|slinear|all] +> disallow = [gsm|lpc10|g723.1|adpcm|ulaw|alaw|mp3|slinear|all] + +The "allow" and "disallow" allow you to fine tune the codec selection +beyond the initial bandwidth selection on a codec-by-codec basis. + +The recommended configuration is to select "low" bandwidth and then +disallow the LPC10 codec just because it doesn't sound very good. + +> jitterbuffer = [yes|no] +> dropcount = <dropamount> +> maxjitterbuffer = <max> +> maxexcessbuffer = <max> + +These parameters control the operation of the jitter buffer. The +jitterbuffer should always be enabled unless you expect all your +connections to be over a LAN. +* drop count is the maximum number of voice packets to allow to drop + (out of 100). Useful values are 3-10. +* maxjitterbuffer is the maximum amount of jitter buffer to permit to be + used. +* maxexcessbuffer is the maximum amount of excess jitter buffer + that is permitted before the jitter buffer is slowly shrunk to eliminate + latency. +* minexcessbuffer is the minimum amount of excess jitter buffer + +> accountcode = <code> +> amaflags = [default|omit|billing|documentation] + +These parameters affect call detail record generation. The first sets the +account code for records received with IAX. The account code can be +overridden on a per-user basis for incoming calls (see below). The +amaflags controls how the record is labeled ("omit" causes no record to be +written. "billing" and "documentation" label the records as billing or +documentation records respectively, and "default" selects the system +default. + +> tos = [lowdelay|throughput|reliability|mincost|none] + +IAX can optionally set the TOS (Type of Service) bits to specified values +to help improve performance in routing. The recommended value is +"lowdelay", which many routers (including any Linux routers with 2.4 +kernels that have not been altered with ip tables) will give priority to +these packets, improving voice quality. + +> register => <name>[:<secret>]@<host>[:port] + +Any number of registry entries may be instantiated in the general +section. Registration allows Asterisk to notify a remote Asterisk server +(with a fixed address) what our current address is. In order for +registration to work, the remote Asterisk server will need to have a +dynamic peer entry with the same name (and secret if provided). + +The name is a required field, and is the remote peer name that we wish to +identify ourselves as. A secret may be provided as well. The secret is +generally a shared password between the local server and the remote +server. However, if the secret is in square brackets ([]'s) then it is +interpreted as the name of a RSA key to use. In that case, the local Asterisk +server must have the *private* key (/var/lib/asterisk/keys/<name>.key) and +the remote server will have to have the corresponding public key. + +The "host" is a required field and is the hostname or IP address of the +remote Asterisk server. The port specification is optional and is by +default 4569 for iax2 if not specified. + +> notransfer = yes | no + +If an IAX phone calls another IAX phone by using a Asterisk server, +Asterisk will transfer the call to go peer to peer. If you do not +want this, turn on notransfer with a "yes". This is also settable +for peers and users. + +------------- + +The following sections, after "general" define either users, peers or +friends. A "user" is someone who connects to us. A "peer" is someone +that we connect to. A "friend" is simply shorthand for creating a "user" +and "peer" with identical parameters (i.e. someone who can contact us and +who we contact). + +> [identifier] + +The section begins with the identifier in square brackets. The identifier +should be an alphanumeric string. + +> type = [user|peer|friend] + +This line tells Asterisk how to interpret this entity. Users are things +that connect to us, while peers are phones we connect to, and a friend is +shorthand for creating a user and a peer with identical information + +---------------- +User fields: + +> context = <context> + +One or more context lines may be specified in a user, thus giving the user +access to place calls in the given contexts. Contexts are used by +Asterisk to divide dialing plans into logical units each with the ability +to have numbers interpreted differently, have their own security model, +auxiliary switch handling, and include other contexts. Most users are +given access to the default context. Trusted users could be given access +to the local context for example. + +> permit = <ipaddr>/<netmask> +> deny = <ipaddr>/<netmask> + +Permit and deny rules may be applied to users, allowing them to connect +from certain IP addresses and not others. The permit and deny rules are +interpreted in sequence and all are evaluated on a given IP address, with +the final result being the decision. For example: + +> permit = 0.0.0.0/0.0.0.0 +> deny = 192.168.0.0/255.255.255.0 + +would deny anyone in 192.168.0.0 with a netmask of 24 bits (class C), +whereas: + +> deny = 192.168.0.0/24 +> permit = 0.0.0.0/0 + +would not deny anyone since the final rule would permit anyone, thus +overriding the denial. + +If no permit/deny rules are listed, it is assumed that someone may connect +from anywhere. + +> callerid = <callerid> + +You may override the Caller*ID information passed by a user to you (if +they choose to send it) in order that it always be accurate from the +perspective of your server. + +> auth = [md5|plaintext|rsa] + +You may select which authentication methods are permitted to be used by +the user to authenticate to us. Multiple methods may be specified, +separated by commas. If md5 or plaintext authentication is selected, a +secret must be provided. If RSA authentication is specified, then one or +more key names must be specified with "inkeys" + +If no secret is specified and no authentication method is specified, then +no authentication will be required. + +> secret = <secret> + +The "secret" line specifies the shared secret for md5 and plaintext +authentication methods. It is never suggested to use plaintext except in +some cases for debugging. + +> inkeys = key1[:key2...] + +The "inkeys" line specifies which keys we can use to authenticate the +remote peer. If the peer's challenge passes with any of the given keys, +then we accept its authentication. The key files live in +/var/lib/asterisk/keys/<name>.pub and are *public keys*. Public keys are +not typically DES3 encrypted and thus do not usually need initialization. + +--------------- +Peer configuration + +> allow = [gsm|lpc10|g723.1|adpcm|ulaw|alaw|mp3|slinear|all] +> disallow = [gsm|lpc10|g723.1|adpcm|ulaw|alaw|mp3|slinear|all] + +The "allow" and "disallow" may be used to enable or disable specific codec +support on a per-peer basis. + +> host = [<ipaddr>|dynamic] + +The host line specifies the hostname or IP address of the remote host, or +may be the word "dynamic" signifying that the host will register with us +(see register => in the general section above). + +> defaultip = <ipaddr> + +If the host uses dynamic registration, Asterisk may still be given a +default IP address to use when dynamic registration has not been performed +or has timed out. + +> peercontext = <context> + +Specifies the context name to be passed to the peer for it to use when routing +the call through its dial plan. This entry will be used only if a context +is not included in the IAX2 channel name passed to the Dial command. + +> qualify = [yes | no | <value>] + +Qualify turns on checking of availability of the remote peer. If the +peer becomes unavailable, no calls are placed to the peer until +it is reachable again. This is also helpful in certain NAT situations. + +> jitterbuffer = [yes | no] + +Turns on or off the jitterbuffer for this peer + +> mailbox = <mailbox>[@mailboxcontext] + +Specifies a mailbox to check for voicemail notification. + +> permit = <ipaddr>/<netmask> +> deny = <ipaddr>/<netmask> + +Permit and deny rules may be applied to users, allowing them to connect +from certain IP addresses and not others. The permit and deny rules are +interpreted in sequence and all are evaluated on a given IP address, with +the final result being the decision. See the user section above +for examples. + +---------------------------------------------------------------------- +For more examples of a configuration, please see the iax.conf.sample in +your the /configs directory of you source code distribution diff --git a/1.4.23-rc4/doc/channels.txt b/1.4.23-rc4/doc/channels.txt new file mode 100644 index 000000000..b907a92aa --- /dev/null +++ b/1.4.23-rc4/doc/channels.txt @@ -0,0 +1,44 @@ +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/1.4.23-rc4/doc/channelvariables.txt b/1.4.23-rc4/doc/channelvariables.txt new file mode 100644 index 000000000..761516fa7 --- /dev/null +++ b/1.4.23-rc4/doc/channelvariables.txt @@ -0,0 +1,815 @@ +---------------------------- +Asterisk dial plan variables +---------------------------- + +There are two levels of parameter evaluation done in the Asterisk +dial plan in extensions.conf. +* The first, and most frequently used, is the substitution of variable + references with their values. +* Then there are the evaluations of expressions done in $[ .. ]. + This will be discussed below. + +Asterisk has user-defined variables and standard variables set +by various modules in Asterisk. These standard variables are +listed at the end of this document. + +___________________________ +PARAMETER QUOTING: +--------------------------- + +exten => s,5,BackGround,blabla + +The parameter (blabla) can be quoted ("blabla"). In this case, a +comma does not terminate the field. However, the double quotes +will be passed down to the Background command, in this example. + +Also, characters special to variable substitution, expression evaluation, etc +(see below), can be quoted. For example, to literally use a $ on the +string "$1231", quote it with a preceding \. Special characters that must +be quoted to be used, are [ ] $ " \. (to write \ itself, use \\). + +These Double quotes and escapes are evaluated at the level of the +asterisk config file parser. + +Double quotes can also be used inside expressions, as discussed below. + +___________________________ +VARIABLES: +--------------------------- + +Parameter strings can include variables. Variable names are arbitrary strings. +They are stored in the respective channel structure. + +To set a variable to a particular value, do : + + exten => 1,2,Set(varname=value) + +You can substitute the value of a variable everywhere using ${variablename}. +For example, to stringwise append $lala to $blabla and store result in $koko, +do: + + exten => 1,2,Set(koko=${blabla}${lala}) + + +There are two reference modes - reference by value and reference by name. +To refer to a variable with its name (as an argument to a function that +requires a variable), just write the name. To refer to the variable's value, +enclose it inside ${}. For example, Set takes as the first argument +(before the =) a variable name, so: + + exten => 1,2,Set(koko=lala) + exten => 1,3,Set(${koko}=blabla) + +stores to the variable "koko" the value "lala" and to variable "lala" the +value "blabla". + +In fact, everything contained ${here} is just replaced with the value of +the variable "here". + +____________________ +VARIABLE INHERITANCE +-------------------- + +Variable names which are prefixed by "_" will be inherited to channels +that are created in the process of servicing the original channel in +which the variable was set. When the inheritance takes place, the +prefix will be removed in the channel inheriting the variable. If the +name is prefixed by "__" in the channel, then the variable is +inherited and the "__" will remain intact in the new channel. + +In the dialplan, all references to these variables refer to the same +variable, regardless of having a prefix or not. Note that setting any +version of the variable removes any other version of the variable, +regardless of prefix. + +Example: + +Set(__FOO=bar) ; Sets an inherited version of "FOO" variable +Set(FOO=bar) ; Removes the inherited version and sets a local + ; variable. + +However, + +NoOp(${__FOO}) is identical to NoOp(${FOO}) + + + +___________________________________ +SELECTING CHARACTERS FROM VARIABLES +----------------------------------- + +The format for selecting characters from a variable can be expressed as: + + ${variable_name[:offset[:length]]} + +If you want to select the first N characters from the string assigned +to a variable, simply append a colon and the number of characters to +skip from the beginning of the string to the variable name. + + ;Remove the first character of extension, save in "number" variable + exten => _9X.,1,Set(number=${EXTEN:1}) + +Assuming we've dialed 918005551234, the value saved to the 'number' variable +would be 18005551234. This is useful in situations when we require users to +dial a number to access an outside line, but do not wish to pass the first +digit. + +If you use a negative offset number, Asterisk starts counting from the end +of the string and then selects everything after the new position. The following +example will save the numbers 1234 to the 'number' variable, still assuming +we've dialed 918005551234. + + ;Remove everything before the last four digits of the dialed string + exten => _9X.,1,Set(number=${EXTEN:-4}) + +We can also limit the number of characters from our offset position that we +wish to use. This is done by appending a second colon and length value to the +variable name. The following example will save the numbers 555 to the 'number' +variable. + + ;Only save the middle numbers 555 from the string 918005551234 + exten => _9X.,1,Set(number=${EXTEN:5:3}) + +The length value can also be used in conjunction with a negative offset. This +may be useful if the length of the string is unknown, but the trailing digits +are. The following example will save the numbers 555 to the 'number' variable, +even if the string starts with more characters than expected (unlike the +previous example). + + ;Save the numbers 555 to the 'number' variable + exten => _9X.,1,Set(number=${EXTEN:-7:3}) + +If a negative length value is entered, Asterisk will remove that many characters +from the end of the string. + + ;Set pin to everything but the trailing #. + exten => _XXXX#,1,Set(pin=${EXTEN:0:-1}) + +___________________________ +EXPRESSIONS: +--------------------------- + +Everything contained inside a bracket pair prefixed by a $ (like $[this]) is +considered as an expression and it is evaluated. Evaluation works similar to +(but is done on a later stage than) variable substitution: the expression +(including the square brackets) is replaced by the result of the expression +evaluation. + +For example, after the sequence: + +exten => 1,1,Set(lala=$[1 + 2]) +exten => 1,2,Set(koko=$[2 * ${lala}]) + +the value of variable koko is "6". + +and, further: + +exten => 1,1,Set,(lala=$[ 1 + 2 ]); + +will parse as intended. Extra spaces are ignored. + + +______________________________ +SPACES INSIDE VARIABLE VALUES +------------------------------ +If the variable being evaluated contains spaces, there can be problems. + +For these cases, double quotes around text that may contain spaces +will force the surrounded text to be evaluated as a single token. +The double quotes will be counted as part of that lexical token. + +As an example: + +exten => s,6,GotoIf($[ "${CALLERIDNAME}" : "Privacy Manager" ]?callerid-liar|s|1:s|7) + +The variable CALLERIDNAME could evaluate to "DELOREAN MOTORS" (with a space) +but the above will evaluate to: + +"DELOREAN MOTORS" : "Privacy Manager" + +and will evaluate to 0. + +The above without double quotes would have evaluated to: + +DELOREAN MOTORS : Privacy Manager + +and will result in syntax errors, because token DELOREAN is immediately +followed by token MOTORS and the expression parser will not know how to +evaluate this expression, because it does not match its grammar. + +_____________________ +OPERATORS +--------------------- +Operators are listed below in order of increasing precedence. Operators +with equal precedence are grouped within { } symbols. + + expr1 | expr2 + Return the evaluation of expr1 if it is neither an empty string + nor zero; otherwise, returns the evaluation of expr2. + + expr1 & expr2 + Return the evaluation of expr1 if neither expression evaluates to + an empty string or zero; otherwise, returns zero. + + expr1 {=, >, >=, <, <=, !=} expr2 + Return the results of integer comparison if both arguments are + integers; otherwise, returns the results of string comparison + using the locale-specific collation sequence. The result of each + comparison is 1 if the specified relation is true, or 0 if the + relation is false. + + expr1 {+, -} expr2 + Return the results of addition or subtraction of integer-valued + arguments. + + expr1 {*, /, %} expr2 + Return the results of multiplication, integer division, or + remainder of integer-valued arguments. + + - expr1 + Return the result of subtracting expr1 from 0. + This, the unary minus operator, is right associative, and + has the same precedence as the ! operator. + + ! expr1 + Return the result of a logical complement of expr1. + In other words, if expr1 is null, 0, an empty string, + or the string "0", return a 1. Otherwise, return a 0. + It has the same precedence as the unary minus operator, and + is also right associative. + + expr1 : expr2 + The `:' operator matches expr1 against expr2, which must be a + regular expression. The regular expression is anchored to the + beginning of the string with an implicit `^'. + + If the match succeeds and the pattern contains at least one regu- + lar expression subexpression `\(...\)', the string correspond- + ing to `\1' is returned; otherwise the matching operator + returns the number of characters matched. If the match fails and + the pattern contains a regular expression subexpression the null + string is returned; otherwise 0. + + Normally, the double quotes wrapping a string are left as part + of the string. This is disastrous to the : operator. Therefore, + before the regex match is made, beginning and ending double quote + characters are stripped from both the pattern and the string. + + expr1 =~ expr2 + Exactly the same as the ':' operator, except that the match is + not anchored to the beginning of the string. Pardon any similarity + to seemingly similar operators in other programming languages! + The ":" and "=~" operators share the same precedence. + + expr1 ? expr2 :: expr3 + Traditional Conditional operator. If expr1 is a number + that evaluates to 0 (false), expr3 is result of the this + expression evaluation. Otherwise, expr2 is the result. + If expr1 is a string, and evaluates to an empty string, + or the two characters (""), then expr3 is the + result. Otherwise, expr2 is the result. In Asterisk, all + 3 exprs will be "evaluated"; if expr1 is "true", expr2 + will be the result of the "evaluation" of this + expression. expr3 will be the result otherwise. This + operator has the lowest precedence. + +Parentheses are used for grouping in the usual manner. + +Operator precedence is applied as one would expect in any of the C +or C derived languages. + +Examples + + "One Thousand Five Hundred" =~ "(T[^ ]+)" + returns: Thousand + + "One Thousand Five Hundred" =~ "T[^ ]+" + returns: 8 + + "One Thousand Five Hundred" : "T[^ ]+" + returns: 0 + + "8015551212" : "(...)" + returns: 801 + + "3075551212":"...(...)" + returns: 555 + + ! "One Thousand Five Hundred" =~ "T[^ ]+" + returns: 0 (because it applies to the string, which is non-null, + which it turns to "0", and then looks for the pattern + in the "0", and doesn't find it) + + !( "One Thousand Five Hundred" : "T[^ ]+" ) + returns: 1 (because the string doesn't start with a word starting + with T, so the match evals to 0, and the ! operator + inverts it to 1 ). + + 2 + 8 / 2 + returns 6. (because of operator precedence; the division is done first, then the addition). + + 2+8/2 + returns 6. Spaces aren't necessary. + +(2+8)/2 + returns 5, of course. + +Of course, all of the above examples use constants, but would work the +same if any of the numeric or string constants were replaced with a +variable reference ${CALLERIDNUM}, for instance. + +__________________________ +NUMBERS VS STRINGS +-------------------------- + +Tokens consisting only of numbers are converted to 64-bit numbers for +most of the operators. This means that overflows can occur when the +numbers get above 18 digits. Warnings will appear in the logs in this +case. +___________________________ +CONDITIONALS +--------------------------- + +There is one conditional application - the conditional goto : + + exten => 1,2,gotoif(condition?label1:label2) + +If condition is true go to label1, else go to label2. Labels are interpreted +exactly as in the normal goto command. + +"condition" is just a string. If the string is empty or "0", the condition +is considered to be false, if it's anything else, the condition is true. +This is designed to be used together with the expression syntax described +above, eg : + + exten => 1,2,gotoif($[${CALLERID} = 123456]?2|1:3|1) + +Example of use : + +exten => s,2,Set(vara=1) +exten => s,3,Set(varb=$[${vara} + 2]) +exten => s,4,Set(varc=$[${varb} * 2]) +exten => s,5,GotoIf($[${varc} = 6]?99|1:s|6) + +___________________________ +PARSE ERRORS +--------------------------- + +Syntax errors are now output with 3 lines. + +If the extensions.conf file contains a line like: + +exten => s,6,GotoIf($[ "${CALLERIDNUM}" = "3071234567" & & "${CALLERIDNAME}" : "Privacy Manager" ]?callerid-liar|s|1:s|7) + +You may see an error in /var/log/asterisk/messages like this: + +Jul 15 21:27:49 WARNING[1251240752]: ast_yyerror(): syntax error: parse error, unexpected TOK_AND, expecting TOK_MINUS or TOK_LP or TOKEN; Input: +"3072312154" = "3071234567" & & "Steves Extension" : "Privacy Manager" + ^ + +The log line tells you that a syntax error was encountered. It now +also tells you (in grand standard bison format) that it hit an "AND" +(&) token unexpectedly, and that was hoping for for a MINUS (-), LP +(left parenthesis), or a plain token (a string or number). + +The next line shows the evaluated expression, and the line after +that, the position of the parser in the expression when it became confused, +marked with the "^" character. + +___________________________ +NULL STRINGS +--------------------------- + +Testing to see if a string is null can be done in one of two different ways: + + exten => _XX.,1,GotoIf($["${calledid}" != ""]?3) + + exten => _XX.,1,GotoIf($[foo${calledid} != foo]?3) + + +The second example above is the way suggested by the WIKI. It will +work as long as there are no spaces in the evaluated value. + +The first way should work in all cases, and indeed, might now +be the safest way to handle this situation. + +___________________________ +WARNING +--------------------------- + +If you need to do complicated things with strings, asterisk expressions +is most likely NOT the best way to go about it. AGI scripts are an +excellent option to this need, and make available the full power of +whatever language you desire, be it Perl, C, C++, Cobol, RPG, Java, +Snobol, PL/I, Scheme, Common Lisp, Shell scripts, Tcl, Forth, Modula, +Pascal, APL, assembler, etc. + +---------------------------- +INCOMPATIBILITIES +---------------------------- + +The asterisk expression parser has undergone some evolution. It is hoped +that the changes will be viewed as positive. + +The "original" expression parser had a simple, hand-written scanner, +and a simple bison grammar. This was upgraded to a more involved bison +grammar, and a hand-written scanner upgraded to allow extra spaces, +and to generate better error diagnostics. This upgrade required bison +1.85, and part of the user community felt the pain of having to +upgrade their bison version. + +The next upgrade included new bison and flex input files, and the makefile +was upgraded to detect current version of both flex and bison, conditionally +compiling and linking the new files if the versions of flex and bison would +allow it. + +If you have not touched your extensions.conf files in a year or so, the +above upgrades may cause you some heartburn in certain circumstances, as +several changes have been made, and these will affect asterisk's behavior on +legacy extension.conf constructs. The changes have been engineered +to minimize these conflicts, but there are bound to be problems. + +The following list gives some (and most likely, not all) of areas +of possible concern with "legacy" extension.conf files: + +1. Tokens separated by space(s). + Previously, tokens were separated by spaces. Thus, ' 1 + 1 ' would evaluate + to the value '2', but '1+1' would evaluate to the string '1+1'. If this + behavior was depended on, then the expression evaluation will break. '1+1' + will now evaluate to '2', and something is not going to work right. + To keep such strings from being evaluated, simply wrap them in double + quotes: ' "1+1" ' + +2. The colon operator. In versions previous to double quoting, the + colon operator takes the right hand string, and using it as a + regex pattern, looks for it in the left hand string. It is given + an implicit ^ operator at the beginning, meaning the pattern + will match only at the beginning of the left hand string. + If the pattern or the matching string had double quotes around + them, these could get in the way of the pattern match. Now, + the wrapping double quotes are stripped from both the pattern + and the left hand string before applying the pattern. This + was done because it recognized that the new way of + scanning the expression doesn't use spaces to separate tokens, + and the average regex expression is full of operators that + the scanner will recognize as expression operators. Thus, unless + the pattern is wrapped in double quotes, there will be trouble. + For instance, ${VAR1} : (Who|What*)+ + may have have worked before, but unless you wrap the pattern + in double quotes now, look out for trouble! This is better: + "${VAR1}" : "(Who|What*)+" + and should work as previous. + +3. Variables and Double Quotes + Before these changes, if a variable's value contained one or more double + quotes, it was no reason for concern. It is now! + +4. LE, GE, NE operators removed. The code supported these operators, + but they were not documented. The symbolic operators, <=, >=, and != + should be used instead. + +5. Added the unary '-' operator. So you can 3+ -4 and get -1. + +6. Added the unary '!' operator, which is a logical complement. + Basically, if the string or number is null, empty, or '0', + a '1' is returned. Otherwise a '0' is returned. + +7. Added the '=~' operator, just in case someone is just looking for + match anywhere in the string. The only diff with the ':' is that + match doesn't have to be anchored to the beginning of the string. + +8. Added the conditional operator 'expr1 ? true_expr :: false_expr' + First, all 3 exprs are evaluated, and if expr1 is false, the 'false_expr' + is returned as the result. See above for details. + +9. Unary operators '-' and '!' were made right associative. + +-------------------------------------------------------- +DEBUGGING HINTS FOR $[ ] EXPRESSIONS +-------------------------------------------------------- + +There are two utilities you can build to help debug the $[ ] in +your extensions.conf file. + +The first, and most simplistic, is to issue the command: + +make testexpr2 + +in the top level asterisk source directory. This will build a small +executable, that is able to take the first command line argument, and +run it thru the expression parser. No variable substitutions will be +performed. It might be safest to wrap the expression in single +quotes... + +testexpr2 '2*2+2/2' + +is an example. + +And, in the utils directory, you can say: + +make check_expr + +and a small program will be built, that will check the file mentioned +in the first command line argument, for any expressions that might be +have problems when you move to flex-2.5.31. It was originally +designed to help spot possible incompatibilities when moving from the +pre-2.5.31 world to the upgraded version of the lexer. + +But one more capability has been added to check_expr, that might make +it more generally useful. It now does a simple minded evaluation of +all variables, and then passes the $[] exprs to the parser. If there +are any parse errors, they will be reported in the log file. You can +use check_expr to do a quick sanity check of the expressions in your +extensions.conf file, to see if they pass a crude syntax check. + +The "simple-minded" variable substitution replaces ${varname} variable +references with '555'. You can override the 555 for variable values, +by entering in var=val arguments after the filename on the command +line. So... + + check_expr /etc/asterisk/extensions.conf CALLERIDNUM=3075551212 DIALSTATUS=TORTURE EXTEN=121 + +will substitute any ${CALLERIDNUM} variable references with +3075551212, any ${DIALSTATUS} variable references with 'TORTURE', and +any ${EXTEN} references with '121'. If there is any fancy stuff +going on in the reference, like ${EXTEN:2}, then the override will +not work. Everything in the ${...} has to match. So, to substitute +#{EXTEN:2} references, you'd best say: + + check_expr /etc/asterisk/extensions.conf CALLERIDNUM=3075551212 DIALSTATUS=TORTURE EXTEN:2=121 + +on stdout, you will see something like: + + OK -- $[ "${DIALSTATUS}" = "TORTURE" | "${DIALSTATUS}" = "DONTCALL" ] at line 416 + +In the expr2_log file that is generated, you will see: + + line 416, evaluation of $[ "TORTURE" = "TORTURE" | "TORTURE" = "DONTCALL" ] result: 1 + +check_expr is a very simplistic algorithm, and it is far from being +guaranteed to work in all cases, but it is hoped that it will be +useful. + +--------------------------------------------------------- +Asterisk standard channel variables +--------------------------------------------------------- +There are a number of variables that are defined or read +by Asterisk. Here is a list of them. More information is +available in each application's help text. All these variables +are in UPPER CASE only. + +Variables marked with a * are builtin functions and can't be set, +only read in the dialplan. Writes to such variables are silently +ignored. + +${ACCOUNTCODE} * Account code (if specified) (Deprecated; use ${CDR(accountcode)}) +${BLINDTRANSFER} The name of the channel on the other side of a blind transfer +${BRIDGEPEER} Bridged peer +${CALLERANI} * Caller ANI (PRI channels) (Deprecated; use ${CALLERID(ani)}) +${CALLERID} * Caller ID (Deprecated; use ${CALLERID(all)}) +${CALLERIDNAME} * Caller ID Name only (Deprecated; use ${CALLERID(name)}) +${CALLERIDNUM} * Caller ID Number only (Deprecated; use ${CALLERID(num)}) +${CALLINGANI2} * Caller ANI2 (PRI channels) +${CALLINGPRES} * Caller ID presentation for incoming calls (PRI channels) +${CALLINGTNS} * Transit Network Selector (PRI channels) +${CALLINGTON} * Caller Type of Number (PRI channels) +${CHANNEL} * Current channel name +${CONTEXT} * Current context +${DATETIME} * Current date time in the format: DDMMYYYY-HH:MM:SS (Deprecated; use ${STRFTIME(${EPOCH},,%d%m%Y-%H:%M:%S)}) +${DB_RESULT} Result value of DB_EXISTS() dial plan function +${DNID} * Dialed Number Identifier (Deprecated; use ${CALLERID(dnid)}) +${EPOCH} * Current unix style epoch +${EXTEN} * Current extension +${ENV(VAR)} Environmental variable VAR +${GOTO_ON_BLINDXFR} Transfer to the specified context/extension/priority + after a blind transfer (use ^ characters in place of + | to separate context/extension/priority when setting + this variable from the dialplan) +${HANGUPCAUSE} * Asterisk cause of hangup (inbound/outbound) +${HINT} * Channel hints for this extension +${HINTNAME} * Suggested Caller*ID name for this extension +${INVALID_EXTEN} The invalid called extension (used in the "i" extension) +${LANGUAGE} * Current language (Deprecated; use ${LANGUAGE()}) +${LEN(VAR)} * String length of VAR (integer) +${PRIORITY} * Current priority in the dialplan +${PRIREDIRECTREASON} Reason for redirect on PRI, if a call was directed +${RDNIS} * Redirected Dial Number ID Service (Deprecated; use ${CALLERID(rdnis)}) +${TIMESTAMP} * Current date time in the format: YYYYMMDD-HHMMSS (Deprecated; use ${STRFTIME(${EPOCH},,%Y%m%d-%H%M%S)}) +${TRANSFER_CONTEXT} Context for transferred calls +${FORWARD_CONTEXT} Context for forwarded calls +${UNIQUEID} * Current call unique identifier +${SYSTEMNAME} * value of the systemname option of asterisk.conf + +Application return values +------------------------- +In Asterisk 1.2, many applications return the result in a variable +instead of, as in Asterisk 1.0, changing the dial plan priority (+101). +For the various status values, see each application's help text. + +${AGISTATUS} * agi() +${AQMSTATUS} * addqueuemember() +${AVAILSTATUS} * chanisavail() +${CHECKGROUPSTATUS} * checkgroup() +${CHECKMD5STATUS} * checkmd5() +${CPLAYBACKSTATUS} * controlplayback() +${DIALSTATUS} * dial() +${DBGETSTATUS} * dbget() +${ENUMSTATUS} * enumlookup() +${HASVMSTATUS} * hasnewvoicemail() +${LOOKUPBLSTATUS} * lookupblacklist() +${OSPAUTHSTATUS} * ospauth() +${OSPLOOKUPSTATUS} * osplookup() +${OSPNEXTSTATUS} * ospnext() +${OSPFINISHSTATUS} * ospfinish() +${PARKEDAT} * parkandannounce() +${PLAYBACKSTATUS} * playback() +${PQMSTATUS} * pausequeuemember() +${PRIVACYMGRSTATUS} * privacymanager() +${QUEUESTATUS} * queue() +${RQMSTATUS} * removequeuemember() +${SENDIMAGESTATUS} * sendimage() +${SENDTEXTSTATUS} * sendtext() +${SENDURLSTATUS} * sendurl() +${SYSTEMSTATUS} * system() +${TRANSFERSTATUS} * transfer() +${TXTCIDNAMESTATUS} * txtcidname() +${UPQMSTATUS} * unpausequeuemember() +${VMSTATUS} * voicmail() +${VMBOXEXISTSSTATUS} * vmboxexists() +${WAITSTATUS} * waitforsilence() + + +Various application variables +----------------------------- +${CURL} * Resulting page content for curl() +${ENUM} * Result of application EnumLookup +${EXITCONTEXT} Context to exit to in IVR menu (app background()) + or in the RetryDial() application +${MONITOR} * Set to "TRUE" if the channel is/has been monitored (app monitor()) +${MONITOR_EXEC} Application to execute after monitoring a call +${MONITOR_EXEC_ARGS} Arguments to application +${MONITOR_FILENAME} File for monitoring (recording) calls in queue +${QUEUE_PRIO} Queue priority +${QUEUE_MAX_PENALTY} Maximum member penalty allowed to answer caller +${QUEUESTATUS} Status of the call, one of: + (TIMEOUT | FULL | JOINEMPTY | LEAVEEMPTY | JOINUNAVAIL | LEAVEUNAVAIL) +${RECORDED_FILE} * Recorded file in record() +${TALK_DETECTED} * Result from talkdetect() +${TOUCH_MONITOR} The filename base to use with Touch Monitor (auto record) +${TOUCH_MONITOR_FORMAT} The audio format to use with Touch Monitor (auto record) +${TOUCH_MONITOR_OUTPUT} * Recorded file from Touch Monitor (auto record) +${TXTCIDNAME} * Result of application TXTCIDName +${VPB_GETDTMF} chan_vpb + +The MeetMe Conference Bridge uses the following variables: +---------------------------------------------------------- +${MEETME_RECORDINGFILE} Name of file for recording a conference with + the "r" option +${MEETME_RECORDINGFORMAT} Format of file to be recorded +${MEETME_EXIT_CONTEXT} Context for exit out of meetme meeting +${MEETME_AGI_BACKGROUND} AGI script for Meetme (zap only) +${MEETMESECS} * Number of seconds a user participated in a MeetMe conference + +The VoiceMail() application uses the following variables: +--------------------------------------------------------- +${VM_CATEGORY} Sets voicemail category +${VM_NAME} * Full name in voicemail +${VM_DUR} * Voicemail duration +${VM_MSGNUM} * Number of voicemail message in mailbox +${VM_CALLERID} * Voicemail Caller ID (Person leaving vm) +${VM_CIDNAME} * Voicemail Caller ID Name +${VM_CIDNUM} * Voicemail Caller ID Number +${VM_DATE} * Voicemail Date +${VM_MESSAGEFILE} * Path to message left by caller + +The VMAuthenticate() application uses the following variables: +--------------------------------------------------------- +${AUTH_MAILBOX} * Authenticated mailbox +${AUTH_CONTEXT} * Authenticated mailbox context + +DUNDiLookup() uses the following variables +--------------------------------------------------------- +${DUNDTECH} * The Technology of the result from a call to DUNDiLookup() +${DUNDDEST} * The Destination of the result from a call to DUNDiLookup() + +The Zaptel channel sets the following variables: +--------------------------------------------------------- +${ANI2} * The ANI2 Code provided by the network on the incoming call. + (ie, Code 29 identifies call as a Prison/Inmate Call) +${CALLTYPE} * Type of call (Speech, Digital, etc) +${CALLEDTON} * Type of number for incoming PRI extension + i.e. 0=unknown, 1=international, 2=domestic, 3=net_specific, + 4=subscriber, 6=abbreviated, 7=reserved +${CALLINGSUBADDR} * Called PRI Subaddress +${FAXEXTEN} * The extension called before being redirected to "fax" +${PRIREDIRECTREASON} * Reason for redirect, if a call was directed +${SMDI_VM_TYPE} * When an call is received with an SMDI message, the 'type' + of message 'b' or 'u' + +The SIP channel uses the following variables: +--------------------------------------------------------- +${SIPCALLID} * SIP Call-ID: header verbatim (for logging or CDR matching) +${SIPDOMAIN} * SIP destination domain of an inbound call (if appropriate) +${SIPUSERAGENT} * SIP user agent (deprecated) +${SIPURI} * SIP uri +${SIP_CODEC} Set the SIP codec for a call +${SIP_URI_OPTIONS} * additional options to add to the URI for an outgoing call +${RTPAUDIOQOS} RTCP QoS report for the audio of this call +${RTPVIDEOQOS} RTCP QoS report for the video of this call + +The Agent channel uses the following variables: +--------------------------------------------------------- +${AGENTMAXLOGINTRIES} Set the maximum number of failed logins +${AGENTUPDATECDR} Whether to update the CDR record with Agent channel data +${AGENTGOODBYE} Sound file to use for "Good Bye" when agent logs out +${AGENTACKCALL} Whether the agent should acknowledge the incoming call +${AGENTAUTOLOGOFF} Auto logging off for an agent +${AGENTWRAPUPTIME} Setting the time for wrapup between incoming calls +${AGENTNUMBER} * Agent number (username) set at login +${AGENTSTATUS} * Status of login ( fail | on | off ) +${AGENTEXTEN} * Extension for logged in agent + +The Dial() application uses the following variables: +--------------------------------------------------------- +${DIALEDPEERNAME} * Dialed peer name +${DIALEDPEERNUMBER} * Dialed peer number +${DIALEDTIME} * Time for the call (seconds) +${ANSWEREDTIME} * Time from dial to answer (seconds) +${DIALSTATUS} * Status of the call, one of: + (CHANUNAVAIL | CONGESTION | BUSY | NOANSWER + | ANSWER | CANCEL | DONTCALL | TORTURE) +${DYNAMIC_FEATURES} * The list of features (from the [applicationmap] section of + features.conf) to activate during the call, with feature + names separated by '#' characters +${LIMIT_PLAYAUDIO_CALLER} Soundfile for call limits +${LIMIT_PLAYAUDIO_CALLEE} Soundfile for call limits +${LIMIT_WARNING_FILE} Soundfile for call limits +${LIMIT_TIMEOUT_FILE} Soundfile for call limits +${LIMIT_CONNECT_FILE} Soundfile for call limits +${OUTBOUND_GROUP} Default groups for peer channels (as in SetGroup) +* See "show application dial" for more information + +The chanisavail() application sets the following variables: +----------------------------------------------------------- +${AVAILCHAN} * the name of the available channel if one was found +${AVAILORIGCHAN} * the canonical channel name that was used to create the channel +${AVAILSTATUS} * Status of requested channel + +When using macros in the dialplan, these variables are available +--------------------------------------------------------- +${MACRO_EXTEN} * The calling extensions +${MACRO_CONTEXT} * The calling context +${MACRO_PRIORITY} * The calling priority +${MACRO_OFFSET} Offset to add to priority at return from macro + +The ChanSpy() application uses the following variables: +--------------------------------------------------------- +${SPYGROUP} * A ':' (colon) separated list of group names. + (To be set on spied on channel and matched against the g(grp) option) + +If you compile with OSP support, these variables are used: +--------------------------------------------------------- +${OSPINHANDLE} OSP handle of in_bound call +${OSPINTIMELIMIT} Duration limit for in_bound call +${OSPOUTHANDLE} OSP handle of out_bound call +${OSPTECH} OSP technology +${OSPDEST} OSP destination +${OSPCALLING} OSP calling number +${OSPOUTTOKEN} OSP token to use for out_bound call +${OSPOUTTIMELIMIT} Duration limit for out_bound call +${OSPRESULTS} Number of remained destinations + +____________________________________ +CDR Variables +------------------------------------ + +If the channel has a cdr, that cdr record has it's own set of variables which +can be accessed just like channel variables. The following builtin variables +are available. + +${CDR(clid)} Caller ID +${CDR(src)} Source +${CDR(dst)} Destination +${CDR(dcontext)} Destination context +${CDR(channel)} Channel name +${CDR(dstchannel)} Destination channel +${CDR(lastapp)} Last app executed +${CDR(lastdata)} Last app's arguments +${CDR(start)} Time the call started. +${CDR(answer)} Time the call was answered. +${CDR(end)} Time the call ended. +${CDR(duration)} Duration of the call. +${CDR(billsec)} Duration of the call once it was answered. +${CDR(disposition)} ANSWERED, NO ANSWER, BUSY +${CDR(amaflags)} DOCUMENTATION, BILL, IGNORE etc +${CDR(accountcode)} The channel's account code. +${CDR(uniqueid)} The channel's unique id. +${CDR(userfield)} The channels uses specified field. + + +In addition, you can set your own extra variables with a traditional +Set(CDR(var)=val) to anything you want. + +Certain functional variables may be accessed with ${foo(<args>)}. A list +of these functional variables may be found by typing "show functions" +at the Asterisk CLI. diff --git a/1.4.23-rc4/doc/cli.txt b/1.4.23-rc4/doc/cli.txt new file mode 100644 index 000000000..9d3f9dbfe --- /dev/null +++ b/1.4.23-rc4/doc/cli.txt @@ -0,0 +1,33 @@ +In addition to being the console for Asterisk, the CLI also sports several +features that make it very helpful to use for obtaining information and +affecting system configuration. The console can also be seen by starting +a remote console, which connects to the running daemon and shows much of +the same information as if using the daemon in foreground mode. + +Connecting a remote console is as easy as using the -r or -R flags. The only +difference between these flags is that the uppercase variation (-R) will +automatically reconnect to the daemon (or at least retry) if the daemon +restarts. To exit a remote console, simply type 'quit' or 'exit'. Please note +that you can differentiate between a remote console and the Asterisk console, +as 'quit' or 'exit' will not function on the main console, which prevents an +accidental shutdown of the daemon. If you would like to shutdown the Asterisk +daemon, you can use the 'stop' set of commands, such as 'stop now', +'stop gracefully', or 'stop when convenient'. + +Once on the console, the 'help' command may be used to see a list of commands +available for use. Note that in addition to the 'help' command, the Asterisk +CLI sports tab command line completion on all commands, including many +arguments. To use tab command line completion, simply press the <Tab> key at +any time while entering the beginning of any command. If the command can be +completed unambiguously, it will do so, otherwise it will complete as much of +the command as possible. Additionally, Asterisk will print a list of all +possible matches, if possible. + +The 'help' command may also be used to obtain more detailed information on +how to use a particular command. For example, if you type 'help core show', +Asterisk will respond with a list of all commands that start with that string. +If you type 'help core show version', specifying a complete command, Asterisk +will respond with a usage message which describes how to use that command. As +with other commands on the Asterisk console, the help command also responds to +tab command line completion. + diff --git a/1.4.23-rc4/doc/cliprompt.txt b/1.4.23-rc4/doc/cliprompt.txt new file mode 100644 index 000000000..fbd7dd99f --- /dev/null +++ b/1.4.23-rc4/doc/cliprompt.txt @@ -0,0 +1,29 @@ +* 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) +%s Asterisk system name (from asterisk.conf) +%h Full hostname +%H Short hostname +%t Time +%% Percent sign +%# '#' if Asterisk is run in console mode, '>' if running as remote console +%Cn[;n] Change terminal foreground (and optional background) color to specified + 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/1.4.23-rc4/doc/configuration.txt b/1.4.23-rc4/doc/configuration.txt new file mode 100644 index 000000000..39e906101 --- /dev/null +++ b/1.4.23-rc4/doc/configuration.txt @@ -0,0 +1,180 @@ +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, chan_dahdi.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 occurred. + + #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/1.4.23-rc4/doc/cygwin.txt b/1.4.23-rc4/doc/cygwin.txt new file mode 100644 index 000000000..0273a1d37 --- /dev/null +++ b/1.4.23-rc4/doc/cygwin.txt @@ -0,0 +1,9 @@ +Cygwin support is completely experimental and unsupported at this time. The +current state of cygwin support is that it will compile, and start the cli, +but will not yet take calls properly. + +To compile with cygwin, you will need at least a standard base cygwin install plus the following packages: + +minires +minires-devel + diff --git a/1.4.23-rc4/doc/datastores.txt b/1.4.23-rc4/doc/datastores.txt new file mode 100644 index 000000000..64b5d35cc --- /dev/null +++ b/1.4.23-rc4/doc/datastores.txt @@ -0,0 +1,63 @@ +Asterisk Channel Data Stores +============================ + +* What is a data store? + +A data store is a way of storing complex data (such as a structure) on a channel +so it can be retrieved at a later time by another application, or the same application. + +If the data store is not freed by said application though, a callback to a destroy function +occurs which frees the memory used by the data in the data store so no memory loss occurs. + +* A datastore info structure +static const struct example_datastore { + .type = "example", + .destroy = callback_destroy +}; + +This is a needed structure that contains information about a datastore, it's used by many API calls. + +* How do you create a data store? + +1. Use ast_channel_datastore_alloc function to return a pre-allocated structure + Ex: datastore = ast_channel_datastore_alloc(&example_datastore, "uid"); + This function takes two arguments: (datastore info structure, uid) +2. Attach data to pre-allocated structure. + Ex: datastore->data = mysillydata; +3. Add datastore to the channel + Ex: ast_channel_datastore_add(chan, datastore); + This function takes two arguments: (pointer to channel, pointer to data store) + +Full Example: + +void callback_destroy(void *data) +{ + ast_free(data); +} + +struct ast_datastore *datastore = NULL; +datastore = ast_channel_datastore_alloc(&example_datastore, NULL); +datastore->data = mysillydata; +ast_channel_datastore_add(chan, datastore); + +NOTE: Because you're passing a pointer to a function in your module, you'll want to include +this in your use count. When allocated increment, when destroyed decrement. + +* How do you remove a data store? + +1. Find the data store + Ex: datastore = ast_channel_datastore_find(chan, &example_datastore, NULL); + This function takes three arguments: (pointer to channel, datastore info structure, uid) +2. Remove the data store from the channel + Ex: ast_channel_datastore_remove(chan, datastore); + This function takes two arguments: (pointer to channel, pointer to data store) +3. If we want to now do stuff to the data on the data store +4. Free the data store (this will call the destroy call back) + Ex: ast_channel_datastore_free(datastore); + This function takes one argument: (pointer to data store) + +* How do you find a data store? + +1. Find the data store + Ex: datastore = ast_channel_datastore_find(chan, &example_datastore, NULL); + This function takes three arguments: (pointer to channel, datastore info structure, uid) diff --git a/1.4.23-rc4/doc/digium-mib.txt b/1.4.23-rc4/doc/digium-mib.txt new file mode 100644 index 000000000..d29cd1b48 --- /dev/null +++ b/1.4.23-rc4/doc/digium-mib.txt @@ -0,0 +1,24 @@ +DIGIUM-MIB DEFINITIONS ::= BEGIN + +IMPORTS + enterprises, MODULE-IDENTITY + FROM SNMPv2-SMI; + +digium MODULE-IDENTITY + LAST-UPDATED "200806202000Z" + ORGANIZATION "Digium, Inc." + CONTACT-INFO + "Mark Spencer + Email: markster@digium.com" + DESCRIPTION + "The Digium private-enterprise MIB" + REVISION "200806202000Z" + DESCRIPTION + "Corrected imports and missing revision for last update. + Addresses bug 12905. - jeffg@opennms.org" + REVISION "200602041900Z" + DESCRIPTION + "Initial revision." + ::= { enterprises 22736 } + +END diff --git a/1.4.23-rc4/doc/dundi.txt b/1.4.23-rc4/doc/dundi.txt new file mode 100644 index 000000000..ffcefc7b8 --- /dev/null +++ b/1.4.23-rc4/doc/dundi.txt @@ -0,0 +1,26 @@ +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 incurring a risk of a single point of failure. In this way, +administrators can locally add extensions which become immediately +available to the other nodes in the system. + +For more information visit http://www.dundi.com diff --git a/1.4.23-rc4/doc/enum.txt b/1.4.23-rc4/doc/enum.txt new file mode 100644 index 000000000..3d3d03b0c --- /dev/null +++ b/1.4.23-rc4/doc/enum.txt @@ -0,0 +1,308 @@ +Enum support in the ENUMLOOKUP dialplan function +------------------------------------------------ +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(number[|Method-type[|options[|record#[|zone-suffix]]]]) + + Performs an ENUM tree lookup on the specified number, method type, and + ordinal record offset, and returns one of four different values: + + 1) post-parsed NAPTR of one method (URI) type + 2) count of elements of one method (URI) type + 3) count of all method types + 4) full URI of method at a particular point in the list of all possible methods + +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 <number> + specified will then be returned, starting with 1 as the first + record (lowest value) in the list. The service types are not + hardcoded in Asterisk except for the default (sip) if no other + service type specified; any method type string (IANA-approved or + not) may be used except for the string "ALL". + +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. + +record# = which record to present if multiple answers are returned + <integer> = The record in priority/order sequence based on the + total count of records passed back by the query. If a service_type + is specified, all entries of that type will be sorted into an + ordinal list starting with 1 (by order first, then priority). + The default of <options> is "1" + +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 + (deprecated) style, reversed method strings such as "sip+E2U" + instead of the more modern "E2U+sip" + + i) There is no provision for multi-part methods at this time. If + 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/${enumresult}) +exten => _011.,n,Dial(Zap/g1/${EXTEN}) +; +; end example 1 + +; example 2 +; +; Assumes North American international dialing (011) prefix. +; Check to see if there are multiple SIP NAPTRs returned by +; the lookup, and dial each in order. If none work (or none +; exist) then send the call out a PRI, group 1. +; +exten => _011.,1,Set(sipcount=${ENUMLOOKUP(${EXTEN:3},sip,c)}|counter=0) +exten => _011.,n,While($["${counter}"<"${sipcount}"]) +exten => _011.,n,Set(counter=$[${counter}+1]) +exten => _011.,n,Dial(SIP/${ENUMLOOKUP(+${EXTEN:3},sip,,${counter})}) +exten => _011.,n,EndWhile +exten => _011.,n,Dial(Zap/g1/${EXTEN}) +; +; end example 2 + +; example 3 +; +; This example expects an ${EXTEN} that is an e.164 number (like +; 14102241145 or 437203001721) +; Search through e164.arpa and then also search through e164.org +; to see if there are any valid SIP or IAX termination capabilities. +; If none, send call out via Zap channel 1. +; +; Start first with e164.arpa zone... +; +exten => _X.,1,Set(sipcount=${ENUMLOOKUP(+${EXTEN},sip,c)}|counter=0) +exten => _X.,2,GotoIf($["${counter}"<"${sipcount}"]?3:6) +exten => _X.,3,Set(counter=$[${counter}+1]) +exten => _X.,4,Dial(SIP/${ENUMLOOKUP(+${EXTEN},sip,,${counter})}) +exten => _X.,5,GotoIf($["${counter}"<"${sipcount}"]?3:6) +; +exten => _X.,6,Set(iaxcount=${ENUMLOOKUP(+${EXTEN},iax2,c)}|counter=0) +exten => _X.,7,GotoIf($["${counter}"<"${iaxcount}"]?8:11) +exten => _X.,8,Set(counter=$[${counter}+1]) +exten => _X.,9,Dial(IAX2/${ENUMLOOKUP(+${EXTEN},iax2,,${counter})}) +exten => _X.,10,GotoIf($["${counter}"<"${iaxcount}"]?8:11) +; +exten => _X.,11,NoOp("No valid entries in e164.arpa for ${EXTEN} - checking in e164.org") +; +; ...then also try e164.org, and look for SIP and IAX NAPTRs... +; +exten => _X.,12,Set(sipcount=${ENUMLOOKUP(+${EXTEN},sip,c,,e164.org)}|counter=0) +exten => _X.,13,GotoIf($["${counter}"<"${sipcount}"]?14:17) +exten => _X.,14,Set(counter=$[${counter}+1]) +exten => _X.,15,Dial(SIP/${ENUMLOOKUP(+${EXTEN},sip,,${counter},e164.org)}) +exten => _X.,16,GotoIf($["${counter}"<"${sipcount}"]?14:17) +; +exten => _X.,17,Set(iaxcount=${ENUMLOOKUP(+${EXTEN},iax2,c,,e164.org)}|counter=0) +exten => _X.,18,GotoIf($["${counter}"<"${iaxcount}"]?19:22) +exten => _X.,19,Set(counter=$[${counter}+1]) +exten => _X.,20,Dial(IAX2/${ENUMLOOKUP(+${EXTEN},iax2,,${counter},e164.org)}) +exten => _X.,21,GotoIf($["${counter}"<"${iaxcount}"]?19:22) +; +; ...then send out PRI. +; +exten => _X.,22,NoOp("No valid entries in e164.org for ${EXTEN} - sending out via Zap") +exten => _X.,23,Dial(Zap/g1/${EXTEN}) +; +; end example 3 diff --git a/1.4.23-rc4/doc/extconfig.txt b/1.4.23-rc4/doc/extconfig.txt new file mode 100644 index 000000000..0a95997ce --- /dev/null +++ b/1.4.23-rc4/doc/extconfig.txt @@ -0,0 +1,91 @@ +Asterisk external configuration +=============================== + +The Asterisk external configuration engine is the result of work by +Anthony Minessale II, Mark Spencer and Constantine Filin. + +It is designed to provide a flexible, seamless integration between +Asterisk's internal configuration structure and external SQL other other +databases (maybe even LDAP one day). + +The external configuration engine is the basis for the ARA, the +Asterisk Realtime Architecture (see doc/realtime.txt for more +information). + +* Configuration + +External configuration is configured in /etc/asterisk/extconfig.conf +allowing you to map any configuration file (static mappings) to +be pulled from the database, or to map special runtime entries which +permit the dynamic creation of objects, entities, peers, etc. without +the necessity of a reload. + +Generally speaking, the columns in your tables should line up with the +fields you would specify in the given entity declaration. If an entry +would appear more than once, in the column it should be separated by a +semicolon. For example, an entity that looks like: + +[foo] +host=dynamic +secret=bar +context=default +context=local + +could be stored in a table like this: + ++------+--------+-------+--------------+----------+-----+-----------+ +| name | host | secret| context | ipaddr | port| regseconds| ++------+--------+-------+--------------+----------+-----+-----------+ +| foo | dynamic| bar | default;local| 127.0.0.1| 4569| 1096954152| ++------+--------+-------+--------------+----------+-----+-----------+ + +Note that for use with IAX or SIP, the table will also need the "name", +"ipaddr", "port", "regseconds" columns. If you wanted to be able to +configure the callerid, you could just add a callerid column to the +table, for example. + +A SIP table would look more like this: + ++------+--------+-------+----------+-----+------------+----------+ +| name | host | secret| ipaddr | port| regseconds | username | ++------+--------+-------+----------+-----+------------+----------+ +| foo | dynamic| bar | 127.0.0.1| 4569| 1096954152 | 1234 | ++------+--------+-------+----------+-----+------------+----------+ + +in order to store appropriate parameters required for SIP. + +In addition to this, if you add a field named "regserver" to the +SIP peers table and have the system name set in asterisk.conf, +Asterisk will store the system name that the user registered on in +the database. This can be used to direct calls to go through the server +that holds the registration (for NAT traversal purposes). + +A Voicemail table would look more like this: + ++----------+---------+----------+----------+-----------+---------------+ +| uniqueid | mailbox | context | password |email | fullname | ++----------+---------+----------+----------+-----------+---------------+ +| 1 | 1234 | default | 4242 | a@b.com | Joe Schmoe | ++----------+---------+----------+----------+-----------+---------------+ + +The uniqueid should be unique to each voicemail user and can be +autoincrement. It need not have any relation to the mailbox or context. + +An extension table would look more like this: + ++----------+---------+----------+-------+-----------+ +| context | exten | priority | app | appdata | ++----------+---------+----------+-------+-----------+ +| default | 1234 | 1 | Dial | Zap/1 | ++----------+---------+----------+-------+-----------+ + +In the dialplan you just use the Realtime switch: + +[foo] +switch => Realtime + +or: + +[bar] +switch => Realtime/bar@extensions + diff --git a/1.4.23-rc4/doc/extensions.txt b/1.4.23-rc4/doc/extensions.txt new file mode 100644 index 000000000..90826f15f --- /dev/null +++ b/1.4.23-rc4/doc/extensions.txt @@ -0,0 +1,58 @@ +The Asterisk dialplan +===================== + +The Asterisk dialplan is divided into contexts. A context is simply a group +of extensions. For each "line" that should be able to be called, an extension +must be added to a context. Then, you configure the calling "line" to have +access to this context. + +If you change the dialplan, you can use the Asterisk CLI command +"extensions reload" to load the new dialplan without disrupting +service in your PBX. + +Extensions are routed according to priority and may be based on any set +of characters (a-z), digits, #, and *. Please note that when matching a +pattern, "N", "X", and "Z" are interpreted as classes of digits. + +For each extension, several actions may be listed and must be given a unique +priority. When each action completes, the call continues at the next priority +(except for some modules which use explicitly GOTO's). + +When each action completes, it generally moves to the next priority (except for +some modules which use explicitly GOTO's. + +Extensions frequently have data they pass to the executing application +(most frequently a string). You can see the available dialplan applications +by entering the "show applications" command in the CLI. + +In this version of Asterisk, dialplan functions are added. These can +be used as arguments to any application. For a list of the installed +functions in your Asterisk, use the "show functions" command. + +* 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 worthwhile 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/1.4.23-rc4/doc/externalivr.txt b/1.4.23-rc4/doc/externalivr.txt new file mode 100644 index 000000000..a1d4757e7 --- /dev/null +++ b/1.4.23-rc4/doc/externalivr.txt @@ -0,0 +1,109 @@ +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/1.4.23-rc4/doc/freetds.txt b/1.4.23-rc4/doc/freetds.txt new file mode 100644 index 000000000..e1c27fba3 --- /dev/null +++ b/1.4.23-rc4/doc/freetds.txt @@ -0,0 +1,18 @@ +PLEASE NOTE + +The cdr_tds module is NOT compatible with version 0.63 of FreeTDS. + +The cdr_tds module is known to work with FreeTDS version 0.62.1; +it should also work with 0.62.2, 0.62.3 and 0.62.4, which are bug +fix releases. + +The cdr_tds module uses the raw "libtds" API of FreeTDS. It appears +that from 0.63 onwards, this is not considered a published API +of FreeTDS and is subject to change without notice. + +Between 0.62.x and 0.63 of FreeTDS, many incompatible changes +have been made to the libtds API. + +For newer versions of FreeTDS, it is recommended that you use the +ODBC driver. + diff --git a/1.4.23-rc4/doc/h323.txt b/1.4.23-rc4/doc/h323.txt new file mode 100644 index 000000000..c7383e7af --- /dev/null +++ b/1.4.23-rc4/doc/h323.txt @@ -0,0 +1,22 @@ +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/1.4.23-rc4/doc/hardware.txt b/1.4.23-rc4/doc/hardware.txt new file mode 100644 index 000000000..9e4e96e91 --- /dev/null +++ b/1.4.23-rc4/doc/hardware.txt @@ -0,0 +1,74 @@ +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: DAHDI devices and +non-DAHDI devices. The DAHDI compatible hardware supports pseudo-TDM +conferencing and all call features through chan_dahdi, whereas non-DAHDI +compatible hardware may have different features. + +DAHDI compatible hardware +========================== + +-- Digium (Primary author of Asterisk) + http://www.digium.com, http://store.digium.com + + * Wildcard T400P (obsolete) - Quad T1 interface connects to four T1/PRI + interfaces. Supports RBS and PRI voice and PPP, FR, and HDLC data. + + * Wildcard E400P (obsolete)- Quad E1 interface connects to four E1/PRI + (or PRA) interfaces. Supports PRA/PRI, EuroISDN voice and data. + + * Wildcard T100P - Single T1 interface connects to a single T1/PRI + interface. Supports RBS and PRI voice and PPP, FR, and HDLC data. + + * Wildcard E100P - Single E1 interface connects to a single E1/PRI (or PRA) + interface. Supports PRA/PRI, EuroISDN voice and PPP, FR, HDLC data. + + * Wildcard TDM400P - Quad Modular FXS interface connects to standard + analog telephones. + + * Wildcard TE410P - Quad T1/E1 switchable interface. Supports PRI and + RBS signalling, as well as PPP, FR, and HDLC data modes. + +Non-DAHDI compatible hardware +============================== + +-- QuickNet, Inc. + http://www.quicknet.net + + * Internet PhoneJack - Single FXS interface. Supports Linux telephony + interface. DSP compression built-in. + + * Internet LineJack - Single FXS or FXO interface. Supports Linux + telephony interface. + +mISDN compatible hardware +========================= +mISDN homepage: http://www.isdn4linux.de/mISDN/ + +Any adapter with an mISDN driver should be compatible with +chan_misdn. See misdn.txt for information. + +-- beroNet + http://www.beronet.com + + * BN4S0 - 4 Port BRI card (TE/NT) + + * BN8S0 - 8 Port BRI card (TE/NT) + + * Billion Card - Single Port BRI card (TE (/NT with crossed cable) ) + + +Miscellaneous other interfaces +============================== + +-- ALSA + http://www.alsa-project.org + + * Any ALSA compatible full-duplex sound card + +-- OSS + http://www.opensound.com + + * Any OSS compatible full-duplex sound card diff --git a/1.4.23-rc4/doc/iax.txt b/1.4.23-rc4/doc/iax.txt new file mode 100644 index 000000000..cf952a113 --- /dev/null +++ b/1.4.23-rc4/doc/iax.txt @@ -0,0 +1,67 @@ +Inter-Asterisk eXchange Protocol +================================ + +Usage: +====== +The format for the dialing string on Asterisk is: +IAX/[user@]peer[:exten[@context]] + +(Note, []'s denote optional fields). The peer is either an IP address +or a peer as specified in the /etc/asterisk/iax.conf file. Exten is +an optional requested extension (otherwise "s" will be used), and +"context" is an optional context to request. The user is an optional +username specified in the peer's iax.conf. If the user is not specified, +the peer will select one. + +The peer uses a score to determine the best user entry to match against if +one is not specified: + +1. User entry with secret and no ACL specified. +2. User entry with secret specified and ACL specified. +3. User entry with no secret specified and no ACL specified. +4. User entry with no secret specified and ACL specified. +5. User entry matched via username. + +The higher the score the better it is with 5 being an exact match and the maximum +score possible. + +Protocol and rationale: +======================= +IAX is a simple, low overhead and low bandwidth VoIP protocol designed to +allow multiple Asterisk PBX's to communicate with one another without +the overhead of more complex protocols like H.323. Payload is sent with +a header overhead of only 4 octets. Control functions (and one payload packet +per minute or so) is sent with a more complex header of 12 octets. + +IAX is slightly stateful. + +IAX contains two kinds of packets: The full header packet type, which +contains much information about the frame, in addition to its contents, +and the mini header type, which is used only for non-reliable voice +packet delivery. + +All packets are immediately transmitted. Packets are received, but not +delivered to the actual channels until a given time quantum has passed, in +order to try to eliminate jitter. + +All full header packets must be ackd (except, obviously for the ACK packets +themselves and not so obviously for hangup packets). The "timestamp" field of +ack packets is not the normal offset, but rather a quote of the timestamp as +included with the original packet that you're acking, and likewise the +seqno field is the seqno of the packet you're acking, not your own seqno, +and you do not increment your own sequence number. ACKing is based on the +sequence number. + +See iax.h for a description of the frame formats. + +IAX internal frames use the AST_FRAME_IAX type. The subclass of these +frames is the IAX control number, as seen in iax.h. The first frame sent +must be an AST_FRAME_IAX with the control AST_IAX_CONTROL_NEW. + +The AST_IAX_CONTROL_NEW establishes a new connection. + +The first frame sent MUST be an AST_CONTROL_NEW to start a connection. + +IAX connnections may require authentication using either simple plaintext +passwords or an md5 challenge/response pair. + diff --git a/1.4.23-rc4/doc/ices.txt b/1.4.23-rc4/doc/ices.txt new file mode 100644 index 000000000..d75236357 --- /dev/null +++ b/1.4.23-rc4/doc/ices.txt @@ -0,0 +1,12 @@ +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/1.4.23-rc4/doc/imapstorage.txt b/1.4.23-rc4/doc/imapstorage.txt new file mode 100644 index 000000000..0dd663371 --- /dev/null +++ b/1.4.23-rc4/doc/imapstorage.txt @@ -0,0 +1,217 @@ +====================== +IMAP Voicemail Storage +====================== + +03-01-2006 - James Rothenberger <jar@onebiztone.com> + +By enabling IMAP Storage, Asterisk will use native IMAP as the storage +mechanism for voicemail messages instead of using the standard file structure. + +Tighter integration of Asterisk voicemail and IMAP email services allows +additional voicemail functionality, including: + + - Listening to a voicemail on the phone will set its state to "read" in + a user's mailbox automatically. + - Deleting a voicemail on the phone will delete it from the user's + mailbox automatically. + - Accessing a voicemail recording email message will turn off the message + waiting indicator (MWI) on the user's phone. + - Deleting a voicemail recording email will also turn off the message + waiting indicator, and delete the message from the voicemail system. + +===================== +Contents of this file +===================== + + - Installation Notes + - Separate vs. Shared Email Accounts + - IMAP Server Implementations + - Quota Support + - Application Notes + - Known Issues + + +================== +Installation Notes +================== + +-------------------------------------- +University of Washington IMAP C-Client +-------------------------------------- +You will need a source distribution of University of Washington's IMAP +c-client (http://www.washington.edu/imap/). Asterisk supports both the +2004 and 2006 versions of c-client, however mail_expunge_full is enabled +in the 2006 version. + +Note that Asterisk only uses the 'client' portion of the UW IMAP toolkit, +but building it also builds an IMAP server and various other utilities. +Because of this, the build instructions for the IMAP toolkit are somewhat +complicated and can lead to confusion about what is needed. + +If you are going to be connecting Asterisk to an existing IMAP server, +then you don't need to care about the server or utilities in the IMAP +toolkit at all. If you want to also install the UW IMAPD server, that +is outside the scope of this document. + +Building the c-client library is fairly straightforward; for example, on a +Debian system there are two possibilities: + +1) if you will not be using SSL to connect to the IMAP server: + $ make slx SSLTYPE=none + +2) if you will be using SSL to connect to the IMAP server: + $ make slx EXTRACFLAGS="-I/usr/include/openssl" + +Once this completes you can proceed with the Asterisk build; there is no +need to run 'make install'. + +------------------ +Compiling Asterisk +------------------ + +Configure with ./configure --with-imap=/usr/src/imap +or where ever you built thfe UWashington IMAP Toolkit. This directory +will be searched for a source installation. If no source installation is +found there, then a package installation of the IMAP c-client will be +searched for in this directory. If one is not found, then configure will fail + +A second configure option is to not specify a directory (i.e. +./configure --with-imap). This will assume that you have the +imap-2004g source installed in the .. directory relative to the +Asterisk source. If you do not have this source, then configure will +default to the "system" option defined in the next paragraph + +A third option is ./configure --with-imap=system. This will assume +that you have installed a dynamically linked version of the c-client +library (most likely via a package provided by your distro). This will +attempt to link agains -lc-client and will search for c-client headers +in your include path starting with the imap directory, and upon failure, +in the c-client directory. + +When you run 'make menuselect', choose 'Voicemail Build Options' and the +IMAP_STORAGE option should be available for selection. + +After selecting it, use the 'x' key to exit menuselect and save +your changes, and the build/install Asterisk normally. + +--------------------- +Modify voicemail.conf +--------------------- +The following directives have been added to voicemail.conf: + +imapserver=<name or IP address of IMAP mail server> +imapport=<IMAP port, defaults to 143> +imapflags=<IMAP flags, "novalidate-cert" for example> +expungeonhangup=<yes or no> +authuser=<username> +authpassword=<password> +imapopentimeout=<TCP open timeout in seconds> +imapclosetimeout=<TCP close timeout in seconds> +imapreadtimeout=<TCP read timeout in seconds> +imapwritetimeout=<TCP write timeout in seconds> + +The "expungeonhangup" flag is used to determine if the voicemail system should +expunge all messages marked for deletion when the user hangs up the phone. + +Each mailbox definition should also have imapuser=<imap username>. +For example: + +4123=>4123,James Rothenberger,jar@onebiztone.com,,attach=yes|imapuser=jar + +The directives "authuser" and "authpassword" are not needed when using +Kerberos. They are defined to allow Asterisk to authenticate as a single +user that has access to all mailboxes as an alternative to Kerberos. + +-------------- +IMAP Folders +-------------- +Besides INBOX, users should create "Old", "Work", "Family" and "Friends" +IMAP folders at the same level of hierarchy as the INBOX. These will be +used as alternate folders for storing voicemail messages to mimic the +behavior of the current (file-based) voicemail system. + + +================================== +Separate vs. Shared Email Accounts +================================== +As administrator you will have to decide if you want to send the voicemail +messages to a separate IMAP account or use each user's existing IMAP mailbox +for voicemail storage. The IMAP storage mechanism will work either way. + +By implementing a single IMAP mailbox, the user will see voicemail messages +appear in the same INBOX as other messages. The disadvantage of this method +is that if the IMAP server does NOT support UIDPLUS, Asterisk voicemail will +expunge ALL messages marked for deletion when the user exits the voicemail +system, not just the VOICEMAIL messages marked for deletion. + +By implementing separate IMAP mailboxes for voicemail and email, voicemail +expunges will not remove regular email flagged for deletion. + +=========================== +IMAP Server Implementations +=========================== +There are various IMAP server implementations, each supports a potentially +different set of features. + +----------------------- +UW IMAP-2005 or earlier +----------------------- +UIDPLUS is currently NOT supported on these versions of UW-IMAP. Please note +that without UID_EXPUNGE, Asterisk voicemail will expunge ALL messages marked +for deletion when a user exits the voicemail system (hangs up the phone). + +------------------------------- +UW IMAP-2006 Development Branch +------------------------------- +This version supports UIDPLUS, which allows UID_EXPUNGE capabilities. This +feature allow the system to expunge ONLY pertinent messages, instead of the +default behavior, which is to expunge ALL messages marked for deletion when +EXPUNGE is called. The IMAP storage mechanism is this version of Asterisk +will check if the UID_EXPUNGE feature is supported by the server, and use it +if possible. + +---------- +Cyrus IMAP +---------- +Cyrus IMAP server v2.3.3 has been tested using a hierarchy delimiter of '/'. + + +============= +Quota Support +============= +If the IMAP server supports quotas, Asterisk will check the quota when +accessing voicemail. Currently only a warning is given to the user that +their quota is exceeded. + + +================= +Application Notes +================= +Since the primary storage mechanism is IMAP, all message information that +was previously stored in an associated text file, AND the recording itself, +is now stored in a single email message. This means that the .gsm recording +will ALWAYS be attached to the message (along with the user's preference of +recording format if different - ie. .WAV). The voicemail message information +is stored in the email message headers. These headers include: + +X-Asterisk-VM-Message-Num +X-Asterisk-VM-Server-Name +X-Asterisk-VM-Context +X-Asterisk-VM-Extension +X-Asterisk-VM-Priority +X-Asterisk-VM-Caller-channel +X-Asterisk-VM-Caller-ID-Num +X-Asterisk-VM-Caller-ID-Name +X-Asterisk-VM-Duration +X-Asterisk-VM-Category +X-Asterisk-VM-Orig-date +X-Asterisk-VM-Orig-time + +================= +Known Issues +================= + + - Forward With Comment advanced option is not currently supported. + This feature will be added in the near future. + - Message Waiting Indicator blinks off and back on when a message arrives. + This should be fixed soon. diff --git a/1.4.23-rc4/doc/ip-tos.txt b/1.4.23-rc4/doc/ip-tos.txt new file mode 100644 index 000000000..36febd99a --- /dev/null +++ b/1.4.23-rc4/doc/ip-tos.txt @@ -0,0 +1,81 @@ +IP Type of Service settings for VoIP channels +--------------------------------------------- + +Asterisk can set the Type of Service (TOS) byte on outgoing IP packets +for various protocols. The TOS byte is used by the network to provide +some level of Quality of Service (QoS) even if the network is +congested with other traffic. + +* SIP +----- +In sip.conf, there are three parameters that control the TOS settings: +"tos_sip", "tos_audio", and "tos_video". tos_sip controls what TOS SIP call +signalling packets are set to. tos_audio controls what TOS RTP audio +packets are set to. tos_video controls what TOS RTP video packets are +set to. +There is a "tos" parameter that is supported for backwards +compatibility. The tos parameter should be avoided in sip.conf +because it sets all three tos settings in sip.conf to the same value. + +* IAX2 +------ +In iax.conf, there is a "tos" parameter that sets the global default TOS +for IAX packets generated by chan_iax2. Since IAX connections combine +signalling, audio, and video into one UDP stream, it is not possible +to set the TOS separately for the different types of traffic. + +In iaxprov.conf, there is a "tos" parameter that tells the IAXy what TOS +to set on packets it generates. As with the parameter in iax.conf, +IAX packets generated by an IAXy cannot have different TOS settings +based upon the type of packet. However different IAXy devices can +have different TOS settings. + +The allowable values for any of the tos* parameters are: +CS0, CS1, CS2, CS3, CS4, CS5, CS6, CS7, AF11, AF12, AF13, +AF21, AF22, AF23, AF31, AF32, AF33, AF41, AF42, AF43 and +ef (expedited forwarding), + +The tos* parameters also take numeric values. + +The lowdelay, throughput, reliability, mincost, and none values are +deprecated because they set the IP TOS using the outdated "IP +precedence" model as defined in RFC 791 and RFC 1349. They still +work in this version of Asterisk, but will be removed in future releases. + +=========================================== +Configuration Parameter Recommended +File Setting +------------------------------------------- +sip.conf tos_sip cs3 +sip.conf tos_audio ef +sip.conf tos_video af41 +------------------------------------------- +iax.conf tos ef +------------------------------------------- +iaxprov.conf tos ef +=========================================== + + +* REFERENCE +----------- +RFC 2474 - "Definition of the Differentiated Services Field +(DS field) in the IPv4 and IPv6 Headers", Nichols, K., et al, +December 1998. + +IANA Assignments, DSCP registry +Differentiated Services Field Codepoints +http://www.iana.org/assignments/dscp-registry + +To get the most out of setting the TOS on packets generated by +Asterisk, you will need to ensure that your network handles packets +with a TOS properly. For Cisco devices, see the previously mentioned +"Enterprise QoS Solution Reference Network Design Guide". For Linux +systems see the "Linux Advanced Routing & Traffic Control HOWTO" at +<http://www.lartc.org/>. + +For more information on Quality of +Service for VoIP networks see the "Enterprise QoS Solution Reference +Network Design Guide" version 3.3 from Cisco at: + +<http://www.cisco.com/application/pdf/en/us/guest/netsol/ns432/c649/ccmigration_09186a008049b062.pdf> + diff --git a/1.4.23-rc4/doc/jabber.txt b/1.4.23-rc4/doc/jabber.txt new file mode 100644 index 000000000..ca3e0f528 --- /dev/null +++ b/1.4.23-rc4/doc/jabber.txt @@ -0,0 +1,15 @@ +(res_jabber is very experimental!) + +Jabber(xmpp) is an xml based protocol primarily for presence and messaging. +It is an open standard and there are several open server implementations, +ejabberd, jabberd(2), wildfire, and many others, as well as several open source +clients, Psi, gajim, gaim etc. Jabber differs from other IM applications as it +is immensly extendable. This allows us to easily integrate Asterisk with +jabber. The Asterisk Jabber Interface is provided by res_jabber.so. res_jabber +allows for Asterisk to connect to any jabber server via the standard client +protocol or also as a simple client. Several simple functions are exposed to +the dial plan, jabberstatus, jabbersend, and soon jabberrecv. res_jabber is also used +to provide the connection interface for chan_jingle. + +The maintainer of res_jabber is Matthew O'Gorman <mogorman@digium.com> or +mog_work on irc or (preferred) mogorman@astjab.org over jabber. diff --git a/1.4.23-rc4/doc/jingle.txt b/1.4.23-rc4/doc/jingle.txt new file mode 100644 index 000000000..76398f10a --- /dev/null +++ b/1.4.23-rc4/doc/jingle.txt @@ -0,0 +1,11 @@ +(Jingle support in asterisk is experimental) +Jingle is an xmpp based protocol for signalling the transfer of media. +Currently asterisk supports the proprietary GoogleTalk protocol that is +very similar to jingle, and hopes to soon support true jingle specs +(JEP-166,167,176,177,180,181 etc) as more clients support the true standard. +Jingle's configuration is very similar to sip.conf only as we are not the +jabber server in this case you must provide a connection for the peer to +travel out on. +chan_gtalk is for supporting the non-jingle google/libjingle spec and +chan_jingle will continue to move in the direction of the correct spec. but +not be supported in version 1.4 diff --git a/1.4.23-rc4/doc/jitterbuffer.txt b/1.4.23-rc4/doc/jitterbuffer.txt new file mode 100644 index 000000000..e5cd81ce0 --- /dev/null +++ b/1.4.23-rc4/doc/jitterbuffer.txt @@ -0,0 +1,137 @@ +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 <n>". This will simulate n percent packet loss +coming _in_ to chan_iax2. You should find that with PLC and the new JB, 10 percent packet +loss should lead to just a tiny amount of distortion, while without PLC, it would lead to +silent gaps in your audio. + +"iax2 show netstats" shows you statistics for each iax2 call you have up. +The columns are "RTT" which is the round-trip time for the last PING, and then a bunch of s +tats for both the local side (what you're receiving), and the remote side (what the other +end is telling us they are seeing). The remote stats may not be complete if the remote +end isn't using the new jitterbuffer. + +The stats shown are: +* 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 <other-end>] + +Report bugs in the Asterisk bugtracker, http://bugs.digium.com. +Please read the bug guidelines before you post a bug. + +Have fun! + +-SteveK diff --git a/1.4.23-rc4/doc/lang/hebrew.ods b/1.4.23-rc4/doc/lang/hebrew.ods Binary files differnew file mode 100644 index 000000000..f8b0f54df --- /dev/null +++ b/1.4.23-rc4/doc/lang/hebrew.ods diff --git a/1.4.23-rc4/doc/linkedlists.txt b/1.4.23-rc4/doc/linkedlists.txt new file mode 100644 index 000000000..340933548 --- /dev/null +++ b/1.4.23-rc4/doc/linkedlists.txt @@ -0,0 +1,98 @@ +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 <asterisk/linkedlists.h> + +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/1.4.23-rc4/doc/localchannel.txt b/1.4.23-rc4/doc/localchannel.txt new file mode 100644 index 000000000..ccedbebed --- /dev/null +++ b/1.4.23-rc4/doc/localchannel.txt @@ -0,0 +1,49 @@ +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 and one audio frame passes, the variables and dial plan will revert back to that of the original call, and the Local channel will become a zombie and be removed from the active channels list. This is desirable in some circumstances, but can result in unexpected dialplan behavior if you are doing fancy things with variables in your call handling. + +* 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/1.4.23-rc4/doc/macroexclusive.txt b/1.4.23-rc4/doc/macroexclusive.txt new file mode 100644 index 000000000..3a3111493 --- /dev/null +++ b/1.4.23-rc4/doc/macroexclusive.txt @@ -0,0 +1,78 @@ +About the MacroExclusive application +------------------------------------ + +Steve Davies <steve@connection-telecom.com + + +The MacroExclusive application was added to solve the problem of +synchronisation between calls running at the same time. + +This is usually an issue when you have calls manipulating global +variables or the Asterisk database, but may be useful elsewhere. + +Consider this example macro, intended to return a "next" number - +each caller is intended to get a different number: + +[macro-next] +exten => s,1,Set(RESULT=${COUNT}) +exten => s,n,SetGlobalVar(COUNT=$[${COUNT} + 1]) + +The problem is that in a box with high activity, you can be sure +that two calls will come along together - both will get the same +"RESULT", or the "COUNT" value will get mangled. + +Calling this Macro via MacroExclusive will use a mutex to make sure +that only one call executes in the Macro at a time. This ensures +that the two lines execute as a unit. + +Note that even the s,2 line above has its own race problem. Two +calls running that line at once will step on each other and +the count will end up as +1 rather than +2. + +I've also been able to use MacroExclusive where I have two Macros +that need to be mutually exclusive. + +Here's the example: + +[macro-push] +; push value ${ARG2} onto stack ${ARG1} +exten => s,1,Set(DB(STACK/${ARG1})=${ARG2}^${DB(STACK/${ARG1})}) + +[macro-pop] +; pop top value from stack ${ARG1} +exten => s,1,Set(RESULT=${DB(STACK/${ARG1})}) +exten => s,n,Set(DB(STACK/${ARG1})=${CUT(RESULT,^,2)}) +exten => s,n,Set(RESULT=${CUT(RESULT,^,1)}) + +All that futzing with the STACK/${ARG1} in the astdb needs protecting +if this is to work. But neither push nor pop can run together. + +So add this "pattern": + +[macro-stack] +exten => Macro(${ARG1},${ARG2},${ARG3}) + +... and use it like so: + +exten => s,1,MacroExclusive(stack,push,MYSTACK,bananas) +exten => s,n,MacroExclusive(stack,push,MYSTACK,apples) +exten => s,n,MacroExclusive(stack,push,MYSTACK,guavas) +exten => s,n,MacroExclusive(stack,push,MYSTACK,pawpaws) +exten => s,n,MacroExclusive(stack,pop,MYSTACK) ; RESULT gets pawpaws (yum) +exten => s,n,MacroExclusive(stack,pop,MYSTACK) ; RESULT gets guavas +exten => s,n,MacroExclusive(stack,pop,MYSTACK) ; RESULT gets apples +exten => s,n,MacroExclusive(stack,pop,MYSTACK) ; RESULT gets bananas + +We get to the push and pop macros "via" the stack macro. But only one call +can execute the stack macro at a time; ergo, only one of push OR pop can +run at a time. + +Hope people find this useful. + +Lastly, its worth pointing out that only Macros that access shared data +will require this MacroExclusive protection. And Macro's that you call +with macroExclusive should run quickly or you will clog up your Asterisk +system. + +Regards, +Steve diff --git a/1.4.23-rc4/doc/manager.txt b/1.4.23-rc4/doc/manager.txt new file mode 100644 index 000000000..a0a832c8d --- /dev/null +++ b/1.4.23-rc4/doc/manager.txt @@ -0,0 +1,311 @@ +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. + +Device status reports +--------------------- +Manager subscribes to extension status reports from all channels, +to be able to generate events when an extension or device changes +state. The level of details in these events may depend on the channel +and device configuration. Please check each channel configuration +file for more information. (in sip.conf, check the section on +subscriptions and call limits) + + +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: PlayDTMF +Parameters: Channel, Digit + +Command: Redirect +Parameters: Channel, ExtraChannel, Exten, Context, Priority + +Command: Timeout +Parameters: Channel, Timeout + +You can always get more information about a manager command +with the "show manager command <command>" CLI command in Asterisk. + +Examples +-------- +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: <Y | N> -- Does ACL exist for object ? + Action: <action> -- request or notification of a particular action + Address-IP: -- IPaddress + Address-Port: -- IP port number + Agent: <string> -- Agent name + AMAflags: -- AMA flag (cdr_manager, sippeers) + AnswerTime: -- Time of answer (cdr_manager) + Append: <bool> -- CDR userfield Append flag + Application: -- Application to use + Async: -- Whether or not to use fast setup + AuthType: -- Authentication type (for login or challenge) + "md5" + BillableSeconds: -- Billable seconds for call (cdr_manager) + CallerID: -- Caller id (name and number in Originate & cdr_manager) + CallerID: -- CallerID number + Number or "<unknown>" or "unknown" + (should change to "<unknown>" in app_queue) + CallerID1: -- Channel 1 CallerID (Link event) + CallerID2: -- Channel 2 CallerID (Link event) + CallerIDName: -- CallerID name + Name or "<unknown>" or "unknown" + (should change to "<unknown>" in app_queue) + Callgroup: -- Call group for peer/user + CallsTaken: <num> -- Queue status variable + Cause: <value> -- Event change cause - "Expired" + Cause: <value> -- Hangupcause (channel.c) + CID-CallingPres: -- Caller ID calling presentation + Channel: <channel> -- Channel specifier + Channel: <dialstring> -- Dialstring in Originate + Channel: <tech/[peer/username]> -- Channel in Registry events (SIP, IAX2) + Channel: <tech> -- Technology (SIP/IAX2 etc) in Registry events + ChannelType: -- Tech: SIP, IAX2, ZAP, MGCP etc + Channel1: -- Link channel 1 + Channel2: -- Link channel 2 + ChanObjectType: -- "peer", "user" + Codecs: -- Codec list + CodecOrder: -- Codec order, separated with comma "," + Command: -- Cli command to run + Context: -- Context + Count: <num> -- Number of callers in queue + Data: -- Application data + Default-addr-IP: -- IP address to use before registration + Default-Username: -- Username part of URI to use before registration + Destination: -- Destination for call (Dialstring ) (dial, cdr_manager) + DestinationContext: -- Destination context (cdr_manager) + DestinationChannel: -- Destination channel (cdr_manager) + DestUniqueID: -- UniqueID of destination (dial event) + Disposition: -- Call disposition (CDR manager) + Domain: <domain> -- DNS domain + Duration: <secs> -- Duration of call (cdr_manager) + Dynamic: <Y | N> -- Device registration supported? + Endtime: -- End time stamp of call (cdr_manager) + EventList: <flag> -- Flag being "Start", "End", "Cancelled" or "ListObject" + Events: <eventmask> -- Eventmask filter ("on", "off", "system", "call", "log") + Exten: -- Extension (Redirect command) + Extension: -- Extension (Status) + Family: <string> -- ASTdb key family + File: <filename> -- Filename (monitor) + Format: <format> -- Format of sound file (monitor) + From: <time> -- Parking time (ParkedCall event) + Hint: -- Extension hint + Incominglimit: -- SIP Peer incoming limit + Key: + Key: -- ASTdb Database key + LastApplication: -- Last application executed (cdr_manager) + LastCall: <num> -- Last call in queue + LastData: -- Data for last application (cdr_manager) + Link: -- (Status) + ListItems: <number> -- Number of items in Eventlist (Optionally sent in "end" packet) + Location: -- Interface (whatever that is -maybe tech/name in app_queue ) + Loginchan: -- Login channel for agent + Logintime: <number> -- Login time for agent + Mailbox: -- VM Mailbox (id@vmcontext) (mailboxstatus, mailboxcount) + MD5SecretExist: <Y | N> -- Whether secret exists in MD5 format + Membership: <string> -- "Dynamic" or "static" member in queue + Message: <text> -- Text message in ACKs, errors (explanation) + Mix: <bool> -- Boolean parameter (monitor) + NewMessages: <count> -- Count of new Mailbox messages (mailboxcount) + Newname: + ObjectName: -- Name of object in list + OldName: -- Something in Rename (channel.c) + OldMessages: <count> -- Count of old mailbox messages (mailboxcount) + Outgoinglimit: -- SIP Peer outgoing limit + Paused: <num> -- Queue member paused status + Peer: <tech/name> -- "channel" specifier :-) + PeerStatus: <tech/name> -- Peer status code + "Unregistered", "Registered", "Lagged", "Reachable" + Penalty: <num> -- Queue penalty + Priority: -- Extension priority + Privilege: <privilege> -- AMI authorization class (system, call, log, verbose, command, agent, user) + Pickupgroup: -- Pickup group for peer + Position: <num> -- Position in Queue + Queue: -- Queue name + Reason: -- "Autologoff" + Reason: -- "Chanunavail" + Response: <response> -- response code, like "200 OK" + "Success", "Error", "Follows" + Restart: -- "True", "False" + RegExpire: -- SIP registry expire + RegExpiry: -- SIP registry expiry + Reason: -- Originate reason code + Seconds: -- Seconds (Status) + Secret: <password> -- Authentication secret (for login) + SecretExist: <Y | N> -- Whether secret exists + Shutdown: -- "Uncleanly", "Cleanly" + SIP-AuthInsecure: + SIP-FromDomain: -- Peer FromDomain + SIP-FromUser: -- Peer FromUser + SIP-NatSupport: + SIPLastMsg: + Source: -- Source of call (dial event, cdr_manager) + SrcUniqueID: -- UniqueID of source (dial event) + StartTime: -- Start time of call (cdr_manager) + State: -- Channel state + Status: -- Registration status (Registry events SIP) + Status: -- Extension status (Extensionstate) + Status: -- Peer status (if monitored) ** Will change name ** + "unknown", "lagged", "ok" + Status: <num> -- Queue Status + Status: -- DND status (DNDState) + Time: <sec> -- Roundtrip time (latency) + Timeout: -- Parking timeout time + Timeout: -- Timeout for call setup (Originate) + Timeout: <seconds> -- Timeout for call + Uniqueid: -- Channel Unique ID + Uniqueid1: -- Channel 1 Unique ID (Link event) + Uniqueid2: -- Channel 2 Unique ID (Link event) + User: -- Username (SIP registry) + UserField: -- CDR userfield (cdr_manager) + Val: -- Value to set/read in ASTdb + Variable: -- Variable AND value to set (multiple separated with | in Originate) + Variable: <name> -- For channel variables + Value: <value> -- Value to set + VoiceMailbox: -- VM Mailbox in SIPpeers + Waiting: -- Count of mailbox messages (mailboxstatus) + + ** Please try to re-use existing headers to simplify manager message parsing in clients. + +Read the CODING-GUIDELINES if you develop new manager commands or events. diff --git a/1.4.23-rc4/doc/math.txt b/1.4.23-rc4/doc/math.txt new file mode 100644 index 000000000..7718f9e44 --- /dev/null +++ b/1.4.23-rc4/doc/math.txt @@ -0,0 +1,69 @@ + +Mathematical dialplan function + +Yeah, I thought it was a little insane too.. + +adds: + +Sum, Multiply, Divide, Subtract, Modulus, GT, LT, GTE, LTE, EQ functions to Asterisk + +All functions follow the same basic pattern for parameters: + +parameter 1 = the math expression +parameter 2 = the type of result + +Perform calculation on number 1 to number 2. Valid ops are: + +,-,/,*,%,<,>,>=,<=,== +and behave as their C equivalents. + +<type_of_result> - wanted type of result: + f, float - float(default) + i, int - integer, + h, hex - hex, + c, char - char + +Each math expression is performed as + + Action param1 on param2 + +eg: + + Action = Divide + Param1 = 10 + Param2 = 2 + +Results in + + Divide 10 by 2 + + +Example dialplan: + +exten => 11099,1,Set(RV=${MATH(1+20)}) +exten => 11099,n,NOOP(${RV}) +exten => 11099,n,Set(RV=${MATH(10*2)}) +exten => 11099,n,NOOP(${RV}) +exten => 11099,n,Set(RV=${MATH(10*2)}) +exten => 11099,n,NOOP(${RV}) +exten => 11099,n,Set(RV=${MATH(10-2)}) +exten => 11099,n,NOOP(${RV}) +exten => 11099,n,Set(RV=${MATH(2%10)}) +exten => 11099,n,NOOP(${RV}) +exten => 11099,n,Set(RV=${MATH(10/0)}) +exten => 11099,n,NOOP(${RV}) +exten => 11099,n,Set(RV=${MATH(10-200)}) +exten => 11099,n,NOOP(${RV}) +exten => 11099,n,Set(RV=${MATH(1-20)}) +exten => 11099,n,NOOP(${RV}) +exten => 11099,n,Set(RV=${MATH(1<20)}) +exten => 11099,n,NOOP(${RV}) +exten => 11099,n,Set(RV=${MATH(1>=20)}) +exten => 11099,n,NOOP(${RV}) +exten => 11099,n,Set(RV=${MATH(101>20)}) +exten => 11099,n,NOOP(${RV}) +exten => 11099,n,Set(RV=${MATH(1==20)}) +exten => 11099,n,NOOP(${RV}) +exten => 11099,n,Set(RV=${MATH(20<=20)}) +exten => 11099,n,NOOP(${RV}) +exten => 11099,n,Set(RV=${MATH(123%16,int)}) +exten => 11099,n,NOOP(${RV}) diff --git a/1.4.23-rc4/doc/misdn.txt b/1.4.23-rc4/doc/misdn.txt new file mode 100644 index 000000000..bb119feaa --- /dev/null +++ b/1.4.23-rc4/doc/misdn.txt @@ -0,0 +1,301 @@ +mISDN Channel Driver for Asterisk PBX +====================================== + + +This package contains the mISDN Channel Driver for the Asterisk PBX. It +supports every mISDN Hardware and provides an interface for Asterisk. + +Features: +--------- + +* NT and TE mode +* PP and PMP mode +* BRI and PRI (with BNE1 and BN2E1 Cards) +* Hardware bridging +* DTMF detection in HW+mISDNdsp +* Display messages on phones (on those that support it) +* app_SendText +* HOLD/RETRIEVE/TRANSFER on ISDN phones : ) +* Allow/restrict user number presentation +* Volume control +* Crypting with mISDNdsp (Blowfish) +* Data (HDLC) callthrough +* Data calling (with app_ptyfork +pppd) +* Echo cancellation +* Call deflection +* Some others + +Supported Hardware: +------------------- + +chan_misdn supports any mISDN compatible Hardware. + +Overview +-------- + +- Fast Installation Guide +- Pre-Requisites +- Configuration +- Dial and Options String +- misdn cli commands +- mISDN Variables +- Debugging and sending Bugreports +- Examples +- Known Problems +- Changes + + +Fast Installation Guide +----------------------- + +It is easy to install mISDN and mISDNuser. This can be done by: + * You can download latest stable releases from http://www.misdn.org/downloads + * Just fetch the newest head of the GIT (mISDN project moved from CVS) + In details this process described here: http://www.misdn.org/index.php/GIT + +then compile and install both with: + +cd mISDN ; +make && make install + +(you will need at least your kernel headers to compile mISDN). + +cd mISDNuser ; +make && make install + +Now you can compile chan_misdn, just by making Asterisk: + +cd asterisk ; +./configure && make && make install + +That's all! + + +Follow the instructions in the mISDN Package for how to load the Kernel +Modules. Also install process described in http://www.misdn.org/index.php/Installing_mISDN + +Pre-Requisites +-------------- + +To compile and install this driver, you'll need at least one mISDN Driver and +the mISDNuser package. Chan_misdn works with both, the current release version +and the development (svn trunk) version of Asterisk. + +You should use Kernels >= 2.6.9 + + +Configuration +------------- + +First of all you must configure the mISDN drivers, please follow the +instructions in the mISDN package to do that, the main config file and config +script is: + +/etc/init.d/misdn-init and +/etc/misdn-init.conf + + +Now you will want to configure the misdn.conf file which resides in the +Asterisk config directory (normally /etc/asterisk). + +- misdn.conf: [general] +The misdn.conf file contains a "general" subsection, and user subsections which +contain misdn port settings and different Asterisk contexts. + +In the general subsection you can set options that are not directly port +related. There is for example the very important debug variable which you can +set from the Asterisk cli (command line interface) or in this configuration +file, bigger numbers will lead to more debug output. There's also a trace file +option, which takes a path+filename where debug output is written to. + +- misdn.conf: [default] subsection + +The default subsection is another special subsection which can contain all the +options available in the user/port subsections. The user/port subsections inherit +their parameters from the default subsection. + +- misdn.conf: user/port subsections + +The user subsections have names which are unequal to "general". Those subsections +contain the ports variable which mean the mISDN Ports. Here you can add +multiple ports, comma separated. + +Especially for TE-Mode Ports there is a msns option. This option tells the +chan_misdn driver to listen for incoming calls with the given msns, you can +insert a '*' as single msn, which leads to getting every incoming call. If you +want to share on PMP TE S0 with Asterisk and a phone or ISDN card you should +insert here the msns which you assign to Asterisk. Finally a context variable +resides in the user subsections, which tells chan_misdn where to send incoming +calls to in the Asterisk dial plan (extension.conf). + + +Dial and Options String +----------------------- + +The dial string of chan_misdn got more complex, because we added more features, +so the generic dial string looks like: + +mISDN/<port>[:bchannel]|g:<group>/<extension>[/<OPTIONSSTRING>] + +The Optionsstring looks Like: +:<optchar><optarg>:<optchar><optarg>... + +the ":" character is the delimiter. + +The available options are: + a - Have Asterisk detect DTMF tones on called channel + c - Make crypted outgoing call, optarg is keyindex + d - Send display text to called phone, text is the optarg + e - Perform echo cancelation on this channel, + takes taps as optarg (32,64,128,256) + e! - Disable echo cancelation on this channel + f - Enable fax detection + h - Make digital outgoing call + h1 - Make HDLC mode digital outgoing call + i - Ignore detected DTMF tones, don't signal them to Asterisk, + they will be transported inband. + jb - Set jitter buffer length, optarg is length + jt - Set jitter buffer upper threshold, optarg is threshold + jn - Disable jitter buffer + n - Disable mISDN DSP on channel. + Disables: echo cancel, DTMF detection, and volume control. + p - Caller ID presentation, + optarg is either 'allowed' or 'restricted' + s - Send Non-inband DTMF as inband + vr - Rx gain control, optarg is gain + vt - Tx gain control, optarg is gain + + +chan_misdn registers a new dial plan application "misdn_set_opt" when +loaded. This application takes the Optionsstring as argument. The Syntax is: + +misdn_set_opt(<OPTIONSSTRING>) + + +When you set options in the dialstring, the options are set in the external +channel. When you set options with misdn_set_opt, they are set in the current +incoming channel. So if you like to use static encryption, the scenario looks +as follows: + +Phone1 --> * Box 1 --> PSTN_TE +PSTN_TE --> * Box 2 --> Phone2 + +The encryption must be done on the PSTN sides, so the dialplan on the boxes +are: + +* Box 1: +exten => _${CRYPT_PREFIX}X.,1,Dial(mISDN/g:outbound/:c1) + +* Box 2: +exten => ${CRYPT_MSN},1,misdn_set_opt(:c1) +exten => ${CRYPT_MSN},2,dial(${PHONE2}) + + + + +mISDN CLI commands +------------------ + +At the Asterisk cli you can try to type in: + +misdn <tab> <tab> + +Now you should see the misdn cli commands: + +- clean + -> pid (cleans a broken call, use with care, leads often + to a segmentation fault) +- send + -> display (sends a Text Message to a Asterisk channel, + this channel must be an misdn channel) +- set + -> debug (sets debug level) +- show + -> config (shows the configuration options) + -> channels (shows the current active misdn channels) + -> channel (shows details about the given misdn channels) + -> stacks (shows the current ports, their protocols and states) + -> fullstacks (shows the current active and inactive misdn channels) + +- restart + -> port (restarts given port (L2 Restart) ) + +- reload (reloads misdn.conf) + +You can only use "misdn send display" when an Asterisk channel is created and +isdn is in the correct state. "correct state" means that you have established a +call to another phone (must not be isdn though). + +Then you use it like this: + +misdn send display mISDN/1/101 "Hello World!" + +where 1 is the Port of the Card where the phone is plugged in, and 101 is the +msn (callerid) of the Phone to send the text to. + + +mISDN Variables +--------------- + +mISDN Exports/Imports a few Variables: + +- MISDN_ADDRESS_COMPLETE : Is either set to 1 from the Provider, or you + can set it to 1 to force a sending complete. + + + +Debugging and sending bug reports +--------------------------------- + +If you encounter problems, you should set up the debugging flag, usually +debug=2 should be enough. The messages are divided into Asterisk and mISDN +parts. mISDN Debug messages begin with an 'I', Asterisk messages begin with +an '*', the rest is clear I think. + +Please take a trace of the problem and open a report in the Asterisk issue +tracker at http://bugs.digium.com in the "channel drivers" project, +"chan_misdn" category. Read the bug guidelines to make sure you +provide all the information needed. + + +Examples +-------- + +Here are some examples of how to use chan_misdn in the dialplan +(extensions.conf): + + +[globals] +OUT_PORT=1 ; The physical Port of the Card +OUT_GROUP=ExternE1 ; The Group of Ports defined in misdn.conf + +[misdnIn] +exten => _X.,1,Dial(mISDN/${OUT_PORT}/${EXTEN}) +exten => _0X.,1,Dial(mISDN/g:${OUT_GROUP}/${EXTEN:1}) +exten => _1X.,1,Dial(mISDN/g:${OUT_GROUP}/${EXTEN:1}/:dHello) +exten => _1X.,1,Dial(mISDN/g:${OUT_GROUP}/${EXTEN:1}/:dHello Test:n) + +On the last line, you will notice the last argument (Hello); this is sent +as Display Message to the Phone. + +Known Problems +-------------- + +* When I use mISDN->IAX I cannot make Trunk calls + +-> You need to use ztdummy as dummy zaptel interface for the iax timing in +trunking mode, simply grab libpri, zaptel and compile them (i think you need +to modify the makefile in zaptel to add ztdummy to the default compiled +modules) then modprobe ztdummy, this resolves the problem. + + +* I cannot hear any tone after a successful CONNECT to the other end + +-> you forgot to load mISDNdsp, which is now needed by chan_misdn for switching +and DTMF tone detection. + + +Changes +------- +in the Changes File + diff --git a/1.4.23-rc4/doc/model.txt b/1.4.23-rc4/doc/model.txt new file mode 100644 index 000000000..10d2d0e05 --- /dev/null +++ b/1.4.23-rc4/doc/model.txt @@ -0,0 +1,15 @@ +Description of call model: + +Incoming Call: + + Channel backend waits for a RING or equivalent on some sort of +interface. Typically this is done in its own thread. When a RING is +detected, the backend should create a channel structure and then call +ast_pbx_start() on that channel, which will create a thread to monitor +that interface. At this point, the PBX and/or applications it launches +will manage the interface, and it need not be monitored by the +aforementioned thread. When the applications are finished, the requisite +hangup function will be called, at which the channel can be considered to +be no longer valid, and the thread that controls it will imminently be +terminated. + diff --git a/1.4.23-rc4/doc/modules.txt b/1.4.23-rc4/doc/modules.txt new file mode 100644 index 000000000..4f6d4c67b --- /dev/null +++ b/1.4.23-rc4/doc/modules.txt @@ -0,0 +1,26 @@ +All modules must have at least the following functions: + +int load_module(): + + Do what you need to do when you get started. This function +returns 0 on success and non-zero on failure (it is not considered loaded +if it fails. + +int unload_module(): + + The module will soon be unloaded. If any channels are using your +features, you should give them a softhangup in an effort to keep the +program from crashing. Generally, unload_module is only called when the +usecount is 0 or less, but the user can force unloading at their +discretion, and thus a module should do its best to comply (although in +some cases there may be no way to avoid a crash). This function should +return 0 on success and non-zero on failure (i.e. it cannot yet be +unloaded). + +char *description(): + + Return a description of the module's functionality. + +int usecnt(): + + Return the number of channels, etc that are using you. diff --git a/1.4.23-rc4/doc/mp3.txt b/1.4.23-rc4/doc/mp3.txt new file mode 100644 index 000000000..82205fdc0 --- /dev/null +++ b/1.4.23-rc4/doc/mp3.txt @@ -0,0 +1,13 @@ +* Asterisk MP3 Support +====================== + +* MP3 Music On Hold +Use of the mpg123 for your music on hold is no longer recommended and is now +officially deprecated. You should now use one of the native formats for your +music on hold selections. + +However, if you still need to use mp3 as your music on hold format, a format +driver for reading MP3 audio files is available in the asterisk-addons SVN +repository on svn.digium.com or in the asterisk-addons release at +http://downloads.digium.com/pub/telephony/asterisk/. + diff --git a/1.4.23-rc4/doc/musiconhold-fpm.txt b/1.4.23-rc4/doc/musiconhold-fpm.txt new file mode 100644 index 000000000..ad11c4815 --- /dev/null +++ b/1.4.23-rc4/doc/musiconhold-fpm.txt @@ -0,0 +1,8 @@ +About Hold Music +================ +Digium has licensed the music included with +the Asterisk distribution From FreePlayMusic +for use and distribution with Asterisk. It +is licensed ONLY for use as hold music within +an Asterisk based PBX. + diff --git a/1.4.23-rc4/doc/mysql.txt b/1.4.23-rc4/doc/mysql.txt new file mode 100644 index 000000000..27adaa956 --- /dev/null +++ b/1.4.23-rc4/doc/mysql.txt @@ -0,0 +1,15 @@ +MYSQL LICENSING UPDATE +====================== +We were recently contacted by MySQL and informed that the MySQL client +libraries are now under GPL license and not LGPL license as before. + +Since Asterisk does allow exceptions to GPL, we are removing MySQL support +from standard Asterisk. We will, where appropriate, make it available via +a separate package which will only be usable when Asterisk is used completely +within GPL (i.e. not in conjunction with G.729, OpenH.323, etc). We +apologize for the confusion. + +You may find this in the new "asterisk-addons" package. + +Mark Spencer +Digium diff --git a/1.4.23-rc4/doc/odbcstorage.txt b/1.4.23-rc4/doc/odbcstorage.txt new file mode 100644 index 000000000..435574b0e --- /dev/null +++ b/1.4.23-rc4/doc/odbcstorage.txt @@ -0,0 +1,30 @@ +ODBC Voicemail Storage +====================== + +ODBC Storage allows you to store voicemail messages within a database +instead of using a file. This is *not* a full realtime engine and +*only* supports ODBC. The table description for the "voicemessages" +table is as follows: + ++----------------+-------------+------+-----+---------+-------+ +| Field | Type | Null | Key | Default | Extra | ++----------------+-------------+------+-----+---------+-------+ +| msgnum | int(11) | YES | | NULL | | +| dir | varchar(80) | YES | MUL | NULL | | +| context | varchar(80) | YES | | NULL | | +| macrocontext | varchar(80) | YES | | NULL | | +| callerid | varchar(40) | YES | | NULL | | +| origtime | varchar(40) | YES | | NULL | | +| duration | varchar(20) | YES | | NULL | | +| mailboxuser | varchar(80) | YES | | NULL | | +| mailboxcontext | varchar(80) | YES | | NULL | | +| recording | longblob | YES | | NULL | | ++----------------+-------------+------+-----+---------+-------+ + +The database name (from /etc/asterisk/res_odbc.conf) is in the +"odbcstorage" variable in the general section of voicemail.conf. + +You may modify the voicemessages table name by using +odbctable=??? in voicemail.conf + + diff --git a/1.4.23-rc4/doc/osp.txt b/1.4.23-rc4/doc/osp.txt new file mode 100644 index 000000000..aff5cd088 --- /dev/null +++ b/1.4.23-rc4/doc/osp.txt @@ -0,0 +1,421 @@ +Asterisk V1.4 OSP Module +User Guide +February 9, 2007 + +Table of Contents +1 Introduction 3 +2 OSP Toolkit 3 +2.1 Build OSP Toolkit 3 +2.1.1 Unpacking the Toolkit 3 +2.1.2 Preparing to build the OSP Toolkit 4 +2.1.3 Building the OSP Toolkit 4 +2.1.4 Installing the OSP Toolkit 5 +2.1.5 Building the Enrollment Utility 5 +2.2 Obtain Crypto Files 5 +3 Asterisk 7 +3.1 OSP Support Implementation 7 +3.1.1 OSPAuth 7 +3.1.2 OSPLookup 7 +3.1.3 OSPNext 8 +3.1.4 OSPFinish 8 +3.2 Build with OSP Support 8 +3.3 Configure with OSP Support 9 +3.3.1 osp.conf 9 +3.3.2 zapata/sip/iax.conf 10 +3.3.3 extensions.conf 10 + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +Asterisk is a trademark of Digium, Inc. +TransNexus and OSP Secured are trademarks of TransNexus, Inc. + +1 Introduction +This document provides instructions on how to build and configure Asterisk V1.4 with the OSP Toolkit to enable secure, multi-lateral peering. The OSP Toolkit is an open source implementation of the OSP peering protocol and is freely available from www.sourceforge.net. The OSP standard defined by the European Telecommunications Standards Institute (ETSI TS 101 321) www.etsi.org. If you have questions or need help, building Asterisk with the OSP Toolkit, please post your question on the OSP mailing list at https://lists.sourceforge.net/lists/listinfo/osp-toolkit-client. + +2 OSP Toolkit +Please reference the OSP Toolkit document "How to Build and Test the OSP Toolkit” available from https://sourceforge.net/projects/osp-toolkit. + +2.1 Build OSP Toolkit +The software listed below is required ti build and use the OSP Toolkit: +* OpenSSL (required for building) - Open Source SSL protocol and Cryptographic Algorithms (version 0.9.7g recommended) from www.openssl.org. Pre-compiled OpenSSL binary packages are not recommended because of the binary compatibility issue. +* Perl (required for building) - A programming language used by OpenSSL for compilation. Any version of Perl should work. One version of Perl is available from www.activestate.com/ActivePerl. If pre-compiled OpenSSL packages are used, Perl package is not required. +* C compiler (required for building) - Any C compiler should work. The GNU Compiler Collection from www.gnu.org is routinely used for building the OSP Toolkit for testing. +* OSP Server (required for testing) - Access to any OSP server should work. OpenOSP is a reference OSP server implementation created by Cisco Systems and is available at http://www.vovida.org/applications/downloads/openosp/. RAMS is a java based open source OSP server available from https://sourceforge.net/projects/rams. A free commercial OSP server may be downloaded from www.transnexus.com. + +2.1.1 Unpacking the Toolkit +After downloading the OSP Toolkit (version 3.3.4 or later release) from https://sourceforge.net/projects/osp-toolkit, perform the following steps in order: + +1) Copy the OSP Toolkit distribution into the directory where it will reside, say /usr/src. + +2) Un-package the distribution file by executing the following command: +gunzip –c OSPToolkit-###.tar.gz | tar xvf – +Where ### is the version number separated by underlines. For example, if the version is 3.3.4, then the above command would be: +gunzip –c OSPToolkit-3_3_4.tar.gz | tar xvf – +A new directory (TK-3_3_4-20051103) will be created within the same directory as the tar file. + +3) Go to the TK-3_3_4-20051103 directory by running this command: +cd TK-3_3_4-20051103 +Within this directory, you will find directories and files similar to what is listed below if the command "ls -F" is executed): +ls -F +enroll/ +RelNotes.txt lib/ +README.txt license.txt +bin/ src/ +crypto/ test/ +include/ + +2.1.2 Preparing to build the OSP Toolkit +4) Compile OpenSSL according to the instructions provided with the OpenSSL distribution (You would need to do this only if you don’t have openssl already). + +5) Copy the OpenSSL header files (the *.h files) into the crypto/openssl directory within the osptoolkit directory. The OpenSSL header files are located under the openssl/include/openssl directory. + +6) Copy the OpenSSL library files (libcrypto.a and libssl.a) into the lib directory within the osptoolkit directory. The OpenSSL library files are located under the openssl directory. +Note: Since the Asterisk requires the OpenSSL package. If the OpenSSL package has been installed, 4~6 are not necessary. +2.1.3 Building the OSP Toolkit + +7) Optionally, change the install directory of the OSP Toolkit. Open the Makefile in the /usr/src/TK-3_3_4-20051103/src directory, look for the install path variable – INSTALL_PATH, and edit it to be anywhere you want (defaults /usr/local). +Note: Please change the install path variable only if you are familiar with both the OSP Toolkit and the Asterisk. Otherwise, it may case that the Asterisk does not support the OSP protocol. + +8) From within the OSP Toolkit directory (/usr/src/TK-3_3_4-20051103), start the compilation script by executing the following commands: +cd src +make clean; make build + +2.1.4 Installing the OSP Toolkit +The header files and the library of the OSP Toolkit should be installed. Otherwise, you must specify the OSP Toolkit path for the Asterisk. + +9) Use the same script to install the Toolkit. +make install +The make script is also used to install the OSP Toolkit header files and the library into the INSTALL_PATH specified in the Makefile. +Note: Please make sure you have the rights to access the INSTALL_PATH directory. For example, in order to access /usr/local directory, normally, you should be root. +By default, the OSP Toolkit is compiled in the production mode. The following table identifies which default features are activated with each compile option: +Default Feature +Production +Development +Debug Information Displayed +No +Yes +The "Development" option is recommended for a first time build. The “CFLAGS” definition in the Makefile must be modified to build in development mode. + +2.1.5 Building the Enrollment Utility +Device enrollment is the process of establishing a trusted cryptographic relationship between the VoIP device and the OSP Server. The Enroll program is a utility application for establishing a trusted relationship between and OSP client and an OSP server. Please see the document "Device Enrollment" at http://www.transnexus.com/OSP%20Toolkit/OSP%20Toolkit%20Documents/Device_Enrollment.pdf for more information about the enroll application. + +10) From within the OSP Toolkit directory (/usr/src/TK-3_3_4-20051103), execute the following commands at the command prompt: +cd enroll +make clean; make linux +Compilation is successful if there are no errors anywhere in the compiler output. The enroll program is now located in the /usr/src/TK-3_3_4-20051103/bin directory. By this point, a fully functioning OSP Toolkit should have been successfully built. + +2.2 Obtain Crypto Files +The OSP module in Asterisk requires three crypto files containing local certificate (localcert.pem), private key (pkey.pem), and CA certificate (cacert_0.pem). Asterisk will try to load the files from the Asterisk public/private key directory - /var/lib/asterisk/key. If the files are not present, the OSP module will not start and the Asterisk will not support the OSP protocol. Use the enroll.sh script from the toolkit distribution to enroll the Asterisk OSP module with an OSP server to obtain the crypto files. Documentation explaining how to use the enroll.sh script (Device Enrollment) to enroll with an OSP server is available at http://www.transnexus.com/OSP%20Toolkit/OSP%20Toolkit%20Documents/Device_Enrollment.pdf. Copy the files file generated by the enrollment process to the Asterisk configuration directory. + +Note: The osptestserver.transnexus.com is configured only for sending and receiving non-SSL messages, and issuing signed tokens. If you need help, post a message on the OSP mailing list at https://lists.sourceforge.net/lists/listinfo/osp-toolkit-client. + +The enroll.sh script takes the domain name or IP addresses of the OSP servers that the OSP Toolkit needs to enroll with as arguments, and then generates pem files – cacert_#.pem, certreq.pem, localcert.pem, and pkey.pem. The ‘#’ in the cacert file name is used to differentiate the ca certificate file names for the various SP’s (OSP servers). If only one address is provided at the command line, cacert_0.pem will be generated. If 2 addresses are provided at the command line, 2 files will be generated – cacert_0.pem and cacert_1.pem, one for each SP. The example below shows the usage when the client is registering with osptestserver.transnexus.com. If all goes well, the following text will be displayed. + +./enroll.sh osptestserver.transnexus.com +Generating a 512 bit RSA private key +........................++++++++++++ +.........++++++++++++ +writing new private key to 'pkey.pem' +----- +You are about to be asked to enter information that will be incorporated +into your certificate request. +What you are about to enter is what is called a Distinguished Name or a DN. +There are quite a few fields but you can leave some blank +For some fields there will be a default value, +If you enter '.', the field will be left blank. +----- +Country Name (2 letter code) [AU]: _______ +State or Province Name (full name) [Some-State]: _______ +Locality Name (eg, city) []:_______ +Organization Name (eg, company) [Internet Widgits Pty Ltd]: _______ +Organizational Unit Name (eg, section) []:_______ +Common Name (eg, YOUR name) []:_______ +Email Address []:_______ + +Please enter the following 'extra' attributes +to be sent with your certificate request +A challenge password []:_______ +An optional company name []:_______ + +Error Code returned from openssl command : 0 + +CA certificate received +[SP: osptestserver.transnexus.com]Error Code returned from getcacert command : 0 + +output buffer after operation: operation=request +output buffer after nonce: operation=request&nonce=1655976791184458 +X509 CertInfo context is null pointer +Unable to get Local Certificate +depth=0 /CN=osptestserver.transnexus.com/O=OSPServer +verify error:num=18:self signed certificate +verify return:1 +depth=0 /CN=osptestserver.transnexus.com/O=OSPServer +verify return:1 +The certificate request was successful. +Error Code returned from localcert command : 0 + +The files generated should be copied to the /var/lib/asterisk/key directory. +Note: The script enroll.sh requires AT&T korn shell (ksh) or any of its compatible variants. The /usr/src/TK-3_3_4-20051103/bin directory should be in the PATH variable. Otherwise, enroll.sh cannot find the enroll file. + +3 Asterisk +3.1 OSP Support Implementation +In Asterisk, all OSP support is implemented as dial plan functions. + +3.1.1 OSPAuth +OSP token validation function. +Input: +* OSPPEERIP: last hop IP address +* OSPINTOKEN: inbound OSP token +* provider: OSP service provider configured in osp.conf. If it is empty, default provider is used. +* priority jump +Output: +* OSPINHANDLE: inbound OSP transaction handle +* OSPINTIMELIMIT: inbound call duration limit +* OSPAUTHSTATUS: OSPAuth return value. SUCCESS/FAILED/ERROR + +3.1.2 OSPLookup +OSP lookup function. +Input: +* OSPPEERIP: last hop IP address +* OSPINHANDLE: inbound OSP transaction handle +* OSPINTIMELIMIT: inbound call duration limit +* exten: called number +* provider: OSP service provider configured in osp.conf. If it is empty, default provider is used. +* priority jump +Output: +* OSPOUTHANDLE: outbound transaction handle +* OSPTECH: outbound protocol +* OSPDEST: outbound destination +* OSPCALLING: outbound calling number +* OSPOUTTOKEN: outbound OSP token +* OSPRESULTS: number of remain destinations +* OSPOUTTIMELIMIT: outbound call duration limit +* OSPLOOKUPSTATUS: OSPLookup return value. SUCCESS/FAILED/ERROR + +3.1.3 OSPNext +OSP lookup next function. +Input: +* OSPINHANDLE: inbound transaction handle +* OSPOUTHANDLE: outbound transaction handle +* OSPINTIMELIMIT: inbound call duration limit +* OSPRESULTS: number of remain destinations +* cause: last destination disconnect cause +* priority jump +Output: +* OSPTECH: outbound protocol +* OSPDEST: outbound destination +* OSPCALLING: outbound calling number +* OSPOUTTOKEN: outbound OSP token +* OSPRESULTS: number of remain destinations +* OSPOUTTIMELIMIT: outbound call duration limit +* OSPNEXTSTATUS: OSPLookup return value. SUCCESS/FAILED/ERROR + +3.1.4 OSPFinish +OSP report usage function. +Input: +* OSPINHANDLE: inbound transaction handle +* OSPOUTHANDLE: outbound transaction handle +* OSPAUTHSTATUS: OSPAuth return value +* OSPLOOKUPTSTATUS: OSPLookup return value +* OSPNEXTSTATUS: OSPNext return value +* cause: last destination disconnect cause +* priority jump +Output: +* OSPFINISHSTATUS: OSPLookup return value. SUCCESS/FAILED/ERROR + +3.2 Build with OSP Support +If the OSP Toolkit is installed in the default install directory, /usr/local, no additional configuration is required. If the OSP Toolkit is installed in another directory, say /myosp, Asterisk must be configured with the location of the OSP Toolkit. +--with-osptk=/myosp +Note: Please change the install path only if you familiar with both the OSP Toolkit and the Asterisk. Otherwise, the change may results Asterisk not supporting the OSP protocol. +Now, you can compile Asterisk according to the instructions provided with the Asterisk distribution. + +3.3 Configure with OSP Support +3.3.1 osp.conf +; +; Open Settlement Protocol Sample Configuration File +; +; This file contains configuration of providers that +; are used by the OSP subsystem of Asterisk. The section +; "general" is reserved for global options. Each other +; section declares an OSP Provider. The provider "default" +; is used when no provider is otherwise specified. +; +[general] +; +; Should hardware accelleration be enabled? May not be changed +; on a reload. +; +accelerate=no +; +; Defines the token format that Asterisk can validate. +; 0 - signed tokens only +; 1 - unsigned tokens only +; 2 - both signed and unsigned +; The defaults to 0, i.e. the Asterisk can validate signed tokens only. +; +tokenformat=0 +; +[default] +; +; All paths are presumed to be under /var/lib/asterisk/keys unless +; the path begins with '/' +; +; Specify the private keyfile. If unspecified, defaults to the name +; of the section followed by "-privatekey.pem" (e.g. default-privatekey.pem) +; +privatekey=pkey.pem +; +; Specify the local certificate file. If unspecified, defaults to +; the name of the section followed by "-localcert.pem" +; +localcert=localcert.pem +; +; Specify one or more Certificate Authority keys. If none are listed, +; a single one is added with the name "-cacert.pem" +; +cacert=cacert_0.pem +; +; Specific parameters can be tuned as well: +; +; maxconnections: Max number of simultaneous connections to the provider (default=20) +; retrydelay: Extra delay between retries (default=0) +; retrylimit: Max number of retries before giving up (default=2) +; timeout: Timeout for response in milliseconds (default=500) +; +maxconnections=20 +retrydelay=0 +retrylimit=2 +timeout=500 +; +; List all service points for this provider +; +;servicepoint=http://osptestserver.transnexus.com:1080/osp +servicepoint=http://OSP server IP:1080/osp +; +; Set the "source" for requesting authorization +; +;source=foo +source=[host IP] +; +; Set the authentication policy. +; 0 - NO +; 1 - YES +; 2 - EXCLUSIVE +; Default is 1, validate token but allow no token. +; +authpolicy=1 + +3.3.2 zapata/sip/iax.conf +There is no configuration required for OSP. + +3.3.3 extensions.conf +An Asterisk box can be configured as OSP source/destination gateway or OSP proxy. + +3.3.3.1 OSP Source Gateway +[PhoneSrcGW] +; Set calling number if necessary +exten => _XXXX.,1,Set(CALLERID(numner)=CallingNumber) +; OSP lookup using default provider, if fail/error jump to 2+101 +exten => _XXXX.,2,OSPLookup(${EXTEN}||j) +; Set calling number which may be translated +exten => _XXXX.,3,Set(CALLERID(number)=${OSPCALLING}) +; Dial to destination, 60 timeout, with call duration limit +exten => _XXXX.,4,Dial(${OSPTECH}/${OSPDEST},60,oL($[${OSPOUTTIMELIMIT}*1000])) +; Wait 3 seconds +exten => _XXXX.,5,Wait,3 +; Hangup +exten => _XXXX.,6,Hangup +; Deal with OSPLookup fail/error +exten => _XXXX.,2+101,Hangup +; OSP report usage +exten => h,1,OSPFinish(${HANGUPCAUSE}) +3.3.3.2 OSP Destination Gateway +[PhoneDstGW] +; Get peer IP +exten => _XXXX.,1,Set(OSPPEERIP=${SIPCHANINFO(peerip)}) +; Get OSP token +exten => _XXXX.,2,Set(OSPINTOKEN=${SIP_HEADER(P-OSP-Auth-Token)}) +; Validate token using default provider, if fail/error jump to 3+101 +exten => _XXXX.,3,OSPAuth(|j) +; Ringing +exten => _XXXX.,4,Ringing +; Wait 1 second +exten => _XXXX.,5,Wait,1 +; Dial phone, timeout 15 seconds, with call duration limit +exten => _XXXX.,6,Dial(${DIALOUTANALOG}/${EXTEN:1},15,oL($[${OSPINTIMELIMIT}*1000])) +; Wait 3 seconds +exten => _XXXX.,7,Wait,3 +; Hangup +exten => _XXXX.,8,Hangup +; Deal with OSPAuth fail/error +exten => _XXXX.,3+101,Hangup +; OSP report usage +exten => h,1,OSPFinish(${HANGUPCAUSE}) + +3.3.3.3 Proxy +[GeneralProxy] +; Get peer IP +exten => _XXXX.,1,Set(OSPPEERIP=${SIPCHANINFO(peerip)}) +; Get OSP token +exten => _XXXX.,2,Set(OSPINTOKEN=${SIP_HEADER(P-OSP-Auth-Token)}) +; Validate token using default provider, if fail/error jump to 3+101 +exten => _XXXX.,3,OSPAuth(|j) +; OSP lookup using default provider, if fail/error jump to 4+101 +exten => _XXXX.,4,OSPLookup(${EXTEN}||j) +; Set calling number which may be translated +exten => _XXXX.,5,Set(CALLERID(number)=${OSPCALLING}) +; Dial to 1st destination, 60 timeout, with call duration limit +exten => _XXXX.,6,Dial(${OSPTECH}/${OSPDEST},24,oL($[${OSPOUTTIMELIMIT}*1000])) +; OSP lookup next, if fail/error jump to 7+101 +exten => _XXXX.,7,OSPNext(${HANGUPCAUSE}||j) +; Set calling number which may be translated +exten => _XXXX.,8,Set(CALLERID(number)=${OSPCALLING}) +; Dial to 2nd destination, 60 timeout, with call duration limit +exten => _XXXX.,9,Dial(${OSPTECH}/${OSPDEST},25,oL($[${OSPOUTTIMELIMIT}*1000])) +; OSP lookup next, if fail/error jump to 10+101 +exten => _XXXX.,10,OSPNext(${HANGUPCAUSE}||j) +; Set calling number which may be translated +exten => _XXXX.,11,Set(CALLERID(number)=${OSPCALLING}) +; Dial to 3rd destination, 60 timeout, with call duration limit +exten => _XXXX.,12,Dial(${OSPTECH}/${OSPDEST},26,oL($[${OSPOUTTIMELIMIT}*1000])) +; Hangup +exten => _XXXX.,13,Hangup +; Deal with OSPAuth fail/error +exten => _XXXX.,3+101,Hangup +; Deal with OSPLookup fail/error +exten => _XXXX.,4+101,Hangup +; Deal with 1st OSPNext fail/error +exten => _XXXX.,7+101,Hangup +; Deal with 2nd OSPNext fail/error +exten => _XXXX.,10+101,Hangup +; OSP report usage +exten => h,1,OSPFinish(${HANGUPCAUSE}) + +5 + diff --git a/1.4.23-rc4/doc/privacy.txt b/1.4.23-rc4/doc/privacy.txt new file mode 100644 index 000000000..3a990fa4b --- /dev/null +++ b/1.4.23-rc4/doc/privacy.txt @@ -0,0 +1,361 @@ +Title: Everything About The Privacy Options In The Dial Command That +You Never Wanted To Know, And Even A Little More On Zapateller and +PrivacyManager: + +by Steve Murphy + + +So, you want to avoid talking to pesky telemarketers/charity +seekers/poll takers/magazine renewers/etc? + +============= +First of all: +============= + +Try the FTC "Don't call" database, this alone will reduce your +telemarketing call volume considerably. (see: +https://www.donotcall.gov/default.aspx ) But, this list won't protect +from the Charities, previous business relationships, etc. + + +================================= +Next, Fight against autodialers!! +================================= + +Zapateller detects if callerid is present, and if not, plays the +da-da-da tones that immediately precede messages like, "I'm sorry, +the number you have called is no longer in service." + +Most humans, even those with unlisted/callerid-blocked numbers, will +not immediately slam the handset down on the hook the moment they hear +the three tones. But autodialers seem pretty quick to do this. + +I just counted 40 hangups in Zapateller over the last year in my +CDR's. So, that is possibly 40 different telemarketers/charities that have +hopefully slashed my back-waters, out-of-the-way, humble home phone +number from their lists. + +I highly advise Zapateller for those seeking the nirvana of "privacy". + + +======================================= +Next, Fight against the empty CALLERID! +======================================= + +A considerable percentage of the calls you don't want, come from +sites that do not provide CallerID. + +Null callerid's are a fact of life, and could be a friend with an +unlisted number, or some charity looking for a handout. The +PrivacyManager application can help here. It will ask the caller to +enter a 10-digit phone number. They get 3 tries(configurable), and this is +configurable, with control being passed to priority+101 if they won't +supply one. + +PrivacyManager can't guarantee that the number they supply is any +good, tho, as there is no way to find out, short of hanging up and +calling them back. But some answers are obviously wrong. For instance, +it seems a common practice for telemarketers to use your own number +instead of giving you theirs. A simple test can detect this. More +advanced tests would be to look for -555- numbers, numbers that count +up or down, numbers of all the same digit, etc. + +My logs show that 39 have hung up in the PrivacyManager script over +the last year. + +(Note: Demanding all unlisted incoming callers to enter their CID may +not always be appropriate for all users. Another option might be to +use call screening. See below.) + +========================== +Next, use a WELCOME MENU ! +========================== + +Experience has shown that simply presenting incoming callers with +a set of options, no matter how simple, will deter them from calling +you. In the vast majority of situations, a telemarketer will simply +hang up rather than make a choice and press a key. + +This will also immediately foil all autodialers that simply belch a +message in your ear and hang up. + + +---------------------------------------------- +Example usage of Zapateller and PrivacyManager: +---------------------------------------------- + +[homeline] +exten => s,1,Answer +exten => s,2,SetVar,repeatcount=0 +exten => s,3,Zapateller,nocallerid +exten => s,4,PrivacyManager +exten => s,105,Background(tt-allbusy) ;; do this if they don't enter a number to Privacy Manager +exten => s,106,Background(tt-somethingwrong) +exten => s,107,Background(tt-monkeysintro) +exten => s,108,Background(tt-monkeys) +exten => s,109,Background(tt-weasels) +exten => s,110,Hangup +exten => s,5,GotoIf($[ "${CALLERIDNUM}" = "7773334444" & "${CALLERIDNAME}" : "Privacy Manager" ]?callerid-liar|s|1:s|7) + +I suggest using Zapateller at the beginning of the context, before +anything else, on incoming calls.This can be followed by the +PrivacyManager App. + +Make sure, if you do the PrivacyManager app, that you take care of the +error condition! or their non-compliance will be rewarded with access +to the system. In the above, if they can't enter a 10-digit number in +3 tries, they get the humorous "I'm sorry, but all household members +are currently helping other telemarketers...", "something is terribly +wrong", "monkeys have carried them away...", various loud monkey +screechings, "weasels have...", and a hangup. There are plenty of +other paths to my torture scripts, I wanted to have some fun. + +In nearly all cases now, the telemarketers/charity-seekers that +usually get thru to my main intro, hang up. I guess they can see it's +pointless, or the average telemarketer/charity-seeker is instructed +not to enter options when encountering such systems. Don't know. + +=================== +Next: Torture Them! +=================== + +I have developed an elaborate script to torture Telemarketers, and +entertain friends. (See +http://www.voip-info.org/wiki-Asterisk+Telemarketer+Torture ) + +While mostly those that call in and traverse my teletorture scripts +are those we know, and are doing so out of curiosity, there have been +these others from Jan 1st,2004 thru June 1st, 2004: +(the numbers may or may not be correct.) + +603890zzzz hung up telemarket options. +"Integrated Sale" called a couple times. hung up in telemarket options +"UNITED STATES GOV" (-- maybe a military recruiter, trying to lure one of my sons). +800349zzzz -- hung up in charity intro +800349zzzz -- hung up in charity choices, intro, about the only one who actually travelled to the bitter bottom of the scripts! +216377zzzz -- hung up the magazine section +626757zzzz = "LIR " (pronounced "Liar"?) hung up in telemarket intro, then choices +757821zzzz -- hung up in new magazine subscription options. + +That averages out to maybe 1 a month. That puts into question whether +the ratio of the amount of labor it took to make the scripts versus +the benefits of lower call volumes was worth it, but, well, I had fun, +so what the heck. + +but, that's about it. Not a whole lot. But I haven't had to say "NO" +or "GO AWAY" to any of these folks for about a year now ...! + +======================================== + Using Call Screening +======================================= + +Another option is to use call screening in the Dial command. It has +two main privacy modes, one that remembers the CID of the caller, and +how the callee wants the call handled, and the other, which does not +have a "memory". + +Turning on these modes in the dial command results in this sequence of +events, when someone calls you at an extension: + +1. The caller calls the Asterisk system, and at some point, selects an +option or enters an extension number that would dial your extension. + +2. Before ringing your extension, the caller is asked to supply an +introduction. The application asks them: "After the tone, say your +name". They are allowed 4 seconds of introduction. + +3. After that, they are told "Hang on, we will attempt to connect you +to your party. Depending on your dial options, they will hear ringing +indications, or get music on hold. I suggest music on hold. + +4. Your extension is then dialed. When (and if) you pick up, you are +told that a caller presenting themselves as <their recorded intro is +played> is calling, and you have options, like being connected, +sending them to voicemail, torture, etc. + +5. You make your selection, and the call is handled as you chose. + + +There are some variations, and these will be explained in due course. + + +To use these options, set your Dial to something like: + +exten => 3,3,Dial(Zap/5r3&Zap/6r3|35|tmPA(beep)) + +or + +exten => 3,3,Dial(Zap/5r3&Zap/6r3|35|tmP(something)A(beep)) + +or + +exten => 3,3,Dial(Zap/5r3&Zap/6r3|35|tmpA(beep)) + + +The 't' allows the dialed party to transfer the call using '#'. It's +optional. + +The 'm' is for music on hold. I suggest it. Otherwise, the calling +party gets to hear all the ringing, and lack thereof. It is generally +better to use Music On Hold. Lots of folks hang up after the 3rd or +4th ring, and you might lose the call before you can enter an option! + +The 'P' option alone will database everything using the extension as a +default 'tree'. To get multiple extensions sharing the same database, use +P(some-shared-key). Also, if the same person has multiple extensions, +use P(unique-id) on all their dial commands. + +Use little 'p' for screening. Every incoming call will include a +prompt for the callee's choice. + +the A(beep), will generate a 'beep' that the callee will hear if they +choose to talk to the caller. It's kind of a prompt to let the callee +know that he has to say 'hi'. It's not required, but I find it +helpful. + +When there is no CallerID, P and p options will always record an intro +for the incoming caller. This intro will be stored temporarily in the +/var/lib/asterisk/sounds/priv-callerintros dir, under the name +NOCALLERID_<extension><channelname> and will be erased after the +callee decides what to do with the call. + +Of course, NOCALLERID is not stored in the database. All those with no +CALLERID will be considered "Unknown". + +======================== + The 'N' and 'n' options +======================== + +Two other options exist, that act as modifiers to the privacy options +'P' and 'p'. They are 'N' and 'n'. You can enter them as dialing +options, but they only affect things if P or p are also in the +options. + +'N' says, "Only screen the call if no CallerID is present". So, if a +callerID were supplied, it will come straight thru to your extension. + +'n' says, "Don't save any introductions". Folks will be asked to +supply an introduction ("At the tone, say your name") every time they +call. Their introductions will be removed after the callee makes a +choice on how to handle the call. Whether the P option or the p option +is used, the incoming caller will have to supply their intro every +time they call. + +======================= +Recorded Introductions +======================= + +[Philosophical Side Note: +The 'P' option stores the CALLERID in the database, along with the +callee's choice of actions, as a convenience to the CALLEE, whereas +introductions are stored and re-used for the convenience of the CALLER.] + +Unless instructed to not save introductions (see the 'n' option above), +the screening modes will save the recordings of the caller's names in +the directory /var/lib/asterisk/sounds/priv-callerintros, if they have +a CallerID. Just the 10-digit callerid numbers are used as filenames, +with a ".gsm" at the end. + +Having these recordings around can be very useful, however... + +First of all, if a callerid is supplied, and a recorded intro for that +number is already present, the caller is spared the inconvenience of +having to supply their name, which shortens their call a bit. + +Next of all, these intros can be used in voicemail, played over +loudspeakers, and perhaps other nifty things. For instance: + +exten => s,7,System(/usr/bin/play /var/lib/asterisk/sounds/priv-callerintros/${CALLERIDNUM}.gsm&|0) + +When a call comes in at the house, the above priority gets executed, +and the callers intro is played over the phone systems speakers. This +gives us a hint who is calling. + +(Note: the |0 option at the end of the System command above, is a +local mod I made to the System command. It forces a 0 result code to +be returned, whether the play command successfully completed or +not. Therefore, I don't have to ensure that the file exists or +not. While I've turned this mod into the developers, it hasn't been +incorporated yet. You might want to write an AGI or shell script to +handle it a little more intelligently) + +And one other thing. You can easily supply your callers with an option +to listen to, and re-record their introductions. Here's what I did in +the home system's extensions.conf. (assume that a +Goto(home-introduction|s|1) exists somewhere in your main menu as an +option): + +[home-introduction] +exten => s,1,Background,intro-options ;; Script: To hear your Introduction, dial 1. + ;; to record a new introduction, dial 2. + ;; to return to the main menu, dial 3. + ;; to hear what this is all about, dial 4. +exten => 1,1,Playback,priv-callerintros/${CALLERIDNUM} +exten => 1,2,Goto(s,1) +exten => 2,1,Goto(home-introduction-record,s,1) +exten => 3,1,Goto(homeline,s,7) +exten => 4,1,Playback,intro-intro ;; Script: + ;; This may seem a little strange, but it really is a neat + ;; thing, both for you and for us. I've taped a short introduction + ;; for many of the folks who normally call us. Using the Caller ID + ;; from each incoming call, the system plays the introduction + ;; for that phone number over a speaker, just as the call comes in. + ;; This helps the folks + ;; here in the house more quickly determine who is calling. + ;; and gets the right ones to gravitate to the phone. + ;; You can listen to, and record a new intro for your phone number + ;; using this menu. +exten => 4,2,Goto(s,1) +exten => t,1,Goto(s,1) +exten => i,1,Background,invalid +exten => i,2,Goto(s,1) +exten => o,1,Goto(s,1) + +[home-introduction-record] +exten => s,1,Background,intro-record-choices ;; Script: + ;; If you want some advice about recording your + ;; introduction, dial 1. + ;; otherwise, dial 2, and introduce yourself after + ;; the beep. +exten => 1,1,Playback,intro-record + ;; Your introduction should be short and sweet and crisp. + ;; Your introduction will be limited to 4 seconds. + ;; This is NOT meant to be a voice mail message, so + ;; please, don't say anything about why you are calling. + ;; After we are done making the recording, your introduction + ;; will be saved for playback. + ;; If you are the only person that would call from this number, + ;; please state your name. Otherwise, state your business + ;; or residence name instead. For instance, if you are + ;; friend of the family, say, Olie McPherson, and both + ;; you and your kids might call here a lot, you might + ;; say: "This is the distinguished Olie McPherson Residence!" + ;; If you are the only person calling, you might say this: + ;; "This is the illustrious Kermit McFrog! Pick up the Phone, someone!!" + ;; If you are calling from a business, you might pronounce a more sedate introduction,like, + ;; "Fritz from McDonalds calling.", or perhaps the more original introduction: + ;; "John, from the Park County Morgue. You stab 'em, we slab 'em!". + ;; Just one caution: the kids will hear what you record every time + ;; you call. So watch your language! + ;; I will begin recording after the tone. + ;; When you are done, hit the # key. Gather your thoughts and get + ;; ready. Remember, the # key will end the recording, and play back + ;; your intro. Good Luck, and Thank you!" +exten => 1,2,Goto(2,1) +exten => 2,1,Background,intro-start + ;; OK, here we go! After the beep, please give your introduction. +exten => 2,2,Background,beep +exten => 2,3,Record,priv-callerintros/${CALLERIDNUM}:gsm|4 +exten => 2,4,Background,priv-callerintros/${CALLERIDNUM} +exten => 2,5,Goto(home-introduction,s,1) +exten => t,1,Goto(s,1) +exten => i,1,Background,invalid +exten => i,2,Goto(s,1) +exten => o,1,Goto(s,1) + + +In the above, you'd most likely reword the messages to your liking, +and maybe do more advanced things with the 'error' conditions (i,o,t priorities), +but I hope it conveys the idea... + + diff --git a/1.4.23-rc4/doc/queuelog.txt b/1.4.23-rc4/doc/queuelog.txt new file mode 100644 index 000000000..fa8cb48e8 --- /dev/null +++ b/1.4.23-rc4/doc/queuelog.txt @@ -0,0 +1,99 @@ +Queue Log Information +===================== + +In order to properly manage ACD queues, it is important to be able to +keep track of details of call setups and teardowns in much greater detail +than traditional call detail records provide. In order to support this, +extensive and detailed tracing of every queued call is stored in the +queue log, located (by default) in /var/log/asterisk/queue_log. + +These are the events (and associated information) in the queue log: + +ABANDON(position|origposition|waittime) +The caller abandoned their position in the queue. The position is the +caller's position in the queue when they hungup, the origposition is +the original position the caller was when they first entered the +queue, and the waittime is how long the call had been waiting in the +queue at the time of disconnect. + +AGENTDUMP +The agent dumped the caller while listening to the queue announcement. + +AGENTLOGIN(channel) +The agent logged in. The channel is recorded. + +AGENTCALLBACKLOGIN(exten@context) +The callback agent logged in. The login extension and context is recorded. + +AGENTLOGOFF(channel|logintime) +The agent logged off. The channel is recorded, along with the total time +the agent was logged in. + +AGENTCALLBACKLOGOFF(exten@context|logintime|reason) +The callback agent logged off. The last login extension and context is +recorded, along with the total time the agent was logged in, and the +reason for the logoff if it was not a normal logoff +(e.g., Autologoff, Chanunavail) + +COMPLETEAGENT(holdtime|calltime|origposition) +The caller was connected to an agent, and the call was terminated normally +by the *agent*. The caller's hold time and the length of the call are both +recorded. The caller's original position in the queue is recorded in +origposition. + +COMPLETECALLER(holdtime|calltime|origposition) +The caller was connected to an agent, and the call was terminated normally +by the *caller*. The caller's hold time and the length of the call are both +recorded. The caller's original position in the queue is recorded in +origposition. + +CONFIGRELOAD +The configuration has been reloaded (e.g. with asterisk -rx reload) + +CONNECT(holdtime|bridgedchanneluniqueid) +The caller was connected to an agent. Hold time represents the amount +of time the caller was on hold. The bridged channel unique ID contains +the unique ID of the queue member channel that is taking the call. This +is useful when trying to link recording filenames to a particular +call in the queue. + +ENTERQUEUE(url|callerid) +A call has entered the queue. URL (if specified) and Caller*ID are placed +in the log. + +EXITEMPTY(position|origposition|waittime) +The caller was exited from the queue forcefully because the queue had no +reachable members and it's configured to do that to callers when there +are no reachable members. The position is the caller's position in the +queue when they hungup, the origposition is the original position the +caller was when they first entered the queue, and the waittime is how +long the call had been waiting in the queue at the time of disconnect. + +EXITWITHKEY(key|position) +The caller elected to use a menu key to exit the queue. The key and +the caller's position in the queue are recorded. + +EXITWITHTIMEOUT(position) +The caller was on hold too long and the timeout expired. + +QUEUESTART +The queueing system has been started for the first time this session. + +RINGNOANSWER(ringtime) +After trying for ringtime ms to connect to the available queue member, +the attempt ended without the member picking up the call. Bad queue +member! + +SYSCOMPAT +A call was answered by an agent, but the call was dropped because the +channels were not compatible. + +TRANSFER(extension|context|holdtime|calltime) +Caller was transferred to a different extension. Context and extension +are recorded. The caller's hold time and the length of the call are both +recorded. PLEASE remember that transfers performed by SIP UA's by way +of a reinvite may not always be caught by Asterisk and trigger off this +event. The only way to be 100% sure that you will get this event when +a transfer is performed by a queue member is to use the built-in transfer +functionality of Asterisk. + diff --git a/1.4.23-rc4/doc/queues-with-callback-members.txt b/1.4.23-rc4/doc/queues-with-callback-members.txt new file mode 100644 index 000000000..c58c30a28 --- /dev/null +++ b/1.4.23-rc4/doc/queues-with-callback-members.txt @@ -0,0 +1,521 @@ + +Setting up Call Queues -- A Tutorial + +Pardon, but the dialplan in this tutorial will be expressed +in AEL, the new Asterisk Extension Language. If you are +not used to its syntax, we hope you will find it to some +degree intuitive. If not, there are documents explaining +its syntax and constructs. + + +====== Configuring Call Queues + +First of all, set up call queues in queue.conf + +Here is an example: + + =========== queues.conf =========== + | ; Cool Digium Queues | + | [general] | + | persistentmembers = yes | + | | + | ; General sales queue | + | [sales-general] | + | music=default | + | context=sales | + | strategy=ringall | + | joinempty=strict | + | leavewhenempty=strict | + | | + | ; Customer service queue | + | [customerservice] | + | music=default | + | context=customerservice | + | strategy=ringall | + | joinempty=strict | + | leavewhenempty=strict | + | | + | ; Support dispatch queue | + | [support-dispatch] | + | music=default | + | context=dispatch | + | strategy=ringall | + | joinempty=strict | + | leavewhenempty=strict | + =================================== + +In the above, we have defined 3 separate calling queues: +sales-general, customerservice, and support-dispatch. + +Please note that the sales-general queue specifies a +context of "sales", and that customerservice specifies the +context of "customerservice", and the support-dispatch +queue specifies the context "dispatch". These three +contexts must be defined somewhere in your dialplan. +We will show them after the main menu below. + +<verbage explaining options above> +In the [general] section, specifying the persistentmembers=yes, +will cause the agent lists to be stored in astdb, and +recalled on startup. + +The strategy=ringall will cause all agents to be dialed +together, the first to answer is then assigned the incoming +call. + +"joinempty" set to "strict" will keep incoming callers from +being placed in queues where there are no agents to take calls. +The Queue() application will return, and the dial plan can +determine what to do next. + +If there are calls queued, and the last agent logs out, the +remaining incoming callers will immediately be removed from +the queue, and the Queue() call will return, IF the "leavewhenempty" is +set to "strict". + + +===================================== +| Routing incoming Calls to Queues | +===================================== + + +Then in extensions.ael, you can do these things: + +================ The Main Menu + +At Digium, incoming callers are sent to the "mainmenu" context, where they +are greeted, and directed to the numbers they choose... + +context mainmenu { + + includes { + digium; + queues-loginout; + } + + 0 => goto dispatch|s|1; + 2 => goto sales|s|1; + 3 => goto customerservice|s|1; + 4 => goto dispatch|s|1; + + s => { + Ringing(); + Wait(1); + Set(attempts=0); + Answer(); + Wait(1); + Background(digium/ThankYouForCallingDigium); + Background(digium/YourOpenSourceTelecommunicationsSupplier); + WaitExten(0.3); + repeat: + Set(attempts=$[${attempts} + 1]); + Background(digium/IfYouKnowYourPartysExtensionYouMayDialItAtAnyTime); + WaitExten(0.1); + Background(digium/Otherwise); + WaitExten(0.1); + Background(digium/ForSalesPleasePress2); + WaitExten(0.2); + Background(digium/ForCustomerServicePleasePress3); + WaitExten(0.2); + Background(digium/ForAllOtherDepartmentsPleasePress4); + WaitExten(0.2); + Background(digium/ToSpeakWithAnOperatorPleasePress0AtAnyTime); + if( ${attempts} < 2 ) { + WaitExten(0.3); + Background(digium/ToHearTheseOptionsRepeatedPleaseHold); + } + WaitExten(5); + if( ${attempts} < 2 ) goto repeat; + Background(digium/YouHaveMadeNoSelection); + Background(digium/ThisCallWillBeEnded); + Background(goodbye); + Hangup(); + } +} + + +============= The Contexts referenced from the queues.conf file + + + +context sales { + + 0 => goto dispatch|s|1; + 8 => Voicemail(${SALESVM}); + + s => { + Ringing(); + Wait(2); + Background(digium/ThankYouForContactingTheDigiumSalesDepartment); + WaitExten(0.3); + Background(digium/PleaseHoldAndYourCallWillBeAnsweredByOurNextAvailableSalesRepresentative); + WaitExten(0.3); + Background(digium/AtAnyTimeYouMayPress0ToSpeakWithAnOperatorOr8ToLeaveAMessage); + Set(CALLERID(name)=Sales); + Queue(sales-general|t); + Set(CALLERID(name)=EmptySalQ); + goto dispatch|s|1; + Playback(goodbye); + Hangup(); + } +} + +Please note that there is only one attempt to queue a call in the sales queue. All sales agents that +are logged in will be rung. + + +context customerservice { + + 0 => { + SetCIDName(CSVTrans); + goto dispatch|s|1; + } + 8 => Voicemail(${CUSTSERVVM}); + + s => { + Ringing(); + Wait(2); + Background(digium/ThankYouForCallingDigiumCustomerService); + WaitExten(0.3); + notracking: + Background(digium/PleaseWaitForTheNextAvailableCustomerServiceRepresentative); + WaitExten(0.3); + Background(digium/AtAnyTimeYouMayPress0ToSpeakWithAnOperatorOr8ToLeaveAMessage); + Set(CALLERID(name)=Cust Svc); + Set(QUEUE_MAX_PENALTY=10); + Queue(customerservice|t); + Set(QUEUE_MAX_PENALTY=0); + Queue(customerservice|t); + Set(CALLERID(name)=EmptyCSVQ); + goto dispatch|s|1; + Background(digium/NoCustomerServiceRepresentativesAreAvailableAtThisTime); + Background(digium/PleaseLeaveAMessageInTheCustomerServiceVoiceMailBox); + Voicemail(${CUSTSERVVM}); + Playback(goodbye); + Hangup(); + } +} + +Note that calls coming into customerservice will first be try to queue +calls to those agents with a QUEUE_MAX_PENALTY of 10, and if none are available, +then all agents are rung. + + +context dispatch +{ + + s => { + Ringing(); + Wait(2); + Background(digium/ThankYouForCallingDigium); + WaitExten(0.3); + Background(digium/YourCallWillBeAnsweredByOurNextAvailableOperator); + Background(digium/PleaseHold); + Set(QUEUE_MAX_PENALTY=10); + Queue(dispatch|t); + Set(QUEUE_MAX_PENALTY=20); + Queue(dispatch|t); + Set(QUEUE_MAX_PENALTY=0); + Queue(dispatch|t); + Background(digium/NoOneIsAvailableToTakeYourCall); + Background(digium/PleaseLeaveAMessageInOurGeneralVoiceMailBox); + Voicemail(${DISPATCHVM}); + Playback(goodbye); + Hangup(); + } +} + +And in the dispatch context, first agents of priority 10 are tried, then +20, and if none are available, all agents are tried. + +Notice that a common pattern is followed in each of the three queue contexts: + +First, you set QUEUE_MAX_PENALTY to a value, then you call +Queue(<queue-name>,option,... (see the documentation for the Queue application)); + +In the above, note that the "t" option is specified, and this allows the +agent picking up the incoming call the luxury of transferring the call to +other parties. + +The purpose of specifying the QUEUE_MAX_PENALTY is to develop a set of priorities +amongst agents. By the above usage, agents with lower number priorities will +be given the calls first, and then, if no-one picks up the call, the QUEUE_MAX_PENALTY +will be incremented, and the queue tried again. Hopefully, along the line, someone +will pick up the call, and the Queue application will end with a hangup. + +The final attempt to queue in most of our examples sets the QUEUE_MAX_PENALTY +to zero, which means to try all available agents. + + +========================================= +| Assigning agents to Queues | +========================================= + +In this example dialplan, we want to be able to add and remove agents to +handle incoming calls, as they feel they are available. As they log in, +they are added to the queue's agent list, and as they log out, they are +removed. If no agents are available, the queue command will terminate, and +it is the duty of the dialplan to do something appropriate, be it sending +the incoming caller to voicemail, or trying the queue again with a higher +QUEUE_MAX_PENALTY. + +Because a single agent can make themselves available to more than one queue, +the process of joining multiple queues can be handled automatically by the +dialplan. + + +================= Agents Log In and Out + + +context queues-loginout +{ + 6092 => { + Answer(); + Read(AGENT_NUMBER,agent-enternum); + VMAuthenticate(${AGENT_NUMBER}@default,s); + Set(queue-announce-success=1); + goto queues-manip,I${AGENT_NUMBER},1; + } + + 6093 => { + Answer(); + Read(AGENT_NUMBER,agent-enternum); + Set(queue-announce-success=1); + goto queues-manip,O${AGENT_NUMBER},1; + } +} + + +In the above contexts, the agents dial 6092 to log into their queues, +and they dial 6093 to log out of their queues. The agent is prompted +for their agent number, and if they are logging in, their passcode, +and then they are transferred to the proper extension in the +queues-manip context. The queues-manip context does all the +actual work: + + +context queues-manip { + + // Raquel Squelch + _[IO]6121 => { + &queue-addremove(dispatch,10); + &queue-success(); + } + + // Brittanica Spears + _[IO]6165 => { + &queue-addremove(dispatch,20); + &queue-success(); + } + + // Rock Hudson + _[IO]6170 => { + &queue-addremove(sales-general,10); + &queue-addremove(customerservice,20); + &queue-addremove(dispatch,30); + &queue-success(); + } + + // Saline Dye-on + _[IO]6070 => { + &queue-addremove(sales-general,20); + &queue-addremove(customerservice,30); + &queue-addremove(dispatch,30); + &queue-success(); + } +} + +In the above extensions, note that the queue-addremove macro is used +to actually add or remove the agent from the applicable queue, +with the applicable priority level. Note that agents with a +priority level of 10 will be called before agents with levels +of 20 or 30. + +In the above example, Raquel will be dialed first in the dispatch +queue, if she has logged in. If she is not, then the second call of +Queue() with priority of 20 will dial Brittanica if she is present, +otherwise the third call of Queue() with MAX_PENALTY of 0 will +dial Rock and Saline simultaneously. + +Also note that Rock will be among the first to be called in the sales-general +queue, and among the last in the dispatch queue. As you can see in +main menu, the callerID is set in the main menu so they can tell +which queue incoming calls are coming from. + +The call to queue-success() gives some feedback to the agent +as they log in and out, that the process has completed. + +macro queue-success() +{ + if( ${queue-announce-success} > 0 ) + { + switch(${MACRO_EXTEN:0:1}) + { + case I: + Playback(agent-loginok); + Hangup(); + break; + case O: + Playback(agent-loggedoff); + Hangup(); + break; + } + } +} + + +The queue-addremove macro is defined in this manner: + +macro queue-addremove(queuename,penalty) +{ + switch(${MACRO_EXTEN:0:1}) + { + case I: // Login + AddQueueMember(${queuename},Local/${MACRO_EXTEN:1}@agents,${penalty}); + break; + case O: // Logout + RemoveQueueMember(${queuename},Local/${MACRO_EXTEN:1}@agents); + break; + case P: // Pause + PauseQueueMember(${queuename},Local/${MACRO_EXTEN:1}@agents); + break; + case U: // Unpause + UnpauseQueueMember(${queuename},Local/${MACRO_EXTEN:1}@agents); + break; + default: // Invalid + Playback(invalid); + break; + } +} + +Basically, it uses the first character of the MACRO_EXTEN variable, to determine the +proper actions to take. In the above dial plan code, only the cases I or O are used, +which correspond to the Login and Logout actions. + + +======================================================= +| Controlling The Way Queues Call the Agents | +======================================================= + +Notice in the above, that the commands to manipulate agents in queues have +"@agents" in their arguments. This is a reference to the agents context: + +context agents +{ + // General sales queue + 8010 => + { + Set(QUEUE_MAX_PENALTY=10); + Queue(sales-general|t); + Set(QUEUE_MAX_PENALTY=0); + Queue(sales-general|t); + Set(CALLERID(name)=EmptySalQ); + goto dispatch|s|1; + } + // Customer Service queue + 8011 => + { + Set(QUEUE_MAX_PENALTY=10); + Queue(customerservice|t); + Set(QUEUE_MAX_PENALTY=0); + Queue(customerservice|t); + Set(CALLERID(name)=EMptyCSVQ); + goto dispatch|s|1; + } + 8013 => + { + Dial(iax2/sweatshop/9456@from-ecstacy); + + Set(CALLERID(name)=EmptySupQ); + Set(QUEUE_MAX_PENALTY=10); + Queue(support-dispatch,t); + Set(QUEUE_MAX_PENALTY=20); + Queue(support-dispatch,t); + Set(QUEUE_MAX_PENALTY=0); // means no max + Queue(support-dispatch,t); + goto dispatch|s|1; + } + 6121 => &callagent(${RAQUEL}); + 6165 => &callagent(${SPEARS}); + 6170 => &callagent(${ROCK}); + 6070 => &callagent(${SALINE}); +} + +In the above, the variables ${RAQUEL}, etc stand for +actual devices to ring that person's +phone (like Zap/37). + +The 8010, 8011, and 8013 extensions are purely for transferring +incoming callers to queues. For instance, a customer service +agent might want to transfer the caller to talk to sales. The +agent only has to transfer to extension 8010, in this case. + +Here is the callagent macro, note that if a person in the +queue is called, but does not answer, then they are automatically +removed from the queue. + +macro callagent(device) +{ + if( ${GROUP_COUNT(${MACRO_EXTEN}@agents)}=0 ) + { + Set(OUTBOUND_GROUP=${MACRO_EXTEN}@agents); + Dial(${device}|300|t); + switch(${DIALSTATUS}) + { + case BUSY: + Busy(); + break; + case NOANSWER: + Set(queue-announce-success=0); + goto queues-manip|O${MACRO_EXTEN}|1; + default: + Hangup(); + break; + } + } + else + { + Busy(); + } +} + +In the callagent macro above, the ${MACRO_EXTEN} will +be 6121, or 6165, etc, which is the extension of the agent. + +The use of the GROUP_COUNT, and OUTBOUND_GROUP follow this line +of thinking. Incoming calls can be queued to ring all agents in the +current priority. If some of those agents are already talking, they +would get bothersome call-waiting tones. To avoid this inconvenience, +when an agent gets a call, the OUTBOUND_GROUP assigns that +conversation to the group specified, for instance 6171@agents. +The ${GROUP_COUNT()} variable on a subsequent call should return +"1" for that group. If GROUP_COUNT returns 1, then the busy() +is returned without actually trying to dial the agent. + +================ Pre Acknowledgement Message + +If you would like to have a pre acknowledge message with option to reject the message +you can use the following dialplan Macro as a base with the 'M' dial argument. + +[macro-screen] +exten=>s,1,Wait(.25) +exten=>s,2,Read(ACCEPT|screen-callee-options|1) +exten=>s,3,Gotoif($[${ACCEPT} = 1] ?50) +exten=>s,4,Gotoif($[${ACCEPT} = 2] ?30) +exten=>s,5,Gotoif($[${ACCEPT} = 3] ?40) +exten=>s,6,Gotoif($[${ACCEPT} = 4] ?30:30) +exten=>s,30,Set(MACRO_RESULT=CONTINUE) +exten=>s,40,Read(TEXTEN|custom/screen-exten|) +exten=>s,41,Gotoif($[${LEN(${TEXTEN})} = 3]?42:45) +exten=>s,42,Set(MACRO_RESULT=GOTO:from-internal^${TEXTEN}^1) +exten=>s,45,Gotoif($[${TEXTEN} = 0] ?46:4) +exten=>s,46,Set(MACRO_RESULT=CONTINUE) +exten=>s,50,Playback(after-the-tone) +exten=>s,51,Playback(connected) +exten=>s,52,Playback(beep) + +================ Caveats + +In the above examples, some of the possible error checking has been omitted, +to reduce clutter and make the examples clearer. + diff --git a/1.4.23-rc4/doc/radius.txt b/1.4.23-rc4/doc/radius.txt new file mode 100644 index 000000000..041f072ac --- /dev/null +++ b/1.4.23-rc4/doc/radius.txt @@ -0,0 +1,203 @@ +Call Detail Recording to RADIUS Server +====================================== + + +Configuration of Asterisk to send CDRs to (Free)RADIUS servers. + + +A. What is needed : + * FreeRADIUS server + * Radiusclient-ng library + * Asterisk PBX + + + +--------------------+ + | Asterisk PBX | + | | + |********************| + | | +---------------+ + | RADIUS client |------->| RADIUS server | + | |<-------| (FreeRADIUS) | + +--------------------+ +---------------+ + + + + +B. Steps to follow in order to have RADIUS support: + + 1.Radiusclient library + 1.a Installation + + Download the sources from: + + http://developer.berlios.de/projects/radiusclient-ng/ + + Untar the source tarball. + root@localhost:/usr/local/src# tar xvfz radiusclient-ng-0.5.2.tar.gz + + Compile and install the library. + root@localhost:/usr/local/src# cd radiusclient-ng-0.5.2 + root@localhost:/usr/local/src/radiusclient-ng-0.5.2# ./configure + root@localhost:/usr/local/src/radiusclient-ng-0.5.2# make + root@localhost:/usr/local/src/radiusclient-ng-0.5.2# make install + + 1.b Configuration + + By default all the configuration files of the radiusclient library will + be in /usr/local/etc/radiusclient-ng directory. + + File "radiusclient.conf" + Open the file and find lines containing the following: + + authserver localhost + + This is the hostname or IP address of the RADIUS server used for + authentication. You will have to change this unless the server is + running on the same host as your Asterisk PBX. + + acctserver localhost + + This is the hostname or IP address of the RADIUS server used for + accounting. You will have to change this unless the server is running + on the same host as your Asterisk PBX. + + File "servers" + + RADIUS protocol uses simple access control mechanism based on shared + secrets that allows RADIUS servers to limit access from RADIUS clients. + + A RADIUS server is configured with a secret string and only RADIUS + clients that have the same secret will be accepted. + + You need to configure a shared secret for each server you have + configured in radiusclient.conf file in the previous step. The shared + secrets are stored in /usr/local/etc/radiusclient-ng/servers file. + + Each line contains hostname of a RADIUS server and shared secret + used in communication with that server. The two values are separated + by white spaces. Configure shared secrets for every RADIUS server you + are going to use. + + File "dictionary" + + Asterisk uses some attributes that are not included in the + dictionary of radiusclient library, therefore it is necessary to add + them. A file called dictionary.digium (kept in the contrib dir) + was created to list all new attributes used by Asterisk. + Add to the end of the main dictionary file + /usr/local/etc/radiusclient-ng/dictionary + the line: + + $INCLUDE /path/to/dictionary.digium + + 2.FreeRADIUS Server (Version 1.1.1) + 2.a Installation + + Download sources tarball from: + + http://freeradius.org/ + + Untar, configure, build, and install the server: + + root@localhost:/usr/local/src# tar xvfz freeradius-1.1.1.tar.gz + root@localhost:/usr/local/src# cd freeradius-1.1.1 + root@localhost"/usr/local/src/freeradius-1.1.1# ./configure + root@localhost"/usr/local/src/freeradius-1.1.1# make + root@localhost"/usr/local/src/freeradius-1.1.1# make install + + All the configuration files of FreeRADIUS server will be in + /usr/local/etc/raddb directory. + + + 2.b Configuration + + There are several file that have to be modified to configure the + RADIUS server. These are presented next. + + File "clients.conf" + + File /usr/local/etc/raddb/clients.conf contains description of + RADIUS clients that are allowed to use the server. For each of the + clients you need to specify its hostname or IP address and also a + shared secret. The shared secret must be the same string you configured + in radiusclient library. + + Example: + client myhost { + secret = mysecret + shortname = foo + } + + This fragment allows access from RADIUS clients on "myhost" if they use + "mysecret" as the shared secret. + The file already contains an entry for localhost (127.0.0.1), so if you + are running the RADIUS server on the same host as your Asterisk server, + then modify the existing entry instead, replacing the default password. + + File "dictionary" + + Note : as of version 1.1.2, the dictionary.digium file ships with FreeRADIUS. + The following procedure brings the dictionary.digium file to previous versions + of FreeRADIUS. + + File /usr/local/etc/raddb/dictionary contains the dictionary of + FreeRADIUS server. You have to add the same dictionary file + (dictionary.digium), which you added to the dictionary of radiusclient-ng + library. You can include it into the main file, adding the following line at the + end of file '/usr/local/etc/raddb/dictionary': + + $INCLUDE /path/to/dictionary.digium + + That will include the same new attribute definitions that are used + in radiusclient-ng library so the client and server will understand each + other. + + + 3. Asterisk Accounting Configuration + + Compilation and installation: + The module will be compiled as long as the radiusclient-ng + library has been detected on your system. + + By default FreeRADIUS server will log all accounting requests into + /usr/local/var/log/radius/radacct directory in form of plain text files. + The server will create one file for each hostname in the directory. The + following example shows how the log files look like. + + Asterisk now generates Call Detail Records. See /include/asterisk/cdr.h + for all the fields which are recorded. By default, records in comma + separated values will be created in /var/log/asterisk/cdr-csv. + + The configuration file for cdr_radius.so module is : + + /etc/asterisk/cdr.conf + This is where you can set CDR related parameters as well as the path to + the radiusclient-ng library configuration file. + + + 4. Logged Values + + "Asterisk-Acc-Code", The account name of detail records + "Asterisk-Src", + "Asterisk-Dst", + "Asterisk-Dst-Ctx", The destination context + "Asterisk-Clid", + "Asterisk-Chan", The channel + "Asterisk-Dst-Chan", (if applicable) + "Asterisk-Last-App", Last application run on the channel + "Asterisk-Last-Data", Argument to the last channel + "Asterisk-Start-Time", + "Asterisk-Answer-Time", + "Asterisk-End-Time", + "Asterisk-Duration", Duration is the whole length that the entire + call lasted. ie. call rx'd to hangup + "end time" minus "start time" + "Asterisk-Bill-Sec", The duration that a call was up after other + end answered which will be <= to duration + "end time" minus "answer time" + "Asterisk-Disposition", ANSWERED, NO ANSWER, BUSY + "Asterisk-AMA-Flags", DOCUMENTATION, BILL, IGNORE etc, specified on + a per channel basis like accountcode. + "Asterisk-Unique-ID", Unique call identifier + "Asterisk-User-Field" User field set via SetCDRUserField + diff --git a/1.4.23-rc4/doc/realtime.txt b/1.4.23-rc4/doc/realtime.txt new file mode 100644 index 000000000..cc90e5f71 --- /dev/null +++ b/1.4.23-rc4/doc/realtime.txt @@ -0,0 +1,138 @@ +The Asterisk Realtime Architecture +---------------------------------- + +The Asterisk Realtime Architecture is a new set of drivers and +functions implemented in Asterisk. + +The benefits of this architecture are many, both from a code management +standpoint and from an installation perspective. + +Additional information on the configuration of Realtime with Asterisk +can be found in doc/extconfig.txt + +The ARA is designed to be independent of storage. Currently, most +drivers are based on SQL, but the architecture should be able to handle +other storage methods in the future, like LDAP. + +The main benefit comes in the database support. In Asterisk v1.0 some +functions supported MySQL database, some PostgreSQL and other ODBC. +With the ARA, we have a unified database interface internally in Asterisk, +so if one function supports database integration, all databases that has a +realtime driver will be supported in that function. + +Currently there are three realtime database drivers: + +* ODBC: Support for UnixODBC, integrated into Asterisk + The UnixODBC subsystem supports many different databases, + please check www.unixodbc.org for more information. +* MySQL: Found in the asterisk-addons subversion repository on svn.digium.com +* PostgreSQL: Native support for Postgres, integrated into Asterisk + +* Two modes: Static and Realtime +-------------------------------- +The ARA realtime mode is used to dynamically load and update objects. +This mode is used in the SIP and IAX2 channels, as well as in the voicemail +system. For SIP and IAX2 this is similar to the v1.0 MYSQL_FRIENDS +functionality. With the ARA, we now support many more databases for +dynamic configuration of phones. + +The ARA static mode is used to load configuration files. For the Asterisk +modules that read configurations, there's no difference between a static +file in the file system, like extensions.conf, and a configuration loaded +from a database. + +You just have to always make sure the var_metric values are properly set and +ordered as you expect in your database server if you're using the static mode +with ARA (either sequentially or with the same var_metric value for everybody). + +If you have an option that depends on another one in a given configuration +file (i.e, 'musiconhold' depending on 'agent' from agents.conf) but their +var_metric are not sequential you'll probably get default values being assigned for +those options instead of the desired ones. You can still use the same +var_metric for all entries in your DB, just make sure the entries +are recorded in an order that does not break the option dependency. + +That doesn't happen when you use a static file in the file system. Although +this might be interpreted as a bug or limitation, it is not. + +* Realtime SIP friends +---------------------- +The SIP realtime objects are users and peers that are loaded in memory +when needed, then deleted. This means that Asterisk currently can't handle +voicemail notification and NAT keepalives for these peers. Other than that, +most of the functionality works the same way for realtime friends as for +the ones in static configuration. + +With caching, the device stays in memory for a specified time. More +information about this is to be found in the sip.conf sample file. + +* Realtime H.323 friends +------------------------ +Like SIP realtime friends, H.323 friends also can be configured using +dynamic realtime objects. + +* New function in the dial plan: The Realtime Switch +---------------------------------------------------- +The realtime switch is more than a port of functionality in v1.0 to the +new architecture, this is a new feature of Asterisk based on the +ARA. The realtime switch lets your Asterisk server do database lookups +of extensions in realtime from your dial plan. You can have many Asterisk +servers sharing a dynamically updated dial plan in real time with this +solution. + +Note that this switch does _NOT_ support Caller ID matching, only +extension name/pattern matching. + +* So what can you do? +--------------------- +The realtime Architecture lets you store all of your configuration in +databases and reload it whenever you want. You can force a reload over +the AMI, Asterisk Manager Interface or by calling Asterisk from a +shell script with + asterisk -rx "reload" + +You may also dynamically add SIP and IAX devices and extensions +and making them available without a reload, by using the realtime +objects and the realtime switch. + + +* Configuration in extconfig.conf +--------------------------------- +You configure the ARA in extconfig.conf (yes, it's a strange name, but +is was defined in the early days of the realtime architecture and kind +of stuck). Please see doc/extconfig.txt for database schemas. + +The part of Asterisk that connects to the ARA use a well defined family +name to find the proper database driver. The syntax is easy: + <family> => <realtime driver>,<db name>[,<table>] + +The options following the realtime driver identified depends on the +driver. + +Defined well-known family names are: + +* sippeers, sipusers SIP peers and users +* iaxpeers, iaxusers IAX2 peers and users +* voicemail Voicemail accounts +* queues Queues +* queue_members Queue members +* extensions Realtime extensions (switch) + +There is documentation of the SQL database in the file +doc/extconfig.txt in your Asterisk source code tree. + +For voicemail storage with the support of ODBC, there is a +doc/odbcstorage.txt documentation file. + + +* Limitations +------------- +Currently, realtime extensions do not support realtime hints. + + +* FreeTDS supported with connection pooling +------------------------------------------- +In order to use a FreeTDS-based database with realtime, you need to turn +connection pooling on in res_odbc.conf. This is due to a limitation within +the FreeTDS protocol itself. Please note that this includes databases such +as MS SQL Server and Sybase. This support is new in the current release. diff --git a/1.4.23-rc4/doc/rtp-packetization.txt b/1.4.23-rc4/doc/rtp-packetization.txt new file mode 100644 index 000000000..647375a98 --- /dev/null +++ b/1.4.23-rc4/doc/rtp-packetization.txt @@ -0,0 +1,73 @@ +Overview +------- +Asterisk currently supports configurable RTP packetization per codec for +select RTP-based channels. + +Channels +------- +These channel drivers allow RTP packetization on a user/peer/friend +or global level: + chan_sip + chan_skinny + chan_h323 + chan_ooh323 (Asterisk-Addons) + +Configuration +------- +To set a desired packetization interval on a specific codec, +append that inteval to the allow= statement. + +Example: +allow=ulaw:30,alaw,g729:60 + +No packetization is specified in the case of alaw in this example, +so the default of 20ms is used. + +Autoframing +------- +In addition, chan_sip has the ability to negotiate the desired +framing at call establishment. + +In sip.conf if autoframing=yes is set in the global section, then +all calls will try to set the packetization based on the remote +endpoint's preferences. This behaviour depends on the endpoints +ability to present the desired packetization (ptime:) in the SDP. +If the endpoint does not include a ptime attribute, the call will +be established with 20ms packetization. + +Autoframing can be set at the global level or on a user/peer/friend +basis. If it is enabled at the global level, it applies to all +users/peers/friends regardless of their prefered codec packetization. + +Codec framing options +------- +The following table lists the minimum and maximum values that are +valid per codec, as well as the increment value used for each. +Please note that the maximum values here are only recommended +maximums, and should not exceed the RTP MTU. + +Name Min Max Default Increment +g723 30 300 30 30 +gsm 20 300 20 20 +ulaw 10 150 20 10 +alaw 10 150 20 10 +g726 10 300 20 10 +ADPCM 10 300 20 10 +SLIN 10 70 20 10 +lpc10 20 20 20 20 +g729 10 230 20 10 +speex 10 60 20 10 +ilbc 30 30 30 30 +g726_aal2 10 300 20 10 + +Invalid framing options are handled based on the following rules: + 1. If the specified framing is less than the codec's minimum, then + the minimum value is used. + 2. If the specific framing is greater than the codec's maximum, then + the maximum value is used + 3. If the specificed framing does not meet the increment requirement, + the specified framing is rounded down to the closest valid + framing options. + example allow=ulaw:33 will set the codec to 30ms framing + 4. If no framing is specified in the allow= directive, then the + codec default is used. diff --git a/1.4.23-rc4/doc/security.txt b/1.4.23-rc4/doc/security.txt new file mode 100644 index 000000000..3adf53624 --- /dev/null +++ b/1.4.23-rc4/doc/security.txt @@ -0,0 +1,80 @@ +==== Security Notes with Asterisk ==== + +PLEASE READ THE FOLLOWING IMPORTANT SECURITY RELATED INFORMATION. +IMPROPER CONFIGURATION OF ASTERISK COULD ALLOW UNAUTHORIZED USE OF YOUR +FACILITIES, POTENTIALLY INCURRING SUBSTANTIAL CHARGES. + +Asterisk security involves both network security (encryption, authentication) +as well as dialplan security (authorization - who can access services in +your pbx). If you are setting up Asterisk in production use, please make +sure you understand the issues involved. + +* NETWORK SECURITY + +If you install Asterisk and use the "make samples" command to install +a demonstration configuration, Asterisk will open a few ports for accepting +VoIP calls. Check the channel configuration files for the ports and IP addresses. + +If you enable the manager interface in manager.conf, please make sure that +you access manager in a safe environment or protect it with SSH or other +VPN solutions. + +For all TCP/IP connections in Asterisk, you can set ACL lists that +will permit or deny network access to Asterisk services. Please check +the "permit" and "deny" configuration options in manager.conf and +the VoIP channel configurations - i.e. sip.conf and iax.conf. + +The IAX2 protocol supports strong RSA key authentication as well as +AES encryption of voice and signalling. The SIP channel does not +support encryption in this version of Asterisk. + +By default, if you have libcap available, Asterisk will try to retain the +CAP_NET_ADMIN capability when running as a non-root user. If you do not need +that capability you may want to configure Asterisk with --without-cap; however, +this will prevent Asterisk from being able to mark high ToS bits under Linux. +More information on CAP_NET_ADMIN is available at: +http://www.lids.org/lids-howto/node48.html + +* DIALPLAN SECURITY + +First and foremost remember this: + +USE THE EXTENSION CONTEXTS TO ISOLATE OUTGOING OR TOLL SERVICES FROM ANY +INCOMING CONNECTIONS. + +You should consider that if any channel, incoming line, etc can enter an +extension context that it has the capability of accessing any extension +within that context. + +Therefore, you should NOT allow access to outgoing or toll services in +contexts that are accessible (especially without a password) from incoming +channels, be they IAX channels, FX or other trunks, or even untrusted +stations within you network. In particular, never ever put outgoing toll +services in the "default" context. To make things easier, you can include +the "default" context within other private contexts by using: + + include => default + +in the appropriate section. A well designed PBX might look like this: + +[longdistance] +exten => _91NXXNXXXXXX,1,Dial(Zap/g2/${EXTEN:1}) +include => local + +[local] +exten => _9NXXNXXX,1,Dial(Zap/g2/${EXTEN:1}) +include => default + +[default] +exten => 6123,Dial(Zap/1) + + +DON'T FORGET TO TAKE THE DEMO CONTEXT OUT OF YOUR DEFAULT CONTEXT. There +isn't really a security reason, it just will keep people from wanting to +play with your Asterisk setup remotely. + +* LOG SECURITY + +Please note that the Asterisk log files, as well as information printed to the +Asterisk CLI, may contain sensitive information such as passwords and call +history. Keep this in mind when providing access to these resources. diff --git a/1.4.23-rc4/doc/sip-retransmit.txt b/1.4.23-rc4/doc/sip-retransmit.txt new file mode 100644 index 000000000..a3431a806 --- /dev/null +++ b/1.4.23-rc4/doc/sip-retransmit.txt @@ -0,0 +1,126 @@ +What is the problem with SIP retransmits? +----------------------------------------- + +Sometimes you get messages in the console like these: + +- "retrans_pkt: Hanging up call XX77yy - no reply to our critical packet." +- "retrans_pkt: Cancelling retransmit of OPTIONs" + +The SIP protocol is based on requests and replies. Both sides send +requests and wait for replies. Some of these requests are important. +In a TCP/IP network many things can happen with IP packets. Firewalls, +NAT devices, Session Border Controllers and SIP Proxys are in the +signalling path and they will affect the call. + +SIP Call setup - INVITE-200 OK - ACK +------------------------------------ +To set up a SIP call, there's an INVITE transaction. The SIP software that +initiates the call sends an INVITE, then wait to get a reply. When a +reply arrives, the caller sends an ACK. This is a three-way handshake +that is in place since a phone can ring for a very long time and +the protocol needs to make sure that all devices are still on line +when call setup is done and media starts to flow. + +- The first reply we're waiting for is often a "100 trying". + This message means that some type of SIP server has received our + request and makes sure that we will get a reply. It could be + the other endpoint, but it could also be a SIP proxy or SBC + that handles the request on our behalf. + +- After that, you often see a response in the 18x class, like + "180 ringing" or "183 Session Progress". This typically means that our + request has reached at least one endpoint and something + is alerting the other end that there's a call coming in. + +- Finally, the other side answers and we get a positive reply, + "200 OK". This is a positive answer. In that message, we get an + address that goes directly to the device that answers. Remember, + there could be multiple phones ringing. The address is specified + by the Contact: header. + +- To confirm that we can reach the phone that answered our call, + we now send an ACK to the Contact: address. If this ACK doesn't + reach the phone, the call fails. If we can't send an ACK, we + can't send anything else, not even a proper hangup. Call + signalling will simply fail for the rest of the call and there's + no point in keeping it alive. + +- If we get an error response to our INVITE, like "Busy" or + "Rejected", we send the ACK to the same address as we sent the + INVITE, to confirm that we got the response. + +In order to make sure that the whole call setup sequence works and that +we have a call, a SIP client retransmits messages if there's too much +delay between request and expected response. We retransmit a number of +times while waiting for the first response. We retransmit the answer to an +incoming INVITE while waiting for an ACK. If we get multiple answers, +we send an ACK to each of them. + +If we don't get the ACK or don't get an answer to our INVITE, +even after retransmissions, we will hangup the call with the first +error message you see above. + +Other SIP requests +------------------ +Other SIP requests are only based on request - reply. There's +no ACK, no three-way handshake. In Asterisk we mark some of +these as CRITICAL - they need to go through for the call to +work as expected. Some are non-critical, we don't really care +what happens with them, the call will go on happily regardless. + +The qualification process - OPTIONS +----------------------------------- +If you turn on qualify= in sip.conf for a device, Asterisk will +send an OPTIONS request every minute to the device and check +if it replies. Each OPTIONS request is retransmitted a number +of times (to handle packet loss) and if we get no reply, the +device is considered unreachable. From that moment, we will +send a new OPTIONS request (with retransmits) every tenth +second. + +Why does this happen? +--------------------- + +For some reason signalling doesn't work as expected between +your Asterisk server and the other device. There could be many reasons +why this happens. + +- A NAT device in the signalling path + A misconfigured NAT device is in the signalling path + and stops SIP messages. +- A firewall that blocks messages or reroutes them wrongly + in an attempt to assist in a too clever way. +- A SIP middlebox (SBC) that rewrites contact: headers + so that we can't reach the other side with our reply + or the ACK. +- A badly configured SIP proxy that forgets to add + record-route headers to make sure that signalling works. +- Packet loss. IP and UDP are unreliable transports. If + you loose too many packets the retransmits doesn't help + and communication is impossible. If this happens with + signalling, media would be unusable anyway. + +What can I do? +-------------- + +Turn on SIP debug, try to understand the signalling that happens +and see if you're missing the reply to the INVITE or if the +ACK gets lost. When you know what happens, you've taken the +first step to track down the problem. See the list above and +investigate your network. + +For NAT and Firewall problems, there are many documents +to help you. Start with reading sip.conf.sample that is +part of your Asterisk distribution. + +The SIP signalling standard, including retransmissions +and timers for these, is well documented in the IETF +RFC 3261. + +Good luck sorting out your SIP issues! + +/Olle E. Johansson + + +-- oej (at) edvina.net, Sweden, 2008-07-22 +-- http://www.voip-forum.com diff --git a/1.4.23-rc4/doc/sla.pdf b/1.4.23-rc4/doc/sla.pdf Binary files differnew file mode 100644 index 000000000..c9f927ee8 --- /dev/null +++ b/1.4.23-rc4/doc/sla.pdf diff --git a/1.4.23-rc4/doc/sla.tex b/1.4.23-rc4/doc/sla.tex new file mode 100644 index 000000000..5aefdd61e --- /dev/null +++ b/1.4.23-rc4/doc/sla.tex @@ -0,0 +1,378 @@ +\documentclass[12pt,a4]{article} +\usepackage{hyperref} + +\author{Russell Bryant \\ Software Engineer \\ Digium, Inc.} +\title{Shared Line Appearances} + +\begin{document} +\maketitle + +\tableofcontents + +\section{Introduction} + +The "SLA" functionality in Asterisk is intended to allow a setup that emulates +a simple key system. It uses the various abstraction layers already built into +Asterisk to emulate key system functionality across various devices, including +IP channels. + +\section{Configuration} + +\subsection{Summary} + +An SLA system is built up of virtual trunks and stations mapped to real +Asterisk devices. The configuration for all of this is done in three +different files: extensions.conf, sla.conf, and the channel specific +configuration file such as sip.conf or chan_dahdi.conf. + +\subsection{Dialplan} + +The SLA implementation can automatically generate the dialplan necessary for +basic operation if the "autocontext" option is set for trunks and stations in +sla.conf. However, for reference, here is an automatically generated dialplan +to help with custom building of the dialplan to include other features, such as +voicemail (\ref{voicemail}). + +However, note that there is a little bit of additional configuration needed if +the trunk is an IP channel. This is discussed in the section on trunks (\ref{trunks}). + +There are extensions for incoming calls on a specific trunk, which execute the SLATrunk +application, as well as incoming calls from a station, which execute SLAStation. +Note that there are multiple extensions for incoming calls from a station. This is +because the SLA system has to know whether the phone just went off hook, or if the +user pressed a specific line button. + +Also note that there is a hint for every line on every station. This lets the SLA +system control each individual light on every phone to ensure that it shows the +correct state of the line. The phones must subscribe to the state of each of their +line appearances. + +Please refer to the examples section for full dialplan samples for SLA. + +\subsection{Trunks} +\label{trunks} + +An SLA trunk is a mapping between a virtual trunk and a real Asterisk device. +This device may be an analog FXO line, or something like a SIP trunk. A trunk +must be configured in two places. First, configure the device itself in the +channel specific configuration file such as chan_dahdi.conf or sip.conf. Once the +trunk is configured, then map it to an SLA trunk in sla.conf. + +\begin{verbatim} +[line1] +type=trunk +device=Zap/1 +\end{verbatim} + +Be sure to configure the trunk's context to be the same one that is set for the +"autocontext" option in sla.conf if automatic dialplan configuration is used. +This would be done in the regular device entry in chan_dahdi.conf, sip.conf, etc. +Note that the automatic dialplan generation creates the SLATrunk() extension +at extension 's'. This is perfect for Zap channels that are FXO trunks, for +example. However, it may not be good enough for an IP trunk, since the call +coming in over the trunk may specify an actual number. + +If the dialplan is being built manually, ensure that calls coming in on a trunk +execute the SLATrunk() application with an argument of the trunk name, as shown +in the dialplan example before. + +IP trunks can be used, but they require some additional configuration to work. + +For this example, let's say we have a SIP trunk called "mytrunk" that is going +to be used as line4. Furthermore, when calls come in on this trunk, they are +going to say that they are calling the number "12564286000". Also, let's say +that the numbers that are valid for calling out this trunk are NANP numbers, +of the form \_1NXXNXXXXXX. + +In sip.conf, there would be an entry for [mytrunk]. For [mytrunk], +set context=line4. + + +\begin{verbatim} +[line4] +type=trunk +device=Local/disa@line4_outbound +\end{verbatim} + + +\begin{verbatim} +[line4] +exten => 12564286000,1,SLATrunk(line4) + +[line4_outbound] +exten => disa,1,Disa(no-password|line4_outbound) +exten => _1NXXNXXXXXX,1,Dial(SIP/\${EXTEN}@mytrunk) +\end{verbatim} + + +So, when a station picks up their phone and connects to line 4, they are +connected to the local dialplan. The Disa application plays dialtone to the +phone and collects digits until it matches an extension. In this case, once +the phone dials a number like 12565551212, the call will proceed out the +SIP trunk. + +\subsection{Stations} + +An SLA station is a mapping between a virtual station and a real Asterisk device. +Currently, the only channel driver that has all of the features necessary to +support an SLA environment is chan\_sip. So, to configure a SIP phone to use +as a station, you must configure sla.conf and sip.conf. + +\begin{verbatim} +[station1] +type=station +device=SIP/station1 +trunk=line1 +trunk=line2 +\end{verbatim} + +Here are some hints on configuring a SIP phone for use with SLA: + +\begin{enumerate} +\item Add the SIP channel as a [station] in sla.conf. + +\item Configure the phone in sip.conf. If automatic dialplan configuration was + used by enabling the "autocontext" option in sla.conf, then this entry in + sip.conf should have the same context setting. + +\item On the phone itself, there are various things that must be configured to + make everything work correctly: + + Let's say this phone is called "station1" in sla.conf, and it uses trunks + named "line1" and line2". + \begin{enumerate} + + \item Two line buttons must be configured to subscribe to the state of the + following extensions: + - station1\_line1 + - station1\_line2 + + \item The line appearance buttons should be configured to dial the extensions + that they are subscribed to when they are pressed. + + \item If you would like the phone to automatically connect to a trunk when it + is taken off hook, then the phone should be automatically configured to + dial "station1" when it is taken off hook. + + \end{enumerate} +\end{enumerate} + + +\section{Configuration Examples} +\subsection{Basic SLA} + +This is an example of the most basic SLA setup. It uses the automatic +dialplan generation so the configuration is minimal. + +sla.conf: +\begin{verbatim} +[line1] +type=trunk +device=Zap/1 +autocontext=line1 + +[line2] +type=trunk +device=Zap/2 +autocontext=line2 + +[station](!) +type=station +trunk=line1 +trunk=line2 +autocontext=sla_stations + +[station1](station) +device=SIP/station1 + +[station2](station) +device=SIP/station2 + +[station3](station) +device=SIP/station3 + +\end{verbatim} + +With this configuration, the dialplan is generated automatically. The first +zap channel should have its context set to "line1" and the second should be +set to "line2" in chan_dahdi.conf. In sip.conf, station1, station2, and station3 +should all have their context set to "sla\_stations". + +For reference, here is the automatically generated dialplan for this situation: +\begin{verbatim} +[line1] +exten => s,1,SLATrunk(line1) + +[line2] +exten => s,2,SLATrunk(line2) + +[sla_stations] +exten => station1,1,SLAStation(station1) +exten => station1_line1,hint,SLA:station1_line1 +exten => station1_line1,1,SLAStation(station1_line1) +exten => station1_line2,hint,SLA:station1_line2 +exten => station1_line2,1,SLAStation(station1_line2) + +exten => station2,1,SLAStation(station2) +exten => station2_line1,hint,SLA:station2_line1 +exten => station2_line1,1,SLAStation(station2_line1) +exten => station2_line2,hint,SLA:station2_line2 +exten => station2_line2,1,SLAStation(station2_line2) + +exten => station3,1,SLAStation(station3) +exten => station3_line1,hint,SLA:station3_line1 +exten => station3_line1,1,SLAStation(station3_line1) +exten => station3_line2,hint,SLA:station3_line2 +exten => station3_line2,1,SLAStation(station3_line2) +\end{verbatim} + + +\subsection{SLA and Voicemail} +\label{voicemail} + +This is an example of how you could set up a single voicemail box for the +phone system. The voicemail box number used in this example is 1234, which +would be configured in voicemail.conf. + +For this example, assume that there are 2 trunks and 3 stations. The trunks +are Zap/1 and Zap/2. The stations are SIP/station1, SIP/station2, and +SIP/station3. + +In chan_dahdi.conf, channel 1 has context=line1 and channel 2 has context=line2. + +In sip.conf, all three stations are configured with context=sla\_stations. + +When the stations pick up their phones to dial, they are allowed to dial +NANP numbers for outbound calls, or 8500 for checking voicemail. + + +sla.conf: +\begin{verbatim} +[line1] +type=trunk +device=Local/disa@line1_outbound + +[line2] +type=trunk +device=Local/disa@line2_outbound + +[station](!) +type=station +trunk=line1 +trunk=line2 + +[station1](station) +device=SIP/station1 + +[station2](station) +device=SIP/station2 + +[station3](station) +device=SIP/station3 + +\end{verbatim} + + +extensions.conf: +\begin{verbatim} +[macro-slaline] +exten => s,1,SLATrunk(${ARG1}) +exten => s,n,Goto(s-${SLATRUNK_STATUS}|1) +exten => s-FAILURE,1,Voicemail(1234|u) +exten => s-UNANSWERED,1,Voicemail(1234|u) + +[line1] +exten => s,1,Macro(slaline|line1) + +[line2] +exten => s,2,Macro(slaline|line2) + +[line1_outbound] +exten => disa,1,Disa(no-password|line1_outbound) +exten => _1NXXNXXXXXX,1,Dial(Zap/1/${EXTEN}) +exten => 8500,1,VoicemailMain(1234) + +[line2_outbound] +exten => disa,1,Disa(no-password|line2_outbound) +exten => _1NXXNXXXXXX,1,Dial(Zap/2/${EXTEN}) +exten => 8500,1,VoicemailMain(1234) + +[sla_stations] + +exten => station1,1,SLAStation(station1) +exten => station1_line1,hint,SLA:station1_line1 +exten => station1_line1,1,SLAStation(station1_line1) +exten => station1_line2,hint,SLA:station1_line2 +exten => station1_line2,1,SLAStation(station1_line2) + +exten => station2,1,SLAStation(station2) +exten => station2_line1,hint,SLA:station2_line1 +exten => station2_line1,1,SLAStation(station2_line1) +exten => station2_line2,hint,SLA:station2_line2 +exten => station2_line2,1,SLAStation(station2_line2) + +exten => station3,1,SLAStation(station3) +exten => station3_line1,hint,SLA:station3_line1 +exten => station3_line1,1,SLAStation(station3_line1) +exten => station3_line2,hint,SLA:station3_line2 +exten => station3_line2,1,SLAStation(station3_line2) + +\end{verbatim} + +\section{Call Handling} +\subsection{Summary} + +This section is intended to describe how Asterisk handles calls inside of the +SLA system so that it is clear what behavior is expected. + +\subsection{Station goes off hook (not ringing)} + +When a station goes off hook, it should initiate a call to Asterisk with the +extension that indicates that the phone went off hook without specifying a +specific line. In the examples in this document, for the station named +"station1", this extension is simply named, "station1". + +Asterisk will attempt to connect this station to the first available trunk +that is not in use. Asterisk will check the trunks in the order that they +were specified in the station entry in sla.conf. If all trunks are in use, +the call will be denied. + +If Asterisk is able to acquire an idle trunk for this station, then trunk +is connected to the station and the station will hear dialtone. The station +can then proceed to dial a number to call. As soon as a trunk is acquired, +all appearances of this line on stations will show that the line is in use. + +\subsection{Station goes off hook (ringing)} + +When a station goes off hook while it is ringing, it should simply answer +the call that had been initiated to it to make it ring. Once the station +has answered, Asterisk will figure out which trunk to connect it to. It +will connect it to the highest priority trunk that is currently ringing. +Trunk priority is determined by the order that the trunks are listed in +the station entry in sla.conf. + +\subsection{Line button on a station is pressed} + +When a line button is pressed on a station, the station should initiate a +call to Asterisk with the extension that indicates which line button was +pressed. In the examples given in this document, for a station named +"station1" and a trunk named "line1", the extension would be "station1\_line1". + +If the specified trunk is not in use, then the station will be connected to it and +will hear dialtone. All appearances of this trunk will then show that it +is now in use. + +If the specified trunk is on hold by this station, then this station will be +reconnected to the trunk. The line appearance for this trunk on this station +will now show in use. If this was the only station that had the call on hold, +then all appearances of this trunk will now show that it is in use. Otherwise, +all stations that are not currently connected to this trunk will show it +on hold. + +If the specified trunk is on hold by a different station, then this station +will be connected to the trunk only if the trunk itself and the station(s) that +have it on hold do not have private hold enabled. If connected, the appeareance +of this trunk on this station will then show in use. All stations that are not +currently connected to this trunk will show it on hold. + +\end{document} diff --git a/1.4.23-rc4/doc/smdi.txt b/1.4.23-rc4/doc/smdi.txt new file mode 100644 index 000000000..2181bc401 --- /dev/null +++ b/1.4.23-rc4/doc/smdi.txt @@ -0,0 +1,137 @@ +=============================================================================== +=============================================================================== +=== Asterisk SMDI (Simple Message Desk Interface) integration ================= +=============================================================================== +=============================================================================== + +=============================================================================== +===== 1) Accessing SMDI information in the dialplan. ========================== +=============================================================================== + +There are two dialplan functions that can be used to access the details of +incoming SMDI messages. + +*CLI> core show function SMDI_MSG_RETRIEVE + + -= Info about function 'SMDI_MSG_RETRIEVE' =- + +[Syntax] +SMDI_MSG_RETRIEVE(<smdi port>,<search key>[,timeout[,options]]) + +[Synopsis] +Retrieve an SMDI message. + +[Description] + This function is used to retrieve an incoming SMDI message. It returns +an ID which can be used with the SMDI_MSG() function to access details of +the message. Note that this is a destructive function in the sense that +once an SMDI message is retrieved using this function, it is no longer in +the global SMDI message queue, and can not be accessed by any other Asterisk +channels. The timeout for this function is optional, and the default is +3 seconds. When providing a timeout, it should be in milliseconds. + The default search is done on the forwarding station ID. However, if +you set one of the search key options in the options field, you can change +this behavior. + Options: + t - Instead of searching on the forwarding station, search on the message + desk terminal. + n - Instead of searching on the forwarding station, search on the message + desk number. + + +*CLI> core show function SMDI_MSG + + -= Info about function 'SMDI_MSG' =- + +[Syntax] +SMDI_MSG(<message_id>,<component>) + +[Synopsis] +Retrieve details about an SMDI message. + +[Description] + This function is used to access details of an SMDI message that was +pulled from the incoming SMDI message queue using the SMDI_MSG_RETRIEVE() +function. + Valid message components are: + station - The forwarding station + callerid - The callerID of the calling party that was forwarded + type - The call type. The value here is the exact character + that came in on the SMDI link. Typically, example values + are: D - Direct Calls, A - Forward All Calls, + B - Forward Busy Calls, N - Forward No Answer Calls + + +Here is an example of how to use these functions: + +; Retrieve the SMDI message that is associated with the number that +; was called in Asterisk. +exten => _0XXX,1,Set(SMDI_MSG_ID=${SMDI_MSG_RETRIEVE(/dev/tty0,${EXTEN})}) + +; Ensure that the message was retrieved. +exten => _0XXX,n,GotoIf($["x${SMDI_MSG_ID}" != "x"]?processcall:hangup) +exten => _0XXX,n(hangup),NoOp(No SMDI message retrieved for ${EXTEN}) + +; Grab the details out of the SMDI message. +exten => _0XXX,n(processcall),NoOp(Message found for ${EXTEN}) +exten => _0XXX,n,Set(SMDI_EXTEN=${SMDI_MSG(${SMDI_MSG_ID},station)}) +exten => _0XXX,n,Set(SMDI_CID=${SMDI_MSG(${SMDI_MSG_ID},callerid)}) + +; Map SMDI message types to the right voicemail option. If it is "B", use the +; busy option. Otherwise, use the unavailable option. +exten => _0XXX,n,GotoIf($["${SMDI_MSG(${SMDI_MSG_ID},type)}" == "B"]?usebusy:useunavail) + +exten => _0XXX,n(usebusy),Set(SMDI_VM_TYPE=b) +exten => _0XXX,n,Goto(continue) + +exten => _0XXX,n,(useunavil),Set(SMDI_VM_TYPE=u) + +exten => _0XXX,n(continue),NoOp( Process the rest of the call ... ) + + +=============================================================================== +===== 2) Ensuring complete MWI information over SMDI ========================== +=============================================================================== + +Another change has been made to ensure that MWI state is properly propagated +over the SMDI link. This replaces the use of externnotify=smdi for +voicemail.conf. The issue is that we have to poll mailboxes occasionally for +changes that were made using an IMAP client. So, this ability was added to +res_smdi. To configure this, there is a new section in smdi.conf. It looks +like this: + +[mailboxes] +; This section configures parameters related to MWI handling for the SMDI link. + ; +; This option configures the polling interval used to check to see if the +; mailboxes have any new messages. This option is specified in seconds. +; The default value is 10 seconds. +; +;pollinginterval=10 +; +; Before specifying mailboxes, you must specify an SMDI interface. All mailbox +; definitions that follow will correspond to that SMDI interface. If you +; specify another interface, then all definitions following that will correspond +; to the new interface. +; +; Every other entry in this section of the configuration file is interpreted as +; a mapping between the mailbox ID on the SMDI link, and the local Asterisk +; mailbox name. In many cases, they are the same thing, but they still must be +; listed here so that this module knows which mailboxes it needs to pay +; attention to. +; +; Syntax: +; <SMDI mailbox ID>=<Asterisk Mailbox Name>[@Asterisk Voicemail Context] +; +; If no Asterisk voicemail context is specified, "default" will be assumed. +; +; +;smdiport=/dev/ttyS0 +;2565551234=1234@vmcontext1 +;2565555678=5678@vmcontext2 +;smdiport=/dev/ttyS1 +;2565559999=9999 + +=============================================================================== +=============================================================================== +=============================================================================== diff --git a/1.4.23-rc4/doc/sms.txt b/1.4.23-rc4/doc/sms.txt new file mode 100644 index 000000000..fe0ec8d85 --- /dev/null +++ b/1.4.23-rc4/doc/sms.txt @@ -0,0 +1,147 @@ +* The SMS application +--------------------- +SMS() is an application to handles calls to/from text message capable phones and +message centres using ETSI ES 201 912 protocol 1 FSK messaging over analog calls. + +Basically it allows sending and receiving of text messages over the PSTN. It is +compatible with BT Text service in the UK and works on ISDN and PSTN lines. It is +designed to connect to an ISDN or zap interface directly and uses FSK so would +probably not work over any sort of compressed link (like a VoIP call using GSM codec). + +Typical applications include:- + +1. Connection to a message centre to send text messages - probably initiated via the + manager interface or "outgoing" directory +2. Connection to an POTS line with an SMS capable phone to send messages - probably + initiated via the manager interface or "outgoing" directory +3. Acceptance of calls from the message centre (based on CLI) and storage of + received messages +4. Acceptance of calls from a POTS line with an SMS capable phone and storage of + received messages + +* Arguments to sms(): + +- First argument is queue name +- Second is options: + a: SMS() is to act as the answering side, and so send the initial FSK frame + s: SMS() is to act as a service centre side rather than as terminal equipment + +- If a third argument is specified, then SMS does not handle the call at all, + but takes the third argument as a destination number to send an SMS to +- The forth argument onward is a message to be queued to the number in the + third argument. All this does is create the file in the me-sc directory. + If 's' is set then the number is the source + address and the message placed in the sc-me directory. + +All text messages are stored in /var/spool/asterisk/sms +A log is recorded in /var/log/asterisk/sms + +There are two subdirectories called sc-me.<queuename> holding all +messages from service centre to phone, and me-sc.<queuename> holding all +messages from phone to service centre. + +In each directory are messages in files, one per file, using any filename not +starting with a dot. + +When connected as a service centre, SMS(s) will send all messages waiting in +the sc-me-<queuename> directory, deleting the files as it goes. Any +received in this mode are placed in the me-sc-<queuename> directory. + +When connected as a client, SMS() will send all messages waiting in the +me-sc-<queuename> directory, deleting the files as it goes. Any received in +this mode are placed in the sc-me-<queuename> directory. + +Message files created by SMS() use a time stamp/reference based filename. + +The format of the sms file is lines that have the form of key=value +Keys are : + +oa Originating Address + Telephone number, national number if just digits + Telephone number starting with + then digits for international + Ignored on sending messages to service centre (CLI used) +da Destination Address + Telephone number, national number if just digits + Telephone number starting with + then digits for international +scts Service Centre Time Stamp + In the format YYYY-MM-DD HH:MM:SS +pid Protocol Identifier (decimal octet value) +dcs Data coding scheme (decimal octet value) +mr Message reference (decimal octet value) +ud The message (see escaping below) +srr 0/1 Status Report Request +rp 0/1 Return Path +vp mins validity period + +Omitted fields have default values. + +Note that there is special format for ud, ud# instead of ud= which is followed +by raw hex (2 characters per octet). This is used in output where characters +other than 10,13,32-126,128-255 are included in the data. In this case a comment (line +starting ;) is added showing the printable characters + +When generating files to send to a service centre, only da and ud need be +specified. oa is ignored. + +When generating files to send to a phone, only oa and ud need be specified. da is ignored. + +When receiving a message as a service centre, only the destination address is +sent, so the originating address is set to the callerid. + +EXAMPLES + +The following are examples of use within the UK using BT Text SMS/landline +service. + +This is a context to use with a manager script. + +[smsdial] +; create and send a text message, expects number+message and +; connect to 17094009 +exten => _X.,1,SMS(${CALLERIDNUM},,${EXTEN},${CALLERIDNAME}) +exten => _X.,n,SMS(${CALLERIDNUM}) +exten => _X.,n,Hangup + +The script sends + + action: originate + callerid: message <from> + exten: to + channel: Local/17094009 + context: smsdial + priority: 1 + +You put the message as the name of the caller ID (messy, I know), the +originating number and hence queue name as the number of the caller ID and the +exten as the number to which the sms is to be sent. The context uses SMS to +create the message in the queue and then SMS to communicate with 17094009 to +actually send the message. + +Note that the 9 on the end of 17094009 is the sub address 9 meaning no sub +address (BT specific). If a different digit is used then that is the sub +address for the sending message source address (appended to the outgoing CLI +by BT). + +For incoming calls you can use a context like this :- + +[incoming] +exten => _XXXXXX/_8005875290,1,SMS(${EXTEN:3},a) +exten => _XXXXXX/_8005875290,n,System(/usr/lib/asterisk/smsin ${EXTEN:3}) +exten => _XXXXXX/_80058752[0-8]0,1,SMS(${EXTEN:3}${CALLERIDNUM:8:1},a) +exten => _XXXXXX/_80058752[0-8]0,n,System(/usr/lib/asterisk/smsin ${EXTEN>:3}${CALLERIDNUM:8:1}) +exten => _XXXXXX/_80058752[0-8]0,n,Hangup + + +In this case the called number we get from BT is 6 digits (XXXXXX) and we are +using the last 3 digits as the queue name. + +Priority 1 causes the SMS to be received and processed for the incoming call. +It is from 080058752X0. The two versions handle the queue name as 3 digits (no +sub address) or 4 digits (with sub address). In both cases, after the call a +script (smsin) is run - this is optional, but is useful to actually processed +the received queued SMS. In our case we email them based on the target number. +Priority 3 hangs up. + +If using the CAPI drivers they send the right CLI and so the _800... would be +_0800... + diff --git a/1.4.23-rc4/doc/snmp.txt b/1.4.23-rc4/doc/snmp.txt new file mode 100644 index 000000000..f1667ee15 --- /dev/null +++ b/1.4.23-rc4/doc/snmp.txt @@ -0,0 +1,39 @@ +Asterisk SNMP Support +--------------------- + +Rudimentary support for SNMP access to Asterisk is available. To build +this, one needs to have Net-SNMP development headers and libraries on +the build system, including any libraries Net-SNMP depends on. + +Note that on some (many?) Linux-distributions the dependency list in +the net-snmp-devel list is not complete, and additional RPMs will need +to be installed. This is typically seen as attempts to build res_snmp +as net-snmp-devel is available, but then fails to find certain +libraries. The packages may include the following: + * bzip2-devel + * lm_sensors-devel + * newt-devel + +SNMP support comes in two varieties -- as a sub-agent to a running SNMP +daemon using the AgentX protocol, or as a full standalone agent. If +you wish to run a full standalone agent, Asterisk must run as root in +order to bind to port 161. + +Configuring access when running as a full agent is something that is +left as an exercise to the reader. + +To enable access to the Asterisk SNMP subagent from a master SNMP +daemon, one will need to enable AgentX support, and also make sure that +Asterisk will be able to access the Unix domain socket. One way of +doing this is to add the following to /etc/snmp/snmpd.conf: + + # Enable AgentX support + master agentx + + # Set permissions on AgentX socket and containing + # directory such that process in group 'asterisk' + # will be able to connect + agentXPerms 0660 0550 nobody asterisk + +This assumes that you run Asterisk under group 'asterisk' (and does +not care what user you run as). diff --git a/1.4.23-rc4/doc/speechrec.txt b/1.4.23-rc4/doc/speechrec.txt new file mode 100644 index 000000000..1e5bf6f49 --- /dev/null +++ b/1.4.23-rc4/doc/speechrec.txt @@ -0,0 +1,295 @@ +The Asterisk Speech Recognition API +=================================== + +The generic speech recognition engine is implemented in the res_speech.so module. +This module connects through the API to speech recognition software, that is +not included in the module. + +To use the API, you must load the res_speech.so module before any connectors. +For your convenience, there is a preload line commented out in the modules.conf +sample file. + +* Dialplan Applications: +------------------------ + +The dialplan API is based around a single speech utilities application file, +which exports many applications to be used for speech recognition. These include an +application to prepare for speech recognition, activate a grammar, and play back a +sound file while waiting for the person to speak. Using a combination of these applications +you can easily make a dialplan use speech recognition without worrying about what +speech recognition engine is being used. + +- SpeechCreate(Engine Name): + +This application creates information to be used by all the other applications. +It must be called before doing any speech recognition activities such as activating a +grammar. It takes the engine name to use as the argument, if not specified the default +engine will be used. + +If an error occurs are you are not able to create an object, the variable ERROR will be +set to 1. You can then exit your speech recognition specific context and play back an +error message, or resort to a DTMF based IVR. + +- SpeechLoadGrammar(Grammar Name|Path): + +Loads grammar locally on a channel. Note that the grammar is only available as long as the +channel exists, and you must call SpeechUnloadGrammar before all is done or you may cause a +memory leak. First argument is the grammar name that it will be loaded as and second +argument is the path to the grammar. + +- SpeechUnloadGrammar(Grammar Name): + +Unloads a locally loaded grammar and frees any memory used by it. The only argument is the +name of the grammar to unload. + +- SpeechActivateGrammar(Grammar Name): + +This activates the specified grammar to be recognized by the engine. A grammar tells the +speech recognition engine what to recognize, and how to portray it back to you in the +dialplan. The grammar name is the only argument to this application. + +- SpeechStart(): + +Tell the speech recognition engine that it should start trying to get results from audio +being fed to it. This has no arguments. + +- SpeechBackground(Sound File|Timeout): + +This application plays a sound file and waits for the person to speak. Once they start +speaking playback of the file stops, and silence is heard. Once they stop talking the +processing sound is played to indicate the speech recognition engine is working. Note it is +possible to have more then one result. The first argument is the sound file and the second is the +timeout. Note the timeout will only start once the sound file has stopped playing. + +- SpeechDeactivateGrammar(Grammar Name): + +This deactivates the specified grammar so that it is no longer recognized. The +only argument is the grammar name to deactivate. + +- SpeechProcessingSound(Sound File): + +This changes the processing sound that SpeechBackground plays back when the speech +recognition engine is processing and working to get results. It takes the sound file as the +only argument. + +- SpeechDestroy(): + +This destroys the information used by all the other speech recognition applications. +If you call this application but end up wanting to recognize more speech, you must call +SpeechCreate again before calling any other application. It takes no arguments. + +* Getting Result Information: +----------------------------- + +The speech recognition utilities module exports several dialplan functions that you can use to +examine results. + +- ${SPEECH(status)}: + +Returns 1 if SpeechCreate has been called. This uses the same check that applications do to see if a +speech object is setup. If it returns 0 then you know you can not use other speech applications. + +- ${SPEECH(spoke)}: + +Returns 1 if the speaker spoke something, or 0 if they were silent. + +- ${SPEECH(results)}: + +Returns the number of results that are available. + +- ${SPEECH_SCORE(result number)}: + +Returns the score of a result. + +- ${SPEECH_TEXT(result number)}: + +Returns the recognized text of a result. + +- ${SPEECH_GRAMMAR(result number)}: + +Returns the matched grammar of the result. + +- SPEECH_ENGINE(name)=value + +Sets a speech engine specific attribute. + +* Dialplan Flow: +----------------- + +1. Create a speech recognition object using SpeechCreate() +2. Activate your grammars using SpeechActivateGrammar(Grammar Name) +3. Call SpeechStart() to indicate you are going to do speech recognition immediately +4. Play back your audio and wait for recognition using SpeechBackground(Sound File|Timeout) +5. Check the results and do things based on them +6. Deactivate your grammars using SpeechDeactivateGrammar(Grammar Name) +7. Destroy your speech recognition object using SpeechDestroy() + +* Dialplan Examples: + +This is pretty cheeky in that it does not confirmation of results. As well the way the +grammar is written it returns the person's extension instead of their name so we can +just do a Goto based on the result text. + +- Grammar: company-directory.gram + +#ABNF 1.0; +language en-US; +mode voice; +tag-format <lumenvox/1.0>; +root $company_directory; + +$josh = ((Joshua | Josh) [Colp]):"6066"; +$mark = (Mark [Spencer] | Markster):"4569"; +$kevin = (Kevin [Fleming]):"2567"; + +$company_directory = ($josh | $mark | $kevin) { $ = $$ }; + +- Dialplan logic + + [dial-by-name] + exten => s,1,SpeechCreate() + exten => s,2,SpeechActivateGrammar(company-directory) + exten => s,3,SpeechStart() + exten => s,4,SpeechBackground(who-would-you-like-to-dial) + exten => s,5,SpeechDeactivateGrammar(company-directory) + exten => s,6,Goto(internal-extensions-${SPEECH_TEXT(0)}) + +- Useful Dialplan Tidbits: + +A simple macro that can be used for confirm of a result. Requires some sound files. +ARG1 is equal to the file to play back after "I heard..." is played. + + [macro-speech-confirm] + exten => s,1,SpeechActivateGrammar(yes_no) + exten => s,2,Set(OLDTEXT0=${SPEECH_TEXT(0)}) + exten => s,3,Playback(heard) + exten => s,4,Playback(${ARG1}) + exten => s,5,SpeechStart() + exten => s,6,SpeechBackground(correct) + exten => s,7,Set(CONFIRM=${SPEECH_TEXT(0)}) + exten => s,8,GotoIf($["${SPEECH_TEXT(0)}" = "1"]?9:10) + exten => s,9,Set(CONFIRM=yes) + exten => s,10,Set(CONFIRMED=${OLDTEXT0}) + exten => s,11,SpeechDeactivateGrammar(yes_no) + +* The Asterisk Speech Recognition C API +--------------------------------------- + +The module res_speech.so exports a C based API that any developer can use to speech +recognize enable their application. The API gives greater control, but requires the +developer to do more on their end in comparison to the dialplan speech utilities. + +For all API calls that return an integer value, a non-zero value indicates an error has occurred. + +- Creating a speech structure: + + struct ast_speech *ast_speech_new(char *engine_name, int format) + + struct ast_speech *speech = ast_speech_new(NULL, AST_FORMAT_SLINEAR); + +This will create a new speech structure that will be returned to you. The speech recognition +engine name is optional and if NULL the default one will be used. As well for now format should +always be AST_FORMAT_SLINEAR. + +- Activating a grammar: + + int ast_speech_grammar_activate(struct ast_speech *speech, char *grammar_name) + + res = ast_speech_grammar_activate(speech, "yes_no"); + +This activates the specified grammar on the speech structure passed to it. + +- Start recognizing audio: + + void ast_speech_start(struct ast_speech *speech) + + ast_speech_start(speech); + +This essentially tells the speech recognition engine that you will be feeding audio to it from +then on. It MUST be called every time before you start feeding audio to the speech structure. + +- Send audio to be recognized: + + int ast_speech_write(struct ast_speech *speech, void *data, int len) + + res = ast_speech_write(speech, fr->data, fr->datalen); + +This writes audio to the speech structure that will then be recognized. It must be written +signed linear only at this time. In the future other formats may be supported. + +- Checking for results: + +The way the generic speech recognition API is written is that the speech structure will +undergo state changes to indicate progress of recognition. The states are outlined below: + + AST_SPEECH_STATE_NOT_READY - The speech structure is not ready to accept audio + AST_SPEECH_STATE_READY - You may write audio to the speech structure + AST_SPEECH_STATE_WAIT - No more audio should be written, and results will be available soon. + AST_SPEECH_STATE_DONE - Results are available and the speech structure can only be used again by + calling ast_speech_start + +It is up to you to monitor these states. Current state is available via a variable on the speech +structure. (state) + +- Knowing when to stop playback: + +If you are playing back a sound file to the user and you want to know when to stop play back because the +individual started talking use the following. + + ast_test_flag(speech, AST_SPEECH_QUIET) - This will return a positive value when the person has started talking. + +- Getting results: + + struct ast_speech_result *ast_speech_results_get(struct ast_speech *speech) + + struct ast_speech_result *results = ast_speech_results_get(speech); + +This will return a linked list of result structures. A result structure looks like the following: + + struct ast_speech_result { + char *text; /*!< Recognized text */ + int score; /*!< Result score */ + char *grammar; /*!< Matched grammar */ + struct ast_speech_result *next; /*!< List information */ + }; + +- Freeing a set of results: + + int ast_speech_results_free(struct ast_speech_result *result) + + res = ast_speech_results_free(results); + +This will free all results on a linked list. Results MAY NOT be used as the memory will have been freed. + +- Deactivating a grammar: + + int ast_speech_grammar_deactivate(struct ast_speech *speech, char *grammar_name) + + res = ast_speech_grammar_deactivate(speech, "yes_no"); + +This deactivates the specified grammar on the speech structure. + +- Destroying a speech structure: + + int ast_speech_destroy(struct ast_speech *speech) + + res = ast_speech_destroy(speech); + +This will free all associated memory with the speech structure and destroy it with the speech recognition engine. + +- Loading a grammar on a speech structure: + + int ast_speech_grammar_load(struct ast_speech *speech, char *grammar_name, char *grammar) + + res = ast_speech_grammar_load(speech, "builtin:yes_no", "yes_no"); + +- Unloading a grammar on a speech structure: + +If you load a grammar on a speech structure it is preferred that you unload it as well, +or you may cause a memory leak. Don't say I didn't warn you. + + int ast_speech_grammar_unload(struct ast_speech *speech, char *grammar_name) + + res = ast_speech_grammar_unload(speech, "yes_no"); + +This unloads the specified grammar from the speech structure. diff --git a/1.4.23-rc4/doc/valgrind.txt b/1.4.23-rc4/doc/valgrind.txt new file mode 100644 index 000000000..b4a69e216 --- /dev/null +++ b/1.4.23-rc4/doc/valgrind.txt @@ -0,0 +1,30 @@ +If you're having certain types of crashes, such as those associated with +memory corruption, a bug marshal may ask you to run Asterisk under valgrind. +You should follow these steps, to give the bug marshal the maximum amount +of information about the crash. + +1. Run 'make menuselect' and in the Compiler Options, enable MALLOC_DEBUG + and DONT_OPTIMIZE. A bug marshal may also ask you to enable additional + compiler flags, such as DEBUG_THREADS, depending upon the nature of the + issue. + +2. Rebuild and install Asterisk. + +3. Run Asterisk as follows: + valgrind --log-file-exactly=valgrind.txt asterisk -vvvvcg 2>malloc_debug.txt + + UPDATE: The newest version of valgrind has eliminated the + --log-file-exactly option. If you are running valgrind 3.3.0 or higher, + just use the --log-file option, keeping in mind that Valgrind will append + a trailing suffix onto valgrind.txt. + +4. Reproduce the issue. Following the manifestation of the issue (or when + the process crashes), upload the two files, valgrind.txt and + malloc_debug.txt to the issue tracker. If you are using the --log-file + option, note that valgrind.txt will have a trailing suffix. That's fine, + just upload that file. + +Please note that even if valgrind prevents Asterisk from crashing, the +information logged may STILL be of use to developers, so please upload the +resulting log file whether Asterisk crashes or not. + diff --git a/1.4.23-rc4/doc/video.txt b/1.4.23-rc4/doc/video.txt new file mode 100644 index 000000000..d7bd282f9 --- /dev/null +++ b/1.4.23-rc4/doc/video.txt @@ -0,0 +1,46 @@ +Asterisk and Video telephony +---------------------------- + +Asterisk supports video telephony in the core infrastructure. Internally, it's one audio stream +and one video stream in the same call. Some channel drivers and applications has video support, +but not all. + +Codecs and formats +------------------ +Asterisk supports the following video codecs and file formats. There's no video +transcoding so you have to make sure that both ends support the same video format. + + Codec Format + ----- ---------- + H.263 read/write + H.264 read/write + H.261 - Passthrough only + +Note that the file produced by Asterisk video format drivers is in no generic +video format. Gstreamer has support for producing these files and converting from +various video files to Asterisk video+audio files. + +Note that H.264 is not enabled by default. You need to add that in the channel +configuration file. + +Channel drivers +--------------- +SIP The SIP channel driver (chan_sip.so) has support for video +IAX2 Supports video calls (over trunks too) +Local Forwards video calls as a proxy channel +Agent Forwards video calls as a proxy channel + +Applications +------------ +This is not yet a complete list. These dialplan applications are known to handle video: + +voicemail Video voicemail storage (does not attach video to e-mail) +record Records audio and video files (give audio format as argument) +playback Plays a video while being instructed to play audio +echo Echos audio and video back to the user + +There is a development group working on enhancing video support for Asterisk. +If you want to participate, join the asterisk-video mailing list on http://lists.digium.com + +--- +Updates to this file are more than welcome! diff --git a/1.4.23-rc4/doc/voicemail_odbc_postgresql.txt b/1.4.23-rc4/doc/voicemail_odbc_postgresql.txt new file mode 100644 index 000000000..622501365 --- /dev/null +++ b/1.4.23-rc4/doc/voicemail_odbc_postgresql.txt @@ -0,0 +1,453 @@ +GETTING ODBC STORAGE WITH POSTGRESQL WORKING WITH VOICEMAIL + +1) Install PostgreSQL, PostgreSQL-devel, unixODBC, and unixODBC-devel, and +PostgreSQL-ODBC. Make sure PostgreSQL is running and listening on a TCP socket. + +2) Log into your server as root, and then type: + +[root@localhost ~]# su - postgres + +This will log you into the system as the "postgres" user, so that you can +create a new role and database within the PostgreSQL database system. At the +new prompt, type: + +$ createuser -s -D -R -l -P -e asterisk +Enter password for new role: +Enter it again: + +Obviously you should enter a password when prompted. This creates the +database role (or user). + +Next we need to create the asterisk database. Type: + +$ createdb -O asterisk -e asterisk + +This creates the database and sets the owner of the database to the asterisk +role. + + +Next, make sure that +you are using md5 authentication for the database user. The line in my +/var/lib/pgsql/data/pg_hba.conf looks like: + +# "local" is for Unix domain socket connections only +local asterisk asterisk md5 +local all all ident sameuser +# IPv4 local connections: +host all all 127.0.0.1/32 md5 + +As soon as you're done editing that file, log out as the postgres user. + +3) Make sure you have the PostgreSQL odbc driver setup in /etc/odbcinst.ini. +Mine looks like: + +[PostgreSQL] +Description = ODBC for PostgreSQL +Driver = /usr/lib/libodbcpsql.so +Setup = /usr/lib/libodbcpsqlS.so +FileUsage = 1 + +You can confirm that unixODBC is seeing the driver by typing: + +[jsmith2@localhost tmp]$ odbcinst -q -d +[PostgreSQL] + + +4) Setup a DSN in /etc/odbc.ini, pointing at the PostgreSQL database and +driver. Mine looks like: + +[testing] +Description = ODBC Testing +Driver = PostgreSQL +Trace = No +TraceFile = sql.log +Database = asterisk +Servername = 127.0.0.1 +UserName = asterisk +Password = supersecret +Port = 5432 +ReadOnly = No +RowVersioning = No +ShowSystemTables = No +ShowOidColumn = No +FakeOidIndex = No +ConnSettings = + +You can confirm that unixODBC sees your DSN by typing: + +[jsmith2@localhost tmp]$ odbcinst -q -s +[testing] + + +5) Test your database connectivity through ODBC. If this doesn't work, +something is wrong with your ODBC setup. + +[jsmith2@localhost tmp]$ echo "select 1" | isql -v testing ++---------------------------------------+ +| Connected! | +| | +| sql-statement | +| help [tablename] | +| quit | +| | ++---------------------------------------+ +SQL> +------------+ +| ?column? | ++------------+ +| 1 | ++------------+ +SQLRowCount returns 1 +1 rows fetched + +If your ODBC connectivity to PostgreSQL isn't working, you'll see an error +message instead, like this: + +[jsmith2@localhost tmp]$ echo "select 1" | isql -v testing +[S1000][unixODBC]Could not connect to the server; +Could not connect to remote socket. +[ISQL]ERROR: Could not SQLConnect +bash: echo: write error: Broken pipe + +6) Compile Asterisk with support for ODBC voicemail. Go to your Asterisk +source directory and run `make menuselect`. Under "Voicemail Build Options", +enable "ODBC_STORAGE". +# See doc/README.odbcstorage for more information + +Recompile Asterisk and install the new version. + + +7) Once you've recompiled and re-installed Asterisk, check to make sure +res_odbc.so has been compiled. + +localhost*CLI> show modules like res_odbc.so +Module Description Use Count +res_odbc.so ODBC Resource 0 +1 modules loaded + + +8) Now it's time to get Asterisk configured. First, we need to tell Asterisk +about our ODBC setup. Open /etc/asterisk/res_odbc.conf and add the following: + +[postgres] +enabled => yes +dsn => testing +pre-connect => yes + +9) At the Asterisk CLI, unload and then load the res_odbc.so module. (You +could restart Asterisk as well, but this way makes it easier to tell what's +happening.) Notice how it says it's connected to "postgres", which is our ODBC +connection as defined in res_odbc.conf, which points to the "testing" DSN in +ODBC. + +localhost*CLI> unload res_odbc.so +Jan 2 21:19:36 WARNING[8130]: res_odbc.c:498 odbc_obj_disconnect: res_odbc: disconnected 0 from postgres [testing] +Jan 2 21:19:36 NOTICE[8130]: res_odbc.c:589 unload_module: res_odbc unloaded. +localhost*CLI> load res_odbc.so + Loaded /usr/lib/asterisk/modules/res_odbc.so => (ODBC Resource) + == Parsing '/etc/asterisk/res_odbc.conf': Found +Jan 2 21:19:40 NOTICE[8130]: res_odbc.c:266 load_odbc_config: Adding ENV var: INFORMIXSERVER=my_special_database +Jan 2 21:19:40 NOTICE[8130]: res_odbc.c:266 load_odbc_config: Adding ENV var: INFORMIXDIR=/opt/informix +Jan 2 21:19:40 NOTICE[8130]: res_odbc.c:295 load_odbc_config: registered database handle 'postgres' dsn->[testing] +Jan 2 21:19:40 NOTICE[8130]: res_odbc.c:555 odbc_obj_connect: Connecting postgres +Jan 2 21:19:40 NOTICE[8130]: res_odbc.c:570 odbc_obj_connect: res_odbc: Connected to postgres [testing] +Jan 2 21:19:40 NOTICE[8130]: res_odbc.c:600 load_module: res_odbc loaded. + +You can also check the status of your ODBC connection at any time from the +Asterisk CLI: + +localhost*CLI> odbc show +Name: postgres +DSN: testing +Connected: yes + +10) Now we can setup our voicemail table in PostgreSQL. Log into PostgreSQL and +type (or copy and paste) the following: + +-- +-- First, let's create our large object type, called "lo" +-- +CREATE FUNCTION loin (cstring) RETURNS lo AS 'oidin' LANGUAGE internal IMMUTABLE STRICT; +CREATE FUNCTION loout (lo) RETURNS cstring AS 'oidout' LANGUAGE internal IMMUTABLE STRICT; +CREATE FUNCTION lorecv (internal) RETURNS lo AS 'oidrecv' LANGUAGE internal IMMUTABLE STRICT; +CREATE FUNCTION losend (lo) RETURNS bytea AS 'oidrecv' LANGUAGE internal IMMUTABLE STRICT; + +CREATE TYPE lo ( INPUT = loin, OUTPUT = loout, RECEIVE = lorecv, SEND = losend, INTERNALLENGTH = 4, PASSEDBYVALUE ); +CREATE CAST (lo AS oid) WITHOUT FUNCTION AS IMPLICIT; +CREATE CAST (oid AS lo) WITHOUT FUNCTION AS IMPLICIT; + +-- +-- If we're not already using plpgsql, then let's use it! +-- +CREATE TRUSTED LANGUAGE plpgsql; + +-- +-- Next, let's create a trigger to cleanup the large object table +-- whenever we update or delete a row from the voicemessages table +-- + +CREATE FUNCTION vm_lo_cleanup() RETURNS "trigger" + AS $$ + declare + msgcount INTEGER; + begin + -- raise notice 'Starting lo_cleanup function for large object with oid %',old.recording; + -- If it is an update action but the BLOB (lo) field was not changed, dont do anything + if (TG_OP = 'UPDATE') then + if ((old.recording = new.recording) or (old.recording is NULL)) then + raise notice 'Not cleaning up the large object table, as recording has not changed'; + return new; + end if; + end if; + if (old.recording IS NOT NULL) then + SELECT INTO msgcount COUNT(*) AS COUNT FROM voicemessages WHERE recording = old.recording; + if (msgcount > 0) then + raise notice 'Not deleting record from the large object table, as object is still referenced'; + return new; + else + perform lo_unlink(old.recording); + if found then + raise notice 'Cleaning up the large object table'; + return new; + else + raise exception 'Failed to cleanup the large object table'; + return old; + end if; + end if; + else + raise notice 'No need to cleanup the large object table, no recording on old row'; + return new; + end if; + end$$ + LANGUAGE plpgsql; + +-- +-- Now, let's create our voicemessages table +-- This is what holds the voicemail from Asterisk +-- + +CREATE TABLE voicemessages +( + uniqueid serial PRIMARY KEY, + msgnum int4, + dir varchar(80), + context varchar(80), + macrocontext varchar(80), + callerid varchar(40), + origtime varchar(40), + duration varchar(20), + mailboxuser varchar(80), + mailboxcontext varchar(80), + recording lo, + label varchar(30), + "read" bool DEFAULT false +); + +-- +-- Let's not forget to make the voicemessages table use the trigger +-- + +CREATE TRIGGER vm_cleanup AFTER DELETE OR UPDATE ON voicemessages FOR EACH ROW EXECUTE PROCEDURE vm_lo_cleanup(); + + +11) Just as a sanity check, make sure you check the voicemessages table via the +isql utility. + +[jsmith2@localhost ODBC]$ echo "SELECT id, msgnum, dir, duration FROM voicemessages WHERE msgnum = 1" | isql testing ++---------------------------------------+ +| Connected! | +| | +| sql-statement | +| help [tablename] | +| quit | +| | ++---------------------------------------+ +SQL> +------------+------------+---------------------------------------------------------------------------------+---------------------+ +| id | msgnum | dir | duration | ++------------+------------+---------------------------------------------------------------------------------+---------------------+ ++------------+------------+---------------------------------------------------------------------------------+---------------------+ +SQLRowCount returns 0 + + +12) Now we can finally configure voicemail in Asterisk to use our database. +Open /etc/asterisk/voicemail.conf, and look in the [general] section. I've +changed the format to gsm (as I can't seem to get WAV or wav working), and +specify both the odbc connection and database table to use. + +[general] +; Default formats for writing Voicemail +;format=g723sf|wav49|wav +format=gsm +odbcstorage=postgres +odbctable=voicemessages + +You'll also want to create a new voicemail context called "odbctest" to do some +testing, and create a sample mailbox inside that context. Add the following to +the very bottom of voicemail.conf: + +[odbctest] +101 => 5555,Example Mailbox + + +13) Once you've updated voicemail.conf, let's make the changes take effect: + +localhost*CLI> unload app_voicemail.so + == Unregistered application 'VoiceMail' + == Unregistered application 'VoiceMailMain' + == Unregistered application 'MailboxExists' + == Unregistered application 'VMAuthenticate' +localhost*CLI> load app_voicemail.so + Loaded /usr/lib/asterisk/modules/app_voicemail.so => (Comedian Mail (Voicemail System)) + == Registered application 'VoiceMail' + == Registered application 'VoiceMailMain' + == Registered application 'MailboxExists' + == Registered application 'VMAuthenticate' + == Parsing '/etc/asterisk/voicemail.conf': Found + +You can check to make sure your new mailbox exists by typing: + +localhost*CLI> show voicemail users for odbctest +Context Mbox User Zone NewMsg +odbctest 101 Example Mailbox 0 + + +14) Now, let's add a new context called "odbc" to extensions.conf. We'll use +these extensions to do some testing: + +[odbc] +exten => 100,1,Voicemail(101@odbctest) +exten => 200,1,VoicemailMain(101@odbctest) + + +15) Next, we need to point a phone at the odbc context. In my case, I've got a +SIP phone called "linksys" that is registering to Asterisk, so I'm setting its +context to the [odbc] context we created in the previous step. The relevant +section of my sip.conf file looks like: + +[linksys] +type=friend +secret=verysecret +disallow=all +allow=ulaw +allow=gsm +context=odbc +host=dynamic +qualify=yes + +I can check to see that my linksys phone is registered with Asterisk correctly: + +localhost*CLI> sip show peers like linksys +Name/username Host Dyn Nat ACL Port Status +linksys/linksys 192.168.0.103 D 5060 OK (9 ms) +1 sip peers [1 online , 0 offline] + + +16) At last, we're finally ready to leave a voicemail message and have it +stored in our database! (Who'd have guessed it would be this much trouble?!?) +Pick up the phone, dial extension 100, and leave yourself a voicemail message. +In my case, this is what appeared on the Asterisk CLI: + +localhost*CLI> + -- Executing VoiceMail("SIP/linksys-10228cac", "101@odbctest") in new stack + -- Playing 'vm-intro' (language 'en') + -- Playing 'beep' (language 'en') + -- Recording the message + -- x=0, open writing: /var/spool/asterisk/voicemail/odbctest/101/tmp/dlZunm format: gsm, 0x101f6534 + -- User ended message by pressing # + -- Playing 'auth-thankyou' (language 'en') + == Parsing '/var/spool/asterisk/voicemail/odbctest/101/INBOX/msg0000.txt': Found + +Now, we can check the database and make sure the record actually made it into +PostgreSQL, from within the psql utility. + +[jsmith2@localhost ~]$ psql +Password: +Welcome to psql 8.1.4, the PostgreSQL interactive terminal. + +Type: \copyright for distribution terms + \h for help with SQL commands + \? for help with psql commands + \g or terminate with semicolon to execute query + \q to quit + +asterisk=# SELECT * FROM voicemessages; + id | msgnum | dir | context | macrocontext | callerid | origtime | duration | mailboxuser | mailboxcontext | recording | label | read | sip_id | pabx_id | iax_id +----+--------+--------------------------------------------------+---------+--------------+-----------------------+------------+----------+-------------+----------------+-----------+-------+------+--------+---------+-------- + 26 | 0 | /var/spool/asterisk/voicemail/odbctest/101/INBOX | odbc | | "linksys" <linksys> | 1167794179 | 7 | 101 | odbctest | 16599 | | f | | | +(1 row) + +Did you notice the the recording column is just a number? When a recording +gets stuck in the database, the audio isn't actually stored in the +voicemessages table. It's stored in a system table called the large object +table. We can look in the large object table and verify that the object +actually exists there: + +asterisk=# \lo_list + Large objects + ID | Description +-------+------------- + 16599 | +(1 row) + +In my case, the OID is 16599. Your OID will almost surely be different. Just +make sure the OID number in the recording column in the voicemessages table +corresponds with a record in the large object table. (The trigger we added to +our voicemessages table was designed to make sure this is always the case.) + +We can also pull a copy of the voicemail message back out of the database and +write it to a file, to help us as we debug things: + +asterisk=# \lo_export 16599 /tmp/odcb-16599.gsm +lo_export + +We can even listen to the file from the Linux command line: + +[jsmith2@localhost tmp]$ play /tmp/odcb-16599.gsm + +Input Filename : /tmp/odcb-16599.gsm +Sample Size : 8-bits +Sample Encoding: gsm +Channels : 1 +Sample Rate : 8000 + +Time: 00:06.22 [00:00.00] of 00:00.00 ( 0.0%) Output Buffer: 298.36K + +Done. + + +17) Last but not least, we can pull the voicemail message back out of the +database by dialing extension 200 and entering "5555" at the password prompt. +You should see something like this on the Asterisk CLI: + +localhost*CLI> + -- Executing VoiceMailMain("SIP/linksys-10228cac", "101@odbctest") in new stack + -- Playing 'vm-password' (language 'en') + -- Playing 'vm-youhave' (language 'en') + -- Playing 'digits/1' (language 'en') + -- Playing 'vm-INBOX' (language 'en') + -- Playing 'vm-message' (language 'en') + -- Playing 'vm-onefor' (language 'en') + -- Playing 'vm-INBOX' (language 'en') + -- Playing 'vm-messages' (language 'en') + -- Playing 'vm-opts' (language 'en') + -- Playing 'vm-first' (language 'en') + -- Playing 'vm-message' (language 'en') + == Parsing '/var/spool/asterisk/voicemail/odbctest/101/INBOX/msg0000.txt': Found + -- Playing 'vm-received' (language 'en') + -- Playing 'digits/at' (language 'en') + -- Playing 'digits/10' (language 'en') + -- Playing 'digits/16' (language 'en') + -- Playing 'digits/p-m' (language 'en') + -- Playing '/var/spool/asterisk/voicemail/odbctest/101/INBOX/msg0000' (language 'en') + -- Playing 'vm-advopts' (language 'en') + -- Playing 'vm-repeat' (language 'en') + -- Playing 'vm-delete' (language 'en') + -- Playing 'vm-toforward' (language 'en') + -- Playing 'vm-savemessage' (language 'en') + -- Playing 'vm-helpexit' (language 'en') + -- Playing 'vm-goodbye' (language 'en') + +That's it! + +Jared Smith +2 Jan 2006 +(updated 11 Mar 2007) |