Merged revisions 44167 via svnmerge from
[asterisk/asterisk.git] / doc / iax.txt
1 Inter-Asterisk eXchange Protocol
2 ================================
3
4 Usage:
5 ======
6 The format for the dialing string on Asterisk is:
7 IAX/[user@]peer[:exten[@context]]
8
9 (Note, []'s denote optional fields).  The peer is either an IP address
10 or a peer as specified in the /etc/asterisk/iax.conf file.  Exten is
11 an optional requested extension (otherwise "s" will be used), and 
12 "context" is an optional context to request.  The user is an optional
13 username specified in the peer's iax.conf.  If the user is not specified,
14 the peer will select one.
15
16 The peer uses a score to determine the best user entry to match against if
17 one is not specified:
18
19 1. User entry last specified in iax.conf (this is the baseline).
20 2. User entry with secret specified and ACL specified.
21 3. User entry with no secret specified and no ACL specified.
22 4. User entry with no secret specified and ACL specified.
23 5. User entry matched via username.
24
25 The higher the score the better it is with 5 being an exact match and the maximum
26 score possible.
27
28 Protocol and rationale:
29 =======================
30 IAX is a simple, low overhead and low bandwidth VoIP protocol designed to 
31 allow multiple Asterisk PBX's to communicate with one another without
32 the overhead of more complex protocols like H.323.  Payload is sent with
33 a header overhead of only 4 octets.  Control functions (and one payload packet
34 per minute or so) is sent with a more complex header of 12 octets.
35
36 IAX is slightly stateful.
37
38 IAX contains two kinds of packets:  The full header packet type, which 
39 contains much information about the frame, in addition to its contents,
40 and the mini header type, which is used only for non-reliable voice
41 packet delivery.
42
43 All packets are immediately transmitted.  Packets are received, but not
44 delivered to the actual channels until a given time quantum has passed, in
45 order to try to eliminate jitter.
46
47 All full header packets must be ackd (except, obviously for the ACK packets
48 themselves and not so obviously for hangup packets).  The "timestamp" field of
49 ack packets is not the normal offset, but rather a quote of the timestamp as
50 included with the original packet that you're acking, and likewise the
51 seqno field is the seqno of the packet you're acking, not your own seqno,
52 and you do not increment your own sequence number.  ACKing is based on the
53 sequence number.
54
55 See iax.h for a description of the frame formats. 
56
57 IAX internal frames use the AST_FRAME_IAX type.  The subclass of these
58 frames is the IAX control number, as seen in iax.h.  The first frame sent
59 must be an AST_FRAME_IAX with the control AST_IAX_CONTROL_NEW.  
60
61 The AST_IAX_CONTROL_NEW establishes a new connection.  
62
63 The first frame sent MUST be an AST_CONTROL_NEW to start a connection.
64
65 IAX connnections may require authentication using either simple plaintext
66 passwords or an md5 challenge/response pair.
67