CI: Add silent cmake SonarCloud scan
[ric-plt/lib/rmr.git] / docs / rmr.7.rst
index e3df91c..91730c3 100644 (file)
@@ -1,14 +1,14 @@
-.. 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 
-============================================================================================ 
+.. 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
@@ -19,395 +19,413 @@ 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 
-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. 
+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
+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. 
+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. 
+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_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_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. 
-          
+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) 
+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)