Proxies Configuration File: proxies.conf

This file contains a collection of Proxy profiles, each of them with custom parameters and properties for routing SIP requests through OverSIP (i.e. timer values, DNS lookup type, etc). Those profiles can be used within the OverSIP::SipEvents.on_request callback for routing a request with specific settings.

The file is written in YAML format. Each section defines is in the form key / parameters, where key becomes the “Proxy” instance identificator.

default_proxy:
  param1: xxx
  param2: xxx
  param3: xxx

proxy_to_gateways:
  param1: xxx
  param2: xxx
  param3: xxx

[...]

NOTE: The default_proxy section defines the proxy to be chosen when no explicit “Proxy” is given for routing a SIP request.

Check the example proxies.conf file that comes with OverSIP.

Proxy instance parameters

do_record_routing

Enable it for remaining on the path of future requests in a SIP dialog. For initial INVITE, SUBSCRIBE and REFER requests and for in-dialog NOTIFY requests OverSIP adds Record-Route header(s). For REGISTER requests OverSIP adds Path header(s).

Valid values are yes and no (Boolean). Default value is yes.

use_dns_cache

Enable DNS cache for DNS NAPTR/SRV/A/AAAA queries.

Valid values are yes and no (Boolean). Default value is yes.

dns_cache_time

DNS cache time (in seconds). A DNS query result is removed from the cache after the given time.

Minimum value is 300. Default value is 300.

use_blacklist

Enable destination blacklist. When a destination (target) fails due to timeout, connection error or TLS validation error, the target is added to a temporal blacklist and future requests to same target are not attempted until the entry in the blacklist expires.

Valid values are yes and no (Boolean). Default value is yes.

blacklist_time

Blacklist expiration time (in seconds). The time of live of failed targets within the blacklist.

Minimum value is 2, maximum value is 600. Default value is 10.

use_naptr

Perform DNS NAPTR queries. If set, a NAPTR query is performed when the URI host is a domain, has no port nor ;transport param.

Valid values are yes and no (Boolean). Default value is yes.

use_srv

Perform DNS SRV queries. If set, a SRV query is performed when the URI host is a domain and has no port. When disabled, use_naptr is automatically disabled.

Valid values are yes and no (Boolean). Default value is yes.

transport_preference

The list of SIP transports this “Proxy” can use for routing requests (in order of preference). When there is a NAPTR record, its SRV records are tryed in the order given by the NAPTR result (unless force_transport_preference is enabled). If there is not NAPTR record, SRV records are then tryed in the order given by this parameter.

Valid transports are udp, tcp and tls. Valid values for this parameter are:

• A transport (String).
• An array of transports (Array of Strings).

Default value is [tls, tcp, udp] (first try TLS transport).

transport_preference: [udp, tcp, tls]

transport_preference: tls

force_transport_preference

If not set, transport preference is taken from NAPTR records (when available). If set, transport preference are taken from the transport_preference parameter even when there are NAPTR records.

Valid values are yes and no (Boolean). Default value is no.

ip_type_preference

IP type preference. When both IPv4 and IPv6 are available, this parameter determines whether to try first DNS A or AAAA queries. It also determines the IP type this proxy is allowed to use for routing requests.

Valid IP types are ipv4 and ipv6. Valid values for this parameters are:

• An IP type (String).
• An array of IP types (Array of Strings).

Default value is [ipv4, ipv6] (first try IPv4).

ip_type_preference: [ipv6, ipv4]

ip_type_preference: ipv4

dns_failover_on_503

DNS failover on received 503. If a DNS query retrieves more than a single destinations and the first attempt receives a 503 response, then OverSIP tries the next destination (when this parameter is set) or replies a 500 error upstream (when not set).

Valid values are yes and no (Boolean). Default value is yes.

timer_B

INVITE transaction timeout (in seconds). Time waiting for a provisional or final response.

Minimum value is 2, maximum value is 64. Default value is 32.

timer_C

Proxy INVITE transaction timeout (in seconds). Time waiting for a final response.

Minimum value is 8, maximum value is 180. Default value is 120.

timer_F

Non-INVITE transaction timeout (in seconds). Time waiting for a final response.

Minimum value is 2, maximum value is 64. Default value is 32.

callback_on_server_tls_handshake

When enabled OverSIP calls the OverSIP::SipEvents.on_server_tls_handshake callback when establishing an outbound SIP TLS connection with a remote SIP peer.

Valid values are yes and no (Boolean). Default value is yes.