modules/dmq/README
24d30bd0
 Distributed Message Queue Module
 
 Marius Ovidiu Bucur
 
923d09f0
 Charles Chance
 
    Sipcentric Ltd.
 
24d30bd0
 Edited by
 
 Marius Ovidiu Bucur
 
923d09f0
 Edited by
 
 Charles Chance
 
5e37d0c9
    Copyright © 2011 Marius Bucur
923d09f0
 
5e37d0c9
    Copyright © 2013 Charles Chance, Sipcentric Ltd.
24d30bd0
      __________________________________________________________________
 
    Table of Contents
 
    1. Admin Guide
 
         1. Overview
         2. Dependencies
 
               2.1. Kamailio Modules
               2.2. External Libraries or Applications
 
ba7961bb
         3. Parameters
24d30bd0
 
923d09f0
               3.1. server_address(str)
               3.2. notification_address(str)
               3.3. num_workers(int)
               3.4. ping_interval(int)
 
         4. Functions
 
               4.1. dmq_handle_message()
9978906d
               4.2. dmq_send_message(peer, node, body, content_type)
5e37d0c9
               4.3. dmq_bcast_message(peer, body, content_type)
9556f8a3
               4.4. dmq_t_replicate([skip_loop_test])
               4.5. dmq_is_from_node()
24d30bd0
 
    2. Developer Guide
 
         1. dmq_load_api(dmq_api_t* api)
923d09f0
         2. register_dmq_peer(dmq_peer_t* peer)
         3. bcast_message(dmq_peer_t* peer, str* body, dmq_node_t* except,
9978906d
                 dmq_resp_cback_t* resp_cback, int max_forwards, str*
                 content_type)
923d09f0
 
         4. send_message(dmq_peer_t* peer, str* body, dmq_node_t* node,
9978906d
                 dmq_resp_cback_t* resp_cback, int max_forwards, str*
                 content_type)
24d30bd0
 
    List of Examples
 
923d09f0
    1.1. Set server_address parameter
    1.2. Set notification_address parameter
    1.3. Set num_workers parameter
    1.4. Set ping_interval parameter
    1.5. dmq_handle_message usage
    1.6. dmq_send_message usage
5e37d0c9
    1.7. dmq_bcast_message usage
9556f8a3
    1.8. dmq_t_replicate usage
    1.9. dmq_is_from_node usage
24d30bd0
    2.1. dmq_api_t structure
923d09f0
    2.2. register_dmq_peer usage
    2.3. bcast_message usage
    2.4. send_message usage
24d30bd0
 
 Chapter 1. Admin Guide
 
    Table of Contents
 
    1. Overview
    2. Dependencies
 
         2.1. Kamailio Modules
         2.2. External Libraries or Applications
 
ba7961bb
    3. Parameters
24d30bd0
 
923d09f0
         3.1. server_address(str)
         3.2. notification_address(str)
         3.3. num_workers(int)
         3.4. ping_interval(int)
 
    4. Functions
 
         4.1. dmq_handle_message()
9978906d
         4.2. dmq_send_message(peer, node, body, content_type)
5e37d0c9
         4.3. dmq_bcast_message(peer, body, content_type)
9556f8a3
         4.4. dmq_t_replicate([skip_loop_test])
         4.5. dmq_is_from_node()
24d30bd0
 
 1. Overview
 
923d09f0
    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.
24d30bd0
 
 2. Dependencies
 
    2.1. Kamailio Modules
    2.2. External Libraries or Applications
 
 2.1. Kamailio Modules
 
    The following modules must be loaded before this module:
      * sl.
      * tm.
 
 2.2. External Libraries or Applications
 
923d09f0
      * The DMQ module itself has no external dependencies. However, each
        peer will need to use its own (de)serialization mechanism. Some
24d30bd0
        examples are libtpl, protobuf. .
 
ba7961bb
 3. Parameters
24d30bd0
 
923d09f0
    3.1. server_address(str)
    3.2. notification_address(str)
    3.3. num_workers(int)
    3.4. ping_interval(int)
 
 3.1. server_address(str)
 
    The local server address. This is the interface over which the DMQ
    engine will send/receive messages.
 
5e37d0c9
    Default value is “NULL”.
923d09f0
 
    Example 1.1. Set server_address parameter
 ...
 modparam("dmq", "server_address", "sip:10.0.0.20:5060")
 ...
 
 3.2. notification_address(str)
 
    The address of another DMQ node from which the local node should
    retrieve initial information about all other nodes.
 
5e37d0c9
    Default value is “NULL”.
923d09f0
 
    Example 1.2. Set notification_address parameter
 ...
 modparam("dmq", "notification_address", "sip:10.0.0.21:5060")
 ...
 
 3.3. num_workers(int)
 
    The number of worker threads for sending/receiving messages.
 
5e37d0c9
    Default value is “2”.
24d30bd0
 
923d09f0
    Example 1.3. Set num_workers parameter
 ...
 modparam("dmq", "num_threads", 4)
 ...
 
 3.4. ping_interval(int)
 
    The number of seconds between node pings (for checking status of other
    nodes).
 
5e37d0c9
    Minimum value is “60” (default).
923d09f0
 
    Example 1.4. Set ping_interval parameter
 ...
 modparam("dmq", "ping_interval", 90)
 ...
 
 4. Functions
24d30bd0
 
923d09f0
    4.1. dmq_handle_message()
9978906d
    4.2. dmq_send_message(peer, node, body, content_type)
5e37d0c9
    4.3. dmq_bcast_message(peer, body, content_type)
9556f8a3
    4.4. dmq_t_replicate([skip_loop_test])
    4.5. dmq_is_from_node()
24d30bd0
 
5e37d0c9
 4.1.  dmq_handle_message()
24d30bd0
 
923d09f0
    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.
24d30bd0
 
923d09f0
    This function can be used from REQUEST_ROUTE.
 
    Example 1.5. dmq_handle_message usage
24d30bd0
 ...
923d09f0
         if(is_method("KDMQ"))
         {
                 dmq_handle_message();
         }
24d30bd0
 ...
 
5e37d0c9
 4.2.  dmq_send_message(peer, node, body, content_type)
923d09f0
 
5e37d0c9
    Sends a DMQ message directly from config file to a single node.
24d30bd0
 
923d09f0
    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.
9978906d
      * content_type - the MIME type of the message body.
24d30bd0
 
923d09f0
    This function can be used from any route.
24d30bd0
 
923d09f0
    Example 1.6. dmq_send_message usage
24d30bd0
 ...
9978906d
         dmq_send_message("peer_name", "sip:10.0.0.21:5060", "Message body...", "
 text/plain");
24d30bd0
 ...
 
5e37d0c9
 4.3.  dmq_bcast_message(peer, body, content_type)
 
    Broadcasts a DMQ message from config file to all active nodes (except
    self).
 
    Meaning of parameters:
      * peer - name of peer that should handle the message.
      * body - the message body.
      * content_type - the MIME type of the message body.
 
    This function can be used from any route.
 
    Example 1.7. dmq_bcast_message usage
 ...
         dmq_bcast_message("peer_name", "Message body...", "text/plain");
 ...
 
9556f8a3
 4.4.  dmq_t_replicate([skip_loop_test])
 
    Replicates the current SIP message to all active nodes (except self).
    Useful for replicating REGISTER, PUBLISH etc. in a clustered
    environment.
 
    Meaning of parameters:
      * skip_loop_test - by default, DMQ checks the source IP of the
        message prior to replication, to ensure it has not been sent by
        another DMQ node (to avoid infinite loops). If this optional
        parameter is set to "1", the loop test is not performed. This makes
        sense, from a performance perspective, if you have already
        performed the necessary checks in the config script (see
        dmq_is_from_node()).
 
    This function can be used from REQUEST_ROUTE only.
 
    Example 1.8. dmq_t_replicate usage
 ...
         dmq_t_replicate();
 ...
 
 4.5.  dmq_is_from_node()
 
    Checks whether the current message has been sent by another DMQ node in
    the cluster.
 
    This function can be used from REQUEST_ROUTE only.
 
    Example 1.9. dmq_is_from_node usage
 ...
         # Example REGISTER block
         if (dmq_is_from_node()) {
                 # Already authenticated, just save contact...
         } else {
                 # Authenticate, save contact etc.
                 # Assuming all successful...
                 dmq_t_replicate("1"); # Already checked source, don't perform lo
 op test again
         }
 ...
 
24d30bd0
 Chapter 2. Developer Guide
 
    Table of Contents
 
    1. dmq_load_api(dmq_api_t* api)
923d09f0
    2. register_dmq_peer(dmq_peer_t* peer)
    3. bcast_message(dmq_peer_t* peer, str* body, dmq_node_t* except,
9978906d
           dmq_resp_cback_t* resp_cback, int max_forwards, str*
           content_type)
923d09f0
 
    4. send_message(dmq_peer_t* peer, str* body, dmq_node_t* node,
9978906d
           dmq_resp_cback_t* resp_cback, int max_forwards, str*
           content_type)
24d30bd0
 
    The module provides the following functions that can be used in other
    Kamailio modules.
 
5e37d0c9
 1.  dmq_load_api(dmq_api_t* api)
24d30bd0
 
923d09f0
    This function binds the DMQ module and fills the structure with the
    exported functions below.
24d30bd0
 
    Example 2.1. dmq_api_t structure
 ...
 typedef struct dmq_api {
         register_dmq_peer_t register_dmq_peer;
         bcast_message_t bcast_message;
         send_message_t send_message;
 } dmq_api_t;
 ...
923d09f0
 
5e37d0c9
 2.  register_dmq_peer(dmq_peer_t* peer)
923d09f0
 
    Registers an entity as a DMQ peer which permits receiving/sending
    messages between nodes which support the same peer.
 
    Example 2.2. register_dmq_peer usage
 ...
         Example to follow.
 ...
 
5e37d0c9
 3.  bcast_message(dmq_peer_t* peer, str* body, dmq_node_t* except,
9978906d
 dmq_resp_cback_t* resp_cback, int max_forwards, str* content_type)
923d09f0
 
    Broadcast a DMQ message to all nodes in the DMQ bus excluding self,
    inactive nodes and "except" if specified.
 
    Example 2.3. bcast_message usage
 ...
         Example to follow.
 ...
 
5e37d0c9
 4.  send_message(dmq_peer_t* peer, str* body, dmq_node_t* node,
9978906d
 dmq_resp_cback_t* resp_cback, int max_forwards, str* content_type)
923d09f0
 
    Send a DMQ message to a single node.
 
    Example 2.4. send_message usage
 ...
         Example to follow.
 ...