Configure IAX clients in Asterisk

Asterisk PBX

This article will cover the process of IAX clients configuration in Asterisk.

There are three authentication methods that are supported: MD5, plaintext and RSA. The least secure is “plaintext”, which sends passwords cleartext across the net. “md5” uses a challenge/response md5 sum arrangement, but still requires both ends have plain text access to the secret. “rsa” allows unidirectional secret knowledge through public/private keys. If “rsa” authentication is used, “inkeys” is a list of acceptable public keys on the local system that can be used to authenticate the remote peer, separated by the “:” character. “outkey” is a single, private key to use to authenticate to the other side.

Public keys are named /var/lib/asterisk/keys/<name>.pub while private keys are named /var/lib/asterisk/keys/<name>.key. Private keys should always be 3DES encrypted.

Asterisk IAX Codecs

The following codecs are valid for the allow/disallow parameter:

  • g723.1
  • gsm
  • ulaw
  • alaw
  • g726
  • slinear
  • lpc10
  • adpcm
  • g729
  • speex
  • ilbc
  • h261
  • h263
  • all

Controlling the media path

With notransfer=yes you can prohibit Asterisk from stepping out of the media path and connecting the two endpoints directly to each other. This, of course, affects your call detail records (CDR) and billing information.
Note: This is quite similar to the sip.conf setting canreinvite=no

This has been changed in 1.4 to transfer=yes, options are “yes”, “no” and “media only”.


Alternatively, you can directly set the bit values:

tos=0x18 ; where the tos bits are set individually and in combination

For example

tos=0x10 = low delay
tos=0x08 = high throughput
tos=0x04 = high reliability
tos=0x02 = ECT bit set
tos=0x01 = CE bit set

or set multiple bits, such as


to set both low delay and high throughput.

The qualify option

The qualify, qualifyfreqok and qualifyfreqnotok settings are used to determine the status availability of an IAX peer.


qualify=no|yes|xxx (“qualify=yes” is equivalent to “qualify=2000”)

where “xxx” is an integer specifying milliseconds.


qualifyfreqok=60000 (60 sec)
qualifyfreqnotok=10000 (10 sec)

How qualify works

If a peer is consdered to be in a reachable (OK or LAGGED) state, it is queried for availability every “qualifyfreqok” milliseconds. If it is considered to be in an UNREACHABLE state, it is queried for availability every “qualifyfreqnotok” milliseconds.

The qualify= setting turns the qualify system on (if the “yes” or xxx options are used) or off (if qualify=no, which is by default). The millisecond value of the qualify= setting specifies the maximum response time of the availability acknowledgement before the peer is considered to be in a “LAGGED” state.

Usefulness in NAT

This feature may be used to keep a UDP session open to a device that is located behind a network address translator (NAT). By sending the availability requests, the UDP port binding in the NAT (on the outside address of the NAT/firewall device) is maintained by sending traffic through it. If the binding were to expire, there would be no way for Asterisk to communicate with the IAX peer.

Problems with some IAX clients

Some IAX clients — including firefly, diax, IAXphone, IAXComm, JackenIAX — don’t seem to like being monitored with the qualify option. If you have this option, you will see messages like this on the console:
Peer ‘2004’ is now UNREACHABLE!
The IAX Softphone IAXComm gives output like:
Timeout for a non-existant session. Dropping
For those clients, set qualify=no.

Simplifying dial strings in extensions.conf

Although IAX channel details (username, secret, etc.) can be written explicitly into each dial string in extensions.conf, dial strings can be simplified/clarified by storing all of this information in the iax.conf file and then simply referencing by the channel name:

For example, to call IAXtel you can create an entry in iax.conf like this:

Then use a Dial command of:

Table of command or directives you can use and where.

Needs updating: added to wiki Oct14, 2004

Directive Value General Peer User
allow <codec> Y Y Y
disallow <codec> Y Y Y
amaflags Y
bandwidth Y Y Y
bindaddr Y
bindport Y
context Y Y
externip SIP only – N SIP only – N
jitterbuffer Y
maxjitterbuffer Y
maxexcessbuffer Y
inkeys Y Y
outkey Y Y
md5secret Y Y
notransfer Y Y
permit Y Y
deny Y Y
qualify Y Y
register Y
secret Y Y
sourceaddress Y
tos Y Y
trunkfreq Y
trunk Y Y
type Y

For the most up to date list of directives supported by your version of Asterisk, check the source code for your version. In the file channels/chan_iax2.c, look for the functions named build_user, build_peer, and set_config. They contain directive names supported in the type=user, type=peer, and [general] sections of iax.conf, respectively. You don’t have to be able to understand C to find the directive names, either; they’re quite obvious. The information you find in the source will be more accurate than any list you’re likely to find on a wiki page.

More Example IAX Provider

N.B. Outbound calling in extensions.conf


  • Register commands to connect to another IAX server has to be in the [general] section of iax.conf.
  • To set up IAX in trunk mode, add “trunk=yes” to your definition in iax.conf. IAX Trunking needs support of a hardware timer.
  • Do not use both “host=dynamic” and “defaultip=111.222.333.444”, make sure it is just one or the other
  • If you do not use IP-based access control for all of your type=user entries, and you expect your Asterisk installation to be reasonably secure, your iax.conf file must contain a “guest” entry with no secret specified. When a remote system connects to yours, it can connect without specifying a username (that is, connect anonymously). If you have a type=user section that does not specify a secret, Asterisk will allow them to connect with any secret specified in the file. This means that if you have a large number of type=user entries but no guest entry in iax.conf, someone only has to guess any one of your secrets to connect to your server as that user. In other words, they do not need to know both the username and the secret; the secret alone is enough! Asterisk gives preference to a secret less user for anonymous incoming connections, though, so the inclusion of such a section will solve this problem. For more information on IAX authentication within Asterisk, see Asterisk IAX authentication.
  • Add a last entry in iax.conf with no password to force anonymous calls into a specific context.
  • If you use realtime, don’t have any user without a password and without permit/deny.
  • Use the general option mailboxdetail=yes for details and the number of waiting voicemails. Works with most IAX phones like the AT-320 or softphones
  • If you have “update_registry: Restricting registration for peer ‘xxxxxx’ to 60 seconds (requested 1200)”, you can add maxregexpire=1300 to the [general] section.

Troubleshooting IAX

Incoming IAX calls

For troubleshooting IAX calls, turning on IAX debugging output can be very useful. In Asterisk 1.4 or later, the CLI command ‘iax2 set debug on’ turns on debugging output.

Rejected connect attempt from, who was trying to reach ‘987654321@’

See also: Asterisk IAX authentication

  • Turn on iax debugging and see as which user the incoming call is trying to connect.
  • You will probably need to have a type=user section which does not specify a secret= line.
  • Check your context= lines. The first context= line listed in that section will be used if the call doesn’t request a specific context.

CAUSE 50: No Authority Found

See also: Asterisk No authority found

  • Turn on iax debugging.
  • Check if the username of the incoming call exists as section name (the text in square brackets) in iax.conf. Note: it is not sufficient to have this specified only in a username= line; username= is used for outbound (i.e., type=peer) connections only. Note that this section will typically have type=user, though type=friend will also work.

CallToken Support required

if you get
Nov 2 15:58:47 ERROR[823]: chan_iax2.c:4040 handle_call_token: Call rejected, CallToken Support required. If unexpected, resolve by placing address in the calltokenignore list or setting user iaxhorst requirecalltoken=no

Since AST-2009-006 there is a check for a call token performed. Older clients (e.g. Asterisk 1.2 before 1.2.35) don’t support call tokens, so there is a parameter

per peer or

per subnet.

Want me to do this for you? Drop me a line: itgalaxyzzz {at} gmail [dot] com