| .. 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. |
| .. To make changes edit the source and recompile the document. |
| .. Do NOT make changes directly to .rst or .md files. |
| |
| ============================================================================================ |
| Man Page: rmr |
| ============================================================================================ |
| |
| |
| |
| |
| RMR LIBRARY |
| =========== |
| |
| |
| |
| NAME |
| ---- |
| |
| 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 |
| applications without having to understand the underlying |
| 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 |
| 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 user application) to an endpoint entry. Once determined, |
| the message is sent directly to the endpoint. The user |
| application is unaware of which endpoint actually receives |
| 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 |
| specific source instance of a message allowing for either a |
| request response, or call response relationship when needed. |
| |
| |
| The Route Table |
| --------------- |
| |
| The library must be given a route table which maps message |
| types (integers) 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 might route to two different groups where group A has |
| two members, worker1 and worker2, while group B has only one |
| member, logger1. |
| |
| The route table consists of a start record, one or more table |
| entry records, and an end record. All table records contain |
| fields separated with vertical bars (|), and allow for |
| trailing comments with the standard shell comment symbol |
| (hash, #) provided that the start of the comment is separated |
| from the last token on the record by one or more spaces. |
| Leading and trailing white space in each field is ignored. |
| The route table supports two entry types: *rte* and *mse*. |
| |
| A *rte* entry defines a message type, an optional sender |
| application, and the endpoint(s) which accept the indicated |
| message type. However, this format is deprecated and may be |
| removed in a future version. An example record appears next. |
| |
| :: |
| |
| rte | 1 | app10:4560 |
| |
| |
| The second type of entry is *mse*. This entry defines a |
| message type, an optional sender application, a subscription |
| ID, and a collection of endpoints. An example record appears |
| next. |
| |
| :: |
| |
| mse | 1000,forwarder:43086 | 10 | app2:43086 |
| |
| |
| 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 |
| 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 types of route |
| table entries. |
| |
| |
| :: |
| |
| newrt | start |
| rte | <message-type>[,<sender-endpoint>] | <round-robin-grp>[;<round-robin-grp>]... |
| mse | <message-type>[,<sender-endpoint>] | <sub-id> | <round-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 an 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. |
| |
| |
| 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 |
| 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 |
| if undefined. |
| |
| .. list-table:: |
| :widths: auto |
| :header-rows: 0 |
| :class: borderless |
| |
| * - **RMR_ASYNC_CONN** |
| - |
| 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 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. |
| |
| * - **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_RTREQ_FREQ** |
| - |
| When RMR needs a new route table it will send a request once |
| every ``n`` seconds. The default value for ``n`` is 5, but |
| can be changed if this variable is set prior to invoking the |
| process. Accepted values are between 1 and 300 inclusive. |
| |
| * - **RMR_RTG_SVC** |
| - |
| 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: |
| |
| |
| .. list-table:: |
| :widths: auto |
| :header-rows: 0 |
| :class: borderless |
| |
| * - **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** |
| - |
| **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. 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** |
| - |
| This is either the name or IP address which is placed into |
| outbound messages as the message source. This will used when |
| an RMR based application uses the rmr_rts_msg() 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_STASH_RT** |
| - |
| Names the file where RMR should write the latest update it |
| receives from the source of route tables (generally Route |
| Manager). This is meant to assist with debugging and/or |
| troubleshooting when it is suspected that route information |
| isn't being sent and/or received correctly. If this variable |
| is not given, RMR will save the last update using the |
| ``RMR_SEED_RT`` variable value and adding a ``.stash`` suffix |
| to the filename so as not to overwrite the static table. |
| |
| * - **RMR_VCTL_FILE** |
| - |
| This supplies the name of a verbosity control file. The core |
| RMR functions do not produce messages unless there is a |
| critical failure. However, the route table collection thread, |
| not a part of the main message processing component, can |
| write additional messages to standard error. If this variable |
| is set, RMR will extract the verbosity level for these |
| messages (0 is silent) from the first line of the file. |
| Changes to the file are detected and thus the level can be |
| changed dynamically, however RMR will only suss out this |
| variable during initialisation, so it is impossible to enable |
| verbosity after startup. |
| |
| * - **RMR_WARNINGS** |
| - |
| If set to 1, RMR will write some warnings which are |
| non-performance impacting. If the variable is not defined, or |
| set to 0, RMR will not write these additional warnings. |
| |
| |
| |
| |
| SEE ALSO |
| -------- |
| |
| rmr_alloc_msg(3), rmr_tralloc_msg(3), rmr_call(3), |
| rmr_free_msg(3), rmr_init(3), rmr_init_trace(3), |
| rmr_get_meid(3), rmr_get_src(3), rmr_get_srcip(3), |
| rmr_get_trace(3), rmr_get_trlen(3), rmr_get_xact(3), |
| rmr_payload_size(3), rmr_rcv_msg(3), rmr_rcv_specific(3), |
| rmr_rts_msg(3), rmr_ready(3), rmr_fib(3), rmr_has_str(3), |
| rmr_tokenise(3), rmr_mk_ring(3), rmr_realloc_payload(3), |
| rmr_ring_free(3), rmr_set_trace(3), rmr_torcv_msg(3), |
| rmr_wh_open(3), rmr_wh_send_msg(3) |