SIP Configuration File

Revision as of 15:06, 8 November 2012

This page describes the main configuration file for SIP protocol: ysipchan.conf.

Introduction

ysipchan is a VoIP SIP driver based on YASS library.

Using the default configuration from ysipchan.conf, Yate will behave as a SIP server that listens on all interfaces.

Main functions

In this file you can define:

• listeners - specify on which network interfaces to listen
• how yate works as a SIP registrar.This is enabled by default in server mode, disabled in client mode. This allows users to register to Yate server.
• methods - enabling/disabling SIP request methods
• flood protections mechanism
• hacks - configures parameters that are broken in some implementations

Note: 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.

Configuration

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

; 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
;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

; 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
;registrar=enable in server mode, disable in client mode

; options: bool: Build and send a default 200 answer to OPTIONS requests
;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
;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
;lazy100=no

; 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

; auth_foreign: bool: Attempt to authenticate nonces not generated locally
;auth_foreign=disable

; 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

[registrar]
; Controls the behaviour when acting as registrar

; 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

[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 general]
; This section has the following purposes:
; - Maintain compatibility with old configuration
; - Setup an UDP listener named 'general'
; This section will be processed before any other listener sections
; The following parameters can be overridden from 'general' section: maxpkt, buffer 

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

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

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

; addr: ipaddress: IP address to bind to
; Leave it empty to listen on all available interfaces
;addr= 

; port: integer: Port to bind to
; Defaults to 5060
;port=5060

; rtp_localip: ipaddress: IP address to bind local RTP to, empty to guess best
; This parameter is applied on reload
; 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
;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= 

; 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 

;[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
; Defaults to yes
;udp_force_bind=yes

; addr: ipaddress: IP address to bind to
; Leave it empty to listen on all available interfaces
;addr=

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

; 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
;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

Extending SIP functionalities

A big advantage of Yate is setting on which interface to listen. This is done by configuring your own listeners. Create sections like [listener your_listener_name] that will have the address and the type of the listener.

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.

See also

• SIP in Yate
• Subscriptions Module