IAX

From Yate Documentation
(Difference between revisions)
Jump to: navigation, search
(→‎Examples)
(→‎Notes)
 
(24 intermediate revisions by 2 users not shown)
Line 1: Line 1:
−
== Jingle module ==
+
Yate has support for IAX2 Protocol. The module is called yiaxchan and the associated configuration file is yiaxchan.conf.
  
−
This module supports the Jingle protocol by implementing XMPP as an external component of another server.
+
This module is a VoIP IAX2 driver based on ours [[Yiax]] library.
  
−
===Routing===
+
Using the default configuration for this file Yate will act as a IAX Server.
  
−
Syntax: jingle/user@server
+
Yate can be used as a [[How to configure Yate as IAX server|IAX Server]] and also as a IAX Client by using [http://yateclient.yate.ro/index.php/UserGuide/CallingwithIAX YateClient].
  
−
A 'callerprompt' parameter may be added with a text to be sent to the called party before making the call
+
==Trunking==
  
−
====Examples====
+
IAX trunking means that audio data between 2 peers (same ip/port) can be combined into a single packet for multiple calls.<br>
 +
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.<br>
 +
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.<br>
 +
The advantage of using trunking is to lower the bandwidth: the number of sent packets decreases leading to lower IP overhead.
  
−
Route a call 125 to the user 'remoteuser' at server 'remotedomain.com'
+
In the next images the green, blue and red rectangles represents audio packets sent by different IAX calls.<br>
−
  ^125$=jingle/remoteuser@remotedomain.com;callerprompt=Hello, this is a call from ME
+
The images show how audio packets are sent without trunking and with trunking.<br>
  
−
===Configuration===
+
[[File:iax_trunk_none.png]]<br>
 +
[[File:iax_trunk.png]]
  
−
yjinglechan.conf
+
'''Note:''' The order of audio packets inside a trunked packet is not important.
  
−
; This file keeps the configuration for the Jingle channel
+
For all calls the remote party can send trunked audio frames.<br>
 +
They will be handled automatically, there is no configuration for it.
  
−
[general]
+
To send trunked frames each call must be configured explicitly, as we can see below for incoming and outgoing calls.
−
; Global settings of Jingle channel
+
  
−
  ; servermode: boolean: Server/client mode
+
=== Outgoing calls===
−
; This parameter can be used to override yate running mode
+
−
; Defaults to true if yate is running in non client mode, false otherwise
+
−
;servermode=
+
  
−
; domains: string: Comma separated list of domains serviced by the jingle channel
+
:The 'call.execute' message must have a '''trunkout'''=true parameter
−
; The parameter is not used in client mode
+
  ^200$=iax/diana@10.0.0.1:4569/123;trunkout=true
−
; When running in non client mode any domain should be a jabber server (sub)domain
+
−
  ;domains=
+
  
−
; resources: string: Comma separated list of resources serviced by the jingle channel
+
=== Incoming calls ===
−
; The parameter is not used in client mode
+
−
; The first resource will be the default one (for outgoing calls)
+
−
; If this parameter is empty the module will handle all resources
+
−
;resources=
+
  
−
; resource_priority: integer: Resource priority for presence sent by the module
+
:A '''trunkin'''=true parameter must be set when routing or executing an incoming IAX call:
−
; Interval allowed -128..127
+
−
; Defaults to 0
+
−
;resource_priority=0
+
  
−
  ; jingle_version: integer: Jingle session version to use for outgoing calls
+
  [contexts]
−
  ; Defaults to the newest version if missing or invalid
+
  ${module}iax=if ${ip_host}^10\.0\.0\.1=;trunkin=true
−
; Allowed values are 0 or 1
+
:or
−
  ; This parameter can be overridden when routing by an 'ojingle_version' parameter
+
  [default]
−
  ;jingle_version=
+
  ^300$=sip/sip:1234@1.2.3.4;trunkin=true
  
−
; jingle_flags: string: Comma separated list of default jingle session flags
+
== Configuration==
−
; Available flags:
+
−
;  - noping: Don't send ping (empty session info)
+
−
; This parameter can be overridden when routing by an 'ojingle_flags' parameter for
+
−
;  outgoing calls or "jingle_flags" for incoming calls
+
−
;jingle_flags=
+
  
−
; accept_relay: bool: Accept a "relay" transport type even if we had another type before
+
File yiaxchan.conf:
−
; This works only with Jingle version 0 (Google Talk, libjingle)
+
−
;accept_relay=disable in server mode, enable in client mode
+
  
−
  ; singletone: boolean: Send chan tones as single characters.
+
  ; Trunking notes:
−
  ; If disabled, the whole text received as chan tone(s) will be sent
+
; 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
 
   
 
   
−
  ;  in the same XML element
+
−
  ; Defaults to enable
+
[general]
−
  ;singletone=enable
+
  ; This section sets global variables of the implementation
−
 
+
  ; It also sets the default listener named 'iaxengine'
−
  ; imtochantext: boolean: Send received IM messages as chan.text if a channel is found
+
  ; Unless specified all parameters are listener specific
−
  ; If disabled, an im.route message will be pushed into the engine
+
−
  ; Defaults to disable
+
; port: int: UDP port for incoming connections
−
  ;imtochantext=disable
+
;port=4569
−
 
+
−
  ; localip: string: Set this machine's IP address. If missing, we will try to guess one
+
; addr: ipaddress: IP address to bind to
−
  ; The local machine's IP address is used to negotiate the audio stream
+
  ;addr=0.0.0.0
−
  ;localip=
+
−
 
+
  ; force_bind: boolean: Try to use a random port if failed to bind on configured one
−
  ; anonymous_caller: string: Set the caller name if missing for outgoing calls
+
  ; Defaults to yes
−
  ; Defaults to unk_caller
+
;force_bind=yes
−
  ;anonymous_caller=unk_caller
+
−
 
+
; default: boolean: Specifiy if this is the default transport to use when none specified
−
  ; request_subscribe: boolean: Make a subscribe request before probing a remote user
+
  ; Defaults to yes (unlike the other listeners)
−
  ;   Defaults to enable
+
  ;default=yes
−
  ; pending_timeout: integer: How much an outgoing call will wait for a response to a probe
+
−
  ;   Defaults to 10000
+
  ; numtype: string: Default calling number type for outgoing calls
−
  ; The parameters are not used in client mode
+
; This parameter is applied on reload
−
  ; These options are used when we want to make an outgoing call and we can't do that because we don't have
+
; It can be overridden from routing by 'callernumtype' parameter
−
  ;   a resource with audio capability for the called party, so we have to probe its presence
+
; Values: unknown,international,national,net-specific,subscriber,abbreviated,reserved
−
  ; Since we might not receive a response if the caller is not subscribed to called's party presence,
+
  ; Defaults to unknown if missing or incorrect
−
  ;   we should make a subscribe request first (enabling request_subscribe will do that)
+
  ;numtype=unknown
−
  ; The jingle channel will wait for the time given by pending_timeout for an an appropriate response
+
−
  ; If no response is received within pending_timeout interval the call will be dropped
+
  ; presentation: string: Default number presentation for outgoing calls
−
  ; When receiving a valid response, the jingle channel will start to negotiate the call
+
; This parameter is applied on reload
−
  ; pending_timeout actually extends the time an outgoing call may be in a not answered state
+
; It can be overridden from routing by 'callerpres' parameter
−
  ;request_subscribe=enable
+
; Values: allowed, restricted, unavailable
−
  ;pending_timeout=10000
+
; Defaults to allowed if missing or incorrect
−
 
+
;presentation=allowed
−
  ; auto_subscribe: boolean: Automatically respond to (un)subscribe requests
+
−
  ; The parameter is not used in client mode
+
; screening: string:  Default number screening for outgoing calls
−
  ; Defaults to disable
+
; This parameter is applied on reload
−
  ; WARNING: If auto_subscribe is enabled when the module is handling the same domain(s) as
+
; It can be overridden from routing by 'callerscreening' parameter
−
  ;  the jabber server this might lead to subscription request aproval on behalf of 'real'
+
; Values: user-provided, user-provided-passed, user-provided-failed, network-provided
−
  ;  jabber users!
+
  ; Defaults to user-provided if missing or incorrect
−
  ;auto_subscribe=disable
+
  ;screening=user-provided
−
 
+
−
  ; stanza_timeout: integer: The timeout interval (in milliseconds) of a stanza sent by a
+
  ; trunk_timestamps: boolean: Configure how trunked audio data is sent, enable it for
−
  ;  jingle session
+
;  trunked data with timestamps and disable it to send trunked data without timestamps
−
  ; Session initiate and ping timeout will automatically lead to session termination
+
; 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
 
  ; Minimum allowed value is 10000
−
  ; Defaults to 20000 if missing or to the minimum value if invalid
+
  ; Defaults to 20000
−
  ;stanza_timeout=20000
+
  ;ping_interval=20000
−
 
+
−
  ; ping_interval: integer: The interval (in milliseconds) to ping the remote party of a
+
  ; adjust_ts_out_threshold: integer: The difference, in milliseconds, between sent audio data
−
  ;  jingle session
+
;  timestamp and transaction timestamp at which audio data timestamp will be adjusted
−
  ; If enabled and the ping element fails the session will be terminated
+
; Its value will be rouded up to a multiple of 10
−
  ; Minimum allowed value is 60000. Set it to 0 to disable ping
+
  ; This value is applied on reload for new calls only
−
  ; Defaults to 300000 if missing or invalid
+
  ; It can be overridden from routing
−
  ; If enabled, it's value must be greater then stanza_timeout
+
  ; Defaults to 120
−
  ;ping_interval=300000
+
; Allowed interval: 20 .. 300
−
 
+
;adjust_ts_out_threshold=120
−
  ; resource.notify: integer: Override the priority of module's resource.notify message handler
+
−
  ;resource.notify=
+
; 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)
−
  ; redirectcount: integer: Default value for outgoing calls redirect counter
+
; When applied the packets will be dropped until data timestamp will be at least at the
−
  ; This parameter controls the behaviour of an outgoing call terminated
+
  ; value of last sent packet timestamp
−
  ;  with 'redirect' reason containing a non empty target
+
; NOTE: Choose values greater the packet time to drop more packets at a time.
−
  ; If non 0 the counter is decreased. If the target is an XMPP uri the call will
+
  ; Lower values will drop less packets in a row but this will happen more frequently
−
  ;  be re-executed internally.
+
; Its value will be rouded up to a multiple of 10
−
  ; If the counter is 0 when terminated, the call parameters list will be filled with
+
  ; This value is applied on reload for new calls only
−
  ;  session parameters to let the PBX deal with it.
+
; It can be overridden from routing
−
  ; This parameter can be overridden from routing
+
; It can't be greater then adjust_ts_out_threshold
−
  ;redirectcount=0
+
  ; Defaults to 120
−
 
+
; Allowed interval: 10 .. adjust_ts_out_threshold
−
  ; dtmfmethod: string: Default value for the method used to send DTMFs
+
;adjust_ts_out_over=120
−
  ; Allowed values:
+
−
  ;  jingle: Use the jingle protocol
+
  ; adjust_ts_out_under: integer: Interval, in milliseconds, to adjust sent audio data
−
  ; rfc2833: Send RFC 2833 DTMFs
+
;  timestamp on data underrun (the sender transmits data on a rate less then expected)
−
  ;  inband: Generate inband tones
+
; Its value will be rouded up to a multiple of 10
−
  ;  chat: Send tones as chat messages
+
; This value is applied on reload for new calls only
−
  ; This parameter can be overridden from routing
+
; It can be overridden from routing
−
  ;dtmfmethod=jingle
+
; It can't be greater then 2 * adjust_ts_out_threshold - 1
−
 
+
  ; Defaults to 60
−
 
+
; Allowed interval: 10 .. 2 * adjust_ts_out_threshold - 1
−
  [codecs]
+
;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
 
  ; This section allows to individually enable or disable the codecs
−
 
−
; default: bool: Enable all unlisted codecs by default
 
−
default=false
 
−
 
−
; mulaw: bool: Companded-only G711 mu-law (PCMU/8000)
 
−
mulaw=true
 
 
   
 
   
−
  ; alaw: bool: Companded-only G711 a-law (PCMU/8000)
+
; default: bool: Default enabling state for codecs
−
  alaw=true
+
;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
  
−
; gsm: bool: European GSM 06.10 (GSM/8000)
+
== Routing a IAX channel==
−
gsm=default
+
  
−
; ilbc: bool: Internet Low Bandwidth Codec (iLBC/8000)
+
From a routing module you can call an IAX channel like this:
−
;ilbc=default
+
  
−
  ; lpc10: bool: Linear Prediction Codec (LPC/8000)
+
  extension=iax/iax:user@ip:port/called_number
−
lpc10=default
+
  
−
; slin: bool: Signed Linear 16-bit uncompressed (L16/8000)
+
For example, in regexroute.conf you can have:
−
  slin=default
+
   
 +
^200$=iax/iax:diana@10.0.0.1/123
  
−
; g723: bool: ITU G.723 all variations (G723/8000)
+
if you want to use the default protocol port (4569), or:
−
g723=default
+
  
−
  ; g726: bool: ITU G.726 32-bit (G726-32/8000)
+
  ^200$=iax/iax:diana@10.0.0.1:4570/123
−
g726=default
+
  
−
; g728: bool: ITU G.728 all variations (G728/8000)
+
if you know that the called party is using the given port for incoming connections.
−
g728=default
+
  
−
; g729: bool: ITU G.729 all variations (G729/8000)
+
==Notes==
−
g729=default
+
  
 +
* 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.
  
−
[hacks]
 
−
; This section holds the dirty stuff required to work with some broken
 
−
;  or old implementations
 
−
 
−
; ilbc_forced: string: Format to offer as iLBC, can be: ilbc20 or ilbc30
 
−
; Defaults to ilbc30
 
−
;ilbc_forced=ilbc30
 
−
 
−
; ilbc_default: string: Format to use for iLBC when packetization is unknown
 
−
; Defaults to ilbc30
 
−
;ilbc_default=ilbc30
 
−
 
−
 
−
===Examples===
 
  
−
This is an example of how to configure the stream with the Jabber server who will expose Yate to the Jabber network
+
'''See also'''
  
−
[mydomain.com]
+
* http://tools.ietf.org/html/rfc5456#section-7.1  
−
address=1.2.3.4
+
* http://www.voip-info.org/wiki/view/Asterisk+bandwidth+iax2
−
port=10000
+
* http://www.voip-info.org/wiki/view/IAX
−
password=whateverstring
+
* [[How to configure Yate as IAX server|Yate as IAX server and YateClient as IAX client]]
−
startup=enable
+
* [[Telephony]]
  
−
Yate will start a TCP connection to the IP address 'mydomain.com' resolves to. The port to use to connect to 'mydomain.com' (10000) will be obtained internally by searching after the value entered in the address parameter (1.2.3.4). The password (whateverstring) will be used to authenticate with the server
+
[[Category:IAX]] [[Category:Trunking]]

Latest revision as of 12:12, 4 November 2013

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

[edit] 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.

Iax trunk none.png
Iax trunk.png 

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.

[edit] Outgoing calls

The 'call.execute' message must have a trunkout=true parameter 
^200$=iax/diana@10.0.0.1:4569/123;trunkout=true

[edit] 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

[edit] 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

[edit] 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.

[edit] 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

Retrieved from "https://docs.yate.ro/wiki/index.php?title=IAX&oldid=7323"
Personal tools
Namespaces

Variants
Actions
Preface
Configuration
Administrators
Developers