SIP Configuration File

Latest revision as of 12:09, 6 July 2018

Yate has support for SIP Protocol. The module is called ysipchan and the associated configuration file is ysipchan.conf.

This module is a VoIP SIP driver based on YASS library.

By using the default configuration file, Yate will act as a SIP server that listens on all interfaces.

[edit] Main functions

In this file you can define:

• listeners - specify on which network interfaces to listen. Yate supports 3 types of listeners: TCP, TLS, UDP.
• methods - enabling/disabling SIP request methods
• flood protections mechanisms
• hacks - configures parameters that are broken in some implementations

[edit] Extending SIP functionalities

You can allow handling of SIP method requests that are not handled by default by setting them in [methods] section.

Example: SUBSCRIBE, MESSAGE. For method SUBSCRIBE, you can then set in sipfeatures.conf the allowed events, and in subscriptions.conf the actual logic for sending subscribe/notify.

Yate allows other modules/external scripts to initiate the sending of arbitrary SIP client transactions. For this to be allowed, set generate=enable. Use xsip.generate from the module to initiate the transaction.

[edit] Configuration file

Configuration file ysipchan.conf:

; This file configures the SIP channel
;
; NOTES on UDP listeners
; - Address/port can be changed and reloaded
; - If address/port is changed for an enabled listener this will be destroyed and recreated
; - When an UDP listener is destroyed all channels using it will be dropped and
;   all lines using it will be unregistered
; - If the only configured listener is 'general' this one will be the default one
; - After initializing the module will find for a default transport:
;   1: First search for a default listener whose name is not 'general'
;   2: Use 'general' if no other listener is set to be the default


[general]
; This section sets global variables of the implementation
; It also configures a listener named 'general' who is always enabled and set as default
;  UDP transport (if type is udp)
; The listener is always processed before other 'listener ' sections

; ipv6_support: boolean: Enable or disable IPv6 support
; This parameter is applied on reload
; This parameter is ignored if yate was not built with IPv6 support
; Defaults to no
;ipv6_support=no

; type: keyword: Listener type
; Allowed values:
; udp: Build an UDP listener
; tcp: Build a TCP listener
; tls: Build a TLS listener (encrypted TCP)
; Defaults to udp if missing or invalid
;type=

; default: boolean: Specifiy if this is the default transport to use when none specified
; Defaults to yes (unlike the other listeners)
;default=yes

; addr: ipaddress: IP address to bind to
; Leave it empty to listen on all available interfaces
; IPv6: An interface name can be added at the end of the address to bind on a specific
;  interface. This is mandatory for Link Local addresses (e.g. addr=fe80::1%eth0)
;addr=

; port: integer: Port to bind to
; Defaults to 5060 for UDP and TCP, 5061 for TLS listener
;port=5060

; ipv6: boolean: Listen on IPv6 address(es)
; Listen will fail if IPv6 support is not enabled or not supported
; Defaults to 'yes' if IP address is an IPv6 one or 'no' otherwise
;ipv6=no

; udp_force_bind: boolean: Try to use a random port if failed to bind on configured one (UDP only)
; Defaults to yes
;udp_force_bind=yes

; rtp_localip: ipaddress: IP address to bind local RTP to
; This parameter is applied on reload
; TCP/TLS: this parameter is applied on reload for new connections only
; RTP local IP address will default to bound IP address if not binding on all interfaces
; Explicitly set it to empty string to avoid using bound IP address
; IPv6: An interface name can be added at the end of the address to bind on a specific
;  interface. This is mandatory for Link Local addresses (e.g. addr=fe80::1%eth0)
;rtp_localip=

; nat_address: ipaddress: IP address to advertise in SDP, empty to use the local RTP
; This parameter is applied on reload
; Set this parameter when you know your RTP is behind a NAT
;nat_address=

; backlog: integer: Maximum length of the queue of pending connections
; This parameter is ignored for UDP listener
; Set it to 0 for system maximum
; Defaults to 5 if missing or invalid
;backlog=5

; sslcontext: string: SSL context if this is an encrypted connection
; Ignored for non TLS listener, required for TLS listener
;sslcontext=

; maxpkt: int: Maximum received UDP packet size, 524 to 65528, default 1500
; This parameter is applied on reload and can be overridden in UDP listener sections
;maxpkt=1500

; buffer: int: Requested size of UDP socket's receive buffer, 0 to use default
; This can be overridden in UDP listener sections
;buffer=0

; tcp_maxpkt: int: Maximum received TCP packet size, 524 to 65528, default 4096
; This parameter is applied on reload and can be overridden in TCP/TLS listener sections
; The parameter is not applied on reload for already created listeners or connections
;tcp_maxpkt=4096

; tcp_out_rtp_localip: ipaddress: IP address to bind local RTP to for outgoing
;  TCP connections, empty to guess best
; This parameter is applied on reload for new connections only
; IPv6: An interface name can be added at the end of the address to bind on a specific
;  interface. This is mandatory for Link Local addresses (e.g. addr=fe80::1%eth0)
;tcp_out_rtp_localip=

; thread: keyword: Default priority of the SIP handling threads
; Can be one of: lowest, low, normal, high, highest
; High priorities need superuser privileges on POSIX operating systems
; Low priorities are not recommended except for debugging
;thread=normal

; role: string: Role to be set in messages sent by connections using this listener
; This parameter is applied on reload
;role=

; floodevents: int: How many SIP events retrieved in a row trigger a flood warning and the drop mechanism
;  for INVITE/REGISTER/SUBSCRIBE/OPTIONS messages if the flood protection is on.
; NOTE! The drop mechanism is separately activated by the floodprotection setting which is on by default. Also,
;  setting this parameter to 0 will disable the flood warning and protection.
;floodevents=100

; floodprotection: bool: Activate the drop mechanism for INVITE/REGISTER/SUBSCRIBE/OPTIONS messages when
;  the number of SIP events retrieved in a row exceeds the number set for floodevents setting.
; Other messages, as well as reINVITEs, will be allowed. 
; NOTE! This mechanism is activated by default, to disable it configure this parameter to false.
;floodprotection=on

; maxforwards: int: Default Max-Forwards header, used to avoid looping calls
;maxforwards=20

; useragent: string: String to set in User-Agent or Server headers
;useragent=YATE/2.0.0

; realm: string: Authentication realm to offer in authentication requests
;realm=Yate

; transfer: bool: Allow handling the REFER message to perform transfers
;transfer=enable in server mode, disable in client mode

; registrar: bool: Allow the SIP module to receive registration requests
; OBSOLETE - please use "enable" in section [registar]
;registrar=enable in server mode, disable in client mode

; options: bool: Build and send a default 200 answer to OPTIONS requests
; OBSOLETE - please use "enable" in section [options]
;options=enable

; prack: bool: Enable acknowledging provisional 1xx answers (RFC 3262)
;prack=disable

; info: bool: Accept incoming INFO messages
;info=enable

; fork: bool: Follow first forked 2xx answer on early dialogs
; This parameter is applied on reload
;fork=enable

; progress: bool: Send an "183 Session Progress" just after successfull routing
;progress=disable

; generate: bool: Allow Yate messages to send arbitrary SIP client transactions
;generate=disable

; nat: bool: Enable automatic NAT support
;nat=enable

; ignorevia: bool: Ignore Via headers and send answer back to the source
;  This violates RFC 3261 but is required to support NAT over UDP transport.
;ignorevia=enable

; lazy100: bool: Do not generate an initial "100 Trying" for non-INVITE
;  transactions unless a retransmission arrives before having a final answer
; This parameter is applied on reload
;lazy100=no

; t1: int: Value of SIP T1 timer in milliseconds
; This is the RTT Estimate and several other SIP timers are derived from it
; Valid values are between 100 and 5000, outside range uses the default of 500
; This parameter is applied on reload
;t1=500

; t4: int: Value of SIP T4 timer in milliseconds
; This is the maximum message lifetime, several other SIP timers are derived from it
; It is enforced to be at least 3 * T1
; Valid values are between 1000 and 25000, outside range uses the default of 5000
; This parameter is applied on reload
;t4=5000

; check_allow_info: bool: Check 'Allow' header in INVITE and OK for INFO support
; If enabled and INFO is not supported the 'info' dtmf method will be disabled
; This parameter can be overridden from routing by 'ocheck_allow_info' for outgoing call leg
;  and 'icheck_allow_info' for incoming call leg
; This parameter is ignored if info method is not enabled
; This parameter is applied on reload for new calls only
;check_allow_info=yes

; missing_allow_info: bool: The default value for dtmf info support if
;  'check_allow_info' is enabled and the 'Allow' header is missing
; This parameter can be overridden from routing by 'omissing_allow_info' for outgoing call leg
;  and 'imissing_allow_info' for incoming call leg
; This parameter is applied on reload for new calls only
;missing_allow_info=enable

; dtmfmethods: string: Comma separated list of methods used to send DTMFs
; Allowed values in list:
;  info: Use SIP INFO if initial transaction finished
;  rfc2833: Use RFC 2833 signals if remote party advertised support
;  inband: Send tones in audio stream
; The methods will be used in the listed order
; Defaults to 'rfc2833,info,inband' if missing or empty
; Invalid values are ignored
; E.g.
;   'info,foo' leads to 'info'
;   'foo,foo1' leads to 'rfc2833,info,inband'
; This parameter can be overridden from routing by 'odtmfmethods' for outgoing call leg
;  and 'idtmfmethods' for incoming call leg
; Also, this parameter can be overridden in chan.dtmf messages by a 'methods' parameter
; NOTE:
;   When overridden from chan.dtmf an empty or invalid 'methods' parameter will be ignored
;   Methods indicated in chan.dtmf message will be intersected with channel capabilities
;    unless an explicit boolean true 'methods_override' parameter is present
; This parameter is applied on reload for new calls only
;dtmfmethods=rfc2833,info,inband

; honor_dtmf_detect: bool: Honor DTMF detected method when sending DTMFs
; If enabled the channel will try to send a DTMF using the same method as received
; If the detected method is not enabled it won't be used
; This parameter can be overridden from routing by 'ohonor_dtmf_detect' for outgoing call leg
;  and 'ihonor_dtmf_detect' for incoming call leg
; This parameter is applied on reload for new calls only
; Defaults to enable
;honor_dtmf_detect=enable

; rfc2833: bool: Offer RFC2833 telephone-event by default
; A numeric payload >= 96 can be provided
;rfc2833=yes

; privacy: bool: Process and generate privacy related SIP headers
;privacy=disable

; secure: bool: Generate and accept RFC 4568 security descriptors for SRTP
;secure=disable

; forward_sdp: bool: Include the raw SDP body to be used as-is for forwarding RTP
;forward_sdp=disable

; rtp_start: bool: Start RTP when sending 200 on incoming instead of receiving ACK
;rtp_start=disable

; multi_ringing: bool: Accept provisional (1xx) messages even after 180 Ringing
;multi_ringing=disable

; refresh_nosdp: bool: Accept session refresh reINVITEs that lack a SDP offer
;refresh_nosdp=enable

; update_target: bool: Update dialog target from Contact in reINVITE
;update_target=disable

; preventive_bye: bool: If possible send a BYE besides CANCEL for unanswered calls
;preventive_bye=enable

; auth_foreign: bool: Attempt to authenticate nonces not generated locally
; This parameter is applied on reload
;auth_foreign=disable

;auth_copy_headers: string: Comma separated list of headers to be copied in user.auth message
; This parameter is applied on reload
;auth_copy_headers=

; body_encoding: keyword: Encoding used for received generic binary bodies
;  Can be one of: base64, hex, hexs, raw
;body_encoding=base64

; async_generic: bool: Process generic SIP messages asynchronously in their own thread
;async_generic=enable

; flags: int: Miscellaneous SIP engine flags for broken implementations
; See SIPMessage::Flags and SIPMessage::complete() in the source for gory details
;flags=0

; autochangeparty: bool: Automatically change remote ip/port when a channel receives
;  a response or a new transaction from a different address
; E.g. if an INVITE sent to 1.2.3.4:5060 receives OK from 1.2.3.4:5080 the ACK
;  (and subsequent transactions) will be sent to 1.2.3.4:5080
; Defaults to disable
; This parameter is applied on reload
;autochangeparty=disable

; ssl_certificate_file: string: File containing client SSL certificate to present
; This parameter is used for outgoing encrypted connections if a certificate
;  is requested by the server during SSL negotiation
; The file path is relative to configuration path
; This parameter is applied on reload
;ssl_certificate_file=

; ssl_key_file: string: Optional file containing the key of the certificate
;  set in ssl_certificate_file
; The file path is relative to configuration path
; The certificate file must contain the key if this parameter is empty
; This parameter is applied on reload
;ssl_key_file=

; sip_req_trans_count: integer: The number of times to transmit a sip request
;  when retransmission is required (e.g. on non reliable transports)
; This parameter is applied on reload
; Minimum allowed value is 2, maximum allowed value is 10
; Defaults to 4 if missing, invalid or out of bounds
;sip_req_trans_count=4

; sip_rsp_trans_count: integer: The number of times to transmit a final response
;  to a sip request when retransmission is required
; Retransmission is required for all responses to INVITE requests on non reliable
;  transports or 2xx responses over reliable transports
; This parameter is applied on reload
; Minimum allowed value is 2, maximum allowed value is 10
; Defaults to 5 if missing, invalid or out of bounds
;sip_rsp_trans_count=5

; maxchans: int: Maximum number of channels running at once
; 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 SIP messages to output
; This parameter is applied on reload
; Defaults to yes
;printmsg=yes


[options]
; Controls the behaviour for SIP options retrieval

; enable: bool: Allow the SIP module to receive OPTIONS requests
;enable=yes


[registrar]
; Controls the behaviour when acting as registrar

; enable: bool: Allow the SIP module to receive registration requests
;enable=yes in server mode, no in client mode

; expires_min: int: Minimum allowed expiration time in seconds
;expires_min=60

; expires_def: int: Default expiration time if not present in REGISTER request
;expires_def=600

; expires_max: int: Value used to limit the expiration time to something sane
;expires_max=3600

; auth_required: bool: Automatically challenge all clients for authentication
;auth_required=enable

; nat_refresh: int: Proposed client NAT refresh interval in seconds
;nat_refresh=25

; async_process: bool: Process registrations asynchronously in their own thread
;async_process=enable


[message]
; Controls the behaviour for SIP messaging

; enable: bool: Allow the SIP module to receive MESSAGE requests
;enable=no

; auth_required: bool: Automatically challenge all senders for authentication
;auth_required=enable

; async_process: bool: Process SIP MESSAGE asynchronously in their own thread
;async_process=enable


[sip-t]
; Controls the SIP-T parameter handling

; isup: bool: Build outgoing or decode incoming application/isup bodies
; If enabled an incoming application/isup body will be decoded and added to
;  the engine message issued by the receiving channel
; If the channel needs to add more then one body to an outgoing message, a
;  multipart/mixed body will be attached to the message
; Defaults to disable
;isup=disable


[codecs]
; This section allows to individually enable or disable the codecs

; default: bool: Enable all unlisted codecs by default if a transcoder exists
;default=enable

; mulaw: bool: Companded-only G711 mu-law (PCMU/8000)
;mulaw=default

; alaw: bool: Companded-only G711 a-law (PCMU/8000)
;alaw=default

; gsm: bool: European GSM 06.10 (GSM/8000)
;gsm=default

; lpc10: bool: Linear Prediction Codec (LPC/8000)
;lpc10=default

; ilbc: bool: Internet Low Bandwidth Codec (iLBC/8000)
;ilbc=default

; amr: bool: Adaptive Multi-Rate 3GPP (AMR/8000)
;amr=default

; slin: bool: Signed Linear 16-bit uncompressed (L16/8000)
;slin=default

; 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)
;g729=default

; g729_annexb: bool: G.729 Annex B (VAD) support default (if not in SDP)
; NOTE: RFC 3555 specifies the default should be yes
;g729_annexb=no

; amr_octet: bool: Octet aligned AMR RTP payload default (if not in SDP)
; NOTE: RFC 4867 (and older 3267) specifies the default is bandwidth efficient
;amr_octet=no


[methods]
; Use this section to allow server processing of various SIP methods by
;  handling Yate messages with name "sip.methodname".
; Each line has to be of the form:
;  methodname=boolean
; You must use lower case method names. The boolean value defaults to
;  true and allows automatically challenging the requests for authentication
;
; Example for accepting SECRET with authentication and MESSAGE without:
;  secret=yes
;  message=no


[hacks]
; This section holds the dirty stuff required to work with some broken
;  implementations
;
; ilbc_forced: string: Format to force as iLBC, can be: ilbc20 or ilbc30
;ilbc_forced=
;
; ilbc_default: string: Format to use for iLBC when packetization is unknown
;ilbc_default=ilbc30

; g729_annexb: bool: Force G.729 Annex B support when parsing the SDP
;g729_annexb=

; ignore_missing_ack: bool: Ignore missing ACK on INVITE, don't drop the calls
;ignore_missing_ack=no

; 1xx_change_formats: bool: Provisional messages can change the formats list
;1xx_change_formats=yes

; ignore_sdp_port: bool: Ignore SDP changes if only the port is different
; This allows preserving the local RTP session and port
;ignore_sdp_port=no

; ignore_sdp_addr: bool: Ignore SDP changes if only the address is different
; This allows preserving the local RTP session and port
;ignore_sdp_addr=no


;[listener name]
; This section configures a listener named 'name' ('general' is reserved and will be ignored)
; The following parameters can be overridden from 'general' section:
;   UDP: maxpkt, buffer
;   TCP/TLS: tcp_maxpkt

; type: keyword: Listener type
; Allowed values:
; udp: Build an UDP listener
; tcp: Build a TCP listener
; tls: Build a TLS listener (encrypted TCP)
; Defaults to udp if missing or invalid
;type=

; enable: boolean: Enable or disable this listener
; This parameter is applied on reload and defaults to yes
;enable=yes

; default: boolean: UDP only: specifiy if this is the default transport to use when none specified
; Defaults to no
;default=no

; udp_force_bind: boolean: UDP only: try to use a random port if failed to bind on configured one (UDP only)
; Defaults to yes
;udp_force_bind=yes

; addr: ipaddress: IP address to bind to
; Leave it empty to listen on all available interfaces
; IPv6: An interface name can be added at the end of the address to bind on a specific
;  interface. This is mandatory for Link Local addresses (e.g. addr=fe80::1%eth0)
;addr=

; port: integer: Port to bind to
; Defaults to 5060 for UDP and TCP, 5061 for TLS listeners
;port=

; ipv6: boolean: Listen on IPv6 address(es)
; Listen will fail if IPv6 support is not enabled or not supported
; Defaults to 'yes' if IP address is an IPv6 one or 'no' otherwise
;ipv6=no

; rtp_localip: ipaddress: IP address to bind local RTP to
; This parameter is applied on reload
; TCP/TLS: this parameter is applied on reload for new connections only
; RTP local IP address will default to bound IP address if not binding on all interfaces
; Explicitly set it to empty string to avoid using bound IP address
; IPv6: An interface name can be added at the end of the address to bind on a specific
;  interface. This is mandatory for Link Local addresses (e.g. addr=fe80::1%eth0)
;rtp_localip=

; backlog: integer: Maximum length of the queue of pending connections
; This parameter is ignored for UDP listeners
; Set it to 0 for system maximum
; Defaults to 5 if missing or invalid
;backlog=5

; sslcontext: string: SSL context if this is an encrypted connection
; Ignored for non TLS listeners, required for TLS listeners
;sslcontext=

; thread: keyword: Listener thread priority
; Can be one of: lowest, low, normal, high, highest
; High priorities need superuser privileges on POSIX operating systems
; Low priorities are not recommended except for debugging
;thread=normal

; role: string: Role to be set in messages sent by connections using this listener
; This parameter is applied on reload
;role=

[edit] Parameters

This are some parameters that can be configured in SIP channel module:

• The port options sets the port to which Yate will bind for SIP signalling. You may also specify an IP address (for multihomed machines) else Yate will listen on all interfaces.

• The registrar option tells Yate to accept registration. Don't forget that registering a user isn't the same as user authentication. This option should be used together with regfile or register modules.

• Ignorevia it's doing what his name is saying. It's using as a response IP the source from where the packet comes insted of the IP in Via. This will allow most of the SIP clients to pass the NAT. This is enabled by default.

• The nat setting will try to replace nonroutable IP addresses of the RTP media stream with the address the SIP signalling was received from. This significantly improves chances that clients behind a dumb NAT get normal voice. This option is also enabled by default.

• The usage of media formats is controlled by the [codecs] section. If default is set to false every codec will need to be enabled manually in the section. If default is set to true then the codecs for which Yate has a translator will be enabled by default. Every default codec setting can be overriden by explicitly setting it to true or false.

• Subscribe allows SIP clients to subscribe to specific events. To use this feature in [default] section enable parameter generate.

• Yate can handle or generate SIP MESSAGE requests through sip.message and xsip.generate messages.

• lazy100 is used to send INFO message dialogless

• dtmfmethods 3 ways of sending DTMF in Yate:

- info: Use SIP INFO if initial transaction finished

- rfc2833: Use RFC 2833 signals if remote party advertised support

- inband: Send tones in audio stream

• TCP/TLS support in Yate set by params: ssl_certificate_file and ssl_key_file

• If retransmision is required you can set the:

- number of times to transmit a sip request (parameter to set sip_req_trans_count)

- number of times to transmit a final response (parameter to set sip_rsp_trans_count)

• isup

- ISUP signalling can be encapsulated in SIP using 2 protocols: SIP-T and SIP-I. Only SIP-T is supported by Yate.

- To enable SIP-T support, enable the isup parameter in section [sip-t].

- Warning: Watch out for bogus SIP implementations. Some SIP clients will reply the MIME formatted SDP with a "488 Not Acceptable Here". Eg: X-Lite, Intelbras TIP-100

• A set of listeners can be set so that Yate will listen to that interfaces. In a routing module: parameter oconnection_id it can be used to set on which IP to send outbound call legs for routing, and you can call an sip channel like this: extension=sip/sip:user@ip:port.

See also

• SIP SIPS URI Support
• SIP IPv6 Support
• SIP Features Module
• Register
• Regfile
• Telephony