Iax.conf

Synopsis
This file is used to configure clients connecting via the Inter-Asterisk Exchange protocol.  IAX is primarily used for passing calls between Asterisk servers. Frequently Multiple Asterisk servers are configured to intercommunicate with each other using this file.

Arrangement
The iax.conf file begins with a general section, which sets global server options.  Within the general section, we can also configure the Asterisk server to register as a client with a remote server, for access to the dialplan of another Asterisk system.

Following the general section, clients are defined, one per section.  Sections are delineated by their name in brackets.

Keywords
The following keywords are used in iax.conf.  

In the general section:

port: The port to listen on for incoming connections.  The default is port 5036.  Takes as it's argument a port number (which must not be in use by another service.)

bindaddr:  If multiple IP addresses are available in the same system, this option may be set to bind Asterisk to a single interface.

amaflags:  Sets the AMA flags, affecting the categorization of entries in the call detail records. This keyword may also be set on a per client basis, within their client definition. Accepts these values:

billing:  Mark the entry for billing
documentation: Mark the entry for documentation.
omit: Do not record calls.
default: Sets the system default.

accountcode: Sets the default account code to log calls to.  This keyword can also be used within a client definition to set the account code for that client.

bandwidth: This option is used to control which codecs are used generally. Rather than allowing or disallowing specific codecs, this option may be set to 'low' to automatically avoid some codecs that don't work well in low bandwidth sitiuations. Takes an option of low or high. 

allow: Specifically allow a certain codec to be used.  Takes a codec, or all. Using all is the same as specifying bandwidth=high.

disallow: Specifically disallow a certain codec.  See allow.

jitterbuffer: Turn on or off the jitter buffer.  The jitter buffer is used to maximize audio quality by balancing latency against the number of dropped packets.  A number of keywords exist to fine tune the jitterbuffer. 

dropcount:  Sets the maximum number of packets to be dropped in order to reduce latency, per memory size.

maxjitterbuffer:   Sets the maximum size of the jitterbuffer. 

maxexcessjitterbuffer:  Sets the the maximum excess jitter buffer, which if exceeded, causes the jitter buffer to slowly shrink in order to improve latency.

register:  Register is used to tell the Asterisk server to register with another Asterisk server.  This is normally only needed if our local server has a dynamic IP address and needs to tell the other server where to find it.  The format of a register statement is:

register => username:secret@server

The ‘secret’ field is optional, if no secret has been specified on the server being connected to.  If RSA encryption is in use, specify the key to send to the server with this format:

register => username:[key]@server

tos:  Specify the type of service bits to set on IAX packets, which may improve routing of the packets. Available values are:

lowdelay: minimize delay
throughput: maximize throughput
reliability: maximize reliability
mincost: use the lowest cost path
none: use no routing flags

Options for individual users

User definitions begin with the username in brackets.  The username is followed by a number of keyword/value pairs applying to the user  they are set within.

The following keywords are available for users:

type: This sets the type of entity for the client. Valid types are:

user: A user can place calls to or through the Asterisk server.
peer:  A peer receives calls from the Asterisk server, but does not place them
friend: A friend both sends and receives calls through the Asterisk server. This makes the most sense for handsets or other station devices. When in doubt use this type.

context:  When used within a client definition, this keyword overrides the default incoming context set in the general section for the user only.

callerid: Sets the caller ID string to be used for this channel.  This callerid string will be used internally, and sent to the PSTN if a PRI line is used to route the call to the outside world.

Format:  callerid => “Judy Judge” <256 555-1234>

auth:   Sets the authentication type.  IAX supports three methods of authentication. The first (and least secure) is plaintext.  The passwords (or secrets) are sent in clear text over the network.  The second is md5, which uses an md5 challenge response algorithm.   Both machines will have cleartext access to the passwords, but they willl be md5 encrypted while passing over the network.  The most secure option is to use RSA  public/private key encryption to store and transmit the secret.  Public/private key pairs can be generated using the included program astgenkey. The public key will need to be manually tranfered to the server and stored in /var/lib/asterisk/keys/name.pub.  Server private keys are stored in the same location as name.key.  

*Important Note: In order use RSA keys with Asterisk, you will have to ‘init keys’ at the console during startup.  Asterisk will prompt you to do so every time it is launched.

inkeys: The public keys to use to decrypt authentication for an incoming client request or registration.

outkey:The private key to encrypt outgoing authentication communication for this client.

permit:  Hosts to permit to connect as this user.  This can be a single host or a host/netmask pair.

Examples:
permit=192.168.0.1/255.255.255.0
permit=216.207.245.45

deny: Hosts to deny for any incoming connection attempt as this user. deny  takes the same argument format as permit.
host: Sets the expected outgoing host for this client. Can be set to an ip address or dynamic, which will allow incoming connections from any host (that is not explicitly denied.)

defaultip: The default IP address for an IAX client.  This field is consulted if Asterisk receives a call for an IAX client that is dynamic and has not registered to let Asterisk know the current IP address.  Takes as it’s argument an IP address.

accountcode: When used within a client definition, sets the account code for that client only.  This is used by the call logging service.

qualify: Tells Asterisk whether to test whether the peer is alive before attempting to connect the call.  If set to yes Asterisk will contact the peer before forwarding any call information.

Complete File Example:

[general]
;set up some general items
port=5036

accountcode=iaxcalls
amaflags=default

bandwidth=low
allow=gsm
disallow=lpc10

jitterbuffer=yes
dropcount=3
maxjitterbuffer=500
maxexcessjitterbuffer=100

register => asterisk1:opensecret@telco.digium.com

context=iax

;from here on it’s client definitions

[trustedhost]
host=192.168.0.50
context=trusted

[authhost]
secret=foobar
host=dynamic
defaultip=68.62.178.239

[rsahost]
auth=rsa
inkeys=rsapublickey
host=dynamic
defaultip=216.207.245.55
accountcode=log1234
callerid=”Mark Spencer” <256 428 6000>