IAX

From Yate Documentation
(Difference between revisions)
Jump to: navigation, search
(→‎Configuration)
(→‎Notes)
 
(23 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.
 +
 
 +
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]
 
  [general]
−
  ; Global settings of Jingle channel
+
  ; This section sets global variables of the implementation
 +
; It also sets the default listener named 'iaxengine'
 +
; Unless specified all parameters are listener specific
 
   
 
   
−
  ; servermode: boolean: Server/client mode
+
  ; port: int: UDP port for incoming connections
−
  ; This parameter can be used to override yate running mode
+
  ;port=4569
−
; 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
+
  ; addr: ipaddress: IP address to bind to
−
  ; The parameter is not used in client mode
+
  ;addr=0.0.0.0
−
; 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
+
  ; force_bind: boolean: Try to use a random port if failed to bind on configured one
−
; The parameter is not used in client mode
+
  ; Defaults to yes
−
; The first resource will be the default one (for outgoing calls)
+
  ;force_bind=yes
−
  ; If this parameter is empty the module will handle all resources
+
−
  ;resources=
+
 
   
 
   
−
  ; resource_priority: integer: Resource priority for presence sent by the module
+
  ; default: boolean: Specifiy if this is the default transport to use when none specified
−
; Interval allowed -128..127
+
  ; Defaults to yes (unlike the other listeners)
−
  ; Defaults to 0
+
  ;default=yes
−
  ;resource_priority=0
+
 
   
 
   
−
  ; jingle_version: integer: Jingle session version to use for outgoing calls
+
  ; numtype: string: Default calling number type for outgoing calls
−
  ; Defaults to the newest version if missing or invalid
+
  ; This parameter is applied on reload
−
  ; Allowed values are 0 or 1
+
  ; It can be overridden from routing by 'callernumtype' parameter
−
; This parameter can be overridden when routing by an 'ojingle_version' parameter
+
  ; Values: unknown,international,national,net-specific,subscriber,abbreviated,reserved
−
  ;jingle_version=
+
; Defaults to unknown if missing or incorrect
 +
;numtype=unknown
 
   
 
   
−
  ; jingle_flags: string: Comma separated list of default jingle session flags
+
  ; presentation: string: Default number presentation for outgoing calls
−
  ; Available flags:
+
  ; This parameter is applied on reload
−
  ; - noping: Don't send ping (empty session info)
+
  ; It can be overridden from routing by 'callerpres' parameter
−
; This parameter can be overridden when routing by an 'ojingle_flags' parameter for
+
  ; Values: allowed, restricted, unavailable
−
  ;  outgoing calls or "jingle_flags" for incoming calls
+
  ; Defaults to allowed if missing or incorrect
−
  ;jingle_flags=
+
  ;presentation=allowed
 
   
 
   
−
  ; accept_relay: bool: Accept a "relay" transport type even if we had another type before
+
  ; screening: string: Default number screening for outgoing calls
−
  ; This works only with Jingle version 0 (Google Talk, libjingle)
+
  ; This parameter is applied on reload
−
  ;accept_relay=disable in server mode, enable in client mode
+
; 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
 
   
 
   
−
  ; singletone: boolean: Send chan tones as single characters.
+
  ; trunk_timestamps: boolean: Configure how trunked audio data is sent, enable it for
−
  ; If disabled, the whole text received as chan tone(s) will be sent
+
  ; trunked data with timestamps and disable it to send trunked data without timestamps
−
 
+
; This parameter is applied on reload
−
  ;  in the same XML element
+
; It can be overridden when routing by 'trunkin_timestamps' for incoming calls
−
  ; Defaults to enable
+
;  or 'trunkout_timestamps' for outgoing calls
−
  ;singletone=enable
+
  ; 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
 
   
 
   
−
  ; imtochantext: boolean: Send received IM messages as chan.text if a channel is found
+
  ; trunk_sendinterval: integer: Interval, in milliseconds, to send trunked trunked audio data
−
  ; If disabled, an im.route message will be pushed into the engine
+
; The interval is measured from the first packet put in a trunk
−
  ; Defaults to disable
+
; Trunked data is sent when this interval ellapses or the buffer is full
−
  ;imtochantext=disable
+
  ; 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
 
   
 
   
−
  ; localip: string: Set this machine's IP address. If missing, we will try to guess one
+
  ; trunk_maxlen: integer: Maximum value for trunked data frames.
−
  ; The local machine's IP address is used to negotiate the audio stream
+
  ; This value includes the length if trunk frame header (8 bytes)
−
  ;localip=
+
; 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
 
   
 
   
−
  ; anonymous_caller: string: Set the caller name if missing for outgoing calls
+
  ; trunk_efficient_use: boolean: Use the trunk efficiently: don't send trunking data when
−
  ; Defaults to unk_caller
+
;  there is only 1 call using it
−
  ;anonymous_caller=unk_caller
+
; 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
 
   
 
   
−
  ; request_subscribe: boolean: Make a subscribe request before probing a remote user
+
  ; trunk_nominits_sync_use_ts: boolean: Configure how to re-build timestamps when
−
  ;   Defaults to enable
+
  ; processing incoming trunked audio without miniframe timestamps
−
  ; pending_timeout: integer: How much an outgoing call will wait for a response to a probe
+
  ; When enabled the transaction will use trunk timestamp and last received full voice
−
  ;   Defaults to 10000
+
  ; frame time and timestamp to build miniframe timestamps
−
  ; The parameters are not used in client mode
+
  ; When disabled the transaction will use the time difference between current time and
−
  ; These options are used when we want to make an outgoing call and we can't do that because we don't have
+
  ; last received full voice frame to build the miniframe timestamps
−
;  a resource with audio capability for the called party, so we have to probe its presence
+
  ; This parameter is applied on reload
−
  ; Since we might not receive a response if the caller is not subscribed to called's party presence,
+
  ; It can be overridden when routing by 'trunkin_nominits_sync_use_ts' for incoming calls
−
  ;   we should make a subscribe request first (enabling request_subscribe will do that)
+
  ;  or 'trunkout_nominits_sync_use_ts' for outgoing calls
−
; The jingle channel will wait for the time given by pending_timeout for an an appropriate response
+
  ; Defaults to yes
−
  ; If no response is received within pending_timeout interval the call will be dropped
+
  ;trunk_nominits_sync_use_ts=yes
−
  ; When receiving a valid response, the jingle channel will start to negotiate the call
+
−
; pending_timeout actually extends the time an outgoing call may be in a not answered state
+
−
  ;request_subscribe=enable
+
−
  ;pending_timeout=10000
+
 
   
 
   
−
  ; auto_subscribe: boolean: Automatically respond to (un)subscribe requests
+
  ; trunk_nominits_ts_diff_restart: integer: The difference (in milliseconds) between
−
  ; The parameter is not used in client mode
+
  ; current timestamp and first timestamp of incoming trunked audio data without miniframe
−
  ; Defaults to disable
+
  ; timestamps at which to restart timestamps build data
−
  ; WARNING: If auto_subscribe is enabled when the module is handling the same domain(s) as
+
  ; This value is used when received trunk timestamp is older then first timestamp
−
  ;  the jabber server this might lead to subscription request aproval on behalf of 'real'
+
; If the difference is less then this value the miniframes will be dropped
−
  ;  jabber users!
+
  ; This will deal with trunk timestamp wraparound or restarted by remote party
−
  ;auto_subscribe=disable
+
  ; 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
 
   
 
   
−
  ; stanza_timeout: integer: The timeout interval (in milliseconds) of a stanza sent by a
+
  ; calltoken_in: boolean: Use call token ip address authentication on incoming calls
−
  ;  jingle session
+
; Note: If the caller don't support the call token IAX extension the call request
−
  ; Session initiate and ping timeout will automatically lead to session termination
+
;  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
+
  ; adjust_ts_out_over: integer: Interval, in milliseconds, to adjust sent audio data
−
  ;resource.notify=
+
;  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
 
   
 
   
−
  ; redirectcount: integer: Default value for outgoing calls redirect counter
+
  ; adjust_ts_out_under: integer: Interval, in milliseconds, to adjust sent audio data
−
  ; This parameter controls the behaviour of an outgoing call terminated
+
  ; timestamp on data underrun (the sender transmits data on a rate less then expected)
−
  ; with 'redirect' reason containing a non empty target
+
  ; Its value will be rouded up to a multiple of 10
−
  ; If non 0 the counter is decreased. If the target is an XMPP uri the call will
+
  ; This value is applied on reload for new calls only
−
  ; be re-executed internally.
+
  ; It can be overridden from routing
−
  ; If the counter is 0 when terminated, the call parameters list will be filled with
+
  ; It can't be greater then 2 * adjust_ts_out_threshold - 1
−
  ; session parameters to let the PBX deal with it.
+
  ; Defaults to 60
−
  ; This parameter can be overridden from routing
+
  ; Allowed interval: 10 .. 2 * adjust_ts_out_threshold - 1
−
  ;redirectcount=0
+
  ;adjust_ts_out_under=60
 
   
 
   
−
  ; dtmfmethod: string: Default value for the method used to send DTMFs
+
  ; challenge_timeout: integer: Interval, in milliseconds, in which a remote party should
−
  ; Allowed values:
+
;  reply with credentials when we are challenging it
−
  ;  jingle: Use the jingle protocol
+
; This value is applied on reload
−
  ;  rfc2833: Send RFC 2833 DTMFs
+
; Minimum allowed value is 5000
−
  ;  inband: Generate inband tones
+
; Defaults to 30000
−
  ;  chat: Send tones as chat messages
+
;challenge_timeout=30000
−
  ; This parameter can be overridden from routing
+
−
  ;dtmfmethod=jingle
+
; tos: keyword: Type Of Service to set in outgoing UDP packets
−
 
+
; numeric TOS value or: lowdelay, throughput, reliability, mincost
−
 
+
;tos=0
−
  [codecs]
+
 +
; 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)
+
−
  g723=default
+
−
 
+
−
; g726: bool: ITU G.726 32-bit (G726-32/8000)
+
−
g726=default
+
−
 
+
−
; g728: bool: ITU G.728 all variations (G728/8000)
+
−
g728=default
+
  
−
; g729: bool: ITU G.729 all variations (G729/8000)
+
if you want to use the default protocol port (4569), or:
−
g729=default
+
  
 +
^200$=iax/iax:diana@10.0.0.1:4570/123
  
−
[hacks]
+
if you know that the called party is using the given port for incoming connections.
−
; 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
+
==Notes==
−
; Defaults to ilbc30
+
−
;ilbc_forced=ilbc30
+
  
−
; ilbc_default: string: Format to use for iLBC when packetization is unknown
+
* 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.
−
; Defaults to ilbc30
+
* When you set a route, be sure you know the destination's port. Again, if the port is incorrect the call will fail.
−
;ilbc_default=ilbc30
+
* If you set the preferred format to a non existing or not enabled one another format will be chosen for library use.
  
−
===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 11: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