diff --git a/src/modules/dmq/doc/dmq_admin.xml b/src/modules/dmq/doc/dmq_admin.xml
index 26555e24a36..3b4121fdb3b 100644
--- a/src/modules/dmq/doc/dmq_admin.xml
+++ b/src/modules/dmq/doc/dmq_admin.xml
@@ -15,29 +15,48 @@
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.
+ The DMQ module implements a distributed message queue on top of Kamailio
+ in order to facilitate data propagation and replication between multiple
+ instances, referred as "nodes" (or "peers").
- Other entities ("peers") are then able to utilize 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.
+ The DMQ data flow between nodes is grouped in a logical entity referred as
+ "channel" (or "bus"), many flows (channels) can be active at the same time.
- DMQ sends SIP requests using the KDMQ request method, that is private
- to Kamailio.
+ The communication between the nodes is done using SIP messages, after all
+ Kamailio's best ability is routing SIP traffic, therefore reusing the same
+ protocol empowers DMQ cluster with flexible routing policies, advanced
+ authorization and security policies, a.s.o. DMQ sends SIP requests using the
+ KDMQ request method (a custom method type specific to
+ Kamailio, compliant with SIP specifications RFC3261). Data can be sent to
+ all the other active nodes (aka "broadcast") or to a specific single node
+ (aka "unicast").
-
- Example of a KDMQ message
+
+ The nodes can utilize the DMQ channels to pass messages between them to
+ distribute data for various services (e.g., cached items, location records,
+ active calls, ...). This grouping of messages on channels (per service)
+ is similar to the topic concept in a typical pub/sub system. The channel name
+ appears in the R-URI username part of KDMQ requests.
+
+
+ The DMQ cluster transparently deals with node discovery, availability,
+ consistency, retransmissions, etc. A new node can join the DMQ cluster by
+ sending an availability notification to an existing node in the clusters.
+ Nodes that are not responding to KDMQ reguests are removed the from local
+ list of active nodes, no longer being considered to be part of the KDMQ cluster.
+
+
+ KDMQ Request Example
- This message is for basic DMQ bus handling. Other messages are produced
- by other modules, like the htable module.
+ This request is generated for DMQ peers availability notifications.
+ Other messages can be produced by various modules, with different R-URI
+ username and body content, such as htable,
+ dialog or usrloc modules.
-
+...
KDMQ sip:notification_peer@192.168.40.15:5090 SIP/2.0
Via: SIP/2.0/UDP 192.168.40.15;branch=z9hG4bK55e5.423d95110000
@@ -54,9 +73,9 @@ sip:192.168.40.16:5060;status=active
sip:192.168.40.15:5060;status=disabled
sip:192.168.40.17:5060;status=active
+...
-
-
+
@@ -86,8 +105,10 @@ sip:192.168.40.17:5060;status=active
- 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.
+ The DMQ module itself has no external dependencies. However,
+ each peer may need to use its own (de)serialization mechanism,
+ like JSON (via jannson module), XML (via xmlops) or string
+ operations with transformations.
.
@@ -128,6 +149,23 @@ modparam("dmq", "server_address", "sip:10.0.0.20:5060")
...
modparam("dmq", "notification_address", "sip:10.0.0.21:5060")
...
+
+
+
+
+ <varname>notification_channel</varname>(str)
+
+ The name of the channel for notifications about peers availability.
+
+
+ Default value is notification_peer
.
+
+
+ Set <varname>notification_channel</varname> parameter
+
+...
+modparam("dmq", "notification_channel", "peers")
+...
@@ -243,17 +281,16 @@ modparam("dmq", "ping_interval", 90)
<function>dmq_handle_message</function> usage
...
- if(is_method("KDMQ"))
- {
- dmq_handle_message();
- }
+ if(is_method("KDMQ")) {
+ dmq_handle_message();
+ }
...
- <function moreinfo="none">dmq_send_message(peer, node, body, content_type)</function>
+ <function moreinfo="none">dmq_send_message(channel, node, body, content_type)</function>
Sends a DMQ message directly from config file to a single node.
@@ -262,12 +299,12 @@ modparam("dmq", "ping_interval", 90)
- peer - name of peer that should handle the message.
+ channel - name of the channel that should handle the message.
- node - the node to which the message should be sent.
+ node - the SIP address of the node to which the message should be sent.
@@ -289,23 +326,24 @@ modparam("dmq", "ping_interval", 90)
<function>dmq_send_message</function> usage
...
- dmq_send_message("peer_name", "sip:10.0.0.21:5060", "Message body...", "text/plain");
+ dmq_send_message("channel1", "sip:10.0.0.21:5060", "Message body...", "text/plain");
...
- <function moreinfo="none">dmq_bcast_message(peer, body, content_type)</function>
+ <function moreinfo="none">dmq_bcast_message(channel, body, content_type)</function>
- Broadcasts a DMQ message from config file to all active nodes (except self).
+ Broadcasts a DMQ message from config file to all active nodes (except self) on the
+ specific channel.
Meaning of parameters:
- peer - name of peer that should handle the message.
+ channel - name of the channel that should handle the message.
@@ -327,7 +365,7 @@ modparam("dmq", "ping_interval", 90)
<function>dmq_bcast_message</function> usage
...
- dmq_bcast_message("peer_name", "Message body...", "text/plain");
+ dmq_bcast_message("channel1", "Message body...", "text/plain");
...
@@ -337,19 +375,19 @@ modparam("dmq", "ping_interval", 90)
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.
+ 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()).
-
+
@@ -360,7 +398,7 @@ modparam("dmq", "ping_interval", 90)
<function>dmq_t_replicate</function> usage
...
- dmq_t_replicate();
+ dmq_t_replicate();
...
@@ -370,7 +408,8 @@ modparam("dmq", "ping_interval", 90)
dmq_is_from_node()
- Checks whether the current message has been sent by another DMQ node in the cluster.
+ Checks whether the current message has been sent by another active
+ DMQ node in the cluster.
This function can be used from REQUEST_ROUTE only.
@@ -380,14 +419,16 @@ modparam("dmq", "ping_interval", 90)
<function>dmq_is_from_node</function> usage
...
- # Example REGISTER block
+ # basic example for REGISTER replication
+ if(is_method("REGISTER")) {
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 loop test again
- }
+ # coming from a DMQ node - already authenticated there
+ # now just save contact, etc...
+ } else {
+ # coming from end point - authenticate, save contact, etc...
+ dmq_t_replicate("1"); # source address checked, skip the loop test
+ }
+ }
...