From d0cb5a6ecf6cb3962e45f28926f4361a64ca613a Mon Sep 17 00:00:00 2001 From: Kamailio Dev Date: Wed, 4 Nov 2020 13:01:16 +0100 Subject: [PATCH] modules: readme files regenerated - dmq ... [skip ci] --- src/modules/dmq/README | 209 ++++++++++++++++++++++++----------------- 1 file changed, 122 insertions(+), 87 deletions(-) diff --git a/src/modules/dmq/README b/src/modules/dmq/README index c4c0dab8a00..2ea40a26423 100644 --- a/src/modules/dmq/README +++ b/src/modules/dmq/README @@ -37,16 +37,17 @@ Charles Chance 3.1. server_address(str) 3.2. notification_address(str) - 3.3. multi_notify(int) - 3.4. num_workers(int) - 3.5. worker_usleep(int) - 3.6. ping_interval(int) + 3.3. notification_channel(str) + 3.4. multi_notify(int) + 3.5. num_workers(int) + 3.6. worker_usleep(int) + 3.7. ping_interval(int) 4. Functions 4.1. dmq_handle_message([continue]) - 4.2. dmq_send_message(peer, node, body, content_type) - 4.3. dmq_bcast_message(peer, body, content_type) + 4.2. dmq_send_message(channel, node, body, content_type) + 4.3. dmq_bcast_message(channel, body, content_type) 4.4. dmq_t_replicate([skip_loop_test]) 4.5. dmq_is_from_node() @@ -68,19 +69,20 @@ Charles Chance List of Examples - 1.1. Example of a KDMQ message + 1.1. KDMQ Request Example 1.2. Set server_address parameter 1.3. Set notification_address parameter - 1.4. Set multi_notify parameter - 1.5. Set num_workers parameter - 1.6. Set worker_usleep parameter - 1.7. Set ping_interval parameter - 1.8. dmq_handle_message usage - 1.9. dmq_send_message usage - 1.10. dmq_bcast_message usage - 1.11. dmq_t_replicate usage - 1.12. dmq_is_from_node usage - 1.13. dmq.list_nodes usage + 1.4. Set notification_channel parameter + 1.5. Set multi_notify parameter + 1.6. Set num_workers parameter + 1.7. Set worker_usleep parameter + 1.8. Set ping_interval parameter + 1.9. dmq_handle_message usage + 1.10. dmq_send_message usage + 1.11. dmq_bcast_message usage + 1.12. dmq_t_replicate usage + 1.13. dmq_is_from_node usage + 1.14. dmq.list_nodes usage 2.1. dmq_api_t structure 2.2. register_dmq_peer usage 2.3. bcast_message usage @@ -100,16 +102,17 @@ Chapter 1. Admin Guide 3.1. server_address(str) 3.2. notification_address(str) - 3.3. multi_notify(int) - 3.4. num_workers(int) - 3.5. worker_usleep(int) - 3.6. ping_interval(int) + 3.3. notification_channel(str) + 3.4. multi_notify(int) + 3.5. num_workers(int) + 3.6. worker_usleep(int) + 3.7. ping_interval(int) 4. Functions 4.1. dmq_handle_message([continue]) - 4.2. dmq_send_message(peer, node, body, content_type) - 4.3. dmq_bcast_message(peer, body, content_type) + 4.2. dmq_send_message(channel, node, body, content_type) + 4.3. dmq_bcast_message(channel, body, content_type) 4.4. dmq_t_replicate([skip_loop_test]) 4.5. dmq_is_from_node() @@ -120,26 +123,42 @@ Chapter 1. Admin Guide 1. 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 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. - - DMQ sends SIP requests using the KDMQ request method, that is private - to Kamailio. - - Example 1.1. Example of a KDMQ message - - This message is for basic DMQ bus handling. Other messages are produced - by other modules, like the htable module. + Kamailio in order to facilitate data propagation and replication + between multiple instances, referred as "nodes" (or "peers"). + + 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. + + 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"). + + 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. + + Example 1.1. KDMQ Request Example + + 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 To: @@ -156,6 +175,8 @@ sip:192.168.40.16:5060;status=active sip:192.168.40.15:5060;status=disabled sip:192.168.40.17:5060;status=active +... + 2. Dependencies 2.1. Kamailio Modules @@ -170,17 +191,19 @@ sip:192.168.40.17:5060;status=active 2.2. 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. . + peer may need to use its own (de)serialization mechanism, like JSON + (via jannson module), XML (via xmlops) or string operations with + transformations. . 3. Parameters 3.1. server_address(str) 3.2. notification_address(str) - 3.3. multi_notify(int) - 3.4. num_workers(int) - 3.5. worker_usleep(int) - 3.6. ping_interval(int) + 3.3. notification_channel(str) + 3.4. multi_notify(int) + 3.5. num_workers(int) + 3.6. worker_usleep(int) + 3.7. ping_interval(int) 3.1. server_address(str) @@ -206,7 +229,18 @@ modparam("dmq", "server_address", "sip:10.0.0.20:5060") modparam("dmq", "notification_address", "sip:10.0.0.21:5060") ... -3.3. multi_notify(int) +3.3. notification_channel(str) + + The name of the channel for notifications about peers availability. + + Default value is “notification_peer”. + + Example 1.4. Set notification_channel parameter +... +modparam("dmq", "notification_channel", "peers") +... + +3.4. multi_notify(int) Enables the ability to resolve multiple IPv4/IPv6 addresses for a single notification address. @@ -217,23 +251,23 @@ modparam("dmq", "notification_address", "sip:10.0.0.21:5060") Default value is “0”. - Example 1.4. Set multi_notify parameter + Example 1.5. Set multi_notify parameter ... modparam("dmq", "multi_notify", 1) ... -3.4. num_workers(int) +3.5. num_workers(int) The number of worker threads for sending/receiving messages. Default value is “2”. - Example 1.5. Set num_workers parameter + Example 1.6. Set num_workers parameter ... modparam("dmq", "num_workers", 4) ... -3.5. worker_usleep(int) +3.6. worker_usleep(int) The default locking/synchronisation mechanism between producer/consumer threads is the optimum for most environments. On some systems (e.g. @@ -248,19 +282,19 @@ modparam("dmq", "num_workers", 4) Default value is 0 (recommended for most systems). - Example 1.6. Set worker_usleep parameter + Example 1.7. Set worker_usleep parameter ... modparam("dmq", "worker_usleep", 1000) ... -3.6. ping_interval(int) +3.7. ping_interval(int) The number of seconds between node pings (for checking status of other nodes). Minimum value is “60” (default). - Example 1.7. Set ping_interval parameter + Example 1.8. Set ping_interval parameter ... modparam("dmq", "ping_interval", 90) ... @@ -268,8 +302,8 @@ modparam("dmq", "ping_interval", 90) 4. Functions 4.1. dmq_handle_message([continue]) - 4.2. dmq_send_message(peer, node, body, content_type) - 4.3. dmq_bcast_message(peer, body, content_type) + 4.2. dmq_send_message(channel, node, body, content_type) + 4.3. dmq_bcast_message(channel, body, content_type) 4.4. dmq_t_replicate([skip_loop_test]) 4.5. dmq_is_from_node() @@ -286,47 +320,47 @@ modparam("dmq", "ping_interval", 90) This function can be used from REQUEST_ROUTE. - Example 1.8. dmq_handle_message usage + Example 1.9. dmq_handle_message usage ... - if(is_method("KDMQ")) - { - dmq_handle_message(); - } + if(is_method("KDMQ")) { + dmq_handle_message(); + } ... -4.2. dmq_send_message(peer, node, body, content_type) +4.2. dmq_send_message(channel, node, body, content_type) Sends a DMQ message directly from config file to a single node. Meaning of parameters: - * peer - name of peer that should handle the message. - * node - the node to which the message should be sent. + * channel - name of the channel that should handle the message. + * node - the SIP address of 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. - Example 1.9. dmq_send_message usage + Example 1.10. dmq_send_message 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...", "t +ext/plain"); ... -4.3. dmq_bcast_message(peer, body, content_type) +4.3. dmq_bcast_message(channel, body, content_type) Broadcasts a DMQ message from config file to all active nodes (except - self). + 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. * body - the message body. * content_type - the MIME type of the message body. This function can be used from any route. - Example 1.10. dmq_bcast_message usage + Example 1.11. dmq_bcast_message usage ... - dmq_bcast_message("peer_name", "Message body...", "text/plain"); + dmq_bcast_message("channel1", "Message body...", "text/plain"); ... 4.4. dmq_t_replicate([skip_loop_test]) @@ -346,29 +380,30 @@ text/plain"); This function can be used from REQUEST_ROUTE only. - Example 1.11. dmq_t_replicate usage + Example 1.12. dmq_t_replicate usage ... - dmq_t_replicate(); + dmq_t_replicate(); ... 4.5. 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. - Example 1.12. dmq_is_from_node usage + Example 1.13. dmq_is_from_node usage ... - # Example REGISTER block + # basic example for REGISTER replication + if(is_method("REGISTER")) { if (dmq_is_from_node()) { - # Already authenticated, just save contact... + # coming from a DMQ node - already authenticated there + # now just save contact, etc... } else { - # Authenticate, save contact etc. - # Assuming all successful... - dmq_t_replicate("1"); # Already checked source, don't perform lo -op test again + # coming from end point - authenticate, save contact, etc... + dmq_t_replicate("1"); # source address checked, skip the loop test } + } ... 5. RPC Commands @@ -379,7 +414,7 @@ op test again List the DMQ nodes. It has no parameters. - Example 1.13. dmq.list_nodes usage + Example 1.14. dmq.list_nodes usage ... kamcmd dmq.list_nodes ...