Documentation

Documentation.Tutorials-Diameter-AAA History

Hide minor edits - Show changes to markup

May 12, 2022, at 05:54 PM by liviu -
Changed line 94 from:
    g++ libidn11-dev ssl-cert debhelper fakeroot \
to:
    g++ libfreediameter-dev libidn11-dev ssl-cert debhelper fakeroot \
Added lines 96-98:
  # for Digest Auth support, the MySQL devel library is needed.  On Debian, for example:
  apt install libmariadb-dev libmariadb-dev-compat
June 17, 2021, at 01:15 AM by liviu -
Changed line 106 from:
  # also, fix a strange compilation issue from this revision, by applying this patch:
to:
  # also, fix a strange compilation issue specific to this revision, by applying this patch:
June 17, 2021, at 01:14 AM by liviu -
Added lines 105-117:
  # also, fix a strange compilation issue from this revision, by applying this patch:
  patch -p1 < <(base64 -d <<EOF | gzip -dc

H4sIAAAAAAAAA4WSX0/bMBTFn8mnuHQaoqSBOAXCgjY1yx/IqOwoSdn2ZLmxQy06ByUpT3z4eQ1M ooVyX2z5nHNt/a65rCqwGnDK+QV3ETu1zzgs5bziZd2Ik7bsHo5Lw7IsYCebx3s56yAXD+CcAkLe 2PHGCBwbnYNpX9i2YZomzLdTxWIFP1YKkAs28tDYQ190ykE6NdapyQQs5JzZIxfM53UyMWBP15F4 FKqDrxCH0W1KA/yLRllGsstenjeC3f/bG9YnWXFRAZmGNA+KlOYkuIkK6qeJYWoNtCiV4IdvGIbw 9AT7L4ZejHBIYz+ZRiGNbiNcDNcXlqwVsGnw+rcUmR9ENIy+z64O49l0OoJBJkohHwXfioCqO1nJ knWyVoPh5XYHH2PyO8FXugvoWgoFHnxerAajPmt9axVtheK0YnIp+HHbVlS77rqFbtcTdZ+Juh8Q za9nRUh+4k2outZc1U6w+zvJHhzAK7CYFEmcBH6REJzTvCBp+h7iHdY3kCc4JlvId7R4NYIR/GHN vVR30C0EsLatS7kWQCoQTVM30HasE/9H9f6//Aug0Y8DXwMAAA== EOF )

June 17, 2021, at 12:35 AM by liviu -
Added lines 277-278:
        record_route();
        create_dialog();
June 17, 2021, at 12:35 AM by liviu -
Changed line 286 from:

And that's it! Your OpenSIPS will be sending each CDR to freeDiameter now:

to:

And that's it! Your OpenSIPS will be sending each CDR to freeDiameter now!

June 17, 2021, at 12:34 AM by liviu -
Changed lines 214-215 from:

For now, app_opensips will connect on startup to a MySQL OpenSIPS database, hardcoded to "mysql://opensips:opensipsrw@localhost/opensips", where it will access the subscriber table data, so make sure to provide the necessary infrastructure. As the module becomes more sophisticated, this section will also be updated.

to:

For now, app_opensips will connect on startup to a MySQL OpenSIPS database, hardcoded to "mysql://opensips:opensipsrw@localhost/opensips", where it will access the subscriber table data, so make sure to provide the necessary infrastructure. As the application becomes more sophisticated, this section will also be updated.

Deleted line 249:
Changed lines 257-286 from:

asdasd

to:

As of now, app_opensips will append each CDR to a hardcoded file path of "/var/log/freeDiameter/acc.log", rotating this file daily, around midnight. Also, there is no way of configuring the custom AVPs required by "acc_extra", however this section will be updated as soon as that is in place.

To enable Diameter accounting support in your opensips.cfg file, make sure to set:

log_stdout = yes # very important, to see the freeDiameter library logs
...
loadmodule "acc.so"
modparam("acc", "aaa_url", "diameter:freeDiameter-client.conf")

loadmodule "aaa_diameter.so"
modparam("aaa_diameter", "fd_log_level", 0) # max amount of logging, quite annoying
modparam("aaa_diameter", "realm", "diameter.test")
modparam("aaa_diameter", "peer_identity", "server")
...
route {
    ...

    if (is_method("INVITE")) {
        ...
        do_accounting("aaa", "cdr");
        ...
    }
}
...


And that's it! Your OpenSIPS will be sending each CDR to freeDiameter now:

June 16, 2021, at 11:58 PM by liviu -
Deleted lines 245-246:

And here is how a successful authentication request looks like in Wireshark:

Changed lines 248-249 from:
to:

And here is what a Diameter authentication request and a "success" reply look like in Wireshark:

June 16, 2021, at 11:57 PM by liviu -
Changed lines 254-255 from:
http://opensips.org/pub/images/diameter-auth.png http://opensips.org/pub/images/diameter-auth-success.png

Native "full sharing" clusterer table

to:
http://opensips.org/pub/images/diameter-auth-request.png http://opensips.org/pub/images/diameter-auth-reply-success.png
June 16, 2021, at 11:56 PM by liviu -
Changed lines 246-247 from:

And here is how an authentication request looks like in Wireshark:

to:

And here is how a successful authentication request looks like in Wireshark:

Changed lines 250-256 from:

http://opensips.org/pub/images/diameter-auth.png

to:


http://opensips.org/pub/images/diameter-auth.png http://opensips.org/pub/images/diameter-auth-success.png

Native "full sharing" clusterer table

June 16, 2021, at 11:52 PM by liviu -
Added lines 220-221:

... alias = udp:sipdomain.invalid:5060

June 16, 2021, at 11:51 PM by liviu -
Changed lines 22-23 from:

freeDiameter Client

to:

freeDiameter Client

Changed lines 26-27 from:

DNS

to:

DNS

Changed lines 35-36 from:

Packages

to:

Packages

Changed lines 43-44 from:

Creating TLS Certificates

to:

Creating TLS Certificates

Changed lines 64-65 from:

The freeDiameter client configuration file

to:

The freeDiameter client configuration file

Changed lines 86-87 from:

freeDiameter Server

to:

freeDiameter Server

Changed lines 90-91 from:

Compiling app_opensips

to:

Compiling app_opensips

Changed lines 129-130 from:

DNS

to:

DNS

Changed lines 138-139 from:

Packages

to:

Packages

Changed lines 146-147 from:

The freeDiameter server configuration file

to:

The freeDiameter server configuration file

Changed lines 196-197 from:

OpenSIPS configuration

to:

OpenSIPS configuration

Changed lines 212-213 from:

Digest Authentication

to:

Digest Authentication

Changed lines 250-252 from:

Accounting

to:

Accounting

asdasd

June 16, 2021, at 11:48 PM by liviu -
Changed line 248 from:

http://opensips.org/pub/images/diameter-auth.png

to:

http://opensips.org/pub/images/diameter-auth.png

June 16, 2021, at 11:47 PM by liviu -
Changed line 248 from:

http://opensips.org/pub/images/diameter-auth.png

to:

http://opensips.org/pub/images/diameter-auth.png

June 16, 2021, at 11:44 PM by liviu -
Added lines 194-195:

If it worked, make sure to give yourself another pat on the back! You are an excellent developer!

Changed lines 198-199 from:

As long as you can compile aaa_diameter with the below command, you only need to worry about the opensips.cfg file now:

to:

As long as you can compile aaa_diameter with the below command, you only need to worry about the opensips.cfg file after this step:

Changed lines 214-249 from:
to:

For now, app_opensips will connect on startup to a MySQL OpenSIPS database, hardcoded to "mysql://opensips:opensipsrw@localhost/opensips", where it will access the subscriber table data, so make sure to provide the necessary infrastructure. As the module becomes more sophisticated, this section will also be updated.

Here are the relevant opensips.cfg sections to perform SIP digest authentication via Diameter:

log_stdout = yes # very important, to see the freeDiameter library logs
...
loadmodule "auth.so"

loadmodule "auth_aaa.so"
modparam("auth_aaa", "aaa_url", "diameter:freeDiameter-client.conf")

loadmodule "aaa_diameter.so"
modparam("aaa_diameter", "fd_log_level", 0) # max amount of logging, quite annoying
modparam("aaa_diameter", "realm", "diameter.test")
modparam("aaa_diameter", "peer_identity", "server")
...
route {
    ...

    if (is_method("INVITE")) {
        ...
        if (!aaa_proxy_authorize("sipdomain.invalid"))
            proxy_challenge("sipdomain.invalid");
        ...
    }
}
...

And here is how an authentication request looks like in Wireshark:


http://opensips.org/pub/images/diameter-auth.png

Added line 251:
June 16, 2021, at 11:23 PM by liviu -
Changed line 106 from:
  # create a build configuration (one-time operation)
to:
  # create a build configuration (one-time operation, feel free to disable some of these flags or include others!)
Added lines 173-193:

Let's test that app_opensips boots properly by launching freeDiameter in full logging mode, in a separate console:

$ freeDiameterd -dd
23:18:24  NOTI   libfdproto '1.2.1' initialized.
23:18:24  NOTI   libgnutls '3.6.13' initialized.
23:18:24   DBG   Core state: 0 -> 1
23:18:24  NOTI   libfdcore '1.2.1' initialized.
23:18:24   DBG   Generating fresh Diffie-Hellman parameters of size 1024 (this takes some time)... 
23:18:24   DBG   Loading : /usr/lib/freeDiameter/dict_sip.fdx
23:18:24   DBG   Extension 'Dictionary definitions for SIP' initialized
23:18:24   DBG   Loading : /home/liviu/src/freeDiameter/fDbuild/extensions/app_opensips.fdx
23:18:24   DBG   opensips entry
23:18:24   DBG   [AUTH] connected to MySQL
23:18:24  NOTI   All extensions loaded.
23:18:24  NOTI   freeDiameter configuration:
23:18:24  NOTI     Default trace level .... : +1
23:18:24  NOTI     Configuration file ..... : /etc/freeDiameter/freeDiameter.conf
...
Changed lines 196-202 from:

The required libraries are , and can be installed via:

Configuring the aaa_diameter OpenSIPS module

Digest Authentication

Accounting

to:

As long as you can compile aaa_diameter with the below command, you only need to worry about the opensips.cfg file now:

make modules module=aaa_diameter

make[1]: Entering directory '/home/liviu/src/opensips-3.3/modules/aaa_diameter'
Compiling aaa_impl.c
Compiling aaa_diameter.c
Compiling peer.c
Compiling app_opensips/avps.c
Linking aaa_diameter.so
make[1]: Leaving directory '/home/liviu/src/opensips-3.3/modules/aaa_diameter'

Digest Authentication

Accounting

June 16, 2021, at 11:15 PM by liviu -
Changed lines 22-25 from:

Client side

The client side is represented by the "aaa_diameter" OpenSIPS module, which is powered by the freeDiameter client library. In this section, we will perform the necessary steps in order to configure the freeDiameter library.

to:

freeDiameter Client

The client side is represented by both the "aaa_diameter" OpenSIPS module and the freeDiameter client library. In this section, we will perform the necessary steps in order to configure the freeDiameter client library.

Changed lines 86-89 from:

Server side

The server side is represented by the app_opensips freeDiameter application.

to:

freeDiameter Server

The server side is represented by the app_opensips freeDiameter application, running within the freeDiameter daemon.

Added lines 107-108:
  mkdir fDbuild
  cd fDbuild
Changed line 123 from:
  [liviu ◄ Z370 fDbuild-2]$ ls extensions/app_opensips.fdx -la
to:
  [liviu@Z370 fDbuild]$ ls extensions/app_opensips.fdx -la
Changed lines 127-134 from:

Congratulations!

Running

DNS

If your freeDiameter server is running on a separate machine, edit /etc/hosts and populate the DNS entries on that box as well:

to:

Congratulations for making it this far, as the hard part is over!

DNS

If your freeDiameter server is running on a separate machine, edit /etc/hosts once again and populate the appropriate DNS entries on that box as well:

Changed lines 138-141 from:

Packages

As we will be using the "dict_sip" extension, install the appropriate package:

to:

Packages

As we will be using the "dict_sip" freeDiameter extension, install the appropriate package (FWIW, you've already built it in the previous step, but it's nicer this way):

Changed lines 146-173 from:

\\

to:

The freeDiameter server configuration file

Edit /etc/freeDiameter/freeDiameter.conf and provide the following:

Identity = "server.diameter.test";
Realm = "diameter.test";
Port = 3868;
No_SCTP;

# Notice we're using the same wildcard certificate!
TLS_Cred = "/path/to/freeDiameter/contrib/PKI/ca_script2/ca_data/my_diameter_ca/clients/*.diameter.test/cert.pem",
"/path/to/freeDiameter/contrib/PKI/ca_script2/ca_data/my_diameter_ca/clients/*.diameter.test/privkey.pem";
TLS_CA = "/path/to/freeDiameter/contrib/PKI/ca_script2/ca_data/my_diameter_ca/clients/*.diameter.test/certchain.pem";

# Load the standard SIP AVP dictionary, as well as the app_opensips module!
LoadExtension = "/usr/lib/freeDiameter/dict_sip.fdx";
LoadExtension = "/path/to/freeDiameter/fDbuild/extensions/app_opensips.fdx";

# Per your preference: the server may optionally also establish the Diameter connection to OpenSIPS on startup (useful after a server restart)
ConnectPeer = "client.diameter.test" {
  No_TLS;
  port = 3866;
};

OpenSIPS configuration

June 16, 2021, at 11:03 PM by liviu -
Changed lines 12-13 from:

This tutorial has been written for a Xubuntu 20.04 LTS, which comes with freeDiameter v1.2.1 packages. Other distros, such as Debian 10, are also known to offer standard package-based support for freeDiameter v1.2.1, so they are expected to be compatible just as well. First, let's go ahead and install it:

to:

This tutorial has been written for a Xubuntu 20.04 LTS, which comes with freeDiameter v1.2.1 packages, which is the only version we've tested so far. Other distros, such as Debian 10, are also known to offer standard package-based support for freeDiameter v1.2.1, so they are expected to be compatible just as well.


First, let's go ahead and install the server:

Added lines 91-125:
  apt install mercurial cmake flex bison gcc make build-essential \
    g++ libidn11-dev ssl-cert debhelper fakeroot \
    swig libsctp-dev libgcrypt20-dev libgnutls28-dev

  cd /path/to/freeDiameter
  # copy or symlink the app_opensips directory into the freeDiameter extensions/ directory
  cp -r /path/to/opensips-master/modules/aaa_diameter/app_opensips extensions/app_opensips

  # enlist the app_opensips extension for compilation
  cat >>extensions/CMakeLists.txt <<EOF
FD_EXTENSION_SUBDIR(app_opensips "OpenSIPS Diameter integration for SIP Authorization, Authentication (RFC 4740) and Accounting" ON)
EOF

  # create a build configuration (one-time operation)
  cmake \
    -DBUILD_TEST_APP:BOOL=ON \
    -DBUILD_DBG_MONITOR:BOOL=ON \
    -DSKIP_TESTS:BOOL=ON \
    -DCMAKE_BUILD_TYPE:STRING=Debug \
    ..

  # now build both freeDiameter and its extensions (any time you change the app_opensips code)
  make -j

If done correctly, you should be able to see the "app_opensips.fdx" freeDiameter extension module:

  [liviu &#9668; Z370 fDbuild-2]$ ls extensions/app_opensips.fdx -la
  -rwxrwxr-x 1 liviu liviu 112048 iun 16 22:58 extensions/app_opensips.fdx

Congratulations!

June 16, 2021, at 10:47 PM by liviu -
Changed lines 12-13 from:

This tutorial has been written for a Xubuntu 20.04 LTS, which comes with freeDiameter v1.2.1 packages. Other distros, such as Debian 10, are also known to offer standard package-based support for freeDiameter v1.2.1, so they are expected to be compatible just as well. So let's go ahead and install it:

to:

This tutorial has been written for a Xubuntu 20.04 LTS, which comes with freeDiameter v1.2.1 packages. Other distros, such as Debian 10, are also known to offer standard package-based support for freeDiameter v1.2.1, so they are expected to be compatible just as well. First, let's go ahead and install it:

Added lines 20-21:

The client side is represented by the "aaa_diameter" OpenSIPS module, which is powered by the freeDiameter client library. In this section, we will perform the necessary steps in order to configure the freeDiameter library.

Changed lines 24-25 from:

It seems freeDiameter is strongly tied to DNS hostnames, so let's add entries to the /etc/hosts file nominating the client and server. In my case, it looks like:

to:

It seems freeDiameter is strongly tied to DNS hostnames, so let's add entries to the /etc/hosts file nominating the client and server. For this tutorial, we will be using the "diameter.test" realm, with the "client" and "server" subdomains. In my case, I point both records to the local machine:

Changed lines 41-42 from:

Even though we will disable TLS support, freeDiameter will not start unless we plug some certificates into it. So let's clone the freeDiameter project, which contains some nice built-in helper tools. For this tutorial, we will be using the "diameter.test" realm and star-certificates resembling "*.diameter.test":

to:

Even though we will disable TLS support, freeDiameter will not start unless we plug some certificates into it. So let's clone the freeDiameter project, which contains some nice built-in helper tools. For ease of use, we will generate wildcard-certificates resembling "*.diameter.test":

Changed lines 56-57 from:
  # notice that the certs have been created under the "ca_data" directory
to:
  # notice that the certs have been created under the "ca_data" directory (I suggest you browse its structure a bit, it's quite fun!)
  # Extra: running "make help" will list all commands available within this tool
Changed lines 62-63 from:

Edit /etc/freeDiameter/freeDiameter-client.conf and include the following:

to:

Edit /etc/freeDiameter/freeDiameter-client.conf and provide the following:

Added lines 80-81:

Notice how we instruct the client to establish a TCP-based Diameter connection to the "server.diameter.test" Diameter peer.

Changed lines 84-85 from:

DNS

to:

The server side is represented by the app_opensips freeDiameter application.

Compiling app_opensips

Running

DNS

Changed line 99 from:

Packages

to:

Packages

June 16, 2021, at 08:44 PM by liviu -
Changed lines 68-69 from:

TLS_Cred = "/path/to/freeDiameter/contrib/PKI/ca_script2/ca_data/my_diameter_ca/clients/*.diameter.test/cert.pem", "/path/to/freeDiameter/contrib/PKI/ca_script2/ca_data/my_diameter_ca/clients/*.diameter.test/privkey.pem";

to:

TLS_Cred = "/path/to/freeDiameter/contrib/PKI/ca_script2/ca_data/my_diameter_ca/clients/*.diameter.test/cert.pem", "/path/to/freeDiameter/contrib/PKI/ca_script2/ca_data/my_diameter_ca/clients/*.diameter.test/privkey.pem";

June 16, 2021, at 08:43 PM by liviu -
Changed lines 22-23 from:

It seems freeDiameter is strongly tied to DNS hostnames, so let's add two new entries to the /etc/hosts file, pointing to your local machine, as both the OpenSIPS client and the freeDiameter server app will run on the same box. In my case, it looks like:

to:

It seems freeDiameter is strongly tied to DNS hostnames, so let's add entries to the /etc/hosts file nominating the client and server. In my case, it looks like:

Deleted line 68:
Added lines 77-81:

DNS

If your freeDiameter server is running on a separate machine, edit /etc/hosts and populate the DNS entries on that box as well:

Changed lines 83-84 from:
  sudo apt install freediameter
to:
  192.168.1.5 client.diameter.test
  192.168.1.5 server.diameter.test
Added lines 87-94:

Packages

As we will be using the "dict_sip" extension, install the appropriate package:

  sudo apt install freediameter-extensions
Changed lines 99-106 from:

Required libraries

Description

Digest Authentication

Accounting

to:

Configuring the aaa_diameter OpenSIPS module

Digest Authentication

Accounting

June 16, 2021, at 08:32 PM by liviu -
Changed lines 57-59 from:

The

Server side

to:

The freeDiameter client configuration file

Edit /etc/freeDiameter/freeDiameter-client.conf and include the following:

Identity = "client.diameter.test";
Realm = "diameter.test";
Port = 3866;
SecPort = 3867;
No_SCTP;

TLS_Cred = "/path/to/freeDiameter/contrib/PKI/ca_script2/ca_data/my_diameter_ca/clients/*.diameter.test/cert.pem", "/path/to/freeDiameter/contrib/PKI/ca_script2/ca_data/my_diameter_ca/clients/*.diameter.test/privkey.pem";

TLS_CA = "/path/to/freeDiameter/contrib/PKI/ca_script2/ca_data/my_diameter_ca/clients/*.diameter.test/certchain.pem";

ConnectPeer = "server.diameter.test" {
  No_TLS;
};
June 16, 2021, at 08:29 PM by liviu -
Changed lines 12-13 from:

This tutorial has been written for a Xubuntu 20.04 LTS, which comes with freeDiameter v1.2.1 packages. Other distros, such as Debian 10, are also known to offer standard package-based support for freeDiameter v1.2.1, so they are expected to be compatible just as well. To install it, simply run:

to:

This tutorial has been written for a Xubuntu 20.04 LTS, which comes with freeDiameter v1.2.1 packages. Other distros, such as Debian 10, are also known to offer standard package-based support for freeDiameter v1.2.1, so they are expected to be compatible just as well. So let's go ahead and install it:

  apt install freediameter
Changed lines 20-23 from:

Packages

On the client side, we have the aaa_diameter OpenSIPS connector module, which makes use of the libfdcore.so and libfdproto.so shared libraries. These libraries can be installed via:

to:

DNS

It seems freeDiameter is strongly tied to DNS hostnames, so let's add two new entries to the /etc/hosts file, pointing to your local machine, as both the OpenSIPS client and the freeDiameter server app will run on the same box. In my case, it looks like:

Changed lines 25-26 from:
  sudo apt install libfdcore6 libfdproto6
to:
  192.168.1.5 client.diameter.test
  192.168.1.5 server.diameter.test
Changed lines 29-31 from:

Configuration File

Server side

to:

Packages

The aaa_diameter OpenSIPS connector module makes use of the libfdcore.so and libfdproto.so shared libraries. These libraries can be installed via:

  sudo apt install libfdcore6 libfdproto6

Creating TLS Certificates

Even though we will disable TLS support, freeDiameter will not start unless we plug some certificates into it. So let's clone the freeDiameter project, which contains some nice built-in helper tools. For this tutorial, we will be using the "diameter.test" realm and star-certificates resembling "*.diameter.test":

  # clone the freeDiameter source code
  sudo apt install mercurial
  mkdir -p ~/src; cd ~/src
  hg clone http://www.freediameter.net/hg/freeDiameter
  cd freeDiameter
  hg checkout 1.2.1

  # generate a certificate/key pair for the client
  cd contrib/PKI/ca_script2
  make init topca=my_diameter_ca
  make newcert name="*.diameter.test" ca=my_diameter_ca

  # notice that the certs have been created under the "ca_data" directory

The

June 16, 2021, at 07:57 PM by liviu -
Added lines 9-36:

Setting up freeDiameter

This tutorial has been written for a Xubuntu 20.04 LTS, which comes with freeDiameter v1.2.1 packages. Other distros, such as Debian 10, are also known to offer standard package-based support for freeDiameter v1.2.1, so they are expected to be compatible just as well. To install it, simply run:

Client side

Packages

On the client side, we have the aaa_diameter OpenSIPS connector module, which makes use of the libfdcore.so and libfdproto.so shared libraries. These libraries can be installed via:

  sudo apt install libfdcore6 libfdproto6

Configuration File

Server side

  sudo apt install freediameter


The required libraries are , and can be installed via:

Required libraries

June 16, 2021, at 03:27 PM by liviu -
Changed lines 12-225 from:

Tip: For a broader view on the "full sharing" topology, see this blog post.


The "full sharing" clustering strategy for the OpenSIPS 2.4+ user location service is a way of performing full-mesh data replication between the nodes of an OpenSIPS cluster. Each node will hold the entire user location dataset, thus being able to serve lookups for any SIP UA registered to the cluster. This type of clustering offers:

  • high availability (any cluster node can properly serve the incoming SIP traffic)
  • distributed NAT pinging support (NAT pinging origination can be spread across cluster nodes)
  • restart persistency for all cluster nodes
  • good horizontal scalability, capped by the maximum amount of data that a single node can handle


IMPORTANT: a mandatory requirement of the full sharing clustering strategy is that any node must be able to route to any registered SIP UA. With simple full sharing setups, such as active/passive, this can be achieved by using a shared virtual IP address between the two nodes. If dealing with larger cluster sizes or if the endpoints register via TCP/TLS, then a front-ending entity (e.g. a SIP load balancer) must be placed in front of the cluster, with enabled Path header support, so any network routing restrictions are alleviated.


Building upon this setup, the federated user location clustering strategy ensures similar features as above, except it will not replicate user location data across different points of presence, allowing you to scale each POP according to the size of its subscriber pool.

Active/passive "full sharing" setup

Configuration

For the smallest possible setup (a 2-node active/passive with a virtual IP in front), you will need:

  • two OpenSIPS instances
  • a working shared/virtual IP between the instances (e.g. using keepalived, vrrpd, etc.)
  • a MySQL instance, for provisioning


The relevant opensips.cfg sections:


listen = sip:10.0.0.150 # virtual IP (same on both nodes)
listen = bin:10.0.0.177

loadmodule "usrloc.so"
modparam("usrloc", "use_domain", 1)
modparam("usrloc", "working_mode_preset", "full-sharing-cluster")
modparam("usrloc", "location_cluster", 1)

loadmodule "clusterer.so"
modparam("clusterer", "current_id", 1) # node number #1
modparam("clusterer", "seed_fallback_interval", 5)
modparam("clusterer", "db_url", "mysql://opensips:opensipsrw@localhost/opensips")

loadmodule "proto_bin.so"

Provisioning

INSERT INTO clusterer(id, cluster_id, node_id, url, state, no_ping_retries, priority, sip_addr, flags, description) VALUES \
(NULL, 1, 1, 'bin:10.0.0.177', 1, 3, 50, NULL, 'seed', NULL), \
(NULL, 1, 2, 'bin:10.0.0.178', 1, 3, 50, NULL, NULL, NULL);


idcluster idnode_idurlstateno_ping_retriesprioritysip_addrflagsdescription
1411bin:10.0.0.1771350NULLseedNULL
1512bin:10.0.0.1781350NULLNULLNULL

Native "full sharing" clusterer table

NAT pinging

Some setups require periodic SIP OPTIONS pings originated by the registrar towards some of the contacts in order to keep the NAT bindings alive. Here is an example configuration:

loadmodule "nathelper.so"
modparam("nathelper", "natping_interval", 30)
modparam("nathelper", "sipping_from", "sip:pinger@localhost")
modparam("nathelper", "sipping_bflag", "SIPPING_ENABLE")
modparam("nathelper", "remove_on_timeout_bflag", "SIPPING_RTO")
modparam("nathelper", "max_pings_lost", 5)

We then enable these branch flags for some or all contacts before calling save():

    ...
    setbflag(SIPPING_ENABLE);
    setbflag(SIPPING_RTO);

    if (!save("location"))
        sl_reply_error();
    ...


To prevent any "permission denied" error logs on the passive node that's trying to originate NAT pings, make sure to hook the nh_enable_ping MI command into your active->passive and passive->active transitions of the VIP:

    opensipsctl fifo nh_enable_ping 1 # run this on the machine that takes over the VIP (new active)
    opensipsctl fifo nh_enable_ping 0 # run this on the machine that gives up the VIP (new passive)

NoSQL "full sharing" cluster with a SIP front-end

This is the ultra-scalable version of the OpenSIPS user location, allowing you to support subscriber pool sizes exceeding the order of millions. By letting an external, specialized database cluster manage all the registration data, we are able to decouple the SIP signaling and data storage systems. This, in turn, allows each system to be scaled without wasting resources or affecting the other one.

Configuration

For the smallest possible setup, you will need:

  • a SIP front-end proxy sitting in front of the cluster, with SIP Path support
  • two backend OpenSIPS instances, forming the cluster
  • a NoSQL DB instance, such as Cassandra or MongoDB, to hold all registrations (you can upgrade it into a cluster later)
  • a MySQL instance, for provisioning


On the backend layer (cluster instances), here are the relevant opensips.cfg sections:


listen = sip:10.0.0.177
listen = bin:10.0.0.177

loadmodule "usrloc.so"
modparam("usrloc", "use_domain", 1)
modparam("usrloc", "working_mode_preset", "full-sharing-cachedb-cluster")
modparam("usrloc", "location_cluster", 1)

# with Cassandra, make sure to create the keyspace and table beforehand:
# CREATE KEYSPACE IF NOT EXISTS opensips WITH replication = {'class': 'SimpleStrategy', 'replication_factor': '1'}  AND durable_writes = true;
# USE opensips;
# CREATE TABLE opensips.userlocation (
#     aor text,
#     aorhash int,
#     contacts map<text, frozen<map<text, text>>>,
#     PRIMARY KEY (aor));
loadmodule "cachedb_cassandra.so"
modparam("usrloc", "cachedb_url", "cassandra://10.0.0.180:9042/opensips.userlocation")

# with MongoDB, we don't need to create any database or collection...
loadmodule "cachedb_mongodb.so"
modparam("usrloc", "cachedb_url", "mongodb://10.0.0.180:27017/opensipsDB.userlocation")

loadmodule "clusterer.so"
modparam("clusterer", "current_id", 1) # node number #1
modparam("clusterer", "db_url", "mysql://opensips:opensipsrw@localhost/opensips")

loadmodule "proto_bin.so"

...

route {
    ...

    # store the registration into the NoSQL DB
    if (!save("location", "p1v")) {
        send_reply("500", "Server Internal Error");
        exit;
    }

    ...
}

Provisioning

INSERT INTO clusterer(id, cluster_id, node_id, url, state, no_ping_retries, priority, sip_addr, flags, description) VALUES \
(NULL, 1, 1, 'bin:10.0.0.177', 1, 3, 50, NULL, 'seed', NULL), \
(NULL, 1, 2, 'bin:10.0.0.178', 1, 3, 50, NULL, NULL, NULL);


idcluster idnode_idurlstateno_ping_retriesprioritysip_addrflagsdescription
1411bin:10.0.0.1771350NULLNULLNULL
1512bin:10.0.0.1781350NULLNULLNULL

NoSQL "full sharing" clusterer table

Shared NAT pinging

loadmodule "nathelper.so"
modparam("nathelper", "natping_interval", 30)
modparam("nathelper", "sipping_from", "sip:pinger@localhost")
modparam("nathelper", "sipping_bflag", "SIPPING_ENABLE")
modparam("nathelper", "remove_on_timeout_bflag", "SIPPING_RTO")
modparam("nathelper", "max_pings_lost", 5)

# partition pings across cluster nodes
modparam("usrloc", "shared_pinging", 1)

We then enable these branch flags for some or all contacts before calling save():

    ...

    setbflag(SIPPING_ENABLE);
    setbflag(SIPPING_RTO);

    # store the registration, along with the Path header, into the NoSQL DB
    if (!save("location", "p1v")) {
        sl_reply_error();
        exit;
    }

    ...
to:

Digest Authentication

Accounting

June 16, 2021, at 03:26 PM by liviu -
Changed line 4 from:

How to configure and deploy the aaa_diameter module and the "app_opensips" freeDiameter application

to:

How to configure and deploy Diameter Authentication and Accounting

June 16, 2021, at 03:26 PM by liviu -
Added lines 1-225:
Documentation -> Tutorials -> Diameter Authentication and Accounting

This page has been visited 4552 times.

How to configure and deploy the aaa_diameter module and the "app_opensips" freeDiameter application

by Liviu Chircu

(:toc-float Table of Content:)


Description

Tip: For a broader view on the "full sharing" topology, see this blog post.


The "full sharing" clustering strategy for the OpenSIPS 2.4+ user location service is a way of performing full-mesh data replication between the nodes of an OpenSIPS cluster. Each node will hold the entire user location dataset, thus being able to serve lookups for any SIP UA registered to the cluster. This type of clustering offers:

  • high availability (any cluster node can properly serve the incoming SIP traffic)
  • distributed NAT pinging support (NAT pinging origination can be spread across cluster nodes)
  • restart persistency for all cluster nodes
  • good horizontal scalability, capped by the maximum amount of data that a single node can handle


IMPORTANT: a mandatory requirement of the full sharing clustering strategy is that any node must be able to route to any registered SIP UA. With simple full sharing setups, such as active/passive, this can be achieved by using a shared virtual IP address between the two nodes. If dealing with larger cluster sizes or if the endpoints register via TCP/TLS, then a front-ending entity (e.g. a SIP load balancer) must be placed in front of the cluster, with enabled Path header support, so any network routing restrictions are alleviated.


Building upon this setup, the federated user location clustering strategy ensures similar features as above, except it will not replicate user location data across different points of presence, allowing you to scale each POP according to the size of its subscriber pool.

Active/passive "full sharing" setup

Configuration

For the smallest possible setup (a 2-node active/passive with a virtual IP in front), you will need:

  • two OpenSIPS instances
  • a working shared/virtual IP between the instances (e.g. using keepalived, vrrpd, etc.)
  • a MySQL instance, for provisioning


The relevant opensips.cfg sections:


listen = sip:10.0.0.150 # virtual IP (same on both nodes)
listen = bin:10.0.0.177

loadmodule "usrloc.so"
modparam("usrloc", "use_domain", 1)
modparam("usrloc", "working_mode_preset", "full-sharing-cluster")
modparam("usrloc", "location_cluster", 1)

loadmodule "clusterer.so"
modparam("clusterer", "current_id", 1) # node number #1
modparam("clusterer", "seed_fallback_interval", 5)
modparam("clusterer", "db_url", "mysql://opensips:opensipsrw@localhost/opensips")

loadmodule "proto_bin.so"

Provisioning

INSERT INTO clusterer(id, cluster_id, node_id, url, state, no_ping_retries, priority, sip_addr, flags, description) VALUES \
(NULL, 1, 1, 'bin:10.0.0.177', 1, 3, 50, NULL, 'seed', NULL), \
(NULL, 1, 2, 'bin:10.0.0.178', 1, 3, 50, NULL, NULL, NULL);


idcluster idnode_idurlstateno_ping_retriesprioritysip_addrflagsdescription
1411bin:10.0.0.1771350NULLseedNULL
1512bin:10.0.0.1781350NULLNULLNULL

Native "full sharing" clusterer table

NAT pinging

Some setups require periodic SIP OPTIONS pings originated by the registrar towards some of the contacts in order to keep the NAT bindings alive. Here is an example configuration:

loadmodule "nathelper.so"
modparam("nathelper", "natping_interval", 30)
modparam("nathelper", "sipping_from", "sip:pinger@localhost")
modparam("nathelper", "sipping_bflag", "SIPPING_ENABLE")
modparam("nathelper", "remove_on_timeout_bflag", "SIPPING_RTO")
modparam("nathelper", "max_pings_lost", 5)

We then enable these branch flags for some or all contacts before calling save():

    ...
    setbflag(SIPPING_ENABLE);
    setbflag(SIPPING_RTO);

    if (!save("location"))
        sl_reply_error();
    ...


To prevent any "permission denied" error logs on the passive node that's trying to originate NAT pings, make sure to hook the nh_enable_ping MI command into your active->passive and passive->active transitions of the VIP:

    opensipsctl fifo nh_enable_ping 1 # run this on the machine that takes over the VIP (new active)
    opensipsctl fifo nh_enable_ping 0 # run this on the machine that gives up the VIP (new passive)

NoSQL "full sharing" cluster with a SIP front-end

This is the ultra-scalable version of the OpenSIPS user location, allowing you to support subscriber pool sizes exceeding the order of millions. By letting an external, specialized database cluster manage all the registration data, we are able to decouple the SIP signaling and data storage systems. This, in turn, allows each system to be scaled without wasting resources or affecting the other one.

Configuration

For the smallest possible setup, you will need:

  • a SIP front-end proxy sitting in front of the cluster, with SIP Path support
  • two backend OpenSIPS instances, forming the cluster
  • a NoSQL DB instance, such as Cassandra or MongoDB, to hold all registrations (you can upgrade it into a cluster later)
  • a MySQL instance, for provisioning


On the backend layer (cluster instances), here are the relevant opensips.cfg sections:


listen = sip:10.0.0.177
listen = bin:10.0.0.177

loadmodule "usrloc.so"
modparam("usrloc", "use_domain", 1)
modparam("usrloc", "working_mode_preset", "full-sharing-cachedb-cluster")
modparam("usrloc", "location_cluster", 1)

# with Cassandra, make sure to create the keyspace and table beforehand:
# CREATE KEYSPACE IF NOT EXISTS opensips WITH replication = {'class': 'SimpleStrategy', 'replication_factor': '1'}  AND durable_writes = true;
# USE opensips;
# CREATE TABLE opensips.userlocation (
#     aor text,
#     aorhash int,
#     contacts map<text, frozen<map<text, text>>>,
#     PRIMARY KEY (aor));
loadmodule "cachedb_cassandra.so"
modparam("usrloc", "cachedb_url", "cassandra://10.0.0.180:9042/opensips.userlocation")

# with MongoDB, we don't need to create any database or collection...
loadmodule "cachedb_mongodb.so"
modparam("usrloc", "cachedb_url", "mongodb://10.0.0.180:27017/opensipsDB.userlocation")

loadmodule "clusterer.so"
modparam("clusterer", "current_id", 1) # node number #1
modparam("clusterer", "db_url", "mysql://opensips:opensipsrw@localhost/opensips")

loadmodule "proto_bin.so"

...

route {
    ...

    # store the registration into the NoSQL DB
    if (!save("location", "p1v")) {
        send_reply("500", "Server Internal Error");
        exit;
    }

    ...
}

Provisioning

INSERT INTO clusterer(id, cluster_id, node_id, url, state, no_ping_retries, priority, sip_addr, flags, description) VALUES \
(NULL, 1, 1, 'bin:10.0.0.177', 1, 3, 50, NULL, 'seed', NULL), \
(NULL, 1, 2, 'bin:10.0.0.178', 1, 3, 50, NULL, NULL, NULL);


idcluster idnode_idurlstateno_ping_retriesprioritysip_addrflagsdescription
1411bin:10.0.0.1771350NULLNULLNULL
1512bin:10.0.0.1781350NULLNULLNULL

NoSQL "full sharing" clusterer table

Shared NAT pinging

loadmodule "nathelper.so"
modparam("nathelper", "natping_interval", 30)
modparam("nathelper", "sipping_from", "sip:pinger@localhost")
modparam("nathelper", "sipping_bflag", "SIPPING_ENABLE")
modparam("nathelper", "remove_on_timeout_bflag", "SIPPING_RTO")
modparam("nathelper", "max_pings_lost", 5)

# partition pings across cluster nodes
modparam("usrloc", "shared_pinging", 1)

We then enable these branch flags for some or all contacts before calling save():

    ...

    setbflag(SIPPING_ENABLE);
    setbflag(SIPPING_RTO);

    # store the registration, along with the Path header, into the NoSQL DB
    if (!save("location", "p1v")) {
        sl_reply_error();
        exit;
    }

    ...

Page last modified on May 12, 2022, at 05:54 PM