How to Use the Enhanced MongoDB Module in OpenSIPS 2.3

Great news for all users of the OpenSIPS “cachedb_mongodb” module! After four successful years since its initial release in Jan 2013, the driver will benefit from a complete revamp in the upcoming OpenSIPS 2.3, and will work on top of the latest libmongoc 1.6.0.

The updated module will be compatible with all MongoDB 2.4+ servers. The main reasons behind the update are:

• support for MongoDB 3.0+ servers (current latest stable MongoDB is 3.4)
• full support for database commands
• packaging support for recent libmongoc versions

Let’s go through all the changes that this new version brings, from library installation to module usage in the OpenSIPS script, as well as newly introduced features.

Installing libmongoc

The upcoming module will support several versions of libmongoc, starting with v1.0.0 all the way up to the latest v1.6.0. Recent versions of Debian/Ubuntu should provide libmongoc:

$ apt-get install libmongoc-1.0-0

For CentOS and RHEL 7:

$ yum install mongo-c-driver

For detailed build instructions, please head over to mongoc.org/libmongoc.

Using the OpenSIPS key-value interface with MongoDB

Things haven’t changed at all here, as the new driver implements the same interface everyone has gotten used to while writing their OpenSIPS scripts over the years:

• cache_store(“mongodb:ipblacklist”, “$fU”, “$si”)
• cache_fetch(“mongodb:ipblacklist”, “$fU”, “$var(val)”)
• cache_remove(“mongodb:ipblacklist”, “$fU”)
• cache_add(“mongodb:billing”, “credit_$fU”, “$var(topup)”)
• cache_sub(“mongodb:billing”, “credit_$fU”, “$var(call_cost)”)

Hint: The first three examples work with a collection of blacklisted username-IP pairs ($fU refers to the “From” header field username, while $si is the source IP of the SIP message). The last two examples handle credit operations on a billing MongoDB database.

A detailed tutorial for the OpenSIPS key-value interface can be found here.

MongoDB commands in the OpenSIPS script

IMPORTANT: if upgrading to OpenSIPS 2.3+, you will need to rewrite all MongoDB raw queries in your OpenSIPS script so they match the standard MongoDB command syntax!

Although this is a backwards-incompatible change, it’s the only way to make progress. The current “cachedb_mongodb” module uses a custom raw query syntax, created by the module’s initial writer, Vlad Paiu. At the time of the module’s initial publish, the MongoDB server was only beginning to support a few basic raw queries (create / update / delete starting with 2.6!). So a fixed JSON format to provide these queries made sense, as it would allow the module to be compatible with MongoDB 2.4 servers and below.

Now that MongoDB has taken its time to expand its command repertoire, we might as well make good use of it. The new way of providing raw MongoDB queries is identical to the standard MongoDB command syntax, available here.

Here are some example raw queries using the new syntax:

cache_raw_query("mongodb:cluster", "{ \
    \"insert\": \"ip_blacklist\", \
    \"documents\": [{ \
        \"username\": \"$fU\", \
        \"ip\": \"$si\", \
        \"attempts\": 1 \
     }]}",
 "$avp(out)");
 xlog("INSERT RAW QUERY returned $rc, output: '$avp(out)'\n");

cache_raw_query("mongodb:cluster", "{ \
    \"update\": \"ip_blacklist\", \
    \"updates\": [{ \
        \"q\": { \
            \"username\": \"$fU\", \
            \"ip\": \"$si\" \
         }, \
        \"u\": { \
            \"$$inc\": {\"attempts\": 1} \
         } \
      }]}",
 "$avp(out)");
 xlog("UPDATE RAW QUERY returned $rc, output: '$avp(out)'\n");

To retain backwards compatibility for these commands with MongoDB servers that have no support for them (e.g. MongoDB 2.4 – 3.0), the driver can convert the commands to normal queries. Just enable one of the following module parameters, and the raw queries will also work with older server versions:

modparam("cachedb_mongodb", "compat_mode_2.4", 1)

modparam("cachedb_mongodb", "compat_mode_3.0", 1)

(Note: in compatibility mode, all optional command options will be ignored!)

Module contributors

Over time, the “cachedb_mongodb” OpenSIPS module has received contributions from the following developers:

• Vlad Paiu (initial version)
• Ovidiu Sas
• Liviu Chircu (current maintainer)