README.iax 14 KB

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