Siproxd by default searches for its configuration file in the following locations:
$HOME/.siproxdrc
<buildingprefix>/etc/siproxd.conf
/etc/siproxd.conf
/usr/etc/siproxd.conf
/usr/local/etc/siproxd.conf
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:
0 - DEBUGs, INFOs, WARNINGs and ERRORs
1 - INFOs, WARNINGs and ERRORs
2 - WARNINGs and ERRORs
3 - only ERRORs
4 - absolutely nothing
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.
DBCLASS_BABBLE 0x00000001 // babble (like entering/leaving fnc)
DBCLASS_NET 0x00000002 // network
DBCLASS_SIP 0x00000004 // SIP manipulations
DBCLASS_REG 0x00000008 // Client registration
DBCLASS_NOSPEC 0x00000010 // non specified class
DBCLASS_PROXY 0x00000020 // proxy
DBCLASS_DNS 0x00000040 // DNS stuff
DBCLASS_NETTRAF 0x00000080 // network traffic
DBCLASS_CONFIG 0x00000100 // configuration
DBCLASS_RTP 0x00000200 // RTP proxy
DBCLASS_ACCESS 0x00000400 // Access list evaluation
DBCLASS_AUTH 0x00000800 // Authentication
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