g++ libfreediameter-dev libidn11-dev ssl-cert debhelper fakeroot \

  # for Digest Auth support, the MySQL devel library is needed.  On Debian, for example:
  apt install libmariadb-dev libmariadb-dev-compat

  # also, fix a strange compilation issue specific to this revision, by applying this patch:

  # 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 )

        record_route();
        create_dialog();

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

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.

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:

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

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

Native "full sharing" clusterer table

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

freeDiameter Client

DNS

Packages

Creating TLS Certificates

The freeDiameter client configuration file

freeDiameter Server

Compiling app_opensips

DNS

Packages

The freeDiameter server configuration file

OpenSIPS configuration

Digest Authentication

Accounting

asdasd

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

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

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

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:

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

  # create a build configuration (one-time operation, feel free to disable some of these flags or include others!)

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

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

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.

freeDiameter Server

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

  mkdir fDbuild
  cd fDbuild

  [liviu@Z370 fDbuild]$ ls extensions/app_opensips.fdx -la

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:

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):

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

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:

  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 ◄ Z370 fDbuild-2]$ ls extensions/app_opensips.fdx -la
  -rwxrwxr-x 1 liviu liviu 112048 iun 16 22:58 extensions/app_opensips.fdx

Congratulations!

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:

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.

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:

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":

  # 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

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

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

The server side is represented by the app_opensips freeDiameter application.

Compiling app_opensips

Running

DNS

Packages

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";

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:

DNS

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

  192.168.1.5 client.diameter.test
  192.168.1.5 server.diameter.test

Packages

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

  sudo apt install freediameter-extensions

Configuring the aaa_diameter OpenSIPS module

Digest Authentication

Accounting

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;
};

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

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:

  192.168.1.5 client.diameter.test
  192.168.1.5 server.diameter.test

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

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

Digest Authentication

Accounting

How to configure and deploy Diameter Authentication and Accounting

Documentation -> Tutorials -> Diameter Authentication and Accounting

This page has been visited 6772 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);

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);

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;
    }

    ...