Move lots of README's
authorMark Spencer <markster@digium.com>
Mon, 12 Jan 2004 03:23:35 +0000 (03:23 +0000)
committerMark Spencer <markster@digium.com>
Mon, 12 Jan 2004 03:23:35 +0000 (03:23 +0000)
git-svn-id: https://origsvn.digium.com/svn/asterisk/trunk@1970 65c4cc65-6c06-0410-ace0-fbb531ad65f3

README
README.cdr [deleted file]
README.festival [deleted file]
README.iax [deleted file]
README.mysql [deleted file]
README.variables [deleted file]

diff --git a/README b/README
index 62a30e2..ab56649 100755 (executable)
--- a/README
+++ b/README
@@ -131,6 +131,8 @@ from the variables specified above.
 
 * MORE INFORMATION
 
 
 * MORE INFORMATION
 
+See the doc directory for more documentation.
+
 Finally, you may wish to visit the web site and join the mailing list if
 you're interested in getting more information.
 
 Finally, you may wish to visit the web site and join the mailing list if
 you're interested in getting more information.
 
diff --git a/README.cdr b/README.cdr
deleted file mode 100755 (executable)
index c2a63ed..0000000
+++ /dev/null
@@ -1,14 +0,0 @@
-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.  You can specify 
-account codes and AMA (Automated Machine Accounting) flags on a per-channel
-(Zaptel et al) or per-user (IAX) basis to help with accounting.  Look
-at the top of cdr/cdr_csv.c to see the format for the records.  
-
-ONE IMPORTANT NOTE: If you are trying to collect records on IAX to IAX calls
-you need to be aware that by default, IAX will attempt to transfer calls
-in this situation (if DTMF is not required).  When the transfer is completed
-the call is dumped from the middle machine and thus the call detail records
-will report a short call time.  If you want detailed records you must
-turn off IAX transfer, but unless your servers are very close together, you
-will definitely get a latency hit from doing so.
diff --git a/README.festival b/README.festival
deleted file mode 100755 (executable)
index 469f4a1..0000000
+++ /dev/null
@@ -1,22 +0,0 @@
-
-app_festival is an application that allows one to send text-to-speech commands
-to a background festival server, and to obtain the resulting waveform which
-gets sent down to the respective channel. app_festival also employs a waveform 
-cache, so invariant text-to-speech strings ("Please press 1 for instructions") 
-do not need to be dynamically generated all the time. 
-
-You need : 
-
-1) festival, patched to produce 8khz waveforms on output. Patch for Festival
-1.4.2 RELEASE are included. The patch adds a new command to festival 
-(asterisk_tts). 
-
-2) My patches to asterisk that provide variable substitution and quoting to 
-the Asterisk Extension Logic. This is not really a requirement, but without
-this, app_festival is mostly useless (you could very well use prerecorded
-voices for static information). 
-
-3) Before running asterisk, you have to run festival-server with a command 
-like : 
-
-/usr/local/festival/bin/festival --server > /dev/null 2>&1 &
diff --git a/README.iax b/README.iax
deleted file mode 100755 (executable)
index 58372e0..0000000
+++ /dev/null
@@ -1,326 +0,0 @@
-Inter-Asterisk eXchange Protocol
-================================
-
-INTRODUCTION
-------------
-
-This document is intended as an introduction to the Inter-Asterisk 
-eXchange (or simply IAX) protocol.  It provides both a theoretical 
-background and practical information on its use.
-
-WHY IAX
--------
-The first question most people are thinking at this point is "Why do you 
-need another VoIP protocol?  Why didn't you just use SIP or H.323?"
-
-Well, the answer is a fairly complicated one, but in a nutshell it's like
-this...  Asterisk is intended as a very flexible and powerful
-communications tool.  As such, the primary feature we need from a VoIP
-protocol is the ability to meet our own goals with Asterisk, and one with
-enough flexibility that we could use it as a kind of laboratory for
-inventing and implementing new concepts in the field.  Neither H.323 or
-SIP fit the roles we needed, so we developed our own protocol, which,
-while not standards based, provides a number of advantages over both SIP
-and H.323, some of which are:
-
-       * Interoperability with NAT/PAT/Masquerade firewalls
-            IAX seamlessly interoperates through all sorts of NAT and PAT
-             and other firewalls, including the ability to place and 
-             receive calls, and transfer calls to other stations.
-
-       * High performance, low overhead protocol
-            When running on low-bandwidth connections, or when running 
-            large numbers of calls, optimized bandwidth utilization is 
-            imperitive.  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:
-
-> port = <portnum>
-
-This sets the port that IAX will bind to.  The default IAX port number is 
-5036.  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.  The drop count is the maximum number of 
-voice packets to allow to drop (out of 100).  Useful values are 3-10.  The 
-maxjitterbuffer is the maximum amount of jitter buffer to permit to be 
-used.  The "maxexcessbuffer" is the maximum amount of excess jitter buffer 
-that is permitted before the jitter buffer is slowly shrunk to eliminate 
-latency.
-
-> 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 registery 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 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 5036 if not specified.
-
--------------
-
-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 people 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, 
-auxilliary 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/255.255.255.0
-> permit = 0.0.0.0/0.0.0.0
-
-would not deny anyone since the final rule would permit anyone, thsu 
-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 specifed 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.
-
-
diff --git a/README.mysql b/README.mysql
deleted file mode 100755 (executable)
index 27adaa9..0000000
+++ /dev/null
@@ -1,15 +0,0 @@
-MYSQL LICENSING UPDATE
-======================
-We were recently contacted by MySQL and informed that the MySQL client 
-libraries are now under GPL license and not LGPL license as before.  
-
-Since Asterisk does allow exceptions to GPL, we are removing MySQL support 
-from standard Asterisk.  We will, where appropriate, make it available via 
-a separate package which will only be usable when Asterisk is used completely
-within GPL (i.e. not in conjunction with G.729, OpenH.323, etc).  We 
-apologize for the confusion.
-
-You may find this in the new "asterisk-addons" package.
-
-Mark Spencer
-Digium
diff --git a/README.variables b/README.variables
deleted file mode 100755 (executable)
index 69a5769..0000000
+++ /dev/null
@@ -1,150 +0,0 @@
-GENERAL ENCHANCEMENTS TO EXTENSION LOGIC : 
-
-QUOTING: 
-
-exten => s,5,BackGround,blabla
-
-The parameter (blabla) can be quoted ("blabla"). In this case, a 
-comma does not terminate the field. 
-
-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 preceeding \. Special characters that must
-be quoted to be used, are [ ] $ " \. (to write \ itself, use \\). 
-
-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,SetVar,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,SetVar,koko=${blabla}${lala}
-
-There are also the following special variables: 
-
-${CALLERID}    Caller ID
-${CALLERIDNAME}        Caller ID Name only
-${CALLERIDNUM} Caller ID Number only
-${EXTEN}       Current extension
-${CONTEXT}      Current context
-${PRIORITY}    Current priority
-${CHANNEL}     Current channel name
-${ENV(VAR)}    Environmental variable VAR
-${LEN(VAR)}    String length of VAR (integer)
-${EPOCH}       Current unix style epoch
-${DATETIME}    Current date time in the format: YYYY-MM-DD_HH:MM:SS
-${TIMESTAMP}   Current date time in the format: YYYYMMDD-HHMMSS
-${UNIQUEID}    Current call unique identifier
-${DNID}         Dialed Number Identifier
-${RDNIS}        Redirected Dial Number ID Service
-${HANGUPCAUSE} Hangup cause on last PRI hangup
-${ACCOUNTCODE}  Account code (if specified)
-
-${SIPDOMAIN}    SIP destination domain of an inbound call (if appropriate)
-
-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, SetVar takes as the first argument 
-(before the =) a variable name, so: 
-
-;exten => 1,2,SetVar,koko=lala
-;exten => 1,3,SetVar,${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". 
-
-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. The arguments and operands of the expression MUST BE separated 
-with spaces (take care NOT to leave ANY spaces between opening and closing 
-square brackets and the first and last arguments). 
-
-For example, after the sequence: 
-
-exten => 1,1,SetVar,"lala=$[1 + 2]";
-exten => 1,2,SetVar,"koko=$[2 * ${lala}]";
-
-the value of variable koko is "6".
-
-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 : 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.
-
-Parentheses are used for grouping in the usual manner.
-
-The parser must be parsed with bison (bison is REQUIRED - yacc cannot 
-produce pure parsers, which are reentrant) 
-
-CONDITIONALS
-
-There is one conditional operator - 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,SetVar,"vara=1"
-exten => s,3,SetVar,"varb=$[${vara} + 2]"
-exten => s,4,SetVar,"varc=$[${varb} * 2]"
-exten => s,5,GotoIf,"$[${varc} = 6]?99|1:s|6";
-