1.3.1 Voipswitch configuration file

The configuration file, voipswitch_conifg.xml, is located in voipswitch’s main directory, along with the voipswitch executable file. When voipswitch application starts it looks for this file in the current folder.

An exemplary file with default settings can be downloaded from here (todo).

Below we will focus only on the basic settings required in all cases.

Database configuration

<database>

     <param name="ipaddr" value="127.0.0.1" />

     <param name="port" value="3306" />

     <param name="username" value="root" />

     <param name="password" value="#DB_PASSWORD#" />

     <param name="connections" value="40" />

     <param name="dbname" value="voipswitch" />

</database>

This section contains information required to connect to a database server hosting voipswitch schemas. When entering the IP address make sure it is accessible from the softswitch’s host computer.

The “connections” parameter defines the number of connections with the database server that the softswitch will try to open on start. By default it is set to 40 but it is recommended to increase this value when handling significant traffic, more on the optimal configuration depending on the nature of the services is explained in chapter (todo).

SIP listeners

<listener type="sip">

     <param name="ipaddr" value="#IP_ADDRESS#" />

     <param name="port" value="5060" />

     <param name="transport" value="udp" />

</listener>

A SIP listener is a socket on which the server is listening for new connections from clients. The socket has to be bound to an internet address and has a transport type assigned which can be UDP, TCP or TLS-TCP.

One server can run multiple listeners, the only requirement is that their IP and port pairs must be different for the same transport type. Below is the list of default port values:

UDP – 5060
TCP – 5060
TLS-TCP – 5061

For TLS-TCP there is an additional parameter with the name of the certificate file.

<listener type="sip">

     <param name="ipaddr" value="#IP_ADDRESS#" />

     <param name="port" value="5061" />

     <param name="transport" value="tls-tcp" />

     <param name="tls-certificate" value="VPS.cert" />

</listener>

If a server has several IP addresses you can bind the SIP service to any of the addresses. For example if you have separate networks without any route between them you can have voipswitch to act as a bridge on the SIP level only thus isolating your protected zone from internet. This is in fact the SBC’s role.

To create more than one SIP listener just copy the above section and change the relevant parameters.

If the server is placed in a private zone behind a router with port forwarding, the SIP listeners will be bound to a private IP non routable from internet. It means that also the endpoints on external networks will not be able to respond to packets coming from the server as they would use the private IP from the VIA header. To make it work the softswitch has to change the private IP in its SIP headers to its external IP address set on the forwarding router. The IP must be specified in the following entry added to the Listener tag.

<!-- masquerade when voipswitch runs on local ip -->

<param name="masq-ipaddr" value="#EXTERNAL_IP_ADDRESS#" />

<param name="masq-port" value="5060" />

RTP port

<protocol type="rtp">

     <param name="start-port" value="6000" />

</protocol>

This section defines the starting port for RTP protocol. When a new media session is being negotiated using SDP offer-answer mechanism the softswitch allocates a next available port from the range above the number defined here. By default it is 6000.

This setting is used only in full proxy configuration where media are sent through the server.

Registrar listener

<listener type="registrar">

     <param name="ipaddr" value="#IP_ADDRESS#" />

     <param name="port" value="5060" />

     <param name="register-expiration" value="60" />

     <param name="subscribe-expiration" value="3600" />

     <param name="transport" value="udp" />

</listener>

Registrar service is represented by a separate section, independent from the SIP listeners group.

If you run registrar listener on the same IP as the SIP listener it will use by default the same port 5060. There is no conflict in this configuration though, for the listeners use in fact the same port and only logically divide packets by the type of incoming requests.

The registrar can use one of the three transport types, same as for the SIP service, i.e.: UDP, TCP and TLS-TCP. If you work with various devices you may need to have two or more registrar listeners running, for example one with UDP and another for devices supporting encrypted SIP over TLS.

There are two additional parameters, namely REGISTER-EXPIRATION and SUBSCRIBE-EXPIRATION.

REGISTER-EXPIRATION is a register expiry time after which a registration session is removed from the location database if has not been renewed before. By default this time is set to 3600 seconds.

SUBSCRIBE-EXPIRATION is the time after which a subscription to the presence service is removed if has not been renewed before. By default it is set to 3600 seconds.

STUN listener

<listener type="stun">

     <param name="ipaddr" value="#IP_ADDRESS#" />

     <param name="port" value="3478" />

</listener>

The STUN listener is set by default to start on port 3478 which is the standard STUN service port.

Dumps

<minidump>

     <param name="enable" value="true" />

     <param name="path" value="logs" />

     <param name="max-dump-files-allowed" value="1" />

</minidump>

In this section you can enable the voipswitch application to write its crash dump files. These are actually mini dumps generated by the application if an internal error occurs. The files contain information which are usually very helpful in further analysis by developers.

The files are stored in a directory defined in the path key.

The max-dump-files-allowed value (by default set to 1) defines how many dumps should be generated since the application starts. For example if you want to catch a specific situation only you may want to keep this number low in order to get only few first files without making the softswitch continuously write next dumps to the hard drive which can consume resources especially when the error occurs repeatedly.

The dump files name are of the following pattern: date_time_ipAddress_versionNumber_dumpNumber.dmp

For example 2015-04-13_15-12-20_ip37.28.157.2_v3.0.315_(000).dmp

Resource list (buddy list)

<web_service>

     <param name="ipaddr" value="37.28.157.2"/>

     <param name="port" value="80"/>

     <param name="username" value=""/>

     <param name="password" value=""/>

     <param name="service" value="emc/bl.ashx"/>

</web_service>

The section tagged as web_service is required in the RCS deployments. Voipswitch sends a request to the EMCI API to get the JSON formatted list of buddies of a user who has subscribed to the RCS presence service.

PUSH service

<push_service>

     <param name="ipaddr" value="107.23.18.138"/>

     <param name="port" value="81"/>

     <param name="username" value=""/>

     <param name="password" value=""/>

     <param name="service" value="/emc.ashx"/>

</push_service>

PUSH service section defines the URL of the EMCI API push method. Voipswitch sends PUSH request to that URL whenever the called user is not registered or is not responding.

Cluster configuration

It applies to versions 2.1.138 and later.

  <cluster>
  <param name="id-voipswitch" value="1" />
  <param name="active" value="true" />
  </cluster>

"id-voipswitch" should have values from 1-99

To define voipswitch cluster nodes an entry in database "settings" table is required with "name" = "Cluster_nodes" and "category" = "voipswitch".
Node number should match cluster setting in voipswitch_config.xml file.

INSERT INTO settings (name, value, category) VALUES ('Cluster_nodes', '{  
   "nodes":{  
      "1":"37.28.157.34:5060",
      "2":"37.28.157.35:5070"
   }
}','voipswitch');

Voipswitch documentation