doc/chaniax.txt

   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              imperative.  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 > bindport = <portnum>
 137
 138 This sets the port that IAX will bind to.  The default IAX version 1
 139 port number is 5036.  For IAX version 2, that is now the default in
 140 Asterisk, the default port is 4569.
 141 It is recommended that this value not be altered in general.
 142
 143 > bindaddr = <ipaddr>
 144
 145 This allows you to bind IAX to a specific local IP address instead of
 146 binding to all addresses.  This could be used to enhance security if, for
 147 example, you only wanted IAX to be available to users on your LAN.
 148
 149 > bandwidth = [low|medium|high]
 150
 151 The bandwidth selection initializes the codec selection to appropriate
 152 values for given bandwidths.  The "high" selection enables all codecs and
 153 is recommended only for 10Mbps or higher connections.  The "medium"
 154 bandwidth eliminates signed linear, Mu-law and A-law codecs, leaving only
 155 the codecs which are 32kbps and smaller (with MP3 as a special case).  It
 156 can be used with broadband connections if desired. "low" eliminates ADPCM
 157 and MP3 formats, leaving only the G.723.1, GSM, and LPC10.
 158
 159 > allow = [gsm|lpc10|g723.1|adpcm|ulaw|alaw|mp3|slinear|all]
 160 > disallow = [gsm|lpc10|g723.1|adpcm|ulaw|alaw|mp3|slinear|all]
 161
 162 The "allow" and "disallow" allow you to fine tune the codec selection
 163 beyond the initial bandwidth selection on a codec-by-codec basis.
 164
 165 The recommended configuration is to select "low" bandwidth and then
 166 disallow the LPC10 codec just because it doesn't sound very good.
 167
 168 > jitterbuffer = [yes|no]
 169 > dropcount = <dropamount>
 170 > maxjitterbuffer = <max>
 171 > maxexcessbuffer = <max>
 172
 173 These parameters control the operation of the jitter buffer.  The
 174 jitterbuffer should always be enabled unless you expect all your
 175 connections to be over a LAN.
 176 * drop count is the maximum number of voice packets to allow to drop
 177   (out of 100).  Useful values are 3-10.
 178 * maxjitterbuffer is the maximum amount of jitter buffer to permit to be
 179   used.
 180 * maxexcessbuffer is the maximum amount of excess jitter buffer
 181   that is permitted before the jitter buffer is slowly shrunk to eliminate
 182   latency.
 183 * minexcessbuffer is the minimum amount of excess jitter buffer
 184
 185 > accountcode = <code>
 186 > amaflags = [default|omit|billing|documentation]
 187
 188 These parameters affect call detail record generation.  The first sets the
 189 account code for records received with IAX.  The account code can be
 190 overridden on a per-user basis for incoming calls (see below).  The
 191 amaflags controls how the record is labeled ("omit" causes no record to be
 192 written.  "billing" and "documentation" label the records as billing or
 193 documentation records respectively, and "default" selects the system
 194 default.
 195
 196 > tos = [lowdelay|throughput|reliability|mincost|none]
 197
 198 IAX can optionally set the TOS (Type of Service) bits to specified values
 199 to help improve performance in routing.  The recommended value is
 200 "lowdelay", which many routers (including any Linux routers with 2.4
 201 kernels that have not been altered with ip tables) will give priority to
 202 these packets, improving voice quality.
 203
 204 > register => <name>[:<secret>]@<host>[:port]
 205
 206 Any number of registry entries may be instantiated in the general
 207 section.  Registration allows Asterisk to notify a remote Asterisk server
 208 (with a fixed address) what our current address is.  In order for
 209 registration to work, the remote Asterisk server will need to have a
 210 dynamic peer entry with the same name (and secret if provided).
 211
 212 The name is a required field, and is the remote peer name that we wish to
 213 identify ourselves as.  A secret may be provided as well.  The secret is
 214 generally a shared password between the local server and the remote
 215 server.  However, if the secret is in square brackets ([]'s) then it is
 216 interpreted as the name of a RSA key to use.  In that case, the local Asterisk
 217 server must have the *private* key (/var/lib/asterisk/keys/<name>.key) and
 218 the remote server will have to have the corresponding public key.
 219
 220 The "host" is a required field and is the hostname or IP address of the
 221 remote Asterisk server.  The port specification is optional and is by
 222 default 4569 for iax2 if not specified.
 223
 224 > notransfer = yes | no
 225
 226 If an IAX phone calls another IAX phone by using a Asterisk server,
 227 Asterisk will transfer the call to go peer to peer. If you do not
 228 want this, turn on notransfer with a "yes". This is also settable
 229 for peers and users.
 230
 231 -------------
 232
 233 The following sections, after "general" define either users, peers or
 234 friends.  A "user" is someone who connects to us.  A "peer" is someone
 235 that we connect to.  A "friend" is simply shorthand for creating a "user"
 236 and "peer" with identical parameters (i.e. someone who can contact us and
 237 who we contact).
 238
 239 > [identifier]
 240
 241 The section begins with the identifier in square brackets.  The identifier
 242 should be an alphanumeric string.
 243
 244 > type = [user|peer|friend]
 245
 246 This line tells Asterisk how to interpret this entity.  Users are things
 247 that connect to us, while peers are phones we connect to, and a friend is
 248 shorthand for creating a user and a peer with identical information
 249
 250 ----------------
 251 User fields:
 252
 253 > context = <context>
 254
 255 One or more context lines may be specified in a user, thus giving the user
 256 access to place calls in the given contexts.  Contexts are used by
 257 Asterisk to divide dialing plans into logical units each with the ability
 258 to have numbers interpreted differently, have their own security model,
 259 auxiliary switch handling, and include other contexts.  Most users are
 260 given access to the default context.  Trusted users could be given access
 261 to the local context for example.
 262
 263 > permit = <ipaddr>/<netmask>
 264 > deny = <ipaddr>/<netmask>
 265
 266 Permit and deny rules may be applied to users, allowing them to connect
 267 from certain IP addresses and not others.  The permit and deny rules are
 268 interpreted in sequence and all are evaluated on a given IP address, with
 269 the final result being the decision.  For example:
 270
 271 > permit = 0.0.0.0/0.0.0.0
 272 > deny = 192.168.0.0/255.255.255.0
 273
 274 would deny anyone in 192.168.0.0 with a netmask of 24 bits (class C),
 275 whereas:
 276
 277 > deny = 192.168.0.0/24
 278 > permit = 0.0.0.0/0
 279
 280 would not deny anyone since the final rule would permit anyone, thus
 281 overriding the denial.
 282
 283 If no permit/deny rules are listed, it is assumed that someone may connect
 284 from anywhere.
 285
 286 > callerid = <callerid>
 287
 288 You may override the Caller*ID information passed by a user to you (if
 289 they choose to send it) in order that it always be accurate from the
 290 perspective of your server.
 291
 292 > auth = [md5|plaintext|rsa]
 293
 294 You may select which authentication methods are permitted to be used by
 295 the user to authenticate to us.  Multiple methods may be specified,
 296 separated by commas. If md5 or plaintext authentication is selected, a
 297 secret must be provided. If RSA authentication is specified, then one or
 298 more key names must be specified with "inkeys"
 299
 300 If no secret is specified and no authentication method is specified, then
 301 no authentication will be required.
 302
 303 > secret = <secret>
 304
 305 The "secret" line specifies the shared secret for md5 and plaintext
 306 authentication methods.  It is never suggested to use plaintext except in
 307 some cases for debugging.
 308
 309 > inkeys = key1[:key2...]
 310
 311 The "inkeys" line specifies which keys we can use to authenticate the
 312 remote peer.  If the peer's challenge passes with any of the given keys,
 313 then we accept its authentication.  The key files live in
 314 /var/lib/asterisk/keys/<name>.pub and are *public keys*.  Public keys are
 315 not typically DES3 encrypted and thus do not usually need initialization.
 316
 317 ---------------
 318 Peer configuration
 319
 320 > allow = [gsm|lpc10|g723.1|adpcm|ulaw|alaw|mp3|slinear|all]
 321 > disallow = [gsm|lpc10|g723.1|adpcm|ulaw|alaw|mp3|slinear|all]
 322
 323 The "allow" and "disallow" may be used to enable or disable specific codec
 324 support on a per-peer basis.
 325
 326 > host = [<ipaddr>|dynamic]
 327
 328 The host line specifies the hostname or IP address of the remote host, or
 329 may be the word "dynamic" signifying that the host will register with us
 330 (see register => in the general section above).
 331
 332 > defaultip = <ipaddr>
 333
 334 If the host uses dynamic registration, Asterisk may still be given a
 335 default IP address to use when dynamic registration has not been performed
 336 or has timed out.
 337
 338 > peercontext = <context>
 339
 340 Specifies the context name to be passed to the peer for it to use when routing
 341 the call through its dial plan. This entry will be used only if a context
 342 is not included in the IAX2 channel name passed to the Dial command.
 343
 344 > qualify = [yes | no | <value>]
 345
 346 Qualify turns on checking of availability of the remote peer. If the
 347 peer becomes unavailable, no calls are placed to the peer until
 348 it is reachable again. This is also helpful in certain NAT situations.
 349
 350 > jitterbuffer = [yes | no]
 351
 352 Turns on or off the jitterbuffer for this peer
 353
 354 > mailbox = <mailbox>[@mailboxcontext]
 355
 356 Specifies a mailbox to check for voicemail notification.
 357
 358 > permit = <ipaddr>/<netmask>
 359 > deny = <ipaddr>/<netmask>
 360
 361 Permit and deny rules may be applied to users, allowing them to connect
 362 from certain IP addresses and not others.  The permit and deny rules are
 363 interpreted in sequence and all are evaluated on a given IP address, with
 364 the final result being the decision.  See the user section above
 365 for examples.
 366
 367 ----------------------------------------------------------------------
 368 For more examples of a configuration, please see the iax.conf.sample in
 369 your the /configs directory of you source code distribution