If you are new are opensips you cab read Over view of Opensisp SIP server here https://telecom.altanai.com/2018/06/06/opensips/

Opensips

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”.

modparam("dispatcher", "list_file", "/var/run/opensips/dispatcher.list")

db_url is used to load the sets of gateways from the database

modparam("dispatcher", "db_url", "mysql://user:passwb@localhost/database")

table_name loads the sets of gateways from the database. Default value is “dispatcher”.

modparam("dispatcher", "table_name", "my_dispatcher")

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.

modparam("dispatcher", "hash_pvar", "$avp(i:273)")

setid_pvar (str) – name of the PV where to store the set ID (group ID) when calling ds_is_from_list() with no parameter.

modparam("dispatcher", "setid_pvar", "$var(setid)")

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”.

modparam("dispatcher", "ds_ping_from", "sip:proxy@sip.somehost.com")

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”.

modparam("dispatcher", "ds_probing_threshhold", 10)

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”.

modparam("dispatcher", "options_reply_codes", "501, 403")

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)

proxies
2 sip:127.0.0.1:5080
2 sip:127.0.0.1:5082

gateways
1 sip:127.0.0.1:7070
1 sip:127.0.0.1:7072
1 sip:127.0.0.1:7074

OpenSIPS config file

sample config file for dispatcher module

debug=9            debug level (cmd line: -dddddddddd)
fork=no
log_stderror=yes  (cmd line: -E)

children=2
check_via=no      (cmd. line: -v)
dns=off           (cmd. line: -r)
rev_dns=off       (cmd. line: -R)
port=5060

module loading

mpath="/usr/local/lib/opensips/modules/"
loadmodule "maxfwd.so"
loadmodule "sl.so"
loadmodule "dispatcher.so"

setting module-specific parameters

dispatcher params

modparam("dispatcher", "list_file", "../etc/dispatcher.list")
// modparam("dispatcher", "force_dst", 1)

route{
if ( !mf_process_maxfwd_header("10") )
{
sl_send_reply("483","To Many Hops");
drop();
};
ds_select_dst("2", "0");
forward();
// t_relay();
}

db_text Module

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.

Sample of a db_text table ,

id(int,auto) name(str) flag(double) desc(str,null)
1:nick:0.34:a\tgood\: friend
2:cole:-3.75:colleague
3:bob:2.50:

Minimal OpenSIPS location db_text table definition

username(str) contact(str) expires(int) q(double) callid(str) cseq(int)

Minimal OpenSIPS subscriber db_text table example

username(str) password(str) ha1(str) domain(str) ha1b(str)
suser:supasswd:xxx:alpha.org:xxx

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.

MI FIFO Command Format:
opensipsctl fifo dbt_reload
opensipsctl fifo dbt_reload /path/to/dbtext/database
opensipsctl fifo dbt_reload /path/to/dbtext/database table_name

Installation and Running

Compile the module and load it instead of mysql or other DB modules.

Load the db_text module

loadmodule "/path/to/opensips/modules/db_text.so"
modparam("module_name", "database_URL", "text:///path/to/dbtext/database
")

Using db_text with basic OpenSIPS configuration

Definition of ‘subscriber’ table (one line)

username(str) domain(str) password(str) first_name(str) last_name(str) phone(str) email_address(str) datetime_created(int) datetime_modified(int) confirmation(str) flag(str) sendnotification(str) greeting(str) ha1(str) ha1b(str) perms(str) allow_find(str) timezone(str,null) rpid(str,null)

Definition of ‘location’ and ‘aliases’ tables (one line)

username(str) domain(str,null) contact(str,null) received(str) expires(i
nt,null) q(double,null) callid(str,null) cseq(int,null) last_modified(st
r) flags(int) user_agent(str) socket(str)

Definition of ‘version’ table and sample records

table_name(str) table_version(int)
subscriber:3
location:6
aliases:6

Configuration file using dbtext databse for oersistant storage . Also using auth

debug_mode=yes
children=4

check_via=no    # (cmd. line: -v)
dns=no          # (cmd. line: -r)
rev_dns=no      # (cmd. line: -R)
listen=udp:10.100.100.1:5060

loadmodule "modules/dbtext/dbtext.so"
loadmodule "modules/sl/sl.so"
loadmodule "modules/tm/tm.so"
loadmodule "modules/rr/rr.so"
loadmodule "modules/maxfwd/maxfwd.so"
loadmodule "modules/usrloc/usrloc.so"
loadmodule "modules/registrar/registrar.so"
loadmodule "modules/textops/textops.so"
loadmodule "modules/textops/mi_fifo.so"
loadmodule "modules/auth/auth.so"
loadmodule "modules/auth_db/auth_db.so"

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.

Combination of opensips working scenarios scripts with code is at https://github.com/altanai/opensipsexamples.