From 8204f581ab1ba33567047e7d196fea95510944a2 Mon Sep 17 00:00:00 2001 From: Olle Johansson Date: Wed, 1 Feb 2006 17:16:08 +0000 Subject: - Adding a doc/00README.1st with an INDEX over README files - Moving files from / to /doc or /configs - Renaming some documentation files Thank you for the initiative, manxpower! git-svn-id: https://origsvn.digium.com/svn/asterisk/trunk@9046 65c4cc65-6c06-0410-ace0-fbb531ad65f3 --- doc/00README.1st | 68 +++++++++++ doc/README.extensions | 58 +++++++++ doc/README.hardware | 70 +++++++++++ doc/README.localchannel | 49 ++++++++ doc/README.manager | 298 +++++++++++++++++++++++++++++++++++++++++++++ doc/README.musiconhold-fpm | 8 ++ doc/README.queuelog | 78 ++++++++++++ doc/README.security | 67 ++++++++++ doc/extensions.txt | 58 --------- doc/localchannel.txt | 49 -------- doc/manager.txt | 298 --------------------------------------------- doc/queuelog.txt | 78 ------------ 12 files changed, 696 insertions(+), 483 deletions(-) create mode 100644 doc/00README.1st create mode 100644 doc/README.extensions create mode 100644 doc/README.hardware create mode 100644 doc/README.localchannel create mode 100644 doc/README.manager create mode 100644 doc/README.musiconhold-fpm create mode 100644 doc/README.queuelog create mode 100644 doc/README.security delete mode 100644 doc/extensions.txt delete mode 100644 doc/localchannel.txt delete mode 100644 doc/manager.txt delete mode 100644 doc/queuelog.txt (limited to 'doc') diff --git a/doc/00README.1st b/doc/00README.1st new file mode 100644 index 000000000..a530922e6 --- /dev/null +++ b/doc/00README.1st @@ -0,0 +1,68 @@ +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 +---------- +README.security IMPORTANT INFORMATION ABOUT ASTERISK SECURITY +README.hardware Hardware supported by Asterisk + +Configuration +------------- +README.configuration Features in the configuration parser +README.extensions Basics about the dialplan +README.extconfig How to use databases for configuration of Asterisk (ARA) +README.realtime The Asterisk Realtime Architecture - database support +README.tds Information about the FreeTDS support +README.ael Information about the Asterisk Extension Language + +Misc +---- +PEERING The General Peering Agreement for Dundi +README.app_sms How to configure the SMS application +README.asterisk.conf Documentation of various options in asterisk.conf +README.callingpres Settings for Caller ID presentation +README.cdr Call Data Record information +README.cliprompt How to change the Asterisk CLI prompt +README.dundi Dundi - a discovery protocol +README.enum Enum support in Asterisk +README.ices Integrating ICEcast streaming in Asterisk +README.jitterbuffer About the IAX2 jitterbuffer implementation +README.math About the math() application +README.mp3 About MP3 support in Asterisk +README.musiconhold-fpm Free Music On Hold music +README.mysql About MYSQL support in Asterisk +README.odbcstorage Voicemail storage of messages in UnixODBC +README.privacy Privacy enhancements in Asterisk +README.queuelog Agent and queue logging +README.variables Channel variables +cdr.txt About CDR storage in various databases (needs update) + +Channel drivers +--------------- +README.misdn +README.h323 How to compile and configure the H.323 channel +README.iax About the IAX2 protocol support in Asterisk +README.localchannel The local channel is a "gosub" in the dialplan + +Portability +----------- +README.cygwin Compiling Asterisk on CygWin platforms (Windows) + +For developers +-------------- +See http://www.asterisk.org/developers for more information + +README.manager About the AMI - Asterisk Manager Interface + for third party call control and PBX management +README.backtrace How to produce a backtrace when Asterisk crashes +CODING-GUIDELINES Guidelines for developers +README.channels What is a channel? +README.externalivr Documentation of the protocol used in externalivr() +README.linkedlists How to develop linked lists in Asterisk (old) +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 diff --git a/doc/README.extensions b/doc/README.extensions new file mode 100644 index 000000000..bab08d319 --- /dev/null +++ b/doc/README.extensions @@ -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 continunes at the next priority +(except for some modules which use explicitly GOTO's). + +When each action completes, it generally moves to the next priority (except for +some modules which use explicitly GOTO's. + +Extensions frequently have data they pass to the executing application +(most frequently a string). You can see the available dialplan applications +by entering the "show applications" command in the CLI. + +In this version of Asterisk, dialplan functions are added. These can +be used as arguments to any application. For a list of the installed +functions in your Asterisk, use the "show functions" command. + +* Example dial plan + +The example dial plan, in the configs/extensions.conf.sample file +is installed as extensions.conf if you run "make samples" after +installation of Asterisk. This file includes many more instructions +and examples than this file, so it's worthwile to read it. + +* Special extensions + +There are some extensions with important meanings: + + s: What to do when an extension context is entered (unless + overridden by the low level channel interface) + This is used in macros, and some special cases. + "s" is not a generic catch-all wildcard extension. + i: What to do if an invalid extension is entered + h: The hangup extension, executed at hangup + t: What to do if nothing is entered in the requisite amount + of time. + T: This is the extension that is executed when the 'absolute' + timeout is reached. See "show function TIMEOUT" for more + information on setting timeouts. + +And finally, the extension context "default" is used when either a) an +extension context is deleted while an extension is in use, or b) a specific +starting extension handler has not been defined (unless overridden by the +low level channel interface). diff --git a/doc/README.hardware b/doc/README.hardware new file mode 100644 index 000000000..86b28bef7 --- /dev/null +++ b/doc/README.hardware @@ -0,0 +1,70 @@ +A PBX is only really useful if you can get calls into it. Of course, you +can use Asterisk with VoIP calls (SIP, H.323, IAX), but you can also talk +to the real PSTN through various cards. + +Supported Hardware is divided into two general groups: Zaptel devices and +non-zaptel devices. The Zaptel compatible hardware supports pseudo-TDM +conferencing and all call features through chan_zap, whereas non-zaptel +compatible hardware may have different features. + +Zaptel compatible hardware +========================== + +-- Digium (Primary author of Asterisk) + http://www.digium.com, http://store.yahoo.com/asteriskpbx + + * Wildcard X100P - Single FXO interface connects to Loopstart phone + line + + * Wildcard T400P (obsolete) - Quad T1 interface connects to four T1/PRI + interfaces. Supports RBS and PRI voice and PPP, FR, and HDLC data. + + * Wildcard E400P (obsolete)- Quad E1 interface connects to four E1/PRI + (or PRA) interfaces. Supports PRA/PRI, EuroISDN voice and data. + + * Wildcard T100P - Single T1 interface connects to a single T1/PRI + interface. Supports RBS and PRI voice and PPP, FR, and HDLC data. + + * Wildcard E100P - Single E1 interface connects to a single E1/PRI (or PRA) + interface. Supports PRA/PRI, EuroISDN voice and PPP, FR, HDLC data. + + * Wildcard S100U - Single FXS interface connects to a standard analog + telephone. + + * Wildcard TDM400P - Quad Modular FXS interface connects to standard + analog telephones. + + * Wildcard TE410P - Quad T1/E1 switchable interface. Supports PRI and + RBS signalling, as well as PPP, FR, and HDLC data modes. + +Non-zaptel compatible hardware +============================== + +-- QuickNet, Inc. + http://www.quicknet.net + + * Internet PhoneJack - Single FXS interface. Supports Linux telephony + interface. DSP compression built-in. + + * Internet LineJack - Single FXS or FXO interface. Supports Linux + telephony interface. + + +Miscellaneous other interfaces +============================== + +-- ISDN4Linux + http://www.isdn4linux.de/ + + * Any ISDN terminal adapter supported by isdn4linux should provide + connectivity. + +-- ALSA + http://www.alsa-project.org + + * Any ALSA compatible full-duplex sound card + +-- OSS + http://www.opensound.com + + * Any OSS compatible full-duplex sound card diff --git a/doc/README.localchannel b/doc/README.localchannel new file mode 100644 index 000000000..f96ea15ec --- /dev/null +++ b/doc/README.localchannel @@ -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, the variables and dial plan will revert back to that of the original call, and the Local channel will become a zombie and be removed from the active channels list. This is desirable in some circumstances, but can result in unexpected dialplan behavior if you are doing fancy things with variables in your call handling. + +* Purpose: + +The Local channel construct can be used to establish dialing into any part of the dialplan. + +Imagine you have a TE410P in your box. You want to do something for which you must use a Dial statement (for instance when dropping files in /var/spool/outgoing) but you do want to be able to use your dialplans least-cost-routes or other intelligent stuff. What you could do before we had chan_local was create a cross-link between two ports of the TE410P and then Dial out one port and in the other. This way you could control where the call was going. + +Of course, this was a nasty hack, and to make it more sensible, chan_local was built. + +The "Local" channel driver allows you to convert an arbitrary extension into a channel. It is used in a variety of places, including agents, etc. + +This also allows us to hop to contexts like a GoSub routine; See examples below. + +Examples: +--------- + +[inbound] ; here falls all incoming calls +exten => s,1,Answer +exten => s,2,Dial(local/200@internal,30,r) +exten => s,3,Playback(sorrynoanswer) +exten => s,4,Hangup + +[internal] ; here where our phones falls for default +exten => 200,1,Dial(sip/blah) +exten => 200,102,VoiceMail(${EXTEN}@default) + +exten => 201,1,Dial(zap/1) +exten => 201,102,VoiceMail(${EXTEN}@default) + +exten => _0.,1,Dial(Zap/g1/${EXTEN:1}) ; outgoing calls with 0+number + + +Caveats: +If you use chan_local from a call-file and you want to pass channel variables into your context, make sure you append the '/n', because otherwise chan_local will 'optimize' itself out of the call-path, and the variables will get lost. i.e. + + Local/00531234567@pbx becomes Local/00531234567@pbx/n + +---------- +2004-01-17 diff --git a/doc/README.manager b/doc/README.manager new file mode 100644 index 000000000..065d70a21 --- /dev/null +++ b/doc/README.manager @@ -0,0 +1,298 @@ +The Asterisk Manager TCP/IP API - AMI +===================================== + +The manager is a client/server model over TCP. With the manager interface, +you'll be able to control the PBX, originate calls, check mailbox status, +monitor channels and queues as well as execute Asterisk commands. + +AMI is the standard management interface into your Asterisk server. +You configure AMI in manager.conf. By default, AMI is available on +TCP port 5038 if you enable it in manager.conf. + +AMI receive commands, called "actions". These generate a "response" +from Asterisk. Asterisk will also send "Events" containing various +information messages about changes within Asterisk. Some actions +generate an initial response and data in the form list of events. +This format is created to make sure that extensive reports do not +block the manager interface fully. + +Management users are configured in the configuration file manager.conf and are +given permissions for read and write, where write represents their ability +to perform this class of "action", and read represents their ability to +receive this class of "event". + +The Asterisk manager interface in version 1.0.x of Asterisk is +not very well standardized. Work is under way to change this +to Asterisk 1.2. If you develop AMI applications, treat the headers +in Actions, Events and Responses as local to that particular +message. There is no cross-message standardization of headers. + +If you develop applications, please try to reuse existing manager +headers and their interpretation. If you are unsure, discuss on +the asterisk-dev mailing list. + + +Command Syntax +-------------- +Management communication consists of tags of the form "header: value", +terminated with an empty newline (\r\n) in the style of SMTP, HTTP, and +other headers. + + +The first tag MUST be one of the following: + + * Action: An action requested by the CLIENT to the Asterisk SERVER. Only one "Action" may be outstanding at any time. + * Response: A response to an action from the Asterisk SERVER to the CLIENT. + * Event: An event reported by the Asterisk SERVER to the CLIENT + + +Manager commands +---------------- +Output from the CLI command 'show manager' command: + + * Ping: Ping + * Logoff: Logoff Manager + * Hangup: Hangup Channel + * Status: Status + * Redirect: Redirect + * Originate: Originate Call + * MailboxStatus: Check Mailbox + * Command: Execute Command + * ExtensionState: Check Extension Status + * AbsoluteTimeout: Set Absolute Timeout + * MailboxCount: Check Mailbox Message Count + * Monitor: Monitor a channel + * StopMonitor: Stop monitoring a channel + * ChangeMonitor: Change monitoring filename of a channel + * IAXpeers: List IAX Peers (Defaults to IAX2) + * SIPpeers: List SIP peers + * SIPshowpeer: Show data about one SIP peer + * Queues: Queues + * QueueStatus: Queue Status + +This list depends on the version of Asterisk you are using, as +well as which modules that are loaded. + +Command Summary +-------------- + +Command: Command +Parameters: Command + +Command: ExtensionState +Parameters: Exten, Context, ActionID + +Command: Hangup +Parameters: Channel + +Command: Logoff +Parameters: None + +Command: MailboxCount +Parameters: Mailbox, ActionID + +Command: MailboxStatus +Parameters: Mailbox, ActionID + +Command: Originate +Parameters: Channel, Exten, Context, Priority, Timeout, + CallerID, Variable, Account, Application, Data, Async + +Command: Ping +Parameters: None + +Command: Redirect +Parameters: Channel, ExtraChannel, Exten, Context, Priority + +Command: Timeout +Parameters: Channel, Timeout + +You can always get more information about a manager command +with the "show manager command " CLI command in Asterisk. + +Examples +-------- +Login - Log a user into the manager interface. + + Action: Login + Username: testuser + Secret: testsecret + +Originate - Originate a call from a channel to an extension. + + Action: Originate + Channel: sip/12345 + Exten: 1234 + Context: default + +Originate - Originate a call from a channel to an extension without waiting +for call to complete. + + Action: Originate + Channel: sip/12345 + Exten: 1234 + Context: default + Async: yes + + +Redirect with ExtraChannel: + Attempted goal: + Have a 'robot' program Redirect both ends of an already-connected call + to a meetme room using the ExtraChannel feature through the management interface. + + Action: Redirect + Channel: Zap/1-1 + ExtraChannel: SIP/3064-7e00 (varies) + Exten: 680 + Priority: 1 + +Where 680 is an extension that sends you to a MeetMe room. + +There are a number of GUI tools that use the manager interface, please search +the mailing list archives and the documentation page on the +http://www.asterisk.org web site for more information. + + +Some standard AMI headers: +-------------------------- + + Account: -- Account Code (Status) + AccountCode: -- Account Code (cdr_manager) + ACL: -- Does ACL exist for object ? + Action: -- request or notification of a particular action + Address-IP: -- IPaddress + Address-Port: -- IP port number + Agent: -- Agent name + AMAflags: -- AMA flag (cdr_manager, sippeers) + AnswerTime: -- Time of answer (cdr_manager) + Append: -- CDR userfield Append flag + Application: -- Application to use + Async: -- Whether or not to use fast setup + AuthType: -- Authentication type (for login or challenge) + "md5" + BillableSeconds: -- Billable seconds for call (cdr_manager) + CallerID: -- Caller id (name and number in Originate & cdr_manager) + CallerID: -- CallerID number + Number or "" or "unknown" + (should change to "" in app_queue) + CallerID1: -- Channel 1 CallerID (Link event) + CallerID2: -- Channel 2 CallerID (Link event) + CallerIDName: -- CallerID name + Name or "" or "unknown" + (should change to "" in app_queue) + Callgroup: -- Call group for peer/user + CallsTaken: -- Queue status variable + Cause: -- Event change cause - "Expired" + Cause: -- Hangupcause (channel.c) + CID-CallingPres: -- Caller ID calling presentation + Channel: -- Channel specifier + Channel: -- Dialstring in Originate + Channel: -- Channel in Registry events (SIP, IAX2) + Channel: -- Technology (SIP/IAX2 etc) in Registry events + ChannelType: -- Tech: SIP, IAX2, ZAP, MGCP etc + Channel1: -- Link channel 1 + Channel2: -- Link channel 2 + ChanObjectType: -- "peer", "user" + Codecs: -- Codec list + CodecOrder: -- Codec order, separated with comma "," + Command: -- Cli command to run + Context: -- Context + Count: -- Number of callers in queue + Data: -- Application data + Default-addr-IP: -- IP address to use before registration + Default-Username: -- Username part of URI to use before registration + Destination: -- Destination for call (Dialstring ) (dial, cdr_manager) + DestinationContext: -- Destination context (cdr_manager) + DestinationChannel: -- Destination channel (cdr_manager) + DestUniqueID: -- UniqueID of destination (dial event) + Disposition: -- Call disposition (CDR manager) + Domain: -- DNS domain + Duration: -- Duration of call (cdr_manager) + Dynamic: -- Device registration supported? + Endtime: -- End time stamp of call (cdr_manager) + EventList: -- Flag being "Start", "End", "Cancelled" or "ListObject" + Events: -- Eventmask filter ("on", "off", "system", "call", "log") + Exten: -- Extension (Redirect command) + Extension: -- Extension (Status) + Family: -- ASTdb key family + File: -- Filename (monitor) + Format: -- Format of sound file (monitor) + From: