# &adminguide;

## Overview

The DMQ module implements a distributed message queue on top of Kamailio in order to enable the passing/replication of data between multiple instances. The DMQ "nodes" within the system are grouped in a logical entity called the DMQ "bus" and are able to communicate with each other by sending/receiving messages (either by broadcast or directly to a specific node). The system transparently deals with node discovery, consistency, retransmissions, etc.

Other entities ("peers") are then able to utlize the DMQ bus to pass messages between themselves. Peers are grouped by name in order to ensure the correct messages are passed to the relevant peers. This grouping of peers can be compared to a topic in a typical pub/sub system.

## Dependencies

### &kamailio; Modules

The following modules must be loaded before this module:

- sl.

- tm.

### External Libraries or Applications

- The DMQ module itself has no external dependencies. However, each peer will need to use its own (de)serialization mechanism. Some examples are libtpl, protobuf. .

## Parameters

### `server_address`(str)

The local server address. This is the interface over which the DMQ engine will send/receive messages.

Default value is NULL.

#### Set `server_address` parameter

    ...
    modparam("dmq", "server_address", "sip:10.0.0.20:5060")
    ...

### `notification_address`(str)

The address of another DMQ node from which the local node should retrieve initial information about all other nodes.

Default value is NULL.

#### Set `notification_address` parameter

    ...
    modparam("dmq", "notification_address", "sip:10.0.0.21:5060")
    ...

### `num_workers`(int)

The number of worker threads for sending/receiving messages.

Default value is 2.

#### Set `num_workers` parameter

    ...
    modparam("dmq", "num_threads", 4)
    ...

### `ping_interval`(int)

The number of seconds between node pings (for checking status of other nodes).

Minimum value is 60 (default).

#### Set `ping_interval` parameter

    ...
    modparam("dmq", "ping_interval", 90)
    ...

## Functions

### `dmq_handle_message()`

Handles a DMQ message by passing it to the appropriate local peer (module). The peer is identified by the user part of the To header.

This function can be used from REQUEST_ROUTE.

#### `dmq_handle_message` usage

    ...
            if(is_method("KDMQ"))
            {
                    dmq_handle_message();
            }
    ...

### `dmq_send_message(peer, node, body, content_type)`

Sends a DMQ message directly from config file.

Meaning of parameters:

- peer - name of peer that should handle the message.

- node - the node to which the message should be sent.

- body - the message body.

- content_type - the MIME type of the message body.

This function can be used from any route.

#### `dmq_send_message` usage

    ...
    	dmq_send_message("peer_name", "sip:10.0.0.21:5060", "Message body...", "text/plain");
    ...