1
Inter-Asterisk eXchange Protocol
2
================================
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.
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?"
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:
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.
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
36
* Internationalization support
37
IAX transmits language information, so that remote PBX
38
content can be delivered in the native language of the
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
46
* Flexible authentication
47
IAX supports cleartext, md5, and RSA authentication,
48
providing flexible security models for outgoing calls and
49
registration services.
52
IAX supports the transmission of voice, video, images, text,
53
HTML, DTMF, and URL's. Voice menus can be presented in both
56
* Call statistic gathering
57
IAX gathers statistics about network performance (including
58
latency and jitter, as well as providing end-to-end latency
61
* Call parameter communication
62
Caller*ID, requested extension, requested context, etc are
63
all communicated through the call.
65
* Single socket design
66
IAX's single socket design allows up to 32768 calls to be
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.
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.
79
Lines within []'s by themselves represent section labels within the
80
configuration file. like this:
84
Options are set using the "=" sign, for example
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
93
> myoption = [value1|value2|value3]
95
means the option "myoption" can be assigned a value of "value1", "value2",
98
Objects, or pseudo-objects are instantiated using the "=>" construct. For
101
> myobject => parameter
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".
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
113
IAX CONFIGURATION IN ASTERISK
114
-----------------------------
116
Like everything else in Asterisk, IAX's configuration lies in
117
/etc/asterisk -- specifically /etc/asterisk/iax.conf
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
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.
130
The first line of the "general" section is always:
134
Following the first line are a number of other possibilities:
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.
141
> bindaddr = <ipaddr>
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.
147
> bandwidth = [low|medium|high]
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.
157
> allow = [gsm|lpc10|g723.1|adpcm|ulaw|alaw|mp3|slinear|all]
158
> disallow = [gsm|lpc10|g723.1|adpcm|ulaw|alaw|mp3|slinear|all]
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.
163
The recommended configuration is to select "low" bandwidth and then
164
disallow the LPC10 codec just because it doesn't sound very good.
166
> jitterbuffer = [yes|no]
167
> dropcount = <dropamount>
168
> maxjitterbuffer = <max>
169
> maxexcessbuffer = <max>
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
180
> accountcode = <code>
181
> amaflags = [default|omit|billing|documentation]
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
191
> tos = [lowdelay|throughput|reliability|mincost|none]
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.
199
> register => <name>[:<secret>]@<host>[:port]
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).
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.
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.
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
229
The section begins with the identifier in square brackets. The identifier
230
should be an alphanumeric string.
232
> type = [user|peer|friend]
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
241
> context = <context>
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.
251
> permit = <ipaddr>/<netmask>
252
> deny = <ipaddr>/<netmask>
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:
259
> permit = 0.0.0.0/0.0.0.0
260
> deny = 192.168.0.0/255.255.255.0
262
would deny anyone in 192.168.0.0 with a netmask of 24 bits (class C),
265
> deny = 192.168.0.0/255.255.255.0
266
> permit = 0.0.0.0/0.0.0.0
268
would not deny anyone since the final rule would permit anyone, thsu
269
overriding the denial.
271
If no permit/deny rules are listed, it is assumed that someone may connect
274
> callerid = <callerid>
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.
280
> auth = [md5|plaintext|rsa]
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"
288
If no secret is specified and no authentication method is specified, then
289
no authentication will be required.
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.
297
> inkeys = key1[:key2...]
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.
308
> allow = [gsm|lpc10|g723.1|adpcm|ulaw|alaw|mp3|slinear|all]
309
> disallow = [gsm|lpc10|g723.1|adpcm|ulaw|alaw|mp3|slinear|all]
311
The "allow" and "disallow" may be used to enable or disable specific codec
312
support on a per-peer basis.
314
> host = [<ipaddr>|dynamic]
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).
320
> defaultip = <ipaddr>
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
added
removed
README.iax
