Chapter 3. Configuration

3.1. The configuration file 'siproxd.conf'

Siproxd by default searches for its configuration file in the following locations:

The following is a list of directives that do exist. Note that string values MUST NOT contain spaces or tabs. Also read the explanations included in the supplied example configuration file fro more explanation. Items with a # in front are normally disabled / not defined.

To start with siproxd in the first run, just adapt the interface definition for the inbound and outbound network interfaces (if_inbound and if_outbound).

Definition of network interfaces for the inbound network (local network where your SIP client is connected, this network normally uses IP addresses from on of the private IP ranges like 10.x.x.x, 192.168.x.x) and outbound network (your connection to the Internet, normally this interface has a public IP assigned by your provider).

if_inbound  = eth0
if_outbound = ppp0

Usually only the if_inbound and if_outbound directives will be used. The host_outbound directive comes into play when running siproxd "in front of" a NAT router. Please check the configuration examples in this document for more details. Also check the STUN plugin.

# host_outbound = <my_public_ip_address>

Access control lists for incoming SIP registrations and SIP traffic in general. These are comma separated lists of the form <IP>/<mask>, note that no spaces are allowed within the list (the configuration file parser cannot yet handle spaces).

# hosts_allow_reg = 192.168.1.0/24,192.168.2.0/24
# hosts_allow_sip = 123.45.0.0/16,123.46.0.0/16
# hosts_deny_sip  = 10.0.0.0/8,11.0.0.0/8

Port to listen for incoming SIP messages. 5060 is usually the correct choice, don't change this unless you have a reason to.

sip_listen_port = 5060

Shall siproxd run as daemon? Usually 1 is the correct choice. If you want siproxd not to daemonize and keep running in foreground and writing its output to the terminal set this to 0.

daemonize = 1

Siproxd does log using the syslog() facility when running a daemon. This setting controls how much logging is done:

silence_log = 0

If siproxd is started as root, it can drop the root privileges and change its user ID at startup. It also can put itself into a chroot() jail (see 4.2 for details)

user = nobody
# chrootjail = /var/lib/siproxd/

Where to store the current registrations and the cycle in seconds to perform the cyclic writing. This allows siproxd to remember registration across a restart. An empty value means we do not save registrations. The specified directory path must exist.

registration_file = /var/lib/siproxd/siproxd_registrations
autosave_registrations = 300

Where to create the PID file.

pid_file = /var/run/siproxd/siproxd.pid

Enable/disable the RTP proxy. This must always be enabled. In some future release this directive will become obsolete and will be removed.

rtp_proxy_enable = 1

Port range (UDP) that siproxd will use for incoming and outgoing RTP traffic. A firewall must be configured to allow traffic from and to these ports (UDP only). By default the range 7070 up to (and including) 7089 is used. This allows up to 10 simultaneous calls (2 ports per call). If you need more simultaneous calls, increase the range.

rtp_port_low  = 7070
rtp_port_high = 7089

Timeout for an RTP stream. If for the specified number of seconds no data is relayed on an active stream, it is considered dead and will be killed.

rtp_timeout = 300

DSCP (differentiated services) value to be assigned to RTP and SIP UDP packets. Allows QOS aware routers to handle different types traffic with different priorities.

rtp_dscp = 46
sip_dscp = 0

If a REGISTER request does not contain an Expires header or expires= parameter in the Contact header, this number of seconds will be used and reported back to the UA in the answer.

default_expires = 600

TCP inactivity timeout: For TCP SIP signalling, this indicates the inactivity timeout (seconds) after that an idling TCP connection is disconnected. Note that making this too short may cause multiple parallell registrations for the same phone. This timeout must be set larger than the used registration interval.

tcp_timeout = 600

Timeout for connection attempts in msec: How many msecs shall siproxd wait for an successful connect when establishing an outgoing SIP signalling connection. This should be kept as short as possible as waiting for an TCP connection to establish is a BLOCKING operation - while waiting for a connect to succeed not SIP messages are processed (RTP is not affected).

tcp_connect_timeout = 500

TCP keepalive period: For TCP SIP signalling, if > 0 empty SIP packets will be sent every 'n' seconds to keep the connection alive. Default is off.

tcp_keepalive = 20

If siproxd is used as registration server and authentication is wanted, define the following directive. If proxy_auth_realm is defined (a string), clients will be forced to authenticate themselfs to the proxy (for registration only). To disable Authentication, simply comment out this line. Default is disabled.

# proxy_auth_realm = Authentication_Realm

The password to be used for authentication may be a global one

# proxy_auth_passwd = some_password

or on a per user base, stored in its own file. proxy_auth_pwfile takes precedence over proxy_auth_passwd

# proxy_auth_pwfile = /etc/mysiproxd_passwd.cfg

To enable additional debug output of siproxd. This is a bit pattern representing the following items. Default is 0x0 - disabled. See below in this document for information on how to create a debug log file.

debug_level = 0x00000000

You may connect to this port from a remote machine and receive the debug output. This allows bettwer creation of debug output on embedded systems that do not have enough memory for large disk files. Port number 0 means this feature is disabled.

debug_port = 0

Some UAs (SIP clients) will always use the host/ip they register TO as host part in the registration record (which will be the inbound ip address/hostname of the proxy) and can not be told to register a different host (public IP address). This Mask feature allows to force such a UA to be masqueraded to a different host. Siemens SIP Phones seem to need this feature. Normally disabled.

# mask_host=local.ip.of.sipphone
# masked_host=public.domaind.org

User Agent Masquerading: Siproxd can masquerade the User Agent string of your local UAs. Useful for Providers that do not work with some specific UAs (e.g. sipcall.ch - it does not work if your outgoing SIP traffic contains an Asterisk UA string...) Default is to do no replacement.

ua_string = Siproxd-UA

Use ;rport in via header: may be required in some cases where you have a NAT router that remaps the source port 5060 to something different and the registrar sends back the responses to port 5060. Default is disabled (0)

use_rport = 0

Siproxd itself can be told to send all traffic to another outbound proxy. You can use this feature to 'chain' multiple siproxd proxies if you have several masquerading firewalls to cross. Normally disabled.

# outbound_proxy_host = my.outboundproxy.org
# outbound_proxy_port = 5060

Outbound proxies can be specified on a per-domain base. This allows to use an outbound proxy needed for ProviderA and none (or another) for ProviderB. Multiple domain specific proxies may be specified, each one with one set of the following directives. Note: These directives must always be specified as a triple, skipping one of them will affect later definitions.

#outbound_domain_name = freenet.de
#outbound_domain_host = proxy.for.domain.freende.de
#outbound_domain_port = 5060

Siproxd supports dynamic loadable plug-ins. Such plug-ins are loaded during runtime and do not require recompilation of the executable. This allows the easy addition of specific functionality to siproxd. Even 3rd party functional extensions are possible without the requirement to patch and rebuild the siproxd source code with each new release.

Note: Dynamic loading of shared libraries is not supported on all platforms. If a platform does not support it, plug-ins can still be used but they will be statically linked during the build process of siproxd. The configuration ("loading" the plugins) is identical. For more information on this topic you may familiarize yourself with libltdl.

Note: As the plug-in mechanism uses LTDL, the plugins to load MUST use a .la extension and not an .so extension! Trying to load an plugin using xxx.so as it's name will fail.

# plugin_dir: MUST be terminated with '/'
plugindir=/usr/lib/siproxd/

# List of plugins to load:
#load_plugin=plugin_demo.la
load_plugin=plugin_logcall.la

Each plugin does manage it's own set of configuration options. They are named like plugin_<pluginname>_xxxxx. For the detailed description of configuration settings, refer to the plugin description.

plugin_demo_string = This_is_a_string_passed_to_the_demo_plugin