+
.. This work is licensed under a Creative Commons Attribution 4.0 International License.
.. SPDX-License-Identifier: CC-BY-4.0
.. CAUTION: this document is generated from source in doc/src/rtd.
.. Do NOT make changes directly to .rst or .md files.
+
RMR Overview
============================================================================================
-RMr Library
+RMR Library
============================================================================================
NAME
--------------------------------------------------------------------------------------------
-RMr -- Ric Message Router Library
+RMR -- Ric Message Router Library
DESCRIPTION
--------------------------------------------------------------------------------------------
-RMr is a library which provides a user application with the
-ability to send and receive messages to/from other RMr based
+RMR is a library which provides a user application with the
+ability to send and receive messages to/from other RMR based
applications without having to understand the underlying
-messaging transport environment (e.g. Nanomsg) and without
+messaging transport environment (e.g., SI95) and without
needing to know which other endpoint applications are
-currently available and accepting messages. To do this, RMr
+currently available and accepting messages. To do this, RMR
depends on a routing table generated by an external source.
This table is used to determine the destination endpoint of
each message sent by mapping the message type T (supplied by
the message, and in some cases whether that message was sent
to multiple applications.
-RMr functions do provide for the ability to respond to the
+RMR functions do provide for the ability to respond to the
specific source instance of a message allowing for either a
request response, or call response relationship when needed.
The Route Table
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-The library is supplied with a route table which maps message
+The library must be given a route table which maps message
numbers to endpoint groups such that each time a message of
type T is sent, the message is delivered to one member of
each group associated with T. For example, message type 2
It is the responsibility of the route table generator to know
which endpoints belong to which groups, and which groups
accept which message types. Once understood, the route table
-generator publishes a table that is ingested by RMr and used
+generator publishes a table that is ingested by RMR and used
for mapping messages to end points.
+The following is a simple route table which causes message
+types 0 through 9 to be routed to specific applications:
+
+::
+
+ newrt|start
+ mse|0|-1| %meid
+ mse|1|-1|app10:4560,app11:4560
+ mse|2|-1|app12:4560
+ mse|3|-1|app14:4560
+ mse|4|-1|app18:4560
+ mse|5|-1|app01:4560
+ mse|6|-1|app02:4560
+ mse|7|-1|app03:4560
+ mse|8|-1|app04:4560
+ mse|9|-1|app05:4560
+ newrt|end
+
+
+
+The special endpoint "%meid" indicates that the message type
+(0 in this case) is to be routed to the endpoint which has
+been listed as the "owner" for the meid appearing in the
+message. MEID ownership is communicated to RMR using the same
+Route Table Manager interface and by supplying a "table" such
+as the one below:
+
+::
+
+ meid_map | start
+ mme_ar | control1 | meid000 meid001 meid002 meid003 meid004 meid005
+ mme_ar | control2 | meid100 meid101 meid102 meid103
+ meid_map | end | 2
+
+
+This table indicates that the application (endpoint)
+*control1* "owns" 6 MEIDs and *control2* owns 4. When message
+type 0 is sent, the MEID in the message will be used to
+select the endpoint via this table.
+
+The MEID table will update the existing owner relationships,
+and add new ones; it is necessary to send only the changes
+with the add/replace (mme_ar) entries in the table. When
+necessary, MEIDs can be deleted by adding an mme_del record
+to the table. The following example illustrates how this
+might look:
+
+::
+
+ meid_map | start
+ mme_ar | control1 | meid000 meid001 meid002 meid003 meid004 meid005
+ mme_ar | control2 | meid100 meid101 meid102 meid103
+ mme_del| meid200 meid401
+ meid_map | end | 3
+
+
+
+Route Table Syntax
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The following illustrates the syntax for both the route
+table.
+
+
+::
+
+ newrt | start
+ mse | <message-type>[,<sender-endpoint>] | <sub-id> <roud-robin-grp>[;<round-robin-grp>]...
+ newrt | end
+
+
+
+A round robin group is one or more endpoints from which one
+will be selected to receive the message. When multiple
+endpoints are given in a group, they must be separated with a
+comma. An endpoint is the IP address and port (e.g.
+192.158.4.30:8219) or DNS name and port of the application
+that should receive the message type. If multiple round-robin
+groups are given, they must be separated by a semicolon, and
+
+MEID Map Syntax
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The MEID map is similar to the route table. Entries are used
+to add or replace the ownership of one or more MEIDs (mme_ar)
+or to delete one or more MEIDs (mme_del). The following is
+the syntax for the MEID map.
+
+
+::
+
+ meid_map | start
+ mme_ar | <owner-endpoint> | <meid> [<meid>...]
+ mme_del | <meid> [<meid>...]
+ meid_map | end | <count> [| <md5sum>
+
+
+
+The <count> on the end record indicates the number of mme_ar
+and mme_del records which were sent; if the count does not
+match the whole map is refused and dropped. The
+<owner-endpoint> is the endpoint which should receive the
+message when a message is routed based on the MEID it
+contains. A MEID may be "owned" by only one endpoint, and if
+supplied multiple times, the last observed relationship is
+used. Each of the lists of MEIDs are blank separated.
+
+The optional <md5sum> on the *end* record should be the
+computed MD5 hash for all records which appear between the
+start and and records. This allows for a tighter verification
+that all data was received exactly as the route manager
+transmitted them.
+
Environment
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
To enable configuration of the library behaviour outside of
-direct user application control, RMr supports a number of
+direct user application control, RMR supports a number of
environment variables which provide information to the
library. The following is a list of the various environment
-variables, what they control and the defaults which RMr uses
+variables, what they control and the defaults which RMR uses
if undefined.
+
RMR_ASYNC_CONN
- Allows the asynch connection mode to be turned off (by
- setting the value to 0. When set to 1, or missing from the
- environment, RMR will invoke the connection interface in
- the transport mechanism using the non-blocking (asynch)
+ Allows the async connection mode to be turned off (by
+ setting the value to 0). When set to 1, or missing from
+ the environment, RMR will invoke the connection interface
+ in the transport mechanism using the non-blocking (async)
mode. This will likely result in many "soft failures"
(retry) until the connection is established, but allows
- the application to continue unimpeeded should the
+ the application to continue unimpeded should the
connection be slow to set up.
+
RMR_BIND_IF
- This provides the interface that RMr will bind listen
- ports to allowing for a single interface to be used rather
- than listening across all interfaces. This should be the
- IP address assigned to the interface that RMr should
- listen on, and if not defined RMr will listen on all
- interfaces.
+ This provides the interface that RMR will bind listen
+ ports to, allowing for a single interface to be used
+ rather than listening across all interfaces. This should
+ be the IP address assigned to the interface that RMR
+ should listen on, and if not defined RMR will listen on
+ all interfaces.
+
+
+RMR_CTL_PORT
+
+ This variable defines the port that RMR should open for
+ communications with Route Manager, and other RMR control
+ applications. If not defined, the port 4561 is assumed.
+
+ Previously, the RMR_RTG_SVC (route table generator service
+ port) was used to define this port. However, a future
+ version of Route Manager will require RMR to connect and
+ request tables, thus that variable is now used to supply
+ the Route Manager's well-known address and port.
+
+ To maintain backwards compatibility with the older Route
+ Manager versions, the presence of this variable in the
+ environment will shift RMR's behaviour with respect to the
+ default value used when RMR_RTG_SVC is **not** defined.
+
+ When RMR_CTL_PORT is **defined:** RMR assumes that Route
+ Manager requires RMR to connect and request table updates
+ is made, and the default well-known address for Route
+ manager is used (routemgr:4561).
+
+ When RMR_CTL_PORT is **undefined:** RMR assumes that Route
+ Manager will connect and push table updates, thus the
+ default listen port (4561) is used.
+
+ To avoid any possible misinterpretation and/or incorrect
+ assumptions on the part of RMR, it is recommended that
+ both the RMR_CTL_PORT and RMR_RTG_SVC be defined. In the
+ case where both variables are defined, RMR will behave
+ exactly as is communicated with the variable's values.
+
RMR_RTG_SVC
- RMr opens a TCP listen socket using the port defined by
- this environment variable and expects that the route table
- generator process will connect to this port. If not
- supplied the port 4561 is used.
+ The value of this variable depends on the Route Manager in
+ use.
+
+ When the Route Manager is expecting to connect to an xAPP
+ and push route tables, this variable must indicate the
+ port which RMR should use to listen for these connections.
+
+ When the Route Manager is expecting RMR to connect and
+ request a table update during initialisation, the variable
+ should be the host of the Route Manager process.
+
+ The RMR_CTL_PORT variable (added with the support of
+ sending table update requests to Route manager), controls
+ the behaviour if this variable is not set. See the
+ description of that variable for details.
+
+
+RMR_HR_LOG
+
+ By default RMR writes messages to standard error
+ (incorrectly referred to as log messages) in human
+ readable format. If this environment variable is set to 0,
+ the format of standard error messages might be written in
+ some format not easily read by humans. If missing, a value
+ of 1 is assumed.
+
+
+RMR_LOG_VLEVEL
+
+ This is a numeric value which corresponds to the verbosity
+ level used to limit messages written to standard error.
+ The lower the number the less chatty RMR functions are
+ during execution. The following is the current
+ relationship between the value set on this variable and
+ the messages written:
+
+
+0
+
+ Off; no messages of any sort are written.
+
+
+1
+
+ Only critical messages are written (default if this
+ variable does not exist)
+
+
+2
+
+ Errors and all messages written with a lower value.
+
+
+3
+
+ Warnings and all messages written with a lower value.
+
+
+4
+
+ Informational and all messages written with a lower
+ value.
+
+
+5
+
+ Debugging mode -- all messages written, however this
+ requires RMR to have been compiled with debugging
+ support enabled.
+
+
RMR_RTG_ISRAW
- Is set to 1 if the route table generator is sending
- "plain" messages (not using RMr to send messages, 0 if the
- rtg is using RMr to send. The default is 1 as we don't
- expect the rtg to use RMr.
+ **Deprecated.** Should be set to 1 if the route table
+ generator is sending "plain" messages (not using RMR to
+ send messages), 0 if the RTG is using RMR to send. The
+ default is 1 as we don't expect the RTG to use RMR.
+
+ This variable is only recognised when using the NNG
+ transport library as it is not possible to support NNG
+ "raw" communications with other transport libraries. It is
+ also necessary to match the value of this variable with
+ the capabilities of the Route Manager; at some point in
+ the future RMR will assume that all Route Manager messages
+ will arrive via an RMR connection and will ignore this
+ variable.
RMR_SEED_RT
This is used to supply a static route table which can be
used for debugging, testing, or if no route table
generator process is being used to supply the route table.
- If not defined, no static table is used and RMr will not
- report *ready* until a table is received.
+ If not defined, no static table is used and RMR will not
+ report *ready* until a table is received. The static route
+ table may contain both the route table (between newrt
+ start and end records), and the MEID map (between meid_map
+ start and end records).
RMR_SRC_ID
function to return a response to the sender. If not
supplied RMR will use the hostname which in some container
environments might not be routable.
+
+ The value of this variable is also used for Route Manager
+ messages which are sent via an RMR connection.
RMR_VCTL_FILE
Code Review / ric-plt / lib / rmr.git / blobdiff