More BSD enhancements
[asterisk/asterisk.git] / README.iax
1 Inter-Asterisk eXchange Protocol
2 ================================
3
4 INTRODUCTION
5 ------------
6
7 This document is intended as an introduction to the Inter-Asterisk 
8 eXchange (or simply IAX) protocol.  It provides both a theoretical 
9 background and practical information on its use.
10
11 WHY IAX
12 -------
13 The first question most people are thinking at this point is "Why do you 
14 need another VoIP protocol?  Why didn't you just use SIP or H.323?"
15
16 Well, the answer is a fairly complicated one, but in a nutshell it's like
17 this...  Asterisk is intended as a very flexible and powerful
18 communications tool.  As such, the primary feature we need from a VoIP
19 protocol is the ability to meet our own goals with Asterisk, and one with
20 enough flexibility that we could use it as a kind of laboratory for
21 inventing and implementing new concepts in the field.  Neither H.323 or
22 SIP fit the roles we needed, so we developed our own protocol, which,
23 while not standards based, provides a number of advantages over both SIP
24 and H.323, some of which are:
25
26         * Interoperability with NAT/PAT/Masquerade firewalls
27              IAX seamlessly interoperates through all sorts of NAT and PAT
28              and other firewalls, including the ability to place and 
29              receive calls, and transfer calls to other stations.
30
31         * High performance, low overhead protocol
32              When running on low-bandwidth connections, or when running 
33              large numbers of calls, optimized bandwidth utilization is 
34              imperitive.  IAX uses only 4 bytes of overhead
35
36         * Internationalization support
37              IAX transmits language information, so that remote PBX 
38              content can be delivered in the native language of the
39              calling party.
40
41         * Remote dialplan polling
42              IAX allows a PBX or IP phone to poll the availability of a 
43              number from a remote server.  This allows PBX dialplans to 
44              be centralized.
45
46         * Flexible authentication
47              IAX supports cleartext, md5, and RSA authentication, 
48              providing flexible security models for outgoing calls and 
49              registration services.
50         
51         * Multimedia protocol
52              IAX supports the transmission of voice, video, images, text, 
53              HTML, DTMF, and URL's.  Voice menus can be presented in both
54              audibly and visually.
55
56         * Call statistic gathering
57              IAX gathers statistics about network performance (including 
58              latency and jitter, as well as providing end-to-end latency
59              measurement.
60
61         * Call parameter communication
62              Caller*ID, requested extension, requested context, etc are
63              all communicated through the call.
64
65         * Single socket design
66              IAX's single socket design allows up to 32768 calls to be 
67              multiplexed.
68         
69 While we value the importance of standards based (i.e. SIP) call handling, 
70 hopefully this will provide a reasonable explanation of why we developed 
71 IAX rather than starting with SIP.
72
73 CONFIG FILE CONVENTIONS
74 -----------------------
75 Lines beginning with '>' represent lines which might appear in an actual 
76 configuration file.  The '>' is used to help separate them from the 
77 descriptive text and should not actually be included in the file itself.
78
79 Lines within []'s by themselves represent section labels within the 
80 configuration file.  like this:
81
82 > [mysection]
83
84 Options are set using the "=" sign, for example
85
86 > myoption = value
87
88 Sometimes an option will have a number of discrete values which it can 
89 take.  In that case, in the documentation, the options will be listed 
90 within square brackets (the "[" and "]" ones) separated by the pipe symbol 
91 ("|").  For example:
92
93 > myoption = [value1|value2|value3]
94
95 means the option "myoption" can be assigned a value of "value1", "value2", 
96 or "value3".
97
98 Objects, or pseudo-objects are instantiated using the "=>" construct.  For 
99 example:
100
101 > myobject => parameter
102
103 creates an object called "myobject" with some parameter whose definition
104 would be specific to that object.  Note that the config file parser
105 considers "=>" and "=" to be equivalent and their use is purely to make
106 configuration files more readable and easier to "humanly parse".
107
108 The comment character in Asterisk configuration files is the semicolon 
109 ";".  The reason it is not "#" is because the "#" symbol can be used as 
110 parts of extensions and it didn't seem like a good idea to have to escape 
111 it.
112
113 IAX CONFIGURATION IN ASTERISK
114 -----------------------------
115
116 Like everything else in Asterisk, IAX's configuration lies in 
117 /etc/asterisk -- specifically /etc/asterisk/iax.conf
118
119 The IAX configuration file is a collection of sections, each of which
120 (with the exception of the "general" section) represents an entity within 
121 the IAX scope.
122
123 ------------
124
125 The first section is typically the "general" section.  In this area, 
126 a number of parameters which affect the entire system are configured.  
127 Specifically, the default codecs, port and address, jitter behavior, TOS 
128 bits, and registrations.
129
130 The first line of the "general" section is always:
131
132 > [general]
133
134 Following the first line are a number of other possibilities:
135
136 > port = <portnum>
137
138 This sets the port that IAX will bind to.  The default IAX port number is 
139 5036.  It is recommended that this value not be altered in general.
140
141 > bindaddr = <ipaddr>
142
143 This allows you to bind IAX to a specific local IP address instead of
144 binding to all addresses.  This could be used to enhance security if, for
145 example, you only wanted IAX to be available to users on your LAN.
146
147 > bandwidth = [low|medium|high]
148
149 The bandwidth selection initializes the codec selection to appropriate
150 values for given bandwidths.  The "high" selection enables all codecs and
151 is recommended only for 10Mbps or higher connections.  The "medium"
152 bandwidth eliminates signed linear, Mu-law and A-law codecs, leaving only
153 the codecs which are 32kbps and smaller (with MP3 as a special case).  It
154 can be used with broadband connections if desired. "low" eliminates ADPCM
155 and MP3 formats, leaving only the G.723.1, GSM, and LPC10.
156
157 > allow = [gsm|lpc10|g723.1|adpcm|ulaw|alaw|mp3|slinear|all]
158 > disallow = [gsm|lpc10|g723.1|adpcm|ulaw|alaw|mp3|slinear|all]
159
160 The "allow" and "disallow" allow you to fine tune the codec selection 
161 beyond the initial bandwidth selection on a codec-by-codec basis.  
162
163 The recommended configuration is to select "low" bandwidth and then 
164 disallow the LPC10 codec just because it doesn't sound very good. 
165
166 > jitterbuffer = [yes|no]
167 > dropcount = <dropamount>
168 > maxjitterbuffer = <max>
169 > maxexcessbuffer = <max>
170
171 These parameters control the operation of the jitter buffer.  The 
172 jitterbuffer should always be enabled unless you expect all your 
173 connections to be over a LAN.  The drop count is the maximum number of 
174 voice packets to allow to drop (out of 100).  Useful values are 3-10.  The 
175 maxjitterbuffer is the maximum amount of jitter buffer to permit to be 
176 used.  The "maxexcessbuffer" is the maximum amount of excess jitter buffer 
177 that is permitted before the jitter buffer is slowly shrunk to eliminate 
178 latency.
179
180 > accountcode = <code>
181 > amaflags = [default|omit|billing|documentation]
182
183 These parameters affect call detail record generation.  The first sets the 
184 account code for records received with IAX.  The account code can be 
185 overridden on a per-user basis for incoming calls (see below).  The 
186 amaflags controls how the record is labeled ("omit" causes no record to be 
187 written.  "billing" and "documentation" label the records as billing or 
188 documentation records respectively, and "default" selects the system 
189 default.
190
191 > tos = [lowdelay|throughput|reliability|mincost|none]
192
193 IAX can optionally set the TOS (Type of Service) bits to specified values 
194 to help improve performance in routing.  The recommended value is 
195 "lowdelay", which many routers (including any Linux routers with 2.4 
196 kernels that have not been altered with ip tables) will give priority to 
197 these packets, improving voice quality.
198
199 > register => <name>[:<secret>]@<host>[:port]
200
201 Any number of registery entries may be instantiated in the general 
202 section.  Registration allows Asterisk to notify a remote Asterisk server 
203 (with a fixed address) what our current address is.  In order for 
204 registration to work, the remote Asterisk server will need to have a 
205 dynamic peer entry with the same name (and secret if provided).  
206
207 The name is a required field, and is the remote peer name that we wish to 
208 identify ourselves as.  A secret may be provided as well.  The secret is 
209 generally a shared password between the local server and the remote 
210 server.  However, if the secret is in square brackets ([]'s) then it is 
211 interpreted as the name of a key to use.  In that case, the local Asterisk 
212 server must have the *private* key (/var/lib/asterisk/keys/<name>.key) and 
213 the remote server will have to have the corresponding public key.
214
215 The "host" is a required field and is the hostname or IP address of the 
216 remote Asterisk server.  The port specification is optional and is by 
217 default 5036 if not specified.
218
219 -------------
220
221 The following sections, after "general" define either users, peers or
222 friends.  A "user" is someone who connects to us.  A "peer" is someone
223 that we connect to.  A "friend" is simply shorthand for creating a "user" 
224 and "peer" with identical parameters (i.e. someone who can contact us and 
225 who we contact). 
226
227 > [identifier]
228
229 The section begins with the identifier in square brackets.  The identifier 
230 should be an alphanumeric string.
231
232 > type = [user|peer|friend]
233
234 This line tells Asterisk how to interpret this entity.  Users are things 
235 that connect to us, while peers are people we connect to, and a friend is 
236 shorthand for creating a user and a peer with identical information
237
238 ----------------
239 User fields:
240
241 > context = <context>
242
243 One or more context lines may be specified in a user, thus giving the user 
244 access to place calls in the given contexts.  Contexts are used by 
245 Asterisk to divide dialing plans into logical units each with the ability 
246 to have numbers interpreted differently, have their own security model, 
247 auxilliary switch handling, and include other contexts.  Most users are 
248 given access to the default context.  Trusted users could be given access 
249 to the local context for example.
250
251 > permit = <ipaddr>/<netmask>
252 > deny = <ipaddr>/<netmask>
253
254 Permit and deny rules may be applied to users, allowing them to connect 
255 from certain IP addresses and not others.  The permit and deny rules are 
256 interpreted in sequence and all are evaluated on a given IP address, with 
257 the final result being the decision.  For example:
258
259 > permit = 0.0.0.0/0.0.0.0
260 > deny = 192.168.0.0/255.255.255.0
261
262 would deny anyone in 192.168.0.0 with a netmask of 24 bits (class C), 
263 whereas:
264
265 > deny = 192.168.0.0/255.255.255.0
266 > permit = 0.0.0.0/0.0.0.0
267
268 would not deny anyone since the final rule would permit anyone, thsu 
269 overriding the denial.  
270
271 If no permit/deny rules are listed, it is assumed that someone may connect 
272 from anywhere.
273
274 > callerid = <callerid>
275
276 You may override the Caller*ID information passed by a user to you (if 
277 they choose to send it) in order that it always be accurate from the 
278 perspective of your server.
279
280 > auth = [md5|plaintext|rsa]
281
282 You may select which authentication methods are permitted to be used by 
283 the user to authenticate to us.  Multiple methods may be specified, 
284 separated by commas.  If md5 or plaintext authentication is selected, a 
285 secret must be provided.  If RSA authentication is specified, then one or 
286 more key names must be specifed with "inkeys"
287
288 If no secret is specified and no authentication method is specified, then 
289 no authentication will be required.
290
291 > secret = <secret>
292
293 The "secret" line specifies the shared secret for md5 and plaintext 
294 authentication methods.  It is never suggested to use plaintext except in 
295 some cases for debugging.
296
297 > inkeys = key1[:key2...]
298
299 The "inkeys" line specifies which keys we can use to authenticate the 
300 remote peer.  If the peer's challenge passes with any of the given keys, 
301 then we accept its authentication.  The key files live in 
302 /var/lib/asterisk/keys/<name>.pub and are *public keys*.  Public keys are 
303 not typically DES3 encrypted and thus do not usually need initialization.
304
305 ---------------
306 Peer configuration
307
308 > allow = [gsm|lpc10|g723.1|adpcm|ulaw|alaw|mp3|slinear|all]
309 > disallow = [gsm|lpc10|g723.1|adpcm|ulaw|alaw|mp3|slinear|all]
310
311 The "allow" and "disallow" may be used to enable or disable specific codec 
312 support on a per-peer basis.  
313
314 > host = [<ipaddr>|dynamic]
315
316 The host line specifies the hostname or IP address of the remote host, or 
317 may be the word "dynamic" signifying that the host will register with us 
318 (see register => in the general section above).
319
320 > defaultip = <ipaddr>
321
322 If the host uses dynamic registration, Asterisk may still be given a 
323 default IP address to use when dynamic registration has not been performed 
324 or has timed out.
325
326