/ home / Documentation / 1.4.x / Configuration / oversip.conf

Main Configuration File: oversip.conf

This is the main configuration file of OverSIP. It’s written in YAML format and contains different sections with configurable parameters.

NOTE: Don’t use tab for indentation as it’s not allowed in YAML files. Instead, respect the existing indentation spaces in the file.

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

Sections and Parameters

Section core

nameservers

DNS nameserver address(es) to use. Valid values are:

  • An IPv4 address (String).
  • An array of IPv4 addresses (Array of Strings).
  • null: nameservers in /etc/resolv.conf are used.

Default value is null.

NOTE: The built-in DNS resolver does not perform recursive DNS queries and thus OverSIP requires a recursive DNS server (i.e. Unbound, a validating, recursive and caching DNS resolver).

nameservers: 127.0.0.1

nameservers: [ 127.0.0.1, 192.168.100.123 ]

nameservers: null

syslog_facility

Syslog facility. Valid valules are kern, user, daemon, local0…local (String). Default value is daemon.

syslog_facility: daemon

syslog_level

Syslog level (logs with a severity below this value won’t be logged to Syslog). Valid values are debug, info, notice, warn, error, crit (String). Default value is info.

syslog_level: debug

Section sip

sip_udp

Enable/disable SIP UDP transport. Valid values are yes and no (Boolean). Default value is yes.

sip_tcp

Enable/disable SIP TCP transport. Valid values are yes and no (Boolean). Default value is yes.

sip_tls

Enable/disable SIP TLS-TCP secure transport. Valid values are yes and no (Boolean). Default value is yes.

enable_ipv4

Enable/disable IPv4 for SIP. Valid values are yes and no (Boolean). Default value is yes.

listen_ipv4

IPv4 in which OverSIP listens for SIP messages. Using 0.0.0.0 is not allowed. Valid values are:

  • An IPv4 address (String).
  • null for IPv4 autodiscovery.

Default value is null.

listen_ipv4: 1.2.3.4

advertised_ipv4

NEW in 1.4.x

IPv4 advertised in Via, Record-Route and Path headers. Useful when OverSIP runs behind a NAT and must expose the router public IPv4 to the outside.

Default value is null.

advertised_ipv4: 9.8.7.6

enable_ipv6

Enable/disable IPv6 for SIP. Valid values are yes and no (Boolean). Default value is yes.

listen_ipv6

IPv6 in which OverSIP listens for SIP messages. Using :: is not allowed. Valid values are:

  • An IPv6 address (String).
  • null for IPv6 autodiscovery.

Default value is null.

listen_ipv6: 2001:838:2:1::30:67

advertised_ipv6

NEW in 1.4.x

IPv6 advertised in Via, Record-Route and Path headers. Useful when OverSIP runs behind a NAT and must expose the router public IPv6 to the outside.

Default value is null.

advertised_ipv6: 123:456::abcd

listen_port

Listening port for SIP over UDP and TCP. Default value is 5060.

listen_port: 9090

listen_port_tls

Listening port for SIP over TLS-TCP. Default value is 5061.

listen_port_tls: 9091

use_tls_tunnel

When enabled, OverSIP spawns Stud (“The Scalable TLS Unwrapping Daemon”) processes for handling inbound TLS connections. Stud listens in the addresses given by listen_ipv4 / listen_ipv6 and listen_port_tls, terminates the TLS connection from clients and forwards the unencrypted traffic to the addresses 127.0.0.1 / ::1 and port listen_port_tls_tunnel in which OverSIP listens for TCP connections.

When disabled, OverSIP handles inbound TLS connections by itself without spawning Stud processes.

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

NOTE: It’s recommended to enable this option since Stud manages incoming TLS connections very efficiently.
NOTE: Outbound TLS connections are handled by OverSIP itself.

listen_port_tls_tunnel

The port in which OverSIP listens for TCP connections from the Stud processes. Default value is 5062.

listen_port_tls_tunnel: 9092

callback_on_client_tls_handshake

When enabled OverSIP calls the OverSIP::SipEvents.on_client_tls_handshake callback when a SIP client attemps a TLS handshake with OverSIP.

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

NOTE: When the SIP parameter use_tls_tunnel is enabled, incoming SIP TLS connections are handled by Stud processes and thus the callback is not called.

callback_on_client_tls_handshake: yes

local_domains

SIP local domains OverSIP is responsible for. IP:port addresses in which OverSIP listen for incoming SIP traffic are automatically added to this list. Valid values are:

  • A domain (String).
  • An array of domains (Array of Strings).
  • null: just listening addresses are matched as local destinations.

Default value is null.

local_domains: example.net

local_domains: [ proxy1.example.net, proxy2.example.net ]

tcp_keepalive_interval

TCP keepalive interval (in seconds). When acting as a SIP TLS/TCP server, OverSIP sends TCP packets with null data payload. If not set, TCP keepalive is disabled.

Minimun value is 180 seconds. Default value is null (not enabled).

tcp_keepalive_interval: 360

record_route_hostname_tls_ipv4

When enabled, OverSIP writes the given domain/hostname in the Record-Route/Path headers when proxing a SIP request via TLS or WSS transport over IPv4 (instead of writing the listening IPv4 address). This is convenient when a peer open a new TLS/WSS connection to OverSIP for sending an in-dialog request so the peer can check whether the host part of the top Route header matches a domain in the certificate OverSIP provides to the peer during the TLS negotiation. This requirement is docummented in RFC 5922 (“Domain Certificates in SIP”) section 7.5.

NOTE: If set, the domain/hostname should also be added to the local_domains list.

Valid values are:

  • A domain/hostname (String).
  • null: not set, the server IPv4 will be used as URI hostpart in the Record-Route/Path headers.

Default value is null.

record_route_hostname_tls_ipv4: proxy1.example.net

record_route_hostname_tls_ipv6

Same as record_route_hostname_tls_ipv4 but for IPv6.

Section websocket

sip_ws

Enable/disable SIP WS transport. Valid values are yes and no (Boolean). Default value is yes.

sip_wss

Enable/disable SIP WSS secure transport. Valid values are yes and no (Boolean). Default value is yes.

enable_ipv4

Enable/disable IPv4 for WebSocket. Valid values are yes and no (Boolean). Default value is yes.

listen_ipv4

IPv4 in which OverSIP listens for WebSocket connections. Using 0.0.0.0 is not allowed. Valid values are:

  • An IPv4 address (String).
  • null for IPv4 autodiscovery.

Default value is null.

advertised_ipv4

NEW in 1.4.x

IPv4 advertised in Via, Record-Route and Path headers. Useful when OverSIP runs behind a NAT and must expose the router public IPv4 to the outside.

Default value is null.

advertised_ipv4: 9.8.7.6

enable_ipv6

Enable/disable IPv6 for WebSocket. Valid values are yes and no (Boolean). Default value is yes.

listen_ipv6

IPv6 in which OverSIP listens for WebSocket connections. Using :: is not allowed. Valid values are:

  • An IPv6 address (String).
  • null for IPv6 autodiscovery.

Default value is null.

advertised_ipv6

NEW in 1.4.x

IPv6 advertised in Via, Record-Route and Path headers. Useful when OverSIP runs behind a NAT and must expose the router public IPv6 to the outside.

Default value is null.

advertised_ipv6: 123:456::abcd

listen_port

Listening port for WebSocket (over plain HTTP) connections. Default value is 10080.

listen_port_tls

Listening port for WebSocket (over secure HTTPS) connections. Default value is 10443.

use_tls_tunnel

Spawn Stud processes for handling inbound WebSocket (over secure HTTPS) connections. Valid values are yes and no (Boolean). Default value is yes.

listen_port_tls_tunnel

The port in which OverSIP listens for TCP connections from the Stud processes. Default value is 10444.

callback_on_client_tls_handshake

When enabled OverSIP calls the OverSIP::WebSocket.on_client_tls_handshake callback when a WebSocket client attemps a TLS handshake with OverSIP.

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

NOTE: When the WebSocket parameter use_tls_tunnel is enabled, incoming WebSocket TLS connections are handled by Stud processes and thus the callback is not called.

max_ws_message_size

WebSocket message max size (in bytes). Default value is 65536.

max_ws_frame_size

WebSocket frame max size (in bytes). Default value is 65536.

ws_keepalive_interval

WebSocket PING frames interval (in seconds). If set, OverSIP sends WebSocket PING control frames as the given interval.

Minimun value is 180. Default value is null (not set).

Section tls

Parameters under this section affect to any interface of OverSIP using TLS, including SIP and WebSocket.

public_cert

Server TLS public certificate. It must be the name of a readable file containing a chain of X509 certificates in PEM format, with the most-resolved certificate at the top of the file, successive intermediate certs in the middle, and the root (or CA) cert at the bottom.

Valid values are:

  • File path (String): the path to the file with the public certificate.
  • null: TLS is disabled.

NOTE: If a relative path is given, it’s searched under the tls/ directoy in the OverSIP configuration directory (typically /etc/oversip/).

Default value is null (not set).

public_cert: example.net.crt

public_cert: /root/certificates/example.net.crt

private_cert

Server TLS private certificate. It must be the name of a readable file containing a private key in the PEM format.

Valid values are:

  • File path (String): the path to the file with the private certificate.
  • null: TLS is disabled.

NOTE: If a relative path is given, it’s searched under the tls/ directoy in the OverSIP configuration directory (typically /etc/oversip/).
NOTE: The private key MUST NOT require password.

Default value is null (not set).

private_cert: example.net.key

private_cert: /root/certificates/example.net.key

ca_dir

Directory of TLS CAs. It must be the name of a readable directory. Every file in that directory will be inspected and every X509 certificate in PEM format extracted.

This is useful for storing the list of trusted CAs (i.e. CA Certs from mozilla.org) or CAs not in a standard trust hierarchy. Setting this parameter is required for validating certificates provided by remote peers (feature not available when using Stud for handling inbound TLS connections).

NOTE: Check the F.A.Q. entry How to Upgrade CA Root Certificates.

Valid values are:

  • Directory path (String): the path to the directory containing X509 files in PEM format.
  • null: disabled, peer’s provided certificated cannot be validated.

NOTE: If a relative path is given, it’s searched under the tls/ directoy in the OverSIP configuration directory (typically /etc/oversip/).

Default value is ca/.

ca_dir: ca/

ca_dir: /root/certificates/ca/

/ home / Documentation / 1.4.x / Configuration / oversip.conf