Version 0.2.0 from FTP
[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 Protocol and rationale:
17 =======================
18 IAX is a simple, low overhead and low bandwidth VoIP protocol designed to 
19 allow multiple Asterisk PBX's to communicate with one another without
20 the overhead of more complex protocols like H.323.  Payload is sent with
21 a header overhead of only 4 octets.  Control functions (and one payload packet
22 per minute or so) is sent with a more complex header of 12 octets.
23
24 IAX is slightly stateful.
25
26 IAX contains two kinds of packets:  The full header packet type, which 
27 contains much information about the frame, in addition to its contents,
28 and the mini header type, which is used only for non-reliable voice
29 packet delivery.
30
31 All packets are immediately transmitted.  Packets are received, but not
32 delivered to the actual channels until a given time quantum has passed, in
33 order to try to eliminate jitter.
34
35 All full header packets must be ackd (except, obviously for the ACK packets
36 themselves and not so obviously for hangup packets).  The "timestamp" field of
37 ack packets is not the normal offset, but rather a quote of the timestamp as
38 included with the original packet that you're acking, and likewise the
39 seqno field is the seqno of the packet you're acking, not your own seqno,
40 and you do not increment your own sequence number.  ACKing is based on the
41 sequence number.
42
43 See iax.h for a description of the frame formats. 
44
45 IAX internal frames use the AST_FRAME_IAX type.  The subclass of these
46 frames is the IAX control number, as seen in iax.h.  The first frame sent
47 must be an AST_FRAME_IAX with the control AST_IAX_CONTROL_NEW.  
48
49 The AST_IAX_CONTROL_NEW establishes a new connection.  
50
51 The first frame sent MUST be an AST_CONTROL_NEW to start a connection.
52
53 IAX connnections may require authentication using either simple plaintext
54 passwords or an md5 challenge/response pair.
55