Due to its very flexible and customisable routing engine it can be used in number of scenarios such as an SIP proxy or a router and due to its high throughput it is widely recommended as an enterprise grade inbound/outbound proxy server.
This article talks about modules and subparts of Opensips and their role in defining the purpose and application of Opensips which can be as an lighweight proxy to loadbalancer or even as AAA server.
Dispatcher Module
This modules implements a dispatcher for destination addresses. It computes hashes over parts of the request and selects an address from a destination set. The selected address is used then as outbound proxy. The module can be used as a stateless load balancer, having no guarantee of fair distribution.
Path to the file with destination sets by default is “/etc/opensips/dispatcher.list” or “/usr/local/etc/opensips/dispatcher.list”.
setid_col (string) – storing the gateway’s group id. Default value is “setid”.
modparam("dispatcher", "setid_col", "groupid")
destination_col (string) – destination’s sip uri.
modparam("dispatcher", "destination_col", "uri")
flags_col (string) – The column’s name in the database storing the flags for destination uri.
modparam("dispatcher", "flags_col", "dstflags")
force_dst (int) – If set to 1, force overwriting of destination address when that is already set. Default value is “0”.
modparam("dispatcher", "force_dst", 1)
flags (int) – affect dispatcher’s behaviour. Default value is “0”.
If flag 1 is set only the username part of the uri will be used when computing an uri based hash.
If no flags are set the username, hostname and port will be used The port is used only if different from 5060 (normal sip uri) or 5061 (in the sips case).
If flag 2 is set, then the failover support is enabled. The functions exported by the module will store the rest of addresses from the destination set in AVP, and use these AVPs to contact next address when the current-tried fails.
modparam("dispatcher", "flags", 3)
use_default (int) – If the parameter is set to 1, the last address in destination set is used as last option to send the message. For example, it is good when wanting to send the call to an anouncement server saying: “the gateways are full, try later”. Default value is “0”.
modparam("dispatcher", "use_default", 1)
dst_avp (str) – The name of the avp which will hold the list with addresses, in the order they have been selected by the chosen algorithm.
modparam("dispatcher", "dst_avp", "$avp(i:271)")
If use_default is 1, the value of last dst_avp_id is the last address in destination set. The first dst_avp_id is the selected destinations. All the other addresses from the destination set will be added in the avp list to be able to implement serial forking.
grp_avp (str) – The name of the avp storing the group id of the destination set. Good to have it for later usage or checks. Default is null.
modparam("dispatcher", "grp_avp", "$avp(i:272)")
cnt_avp (str) – The name of the avp storing the number of destination addresses kept in dst_avp avps.
modparam("dispatcher", "cnt_avp", "$avp(i:273)")
hash_pvar (str) – String with PVs used for the hashing algorithm like to do hashing over custom message parts.Default value is “null” – disabled.
ds_ping_method (string) – With this Method you can define, with which method you want to probe the failed gateways. This method is only available, if compiled with the probing of failed gateways enabled. Default value is “OPTIONS”.
modparam("dispatcher", "ds_ping_method", "INFO")
ds_ping_from (string) – With this Method you can define the “From:”-Line for the request, sent to the failed gateways. This method is only available, if compiled with the probing of failed gateways enabled. Default value is “sip:dispatcher@localhost”.
ds_ping_interval (int – With this Method you can define the interval for sending a request to a failed gateway. This parameter is only used, when the TM-Module is loaded. If set to “0”, the pinging of failed requests is disabled.Default value is “10”.
modparam("dispatcher", "ds_ping_interval", 30)
ds_probing_threshhold (int) – If you want to set a gateway into probing mode, you will need a specific number of requests until it will change from “active” to probing. The number of attempts can be set with this parameter. Default value is “3”.
ds_probing_mode (int) – Controls what gateways are tested to see if they are reachable.
If set to 0, only the gateways with state PROBING are tested,
if set to 1, all gateways are tested. If set to 1 and the response is 407 (timeout), an active gateway is set to PROBING state. Default value is “0”.
modparam("dispatcher", "ds_probing_mode", 1)
options_reply_codes (str) – The codes defined here will be considered as valid reply codes for OPTIONS messages used for pinging, apart for 200. Default value is “NULL”.
ds_select_dst(set, alg) – The method selects a destination from addresses set. Algorithm used to select the destination address can be :
“0” – hash over callid
“1” – hash over from uri.
“2” – hash over to uri.
“3” – hash over request-uri.
“4” – round-robin (next destination).
“5” – hash over authorization-username (Proxy-Authorization or “normal” authorization). If no username is found, round robin is used.
“6” – random (using rand()).
“7” – hash over the content of PVs string. Note: This works only when the parameter hash_pvar is set.
“X” – if the algorithm is not implemented, the first entry in set is chosen.
ds_select_dst("1", "0");
You can use ‘ds_next_dst()’ to use next address to achieve serial forking to all possible destinations. This function can be used from REQUEST_ROUTE.
ds_select_domain(set, alg) – selects a destination from addresses set and rewrites the host and port from R-URI. This function can be used from REQUEST_ROUTE.
ds_next_dst() – Takes the next destination address from the AVPs with id ‘dst_avp_id’ and sets the dst_uri (outbound proxy address). This function can be used from FAILURE_ROUTE.
ds_next_domain() – Takes the next destination address from the AVPs with id ‘dst_avp_id’ and sets the domain part of the request uri. This function can be used from FAILURE_ROUTE.
ds_mark_dst() – Mark the last used address from destination set as inactive, in order to be ingnored in the future. In this way it can be implemented an automatic detection of failed gateways. When an address is marked as inactive, it will be ignored by ‘ds_select_dst’ and ‘ds_select_domain’. This function can be used from FAILURE_ROUTE.
ds_mark_dst(“s”) – Mark the last used address from destination set as :
inactive (“i”/”I”/”0”),
active (“a”/”A”/”1”) or
probing (“p”/”P”/”2”).
With this function, an automatic detection of failed gateways can be implemented. When an address is marked as inactive or probing, it will be ignored by ‘ds_select_dst’ and ‘ds_select_domain’.
ds_is_from_list() – This function returns true, if the current request comes from a host from the dispatcher-list; otherwise false. This function can be used from REQUEST_ROUTE, FAILURE_ROUTE, BRANCH_ROUTE and ONREPLY_ROUTE.
ds_is_from_list(“group”) – This function returns true, if the current request comes from a host in the given group of the dispatcher-list; otherwise false.
This function can be used from REQUEST_ROUTE, FAILURE_ROUTE, BRANCH_ROUTE and ONREPLY_ROUTE.
Exported MI Functions
ds_set_state – Sets the status for a destination address (can be use to mark the destination as active or inactive).
Parameters: state : state of the destination address
“a”: active
“i”: inactive
“p”: probing group: destination group id address: address of the destination in the group
MI FIFO Command Format:
:ds_set_state:reply_fifo_file state group address empty_line
ds_list – It lists the groups and included destinations.
MI FIFO Command Format:
:ds_list:reply_fifo_file empty_line
ds_reload – reloads the groups and included destinations.
MI DATAGRAM Command Format:
":ds_reload:\n."
Installation and Running
Destination List File – Each destination point must be on one line. First token is the set id, followed by destination address. Optionally, the third field can be flags value (1 – destination inactive, 2 – destination in probing mod — you can do bitwise OR to set both flags). The set id must be an integer value. Destination address must be a valid SIP URI. Empty lines or lines starting with “#” are ignored.
Exmaple of a dispatcher list file
line format
setit(integer) destination(sip uri) flags (integer, optional)
Implementation for a simplified database engine based on text files. It can be used by OpenSIPS DB interface instead of other database module (like MySQL). It keeps everything in memory.
The db_text database system architecture contains
a database is represented by a directory in the local file system. NOTE: when you use db_text in OpenSIPS, the database URL for modules must be the path to the directory where the table-files are located, prefixed by “text://”,
e.g., “text:///var/dbtext/opensips”.
a table is represented by a text file inside database directory.
Internal format of a db_text table
column definition name(type,attr) where types can be int , double , str and attributes be auto , null ,
* each other line is a row with data. The line ends with “\n”.
* the fields are separated by “:”.
* no value between two ‘:’ (or between ‘:’ and start/end of a row) means “null” value.
* next characters must be escaped in strings: “\n”, “\r”, “\t”, “:”.
* 0 — the zero value must be escaped too.
This database interface don’t support the data insertion with default values. All such values specified in the database
template are ignored.
db_mode (integer) – Set caching mode (0 – default) or non-caching mode (1). In caching mode, data is loaded at startup. In non-caching mode, the module check every time a table is requested whether the correspondingfile on disk has changed, and if yes, will re-load table from file.
modparam("db_text", "db_mode", 1)
Exported MI Functions
dbt_dump – Write back to hard drive modified tables.
opensipsctl fifo dbt_dump
dbt_reload – Causes db_text module to reload cached tables from disk. Parameters:
1 db_name (optional) – database name to reload.
2 table_name (optional, but cannot be present without the
db_name parameter) – specific table to reload.
setting module-specific parameters and making initial sanity checks — messages with max_forwards==0, or excessively long requests
-- mi_fifo params --
modparam("mi_fifo", "fifo_name", "/tmp/opensips_fifo")
-- usrloc params --
modparam("usrloc", "db_mode", 2)
modparam("usrloc|auth_db", "db_url", "text:///tmp/opensipsdb")
modparam("auth_db", "calculate_ha1", 1)
modparam("auth_db", "password_column", "password")
modparam("auth_db", "user_column", "username")
modparam("auth_db", "domain_column", "domain")
route{
if (!mf_process_maxfwd_header("10")) {
sl_send_reply("483","Too Many Hops");
exit;
};
if ($ml >= 65535 ) {
sl_send_reply("513", "Message too big");
exit;
};
if (!$rm=="REGISTER") record_route();
//if the request is for other domain use UsrLoc
if (is_myself("$rd")) {
if ($rm=="REGISTER") {
# digest authentication
if (!www_authorize("", "subscriber")) {
www_challenge("", "0");
exit;
};
save("location");
exit;
};
lookup("aliases");
if (!is_myself("$rd")) {
append_hf("P-hint: outbound alias\r\n");
route(1);
exit;
};
# native SIP destinations are handled using our USRLOC DB
if (!lookup("location")) {
sl_send_reply("404", "Not Found");
exit;
};
};
append_hf("P-hint: usrloc applied\r\n");
route(1);
}
route[1]
{
if (!t_relay()) {
sl_reply_error();
};
}
After the starting of a transaction such as REGISTER or INVITE we ensure that subsequent messages withing a dialog should take the path determined by record-routing using “record_route” function.
It is an multi-functional, multi-purpose SIP server especially used in VoIP landscape as standalone SIP server or SBC ( Session Border Controller ) for inbound and outbound traffic by carriers, telecoms backend layers or ITSPs for call routing and trunking solutions. It can be deployed with Class4/5 Platforms, SIP Trunking , hosted or IP PBX setup , existing gateways/ Session Border Controllers, Application Servers, proxy server, Front-End Load Balancers, IMS Platforms, Call Center etc.
Due to its very flexible and customisable routing engine it can be used in number of scenarios such as an SIP proxy or a router and due to its high throughput it is widely recommended as an enterprise grade inbound/outbound proxy server.
SIP to XMPP gateway for presence and IM (bidirectional)
Load-balancer or dispatcher
Inbound/front end for gateways/asterisk
SIP NAT traversal unit
Application server with custom logic
Since Opensips has emerged as a resilent SIP server , it is also used in specific usecases such as – DID ( Direct Inward dialling ) for SIP trunking solutions , – Local Number Portability (LNP) providers, – Canonical Name (CNAME) providers etc
It can act as Registrar with NAT traversal abilities (STUN, TURN, SIP pinging)
UDP , TCP , TLS , SCTP and WS transports over both IPv4 and IPv6 Additionally it can be connected to multiple networks ( Multihomed ) and do IP authentication or IP blacklisting
Class 4 routing capabilities in opensips include SIP aliases, Direct Inward Dialing , Speed dial, CPL,vDialplan , dispatcher with various algorithms, prefix-based routing to multiple carriers , failover support, Load balancing , ENUM-based or Geolocation-based routing etc. Some of the Class 5 capabilities in opensips are B2B , call queuing UAC registration , authentication, mangling, White/Black list
SIP SIMPLE features as messaging , Presence , Busy Lamp Field (BLF), Shared Call/Line Appearance (SCA) , Bridged Line Appearance (BLA) , Message Waiting notifications (MWI), XCAP , Resource List Server ( RLS ) , XMPP , SMS gateway (AT and SMPP)
Although opensips has no built-in media capabilities, but it modules for external media engines for Media relaying (RTPProxy, MediaProxy, RTPEngine), Media transcoding (Sangoma D1 cards) , Codec manipulation.
Opensips has majorly 2 parts core and addon-modules.
Opensips Core part is only a proxy stateless SIP server . It contains
SIP transport layer which supports UDP, TCP, TLS and WS for SIP. As per the listener in routing script transport protocols is selected .
SIP factory — the message parser and builder which can be used to add new headers or remove existing ones.
Routing script parser and interpreter for the routing script which loads it to the memory at the startup time. To load a new script server restart is required.
Memory and locking manager for the memory allocation and locking to prevent deadlocks and starvation. Although these arn’t accesible by route scripting, it can be configured at compile time.
Core script functions and variables which can be used in routing scripts in addition to the functions exported by add-on modules.
Interfaces
Events Interface
Used to notify external applications about events triggered internal to OpenSIPS such as
core events – E_CORE_THRESHOLD ,E_CORE_PKG_THRESHOLD , E_CORE_SHM_THRESHOLD , modules events , or even a custom event using raise_event() command
Statistics Interface
Provide insights to statistics of opensips in numerical results which could be used for services like monitoring, load evaluation, realtime integration etc. The statictsics can be of two kinds :
1. counter like – variables that keep counting things that happened in OpenSIPS, like received requests, processed dialogs, failed DB queries, etc
2. computed values – variables that are calculated in realtime, like how much memory is used, the current load, active dialogs, active transactions, etc
These variable would reset form 0 at start sometimes even during runtime.
Binary Internal Interface
Provider communication between individual OpenSIPS instances. Used in cases such as failovers where dialogs needs to persist for service continuity. Hence with this interface one can replicate all the events related to the runtime data (creation / updating / deletion) to a backup OpenSIPS instance.
SQL interface and NoSQL interface
SQL interfaces provides interaction with Sql DB drivers and services such as MySQL, Postgres, Oracle, Berkeley, unixODBC etc , while NoSQL interface provides access to Redis, CouchBase, Cassandra, MongoDB, Memcached, and other databases which are more frequently implemented as external caches.
AAA interface definition
Currently, OpenSIPS supports the RADIUS driver for the AAA interface with upcoming support for DIAMETER.
Management interface
Allows the external applications to trigger predefined commands
Push data like setting a debug level, registering a contact etc
Fetch data like registered users, ongoing calls, get statistics etc
Trigger an internal action as reloading the data, sending a message so on
1. Functional SIP modules
SIP signalling modules such as B2B_ENTITIES , B2B_LOGIC , CALL CENTER ( for Inbound call center system ) , DIALOG , NAT_TRAVERSAL , NATHELPER
OPTIONS , REGISTRAR ,SIGNALING , UAC_REGISTRANT
TM (Transaction/stateful module) , SL (Stateless replier ) , SMS (SIP-to-SMS IM gateway)
A config file opensips.config has 3 main logical parts :
1.global parameters – network listeners, available transport protocols, forking (and number of processes), the logging
2.modules section – the modules that are to be loaded with path to their .so file
3.routing logic – logic for routing sip traffic
Routes
OpenSIPS routing logic uses several types of routes. Each type of route is triggered by a certain event and allows you to process a certain type of message (request or reply).
route SIP requests routing. The main ‘route’ block identified by ‘route{…}’ or ‘route[0]{…}’ is executed for each SIP request. To send a reply or forward the request, explicit actions must be called inside the route block. in example below which sends 200 ok reply for each options request.
branch_route Handles different branches of a SIP request. if the branch is not dropped the branch will be automatically sent out. It is executed only by TM module after it was armed via t_on_branch(“branch_route_index”).
if (is_method("INVITE|BYE|SUBSCRIBE|UPDATE")) {
if(!t_is_set("branch_route")) t_on_branch("MANAGE_BRANCH");
}
branch_route[MANAGE_BRANCH] {
xdbg("new branch [$T_branch_idx] to $ru\n");
route(NATMANAGE);
}
or lookup location and discard branches where uri matches ip 1.2.3.4 by using drop()
failure_route Failed transaction routing block. It contains a set of actions to be taken each transaction that received only negative replies (>=300) for all branches which completes the transaction. The ‘failure_route’ is executed only by TM module after it was armed via t_on_failure(“failure_route_index”).
if (is_method("INVITE")) {
if(!t_is_set("failure_route")) t_on_failure("MANAGE_FAILURE");
}
failure_route[MANAGE_FAILURE] {
route(NATMANAGE);
if (t_is_canceled()) {
exit;
}
}
onreply_route Reply routing block. It can be stateful (if bound to a transaction) or stateless (if global reply route). If the reply is not dropped (only provisional replies can be), it will be injected and processed by the transaction engine. There are three types of onreply routes:
global – catches all replies and uses simple definition ‘onreply_route {…}’ or ‘onreply_route[0] {…}’.
Exmaple for “global” reply route set the whole transaction
route {
seturi("sip:bob@opensips.org"); first branch
append_branch("sip:alice@opensips.org"); second branch
t_on_reply("global");
t_on_branch("1");
t_relay();
}
onreply_route {
xlog("OpenSIPS received a reply from $si\n");
}
onreply_route[global] {
if (t_check_status("1[0-9][0-9]")) {
setflag(1);
log("provisional reply received\n");
if (t_check_status("183"))
drop;
}
}
per request/transaction – it catches all received replies belonging to a certain transaction and uses “t_on_reply()” at request time, in REQUEST ROUTE – named ‘onreply_route[N] {…}’.
per branch – it catches only the replies that belong to a certain branch from a transaction via “t_on_reply()” ) at request time, but in BRANCH ROUTE, when a certain outgoing branch is processed – named ‘onreply_route[N] {…}’.
Certain ‘onreply_route’ blocks can be executed by TM module for special replies. For this, the ‘onreply_route’ must be armed for the SIP requests whose replies should be processed within it, via t_on_reply(“onreply_route_index”).
Exmaple of reply route set for this branch only
branch_route[1] {
if ($rU=="alice")
t_on_reply("alice");
}
onreply_route[alice] {
xlog("received reply on the branch from alice\n");
}
error_route
executed automatically on meeting and error such as parsing error in SIP request processing, script assert failure. Performs error handling . The Default action is to discard request. In error_route, the following pseudo-variables are available to get access to error details:
$(err.class) - the class of error (now is '1' for parsing errors)
$(err.level) - severity level for the error
$(err.info) - text describing the error
$(err.rcode) - recommended reply code
$(err.rreason) - recommended reply reason phrase
error_route {
xlog("--- error route class=$(err.class) level=$(err.level)
info=$(err.info) rcode=$(err.rcode) rreason=$(err.rreason) ---\n");
xlog("--- error from [$si:$sp]\n+++++\n$mb\n++++\n");
sl_send_reply("$err.rcode", "$err.rreason");
exit;
}
local_route
executed automatically as TM created a new request, internally (no UAC side). This is a route intended to be used for message inspection, accounting and for applying last changes on the message headers. Routing and signaling functions are not allowed.
startup_route Executed only once when OpenSIPS is started and before the processing of SIP messages begins. Used in initilization cases cases such as loading some data in the cache.
startup_route {
avp_db_query("select gwlist where ruleid==1",$avp(i:100));
cache_store("local", "rule1", "$avp(i:100)");
}
timer_route Route executed periodically at a configured interval of time specified next to the name(in seconds).
timer_route[gw_update, 300] {
avp_db_query("select gwlist where ruleid==1",$avp(i:100));
$shv(i:100) =$avp(i:100);
}
event_route execute script code when an event is triggered. If no way to handle the event specified, default will be synchronously. Triggered by the event_route module when an event is raised by the OpenSIPS Event Interface such as event raised by the pike module when it decides an ip should be blocked called E_PIKE_BLOCKED or E_SCRIPT_EVENT etc ( checke events interface for more events)
event_route[E_PIKE_BLOCKED] {
xlog("The E_PIKE_BLOCKED event was raised\n");
}
event_route[E_PIKE_BLOCKED, async] {
xlog("The E_PIKE_BLOCKED event was raised\n");
}
Scripting Language
Opensips scripting provided more advanced controls
1. Core Keywords
Keywords specific to SIP messages which can be used mainly in ‘if’ expressions. af – address family of the received SIP message. It is INET if the message was received over IPv4 or INET6 if the message was received over IPv6.
if(af==INET6) {
log("Message received over IPv6 link\n");
};
dst_ip – IP of the local interface where the SIP message was received.
if(dst_ip==127.0.0.1) {
log("message received on loopback interface\n");
};
dst_port – local port where the SIP packet was received
if(dst_port==5061)
{
log("message was received on port 5061\n");
};
from_uri – reference to the URI of ‘From’ header.
if(is_method("INVITE") && from_uri=~".*@opensips.org")
{
log("the caller is from opensips.org\n");
};
method – SIP method of the message.
if(method=="REGISTER")
{
log("this SIP request is a REGISTER message\n");
};
msg:len – the size of the message
if(msg:len>2048)
{
sl_send_reply("413", "message too large");
exit;
};
$retcode – value returned by last function executed like $?. If tested after a call of a route, it is the value retuned by that route.
route {
route(1);
if($retcode==1)
{
log("The request is an INVITE\n");
};
}
route[1] {
if(is_method("INVITE"))
return(1);
return(2);
}
proto – transport protocol of the SIP message.
if(proto==UDP)
{
log("SIP message received over UDP\n");
};
status – status code of the reply.
if(status=="200")
{
log("this is a 200 OK reply\n");
};
1.10 src_ip – source IP address
if(src_ip==127.0.0.1)
{
log("the message was sent from localhost!\n");
};
1.11 src_port – source port of the SIP message (from which port the message was sent by previous hop).
if(src_port==5061)
{
log("message sent from port 5061\n");
}
1.12 to_uri – URI from To header.
if(to_uri=~"sip:.+@opensips.org")
{
log("this is a request for opensips.org users\n");
};
1.13 uri – request URI.
if(uri=~"sip:.+@opensips.org")
{
log("this is a request for opensips.org users\n");
};
2. Core Values
Values that can be used in ‘if’ expressions to check against Core Keywords
if(msg:len>max_len)
{
sl_send_reply("413", "message too large to be forwarded over UDP without fragmentation");
exit;
}
myself – reference to the list of local IP addresses, hostnames and aliases that has been set in OpenSIPS configuration file. This lists contain the domains served by OpenSIPS.
if(uri==myself) {
log("the request is for local processing\n");
};
null – reset the value of a per-script variable or to delete an avp.
$avp(i:12) = null;
$var(x) = null;
3. Core parameters
abort_on_assert – Set to true in order to make OpenSIPS shut down immediately in case a script assert fails.
abort_on_assert = true // default is false
advertised_address – address advertised in Via header and other destination lumps (e.g RR header).
advertised_port – port advertised in Via header and other destination lumps (e.g. RR).
db_max_async_connections – Maximum number of TCP connections opened from a single OpenSIPS worker to each individual SQL backend. Default value is 10. Individual backends are determined from DB URLs as follows: [ scheme, user, pass, host, port, database ]
disable_503_translation – If ‘yes’, OpenSIPS will not translate the received 503 replies into 500 replies . disable_core_dump – By default core dump limits are set to unlimited or a high enough value. Set this config variable to ‘yes’ to disable core dump-ing (will set core limits to 0).
disable_core_dump=yes //Default value is 'no'.
disable_dns_blacklist– DNS resolver, when configured with failover, can automatically store in a temporary blacklist the failed destinations. This will prevent (for a limited period of time) OpenSIPS to send requests to destination known as failed. So, the blacklist can be used as a memory for the DNS resolver.
The temporary blacklist created by DNS resolver is named “dns” and it is by default selected for usage (no need use the use_blacklist()) function. The rules from this list have a life time of 4 minutes – you can change it at compile time, from resolve.c . Can be ‘yes’ or ‘no’. By default the blacklist is disabled (Default value is ‘yes’).
disable_dns_failover – By default DNS-based failover is enabled. Set this config variable to ‘yes’ to disable the DNS-based failover. This is a global option, affecting the core and the modules also.
disable_stateless_fwd – controls the handling of stateless replies:
yes – drop stateless replies if stateless fwd functions (like forward) are not used in script
no – forward stateless replies
dns – controls if the SIP server should attempt to lookup its own domain name in DNS. Default is no.
dns_retr_time – Time in seconds before retrying a dns request. Default value is system specific, depends also on the ‘/etc/resolv.conf’ content (usually 5s).
dns_retr_no – Number of dns retransmissions before giving up.
dns_servers_no – How many dns servers from the ones defined in ‘/etc/resolv.conf’ will be used. Default value is to use all of them.
dns_try_ipv6 – If it is set to ‘yes’ and a DNS lookup fails, it will retry it for ipv6 (AAAA record). Default value is ‘no’.
dns_try_naptr – Disables the NAPTR lookups when doing DNS based routing for SIP requests – if disabled, the DNS lookup will start with SRV lookups. By default it is enabled, value ‘yes’.
dns_use_search_list
dst_blacklist – static (read-only) IP/destination blacklist. These lists can be selected from script (at runtime) to filter the outgoing requests, based on IP, protocol, port, etc.
test patter – is a filename like matching (see “man 3 fnmatch”) applied on the outgoing request buffer (first_line+hdrs+body)
enable_asserts – Set to true in order to enable the assert script statement.
event_pkg_threshold – A number representing the percentage threshold above which the E_CORE_PKG_THRESHOLD event is raised, warning about low amount of free private memory. It accepts integer values between 0 and 100. Default value is 0 ( event disabled ).
event_pkg_threshold = 90
event_shm_threshold A number representing the percentage threshold above which the E_CORE_SHM_THRESHOLD event is raised, warning about low amount of free shared memory. It accepts integer values between 0 and 100. Default value is 0 ( event disabled ).
event_shm_threshold = 90
exec_dns_threshold – A number representing the maximum number of microseconds a DNS query is expected to last. Anything above the set number will trigger a warning message to the logging facility. Default value is 0 ( logging disabled ).
exec_dns_threshold = 60000
exec_msg_threshold – A number representing the maximum number of microseconds the processing of a SIP msg is expected to last. Anything above the set number will trigger a warning message to the logging facility. Aside from the message and the processing time, the most time consuming function calls from the script will also be logged. Default value is 0 ( logging disabled ).
exec_msg_threshold = 60000
include_file – load additional routes/blocks with file path
include_file "proxy_regs.cfg"
import_file – Same as include_file but will not throw an error if file is not found.
import_file "proxy_regs.cfg"
listen – Set the network addresses the SIP server should listen to. syntax is protocol:address[:port]
The listen definition may accept several optional parameters for:
configuring an advertised IP and port only for an interface. Syntax “AS 11.22.33.44:5060”
setting a different number of children for this interface only (for UDP, SCTP and HEP_UDP interfaces only). This will override the global “children” parameter. Syntax “use_children 5”
Remember that the above parameters only affect the interface they are configured for; if they are not defined for a given interface, the global values will be used instead.
listen = udp:* listen = udp:eth1 listen = tcp:eth1:5062 listen = tls:localhost:5061 listen = hep_udp:10.10.10.10:5064 listen = ws:127.0.0.1:5060 use_children 5 listen = sctp:127.0.0.1:5060 as 99.88.44.33:5060 use_children 3 On startup, OpenSIPS reports all the interfaces that it is listening on. The TCP engine processes will be created regardless if you specify only UDP interfaces here. 3.41 log_facility – control the facility for logging in syslog. Default value is LOG_DAEMON.
log_facility=LOG_LOCAL0
3.42 log_level – logging level (how verbose OpenSIPS should be). Higher values make OpenSIPS to print more messages.
log_level=1 — print only important messages (like errors or more critical situations) recommended for running proxy as daemon
log_level=4 — print a lot of debug messages use it only when doing debugging sessions
Actual values are:
-3 – Alert level
-2 – Critical level
-1 – Error level
1 – Warning level
2 – Notice level
3 – Info level
4 – Debug level
The ‘log_level’ parameter is usually used in concordance with ‘log_stderror’ parameter.
Value of ‘log_level’ parameter can also be get and set dynamically using log_level Core MI function or $log_level script variable.
3.43 log_name – Set the id to be printed in syslog. The value must be a string and has effect only when OpenSIPS runs in daemon mode (fork=yes), after daemonize. Default value is argv[0].
log_name=”osips-5070″
3.44 log_stderror – write log messages to standard error. Possible values are: – “yes” – write the messages to standard error – “no” – write the messages to syslog , also the default
max_while_loops – maximum loops that can be done within a “while”. Comes as a protection to avoid infinite loops in config file execution. Default is 100.
max_while_loops=200
maxbuffer – size in bytes not to be exceeded during the auto-probing procedure of discovering the maximum buffer size for receiving UDP messages. Default value is 262144.
maxbuffer=65536
mem-group – Defines a group of modules (by name) to get separate memory statistics.In order for the feature to work you have to run “make generate-mem-stats” and complile with the variable SHM_EXTRA_STATS defined and complile with the variable SHM_SHOW_DEFAULT_GROUP definedwill generate the statistics for the default group
mem_warming – Only relevant when the HP_MALLOC compile flag is enabled. If set to “on”, on each startup, OpenSIPS will attempt to restore the memory fragmentation pattern it had before the stop/restart. Memory warming is useful when dealing with high volumes of traffic (thousands of cps on multi-core machines – the more cores, the more useful), because processes must mutually exclude themselves when chopping up the initial big memory chunk. By performing fragmentation on startup, OpenSIPS will also behave optimally in the first minute(s) after a restart. Fragmentation usually lasts a few seconds (e.g. ~5 seconds on an 8GB shm pool and 2.4Ghz CPU) – traffic will not be processed at all during this period.
mem_warming = on
mem_warming_percentage – How much of OpenSIPS’s memory should be fragmented with the pattern of the previous run, upon a restart.
mem_warming_percentage = 50 //Default value: 75
mem_warming_pattern_file – Default value: “CFG_DIR/mem_warming_pattern”.The memory fragmentation pattern of a previous OpenSIPS run. Used at startup, if mem_warming is enabled.
memdump | mem_dump – Log level to print memory status information (runtime and shutdown). Default: memdump=L_DBG (4)
memlog | mem_lo – Log level to print memory debug info. It has to be less than the value of ‘log_level’ parameter if you want memory info to be logged. Default: memlog=L_DBG (4)
mcast_loopback – If set to ‘yes’, multicast datagram are sent over loopback. Default value is ‘no’.
mcast_loopback=yes
mcast_ttl – Set the value for multicast ttl. Default value is OS specific (usually 1).
mhomed – Set the server to try to locate outbound interface on multihomed host. By default is not (0) – it is rather time consuming.
mhomed=1
mpath – Set the module search path. This can be used to simplify the loadmodule parameter
open_files_limit – If set and bigger than the current open file limit, OpenSIPS will try to increase its open file limit to this number. Note: OpenSIPS must be started as root to be able to increase a limit past the hard limit (which, for open files, is 1024 on most systems).
open_files_limit=2048
poll_method – (deprecated post 2.2) poll method to be used by the I/O internal reactor – by default the best one for the current OS is selected. The available types are: poll, epoll_lt, sigio_rt, select, kqueue, /dev/poll.
Starting with version 2.2, epoll_et is deprecated and if it is used in the script, it will be automatically replaced by epoll_lt.
poll_method=select
port – port the SIP server listens to. The default value for it is 5060.
reply_to_via – If it is set to 1, any local reply is sent to the address advertised in top most Via of the request. Default value is 0 (off).
reply_to_via=0
query_buffer_size -If set to a value greater than 1, inserts to DB will not be flushed one by one. Rows to be inserted will be kept in memory until until they gather up to query_buffer_size rows, and only then they will be flushed to the database.
query_buffer_size=5
query_flush_time – If query_buffer_size is set to a value greater than 1, a timer will trigger once every query_flush_time seconds, ensuring that no row will be kept for too long in memory.
query_flush_time=10
rev_dns – should the SIP server attempt to lookup its own IP address in DNS. If this parameter is set to yes and the IP address is not in DNS a warning is printed on syslog and a “received=” field is added to the via header. Default is no.
server_header – The body of Server header field generated by OpenSIPS when it sends a request as UAS. It defaults to “OpenSIPS (<version> (<arch>/<os>))”.
server_header="Server: My Company SIP Proxy"
server_signature – control “Server” header in any locally generated message. If it is enabled (default=yes) a header is generated as Server: OpenSIPS (0.9.5 (i386/linux))
shm_hash_split_percentage – Only relevant when the HP_MALLOC compile flag is enabled. It controls how many memory buckets will be optimized. (e.g. setting it to 2% will optimize the first 81 most used buckets as frequency). The default value is 1.
shm_secondary_hash_size – Only relevant when the HP_MALLOC compile flag is enabled. It represents the optimization factor of a single bucket (e.g. setting it to 4 will cause the optimized buckets to be further split into 4). The default value is 8.
sip_warning – Can be 0 or 1. If set to 1 (default value is 0) a ‘Warning’ header is added to each reply generated by OpenSIPS. The header contains several details that help troubleshooting using the network traffic dumps.
sip_warning=0
tcp_children – Number of children processes to be created for reading from TCP connections. If no value is explicitly set, the same number of TCP children as UDP children (see “children” parameter) will be used.
tcp_accept_aliases – If enabled, OpenSIPS will enforce RFC 5923 behaviour when detecting an “;alias” Via header field parameter and will reuse any TCP (or TLS, WS, WSS) connection opened for such SIP requests (source IP + Via port + proto) when sending other SIP requests backwards, towards the same (source IP + Via port + proto) pair. Default value 0 (disabled).
tcp_listen_backlog – maximum length for the queue of pending connections for the TCP listeners. Default configured value is 10.
tcp_connect_timeout – Time in milliseconds before an ongoing blocking attempt to connect will be aborted. Default value is 100ms.
tcp_connection_lifetime – Lifetime in seconds for TCP sessions. Default value is defined in tcp_conn.h: define DEFAULT_TCP_CONNECTION_LIFETIME 120.
tcp_connection_lifetime = 3600
tcp_max_connections – maximum number of tcp connections. Default is defined in tcp_conn.h: define DEFAULT_TCP_MAX_CONNECTIONS 2048
tcp_max_connections = 4096
tcp_max_msg_time – maximum number of seconds that a SIP message is expected to arrive via TCP. Default value is 4
tcp_max_msg_time = 8
tcp_no_new_conn_bflag -A branch flag to be used as marker to instruct OpenSIPS not to attempt to open a new TCP connection when delivering a request, but only to reuse an existing one (if available). If no existing conn, a generic send error will be returned.
This is intended to be used in NAT scenarios, where makes no sense to open a TCP connection towards a destination behind a NAT (like TCP connection created during registration was lost, so there is no way to contact the device until it re-REGISTER). Also this can be used to detect when a NATed registered user lost his TCP connection, so that opensips can disable his registration as useless.
tcp_no_new_conn_bflag = TCP_NO_CONNECT<br> ...<br> route {<br> ...<br> if (isflagset(DST_NATED) && $proto == "TCP")<br> setbflag(TCP_NO_CONNECT);<br> ...<br> t_relay("0x02"); // no auto error reply<br> $var(retcode) = $rc;<br> if ($var(retcode) == -6) {<br> xlog("unable to send request to destination");<br> send_reply("404", "Not Found");<br> exit;<br> } else if ($var(retcode) < 0) {<br> sl_reply_error();<br> exit;<br> }<br> }
3.77 tcp_threshold – A number representing the maximum number of microseconds sending of a TCP request is expected to last. Anything above the set number will trigger a warning message to the logging facility. Default value is 0 ( logging disabled ).
tcp_threshold = 60000
tcp_keepalive – Enable or disable TCP keepalive (OS level). Enabled by default.
tcp_keepcount -Number of keepalives to send before closing the connection (Linux only). Default value: 0 (not set). Setting tcp_keepcount to any value will enable tcp_keepalive.
tcp_keepidle – Amount of time before OpenSIPS will start to send keepalives if the connection is idle (Linux only). Default value: 0 (not set)
tcp_keepidle = 30
tcp_keepinterval – Interval between keepalive probes, if the previous one failed (Linux only).Default value: 0 (not set). Setting tcp_keepinterval to any value will enable tcp_keepalive.
tcp_keepinterval = 10
tls_ca_list
tls_certificate
tls_ciphers_list
tls_domain
tls_handshake_timeout
tls_log
tls_method
tls_port_no
tls_private_key
tls_require_certificate
tls_send_timeout
tls_verify
tos – TOS (Type Of Service) to be used for the sent IP packages (both TCP and UDP).
user_agent_header – The body of User-Agent header field generated by OpenSIPS when it sends a request as UAC. It defaults to “OpenSIPS (<version> (<arch>/<os>))”.
user_agent_header=”User-Agent: My Company SIP Proxy”
wdir – working directory used by OpenSIPS at runtime.
wdir="/usr/local/opensips"
xlog_buf_size – Default value: 4096
Size of the buffer used to print a single line on the chosen logging facility of OpenSIPS. If the buffer is too small, an overflow error will be printed, and the concerned line will be skipped.
xlog_buf_size = 8388608 #given in bytes
xlog_force_color
xlog_default_level -Default value for the logging level of the xlog core function, when the log_level parameter is omitted.
OpenSIPS routing logic uses several types of routes. Each type of route is triggered by a certain event and allows you to process a certain type of message (request or reply).
route SIP requests routing. The main ‘route’ block identified by ‘route{…}’ or ‘route[0]{…}’ is executed for each SIP request. To send a reply or forward the request, explicit actions must be called inside the route block. in example below which sends 200 ok reply for each options request.
branch_route Handles different branches of a SIP request. if the branch is not dropped the branch will be automatically sent out. It is executed only by TM module after it was armed via t_on_branch(“branch_route_index”).
if (is_method("INVITE|BYE|SUBSCRIBE|UPDATE")) {
if(!t_is_set("branch_route")) t_on_branch("MANAGE_BRANCH");
}
branch_route[MANAGE_BRANCH] {
xdbg("new branch [$T_branch_idx] to $ru\n");
route(NATMANAGE);
}
or lookup location and discard branches where uri matches ip 1.2.3.4 by using drop()
failure_route Failed transaction routing block. It contains a set of actions to be taken each transaction that received only negative replies (>=300) for all branches which completes the transaction. The ‘failure_route’ is executed only by TM module after it was armed via t_on_failure(“failure_route_index”).
if (is_method("INVITE")) {
if(!t_is_set("failure_route")) t_on_failure("MANAGE_FAILURE");
}
failure_route[MANAGE_FAILURE] {
route(NATMANAGE);
if (t_is_canceled()) {
exit;
}
}
onreply_route Reply routing block. It can be stateful (if bound to a transaction) or stateless (if global reply route). If the reply is not dropped (only provisional replies can be), it will be injected and processed by the transaction engine. There are three types of onreply routes:
global – catches all replies and uses simple definition ‘onreply_route {…}’ or ‘onreply_route[0] {…}’.
Exmaple for “global” reply route set the whole transaction
route {
seturi("sip:bob@opensips.org"); first branch
append_branch("sip:alice@opensips.org"); second branch
t_on_reply("global");
t_on_branch("1");
t_relay();
}
onreply_route {
xlog("OpenSIPS received a reply from $si\n");
}
onreply_route[global] {
if (t_check_status("1[0-9][0-9]")) {
setflag(1);
log("provisional reply received\n");
if (t_check_status("183"))
drop;
}
}
per request/transaction – it catches all received replies belonging to a certain transaction and uses “t_on_reply()” at request time, in REQUEST ROUTE – named ‘onreply_route[N] {…}’.
per branch – it catches only the replies that belong to a certain branch from a transaction via “t_on_reply()” ) at request time, but in BRANCH ROUTE, when a certain outgoing branch is processed – named ‘onreply_route[N] {…}’.
Certain ‘onreply_route’ blocks can be executed by TM module for special replies. For this, the ‘onreply_route’ must be armed for the SIP requests whose replies should be processed within it, via t_on_reply(“onreply_route_index”).
Exmaple of reply route set for this branch only
branch_route[1] {
if ($rU=="alice")
t_on_reply("alice");
}
onreply_route[alice] {
xlog("received reply on the branch from alice\n");
}
error_route
executed automatically on meeting and error such as parsing error in SIP request processing, script assert failure. Performs error handling . The Default action is to discard request. In error_route, the following pseudo-variables are available to get access to error details:
$(err.class) - the class of error (now is '1' for parsing errors)
$(err.level) - severity level for the error
$(err.info) - text describing the error
$(err.rcode) - recommended reply code
$(err.rreason) - recommended reply reason phrase
error_route {
xlog("--- error route class=$(err.class) level=$(err.level)
info=$(err.info) rcode=$(err.rcode) rreason=$(err.rreason) ---\n");
xlog("--- error from [$si:$sp]\n+++++\n$mb\n++++\n");
sl_send_reply("$err.rcode", "$err.rreason");
exit;
}
local_route
executed automatically as TM created a new request, internally (no UAC side). This is a route intended to be used for message inspection, accounting and for applying last changes on the message headers. Routing and signaling functions are not allowed.
startup_route Executed only once when OpenSIPS is started and before the processing of SIP messages begins. Used in initilization cases cases such as loading some data in the cache.
startup_route {
avp_db_query("select gwlist where ruleid==1",$avp(i:100));
cache_store("local", "rule1", "$avp(i:100)");
}
timer_route Route executed periodically at a configured interval of time specified next to the name(in seconds).
timer_route[gw_update, 300] {
avp_db_query("select gwlist where ruleid==1",$avp(i:100));
$shv(i:100) =$avp(i:100);
}
event_route execute script code when an event is triggered. If no way to handle the event specified, default will be synchronously. Triggered by the event_route module when an event is raised by the OpenSIPS Event Interface such as event raised by the pike module when it decides an ip should be blocked called E_PIKE_BLOCKED or E_SCRIPT_EVENT etc ( checke events interface for more events)
event_route[E_PIKE_BLOCKED] {
xlog("The E_PIKE_BLOCKED event was raised\n");
}
event_route[E_PIKE_BLOCKED, async] {
xlog("The E_PIKE_BLOCKED event was raised\n");
}
opensipsctlrc
opensipsctlrc file controls the opensipsctl and osipsconsole utilities. It is a shell script utility to manage opensips from command line
opensipsctl can manage
Start, stop, and restart
Show, grant, and revoke ACLs Add, remove, and list aliases
Add, remove, and configure an AVP
Low Cost Route (LCR)
Remote Party Identity (RPID)
Add, remove, and list subscribers
Add, remove, and show the usrloc table in-Random Access Memory (RAM)
Telecom R & D 