IAX
From Yate Documentation
Yate has support for IAX2 Protocol. The module is called yiaxchan and the associated configuration file is yiaxchan.conf.
This module is a VoIP IAX2 driver based on ours Yiax library.
Using the default configuration for this file Yate will act as a IAX Server.
Yate can be used as a IAX Server and also as a IAX Client by using YateClient.
Contents |
Trunking
IAX trunking means that audio data between 2 peers (same ip/port) can be combined into a single packet for multiple calls.
E.g. an entity wanting to send trunked media packets from local ip 1.2.3.4:4569 to 1.2.3.5:4569 would gather media packets from multiple calls into a single packet and send it when a certain amount of time had ellapsed or the packet had reached some length limit.
It is essential to understand that trunking can occur between same local/remote ip/port: packets for calls with different local or remote ip/port can't be put together in a trunked packet.
The advantage of using trunking is to lower the bandwidth: the number of sent packets decreases leading to lower IP overhead.
In the next images the green, blue and red rectangles represents audio packets sent by different IAX calls.
The images show how audio packets are sent without trunking and with trunking.
Note: The order of audio packets inside a trunked packet is not important.
For all calls the remote party can send trunked audio frames.
They will be handled automatically, there is no configuration for it.
To send trunked frames each call must be configured explicitly, as we can see below for incoming and outgoing calls.
Outgoing calls
- The 'call.execute' message must have a trunkout=true parameter
^200$=iax/diana@10.0.0.1:4569/123;trunkout=true
Incoming calls
- A trunkin=true parameter must be set when routing or executing an incoming IAX call:
[contexts]
${module}iax=if ${ip_host}^10\.0\.0\.1=;trunkin=true
- or
[default] ^300$=sip/sip:1234@1.2.3.4;trunkin=true
Configuration
File yiaxchan.conf:
; Trunking notes: ; Trunking can be enabled when routing by a 'trunkout' parameter for outgoing calls ; and 'trunkin' parameter for incoming calls. ; When registering a line to a remote server trunking can be enabled using a 'trunking' ; parameter set in 'user.login' message ; The following parameters can be set in 'user.login' to override the defaults: ; trunk_timestamps, trunk_sendinterval, trunk_maxlen, trunk_efficient_use, ; trunk_nominits_sync_use_ts, trunk_nominits_ts_diff_restart ; When setting trunking parameters for a call the order is: ; - init with configured parameters value ; - override with parameters set for line (outgoing calls only) ; - override parameters set when routing ; IMPORTANT: When a call is set to send trunked data all parameters related to ; trunk (timestamps use, send interval, max packet length) are ignored if there ; is another call using trunking with the same remote ip/port. ; TAKE CARE WHEN SETTING TRUNKING PARAMETERS IN MORE THEN 1 PLACE FOR THE SAME ; REMOTE IP/PORT !!! ; When routing a call to iax module a specific listener can be specfied: ; 1: Its name can be set in 'oconnection_id' parameter. ; The name of the listener created from 'general' section is 'iaxengine' ; 2: Local ip/port can be specified in 'oip_transport_localip' and ; 'oip_transport_localport'. The port defaults to 4569 if missing. ; If a non empty connection id or local address is specified and a valid listener ; is not found the call will fail [general] ; This section sets global variables of the implementation ; It also sets the default listener named 'iaxengine' ; Unless specified all parameters are listener specific ; port: int: UDP port for incoming connections ;port=4569 ; addr: ipaddress: IP address to bind to ;addr=0.0.0.0 ; force_bind: boolean: Try to use a random port if failed to bind on configured one ; Defaults to yes ;force_bind=yes ; default: boolean: Specifiy if this is the default transport to use when none specified ; Defaults to yes (unlike the other listeners) ;default=yes ; numtype: string: Default calling number type for outgoing calls ; This parameter is applied on reload ; It can be overridden from routing by 'callernumtype' parameter ; Values: unknown,international,national,net-specific,subscriber,abbreviated,reserved ; Defaults to unknown if missing or incorrect ;numtype=unknown ; presentation: string: Default number presentation for outgoing calls ; This parameter is applied on reload ; It can be overridden from routing by 'callerpres' parameter ; Values: allowed, restricted, unavailable ; Defaults to allowed if missing or incorrect ;presentation=allowed ; screening: string: Default number screening for outgoing calls ; This parameter is applied on reload ; It can be overridden from routing by 'callerscreening' parameter ; Values: user-provided, user-provided-passed, user-provided-failed, network-provided ; Defaults to user-provided if missing or incorrect ;screening=user-provided ; trunk_timestamps: boolean: Configure how trunked audio data is sent, enable it for ; trunked data with timestamps and disable it to send trunked data without timestamps ; This parameter is applied on reload ; It can be overridden when routing by 'trunkin_timestamps' for incoming calls ; or 'trunkout_timestamps' for outgoing calls ; This parameter is applied when a new trunk is created (a trunked call is created and ; there is no trunk for the same remote address) ; Defaults to yes ;trunk_timestamps=yes ; trunk_sendinterval: integer: Interval, in milliseconds, to send trunked trunked audio data ; The interval is measured from the first packet put in a trunk ; Trunked data is sent when this interval ellapses or the buffer is full ; This parameter is applied on reload ; It can be overridden when routing by 'trunkin_sendinterval' for incoming calls ; or 'trunkout_sendinterval' for outgoing calls ; This parameter is applied when a new trunk is created (a trunked call is created and ; there is no trunk for the same remote address) ; Minimum allowed value is 5 ; Defaults to 20 ;trunk_sendinterval=20 ; trunk_maxlen: integer: Maximum value for trunked data frames. ; This value includes the length if trunk frame header (8 bytes) ; Trunked data is sent when the send interval ellapses or the buffer is full ; This parameter is applied on reload ; It can be overridden when routing by 'trunkin_maxlen' for incoming calls ; or 'trunkout_maxlen' for outgoing calls ; This parameter is applied when a new trunk is created (a trunked call is created and ; there is no trunk for the same remote address) ; Minimum allowed value is 20 ; Defaults to 1400 ;trunk_maxlen=1400 ; trunk_efficient_use: boolean: Use the trunk efficiently: don't send trunking data when ; there is only 1 call using it ; This parameter is applied on reload ; It can be overridden when routing by 'trunkin_efficient_use' for incoming calls ; or 'trunkout_efficient_use' for outgoing calls ; Defaults to no ;trunk_efficient_use=0 ; trunk_nominits_sync_use_ts: boolean: Configure how to re-build timestamps when ; processing incoming trunked audio without miniframe timestamps ; When enabled the transaction will use trunk timestamp and last received full voice ; frame time and timestamp to build miniframe timestamps ; When disabled the transaction will use the time difference between current time and ; last received full voice frame to build the miniframe timestamps ; This parameter is applied on reload ; It can be overridden when routing by 'trunkin_nominits_sync_use_ts' for incoming calls ; or 'trunkout_nominits_sync_use_ts' for outgoing calls ; Defaults to yes ;trunk_nominits_sync_use_ts=yes ; trunk_nominits_ts_diff_restart: integer: The difference (in milliseconds) between ; current timestamp and first timestamp of incoming trunked audio data without miniframe ; timestamps at which to restart timestamps build data ; This value is used when received trunk timestamp is older then first timestamp ; If the difference is less then this value the miniframes will be dropped ; This will deal with trunk timestamp wraparound or restarted by remote party ; This parameter is ignored if trunk_nominits_sync_use_ts is disabled ; This parameter is applied on reload ; It can be overridden when routing by 'trunkin_nominits_ts_diff_restart' for incoming ; calls or 'trunkout_nominits_ts_diff_restart' for outgoing calls ; Minimum allowed value is 1000 ; Defaults to 5000 ;trunk_nominits_ts_diff_restart=5000 ; calltoken_in: boolean: Use call token ip address authentication on incoming calls ; Note: If the caller don't support the call token IAX extension the call request ; will be ignored anyway ; This parameter is applied on reload ; Defaults to no ;calltoken_in=no ; calltoken_out: boolean: Offer call token ip address authentication on outgoing calls ; This is not a listener specific parameter, it will be applied for all listeners ; This parameter is applied on reload and can be overridden from routing ; Defaults to yes ;calltoken_out=yes ; calltoken_rejectmissing: boolean: Reject incoming calls without call token support ; when calltoken_in is enabled ; If disabled the requests will be ignored (dropped) ; This parameter is applied on reload ; Defaults to yes ;calltoken_rejectmissing=yes ; retrans_count: integer: The number of frame retransmissions ; This parameter is applied on reload for new calls only ; Allowed interval: 1..10 ; Defaults to 4 ;retrans_count=4 ; retrans_interval: integer: The first frame retransmission interval in milliseconds ; This parameter is applied on reload for new calls only ; Allowed interval: 200..5000 ; Defaults to 500 ;retrans_interval=500 ; ping_interval: integer: The interval, in milliseconds, to send ping ; This parameter is applied on reload for new calls only ; Minimum allowed value is 10000 ; Defaults to 20000 ;ping_interval=20000 ; adjust_ts_out_threshold: integer: The difference, in milliseconds, between sent audio data ; timestamp and transaction timestamp at which audio data timestamp will be adjusted ; Its value will be rouded up to a multiple of 10 ; This value is applied on reload for new calls only ; It can be overridden from routing ; Defaults to 120 ; Allowed interval: 20 .. 300 ;adjust_ts_out_threshold=120 ; adjust_ts_out_over: integer: Interval, in milliseconds, to adjust sent audio data ; timestamp on data overrun (the sender transmits data on a rate greater then expected) ; When applied the packets will be dropped until data timestamp will be at least at the ; value of last sent packet timestamp ; NOTE: Choose values greater the packet time to drop more packets at a time. ; Lower values will drop less packets in a row but this will happen more frequently ; Its value will be rouded up to a multiple of 10 ; This value is applied on reload for new calls only ; It can be overridden from routing ; It can't be greater then adjust_ts_out_threshold ; Defaults to 120 ; Allowed interval: 10 .. adjust_ts_out_threshold ;adjust_ts_out_over=120 ; adjust_ts_out_under: integer: Interval, in milliseconds, to adjust sent audio data ; timestamp on data underrun (the sender transmits data on a rate less then expected) ; Its value will be rouded up to a multiple of 10 ; This value is applied on reload for new calls only ; It can be overridden from routing ; It can't be greater then 2 * adjust_ts_out_threshold - 1 ; Defaults to 60 ; Allowed interval: 10 .. 2 * adjust_ts_out_threshold - 1 ;adjust_ts_out_under=60 ; challenge_timeout: integer: Interval, in milliseconds, in which a remote party should ; reply with credentials when we are challenging it ; This value is applied on reload ; Minimum allowed value is 5000 ; Defaults to 30000 ;challenge_timeout=30000 ; tos: keyword: Type Of Service to set in outgoing UDP packets ; numeric TOS value or: lowdelay, throughput, reliability, mincost ;tos=0 ; read_threads: int: Number of threads that read packets from socket ;read_threads=1 in client mode, 3 in server mode ; event_threads: int: Number of threads that process events ;event_threads=1 in client mode, 3 in server mode ; trunk_threads: int: Number of threads that service trunked voice packets ;trunk_threads=1 ; thread: keyword: Default priority of the data service threads (socket listener and data trunking) ; Can be one of: lowest, low, normal, high, highest ; It is a bad idea to set a low priority for anything but testing ;thread=normal ; maxchans: int: Maximum number of channels running at once ; This is not a listener specific parameter, it will be applied for all listeners ; A value of 0 specifies that there is no limit enforced. ; Defaults to the value set by the maxchans setting from yate.conf ;maxchans= ; printmsg: boolean: Print sent/received frames to output if the module's debug ; level is at least 9 ; This parameter is applied on reload ; Defaults to yes ;printmsg=yes [registrar] ; Controls the behaviour when acting as registrar ; expires_min: int: Minimum allowed expiration time in seconds ; This parameter is applied on reload ; Minimum allowed value is 1 ; Defaults to 60 if missing ;expires_min=60 ; expires_max: int: Value used to limit the expiration time to something sane ; This parameter is applied on reload ; Minimum allowed value is the value set in expires_min ; Defaults to 3600 if missing ;expires_max=3600 ; expires_def: int: Default expiration time if not present in register requests ; This parameter is applied on reload ; The value is checked to be between expires_min and expires_max ; Defaults to 60 if missing ;expires_def=60 [formats] ; This section allows to individually enable or disable the codecs ; default: bool: Default enabling state for codecs ;default=enable ; preferred: string: Preferred format to use ;preferred= ; slin: bool: Uncompressed 16-bit signed linear ;slin=enable ; mulaw: bool: Companded-only G711 mu-law ;mulaw=enable ; alaw: bool: Companded-only G711 a-law ;alaw=enable ; gsm: bool: European GSM 06.10 ;gsm=enable ; gsmhr: bool: European GSM 06.20 (GSM Half Rate) ;gsmhr=enable ; lpc10: bool: LPC 10 ;lpc10=enable ;[listener listener_name] ; This section configures an extra listener to use ; 'iaxengine' can't be used as listener name ; Listed parameters can't use the default value from 'general' section ; All other parameters from 'general' section who are listener specific can be overriden ; for this listener ; enable: boolean: Enable or disable this listener ; This parameter is applied on reload and defaults to yes ;enable=yes ; port: int: UDP port for incoming connections ;port=4569 ; addr: ipaddress: IP address to bind to ;addr=0.0.0.0 ; force_bind: boolean: Try to use a random port if failed to bind on configured one ; Defaults to yes ;force_bind=yes ; default: boolean: Specifiy if this is the default transport to use when none specified ; Defaults to no ;default=no
Routing a IAX channel
From a routing module you can call an IAX channel like this:
extension=iax/iax:user@ip:port/called_number
For example, in regexroute.conf you can have:
^200$=iax/iax:diana@10.0.0.1/123
if you want to use the default protocol port (4569), or:
^200$=iax/iax:diana@10.0.0.1:4570/123
if you know that the called party is using the given port for incoming connections.
Notes
- The port you set it's the port the library is using to listen for incoming connections. If you change the default protocol port the callers might not know the new one, so any call they made will fail.
- When you set a route, be sure you know the destination's port. Again, if the port is incorrect the call will fail.
- If you set the preferred format to a non existing or not enabled one another format will be chosen for library use.
See also
