diff --git a/README b/README index 62a30e27d..ab566493b 100755 --- a/README +++ b/README @@ -131,6 +131,8 @@ from the variables specified above. * 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. diff --git a/README.cdr b/README.cdr deleted file mode 100755 index c2a63ed81..000000000 --- a/README.cdr +++ /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 index 469f4a168..000000000 --- a/README.festival +++ /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 index 58372e0d2..000000000 --- a/README.iax +++ /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 = - -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 = - -This allows you to bind IAX to a specific local IP address instead of -binding to all addresses. This could be used to enhance security if, for -example, you only wanted IAX to be available to users on your LAN. - -> bandwidth = [low|medium|high] - -The bandwidth selection initializes the codec selection to appropriate -values for given bandwidths. The "high" selection enables all codecs and -is recommended only for 10Mbps or higher connections. The "medium" -bandwidth eliminates signed linear, Mu-law and A-law codecs, leaving only -the codecs which are 32kbps and smaller (with MP3 as a special case). It -can be used with broadband connections if desired. "low" eliminates ADPCM -and MP3 formats, leaving only the G.723.1, GSM, and LPC10. - -> allow = [gsm|lpc10|g723.1|adpcm|ulaw|alaw|mp3|slinear|all] -> disallow = [gsm|lpc10|g723.1|adpcm|ulaw|alaw|mp3|slinear|all] - -The "allow" and "disallow" allow you to fine tune the codec selection -beyond the initial bandwidth selection on a codec-by-codec basis. - -The recommended configuration is to select "low" bandwidth and then -disallow the LPC10 codec just because it doesn't sound very good. - -> jitterbuffer = [yes|no] -> dropcount = -> maxjitterbuffer = -> maxexcessbuffer = - -These parameters control the operation of the jitter buffer. The -jitterbuffer should always be enabled unless you expect all your -connections to be over a LAN. 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 = -> amaflags = [default|omit|billing|documentation] - -These parameters affect call detail record generation. The first sets the -account code for records received with IAX. The account code can be -overridden on a per-user basis for incoming calls (see below). The -amaflags controls how the record is labeled ("omit" causes no record to be -written. "billing" and "documentation" label the records as billing or -documentation records respectively, and "default" selects the system -default. - -> tos = [lowdelay|throughput|reliability|mincost|none] - -IAX can optionally set the TOS (Type of Service) bits to specified values -to help improve performance in routing. The recommended value is -"lowdelay", which many routers (including any Linux routers with 2.4 -kernels that have not been altered with ip tables) will give priority to -these packets, improving voice quality. - -> register => [:]@[:port] - -Any number of 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/.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 = - -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 = / -> deny = / - -Permit and deny rules may be applied to users, allowing them to connect -from certain IP addresses and not others. The permit and deny rules are -interpreted in sequence and all are evaluated on a given IP address, with -the final result being the decision. For example: - -> permit = 0.0.0.0/0.0.0.0 -> deny = 192.168.0.0/255.255.255.0 - -would deny anyone in 192.168.0.0 with a netmask of 24 bits (class C), -whereas: - -> deny = 192.168.0.0/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 = - -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 = - -The "secret" line specifies the shared secret for md5 and plaintext -authentication methods. It is never suggested to use plaintext except in -some cases for debugging. - -> inkeys = key1[:key2...] - -The "inkeys" line specifies which keys we can use to authenticate the -remote peer. If the peer's challenge passes with any of the given keys, -then we accept its authentication. The key files live in -/var/lib/asterisk/keys/.pub and are *public keys*. Public keys are -not typically DES3 encrypted and thus do not usually need initialization. - ---------------- -Peer configuration - -> allow = [gsm|lpc10|g723.1|adpcm|ulaw|alaw|mp3|slinear|all] -> disallow = [gsm|lpc10|g723.1|adpcm|ulaw|alaw|mp3|slinear|all] - -The "allow" and "disallow" may be used to enable or disable specific codec -support on a per-peer basis. - -> host = [|dynamic] - -The host line specifies the hostname or IP address of the remote host, or -may be the word "dynamic" signifying that the host will register with us -(see register => in the general section above). - -> defaultip = - -If the host uses dynamic registration, Asterisk may still be given a -default IP address to use when dynamic registration has not been performed -or has timed out. - - diff --git a/README.mysql b/README.mysql deleted file mode 100755 index 27adaa956..000000000 --- a/README.mysql +++ /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 index 69a5769e5..000000000 --- a/README.variables +++ /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"; -