NATS Module

Emmanuel Schmidbauer

   <eschmidbauer@gmail.com>

Joe Mordica

   <joe@voxo.co>

Edited by

Emmanuel Schmidbauer

   <eschmidbauer@gmail.com>

   Copyright © 2021 Voxcom Inc

   Copyright © 2021 VOXO
     __________________________________________________________________

   Table of Contents

   1. Admin Guide

        1. Overview
        2. How it works
        3. Dependencies

              3.1. Kamailio Modules
              3.2. External Libraries or Applications

        4. Parameters

              4.1. nats_url (str)
              4.2. tls (int)
              4.3. tls_ca_file (str)
              4.4. tls_cert_file (str)
              4.5. tls_key_file (str)
              4.6. tls_expected_hostname (str)
              4.7. num_publish_workers (int)
              4.8. subject_queue_group (str)
              4.9. event_callback (str)

        5. Functions

              5.1. nats_publish(subject, payload, reply)

        6. Pseudo Variables
        7. Event Routes

   List of Examples

   1.1. Set nats_url parameter
   1.2. Set tls parameter
   1.3. Set tls_ca_file parameter
   1.4. Set tls_cert_file parameter
   1.5. Set tls_key_file parameter
   1.6. Set tls_expected_hostname parameter
   1.7. Set num_publish_workers parameter
   1.8. TLS configuration example
   1.9. Set subject_queue_group parameter
   1.10. Set event_callback parameter
   1.11. nats_publish usage
   1.12. Example usage of $natsData pseudo variable
   1.13. Define the event routes

Chapter 1. Admin Guide

   Table of Contents

   1. Overview
   2. How it works
   3. Dependencies

        3.1. Kamailio Modules
        3.2. External Libraries or Applications

   4. Parameters

        4.1. nats_url (str)
        4.2. tls (int)
        4.3. tls_ca_file (str)
        4.4. tls_cert_file (str)
        4.5. tls_key_file (str)
        4.6. tls_expected_hostname (str)
        4.7. num_publish_workers (int)
        4.8. subject_queue_group (str)
        4.9. event_callback (str)

   5. Functions

        5.1. nats_publish(subject, payload, reply)

   6. Pseudo Variables
   7. Event Routes

1. Overview

   The module provides an NATS consumer for Kamailio. NATS is a real time
   distributed messaging platform, more details about it can be found at
   nats.io .

   From a high-level perspective, the module may be used for:
     * Provide a real-time distributed messaging layer in Kamailio

   Supported NATS operations are:
     * Subscribe to a Subject and Queue Group

2. How it works

   The module creates invokes a consumer process for each defined
   `subject_queue_group`. The messages are visible in event routes
   matching the "subject" name.

3. Dependencies

   3.1. Kamailio Modules
   3.2. External Libraries or Applications

3.1. Kamailio Modules

   The following modules must be loaded before this module:
     * none .

3.2. External Libraries or Applications

   The following libraries or applications must be installed
     * libuv
     * nats.c - https://github.com/nats-io/nats.c/releases

4. Parameters

   4.1. nats_url (str)
   4.2. tls (int)
   4.3. tls_ca_file (str)
   4.4. tls_cert_file (str)
   4.5. tls_key_file (str)
   4.6. tls_expected_hostname (str)
   4.7. num_publish_workers (int)
   4.8. subject_queue_group (str)
   4.9. event_callback (str)

4.1.  nats_url (str)

   The nats url.

   Usage: nats related.

   Default value is nats://127.0.0.1:4222

   Example 1.1.  Set nats_url parameter
...
modparam("nats", "nats_url", "nats://127.0.0.1:4222")
modparam("nats", "nats_url", "nats://user1:pass1@127.0.1.2:4222") // with auth
modparam("nats", "nats_url", "nats://127.1.2.3:4222")
...

4.2.  tls (int)

   Enable TLS for all configured NATS servers.

   When enabled, tls_ca_file must also be set. If client authentication is
   required, tls_cert_file and tls_key_file must be set together.

   Default value is “0”.

   Example 1.2.  Set tls parameter
...
modparam("nats", "tls", 1)
...

4.3.  tls_ca_file (str)

   Path to the CA certificate bundle used to validate the NATS server
   certificate.

   This parameter is required when tls is enabled.

   Default value is not set.

   Example 1.3.  Set tls_ca_file parameter
...
modparam("nats", "tls_ca_file", "/etc/kamailio/nats/ca.crt")
...

4.4.  tls_cert_file (str)

   Path to the client certificate presented to the NATS server for mTLS.

   If set, tls_key_file must also be set.

   Default value is not set.

   Example 1.4.  Set tls_cert_file parameter
...
modparam("nats", "tls_cert_file", "/etc/kamailio/nats/client.crt")
...

4.5.  tls_key_file (str)

   Path to the client private key used with tls_cert_file.

   If set, tls_cert_file must also be set.

   Default value is not set.

   Example 1.5.  Set tls_key_file parameter
...
modparam("nats", "tls_key_file", "/etc/kamailio/nats/client.key")
...

4.6.  tls_expected_hostname (str)

   Expected hostname in the NATS server certificate. Use it when the
   server certificate hostname should be pinned explicitly.

   Default value is not set.

   Example 1.6.  Set tls_expected_hostname parameter
...
modparam("nats", "tls_expected_hostname", "nats.internal")
...

4.7.  num_publish_workers (int)

   The number of worker threads for publishing messages.

   Usage: nats related.

   Default value is “2”.

   Example 1.7.  Set num_publish_workers parameter
...
modparam("nats", "num_publish_workers", 4)
...

   Example 1.8. TLS configuration example
...
modparam("nats", "nats_url", "nats://nats-1:4222")
modparam("nats", "nats_url", "nats://nats-2:4222")
modparam("nats", "tls", 1)
modparam("nats", "tls_ca_file", "/etc/kamailio/nats/ca.crt")
modparam("nats", "tls_cert_file", "/etc/kamailio/nats/client.crt")
modparam("nats", "tls_key_file", "/etc/kamailio/nats/client.key")
modparam("nats", "tls_expected_hostname", "nats.internal")
...

4.8.  subject_queue_group (str)

   The NATS Subject and Queue Group. Separated by ":"

   Usage: nats related.

   Default value is not set.

   Example 1.9.  Set subject_queue_group parameter
...
modparam("nats", "subject_queue_group", "Kamailio-World:2020")
modparam("nats", "subject_queue_group", "Kamailio-World:2021") // this will crea
te two processes for the Kamailio-World subject
modparam("nats", "subject_queue_group", "MyQueue1:2021")
modparam("nats", "subject_queue_group", "MyQueue2:2021")
...

4.9.  event_callback (str)

   Name of the KEMI function to be executed instead of the event route.

   Default value is not set.

   Example 1.10.  Set event_callback parameter
...
modparam("nats", "event_callback", "ksr_nats_event")

-- event callback function implemented in Lua
function ksr_nats_event(evname)
        KSR.info("===== nats module received event: " .. evname ..
                ", data:" .. KSR.pv.gete('$natsData') .. "\n");
        return 1;
end
...

5. Functions

   5.1. nats_publish(subject, payload, reply)

5.1.  nats_publish(subject, payload, reply)

   Publishes the payload to subject, with an optional reply subject.

   Example 1.11.  nats_publish usage
...
$var(my_info) = "$ci=" + $ci + " $fU=" + $fU;
nats_publish("mysubject", "$var(my_info)"); # publish $var(my_info) to "mysubjec
t"

# publish $var(my_info) to "mysubject" with a reply.topic topic, so a response
# can be published back from the other side, like the NATS Request-Reply mode.
nats_publish("mysubject", "$var(my_info)", "reply.topic");
...

6. Pseudo Variables

   Example 1.12. Example usage of $natsData pseudo variable
        ...
        xlog("L_INFO", "received payload $natsData");
}

     * $natsData Contains the payload of a consumed message

7. Event Routes

   The worker process issues an event-route where we can act on the
   received payload. The name of the event-route name must match the
   subject of the message.

   Example 1.13. Define the event routes
...
modparam("nats", "subject_queue_group", "Kamailio-World:2021")
modparam("nats", "subject_queue_group", "MyQueue1:2021")
...

event_route[nats:Kamailio-World]
{
        if ($(natsData{json.parse,Event-Package}) == "dialog") {
                xlog("L_INFO", "received $(natsData{json.parse,Event-Package}) u
pdate for $(natsData{json.parse,From})");
                pua_json_publish($natsData);
        }
}

event_route[nats:MyQueue1]
{
        xlog("L_INFO", "received $(natsData{json.parse,Event-Package}) update fo
r $(natsData{json.parse,From})");
        ...
}
