docs/rmr.7.rst

   1 .. This work is licensed under a Creative Commons Attribution 4.0 International License.
   2 .. SPDX-License-Identifier: CC-BY-4.0
   3 .. CAUTION: this document is generated from source in doc/src/rtd.
   4 .. To make changes edit the source and recompile the document.
   5 .. Do NOT make changes directly to .rst or .md files.
   6
   7 ============================================================================================
   8 Man Page: rmr
   9 ============================================================================================
  10
  11
  12
  13
  14 RMR LIBRARY
  15 ===========
  16
  17
  18
  19 NAME
  20 ----
  21
  22 RMR -- Ric Message Router Library
  23
  24
  25 DESCRIPTION
  26 -----------
  27
  28 RMR is a library which provides a user application with the
  29 ability to send and receive messages to/from other RMR based
  30 applications without having to understand the underlying
  31 messaging transport environment (e.g., SI95) and without
  32 needing to know which other endpoint applications are
  33 currently available and accepting messages. To do this, RMR
  34 depends on a routing table generated by an external source.
  35 This table is used to determine the destination endpoint of
  36 each message sent by mapping the message type T (supplied by
  37 the user application) to an endpoint entry. Once determined,
  38 the message is sent directly to the endpoint. The user
  39 application is unaware of which endpoint actually receives
  40 the message, and in some cases whether that message was sent
  41 to multiple applications.
  42
  43 RMR functions do provide for the ability to respond to the
  44 specific source instance of a message allowing for either a
  45 request response, or call response relationship when needed.
  46
  47
  48 The Route Table
  49 ---------------
  50
  51 The library must be given a route table which maps message
  52 types (integers) to endpoint groups such that each time a
  53 message of type T is sent, the message is delivered to one
  54 member of each group associated with T. For example, message
  55 type 2 might route to two different groups where group A has
  56 two members, worker1 and worker2, while group B has only one
  57 member, logger1.
  58
  59 The route table consists of a start record, one or more table
  60 entry records, and an end record. All table records contain
  61 fields separated with vertical bars (|), and allow for
  62 trailing comments with the standard shell comment symbol
  63 (hash, #) provided that the start of the comment is separated
  64 from the last token on the record by one or more spaces.
  65 Leading and trailing white space in each field is ignored.
  66 The route table supports two entry types: *rte* and *mse*.
  67
  68 A *rte* entry defines a message type, an optional sender
  69 application, and the endpoint(s) which accept the indicated
  70 message type. However, this format is deprecated and may be
  71 removed in a future version. An example record appears next.
  72
  73 ::
  74
  75       rte | 1 | app10:4560
  76
  77
  78 The second type of entry is *mse*. This entry defines a
  79 message type, an optional sender application, a subscription
  80 ID, and a collection of endpoints. An example record appears
  81 next.
  82
  83 ::
  84
  85       mse | 1000,forwarder:43086 | 10 | app2:43086
  86
  87
  88 It is the responsibility of the route table generator to know
  89 which endpoints belong to which groups, and which groups
  90 accept which message types. Once understood, the route table
  91 generator publishes a table that is ingested by RMR and used
  92 for mapping messages to end points.
  93
  94 The following is a simple route table which causes message
  95 types 0 through 9 to be routed to specific applications:
  96
  97 ::
  98
  99   newrt|start
 100      mse|0|-1| %meid
 101      mse|1|-1|app10:4560,app11:4560
 102      mse|2|-1|app12:4560
 103      mse|3|-1|app14:4560
 104      mse|4|-1|app18:4560
 105      mse|5|-1|app01:4560
 106      mse|6|-1|app02:4560
 107      mse|7|-1|app03:4560
 108      mse|8|-1|app04:4560
 109      mse|9|-1|app05:4560
 110   newrt|end
 111
 112
 113 The special endpoint "%meid" indicates that the message type
 114 (0 in this case) is to be routed to the endpoint which has
 115 been listed as the "owner" for the meid appearing in the
 116 message. MEID ownership is communicated to RMR using the same
 117 Route Table Manager interface and by supplying a "table" such
 118 as the one below:
 119
 120 ::
 121
 122   meid_map | start
 123      mme_ar | control1 | meid000 meid001 meid002 meid003 meid004 meid005
 124      mme_ar | control2 | meid100 meid101 meid102 meid103
 125   meid_map | end | 2
 126
 127
 128 This table indicates that the application (endpoint)
 129 *control1* "owns" 6 MEIDs and *control2* owns 4. When message
 130 type 0 is sent, the MEID in the message will be used to
 131 select the endpoint via this table.
 132
 133 The MEID table will update the existing owner relationships,
 134 and add new ones; it is necessary to send only the changes
 135 with the add/replace (mme_ar) entries in the table. When
 136 necessary, MEIDs can be deleted by adding an ``mme_del``
 137 record to the table. The following example illustrates how
 138 this might look:
 139
 140 ::
 141
 142   meid_map | start
 143      mme_ar | control1 | meid000 meid001 meid002 meid003 meid004 meid005
 144      mme_ar | control2 | meid100 meid101 meid102 meid103
 145      mme_del| meid200 meid401
 146   meid_map | end | 3
 147
 148
 149
 150 Route Table Syntax
 151 ------------------
 152
 153 The following illustrates the syntax for both types of route
 154 table entries.
 155
 156
 157 ::
 158
 159   newrt | start
 160   rte | <message-type>[,<sender-endpoint>] | <round-robin-grp>[;<round-robin-grp>]...
 161   mse | <message-type>[,<sender-endpoint>] | <sub-id> | <round-robin-grp>[;<round-robin-grp>]...
 162   newrt | end
 163
 164
 165 A round robin group is one or more endpoints from which one
 166 will be selected to receive the message. When multiple
 167 endpoints are given in a group, they must be separated with a
 168 comma. An endpoint is an IP address and port (e.g.
 169 192.158.4.30:8219), or DNS name and port, of the application
 170 that should receive the message type. If multiple round-robin
 171 groups are given, they must be separated by a semicolon.
 172
 173
 174 MEID Map Syntax
 175 ---------------
 176
 177 The MEID map is similar to the route table. Entries are used
 178 to add or replace the ownership of one or more MEIDs (mme_ar)
 179 or to delete one or more MEIDs (mme_del). The following is
 180 the syntax for the MEID map.
 181
 182
 183 ::
 184
 185   meid_map | start
 186   mme_ar | <owner-endpoint> | <meid> [<meid>...]
 187   mme_del | <meid> [<meid>...]
 188   meid_map | end | <count> | <md5sum>
 189
 190
 191 The <count> on the end record indicates the number of mme_ar
 192 and mme_del records which were sent; if the count does not
 193 match the whole map is refused and dropped. The
 194 <owner-endpoint> is the endpoint which should receive the
 195 message when a message is routed based on the MEID it
 196 contains. A MEID may be "owned" by only one endpoint, and if
 197 supplied multiple times, the last observed relationship is
 198 used. Each of the lists of MEIDs are blank separated.
 199
 200 The optional <md5sum> on the *end* record should be the
 201 computed MD5 hash for all records which appear between the
 202 start and and records. This allows for a tighter verification
 203 that all data was received exactly as the route manager
 204 transmitted them.
 205
 206
 207 Environment
 208 -----------
 209
 210 To enable configuration of the library behaviour outside of
 211 direct user application control, RMR supports a number of
 212 environment variables which provide information to the
 213 library. The following is a list of the various environment
 214 variables, what they control and the defaults which RMR uses
 215 if undefined.
 216
 217     .. list-table::
 218       :widths: auto
 219       :header-rows: 0
 220       :class: borderless
 221
 222       * - **RMR_ASYNC_CONN**
 223         -
 224           Allows the async connection mode to be turned off (by setting
 225           the value to 0). When set to 1, or missing from the
 226           environment, RMR will invoke the connection interface in the
 227           transport mechanism using the non-blocking (async) mode. This
 228           will likely result in many "soft failures" (retry) until the
 229           connection is established, but allows the application to
 230           continue unimpeded should the connection be slow to set up.
 231
 232       * - **RMR_BIND_IF**
 233         -
 234           This provides the interface that RMR will bind listen ports
 235           to, allowing for a single interface to be used rather than
 236           listening across all interfaces. This should be the IP
 237           address assigned to the interface that RMR should listen on,
 238           and if not defined RMR will listen on all interfaces.
 239
 240       * - **RMR_CTL_PORT**
 241         -
 242           This variable defines the port that RMR should open for
 243           communications with Route Manager, and other RMR control
 244           applications. If not defined, the port 4561 is assumed.
 245
 246           Previously, the ``RMR_RTG_SVC`` (route table generator
 247           service port) was used to define this port. However, a future
 248           version of Route Manager will require RMR to connect and
 249           request tables, thus that variable is now used to supply the
 250           Route Manager's well-known address and port.
 251
 252           To maintain backwards compatibility with the older Route
 253           Manager versions, the presence of this variable in the
 254           environment will shift RMR's behaviour with respect to the
 255           default value used when ``RMR_RTG_SVC`` is **not** defined.
 256
 257           When ``RMR_CTL_PORT`` is **defined:** RMR assumes that Route
 258           Manager requires RMR to connect and request table updates is
 259           made, and the default well-known address for Route manager is
 260           used (routemgr:4561).
 261
 262           When ``RMR_CTL_PORT`` is **undefined:** RMR assumes that
 263           Route Manager will connect and push table updates, thus the
 264           default listen port (4561) is used.
 265
 266           To avoid any possible misinterpretation and/or incorrect
 267           assumptions on the part of RMR, it is recommended that both
 268           the ``RMR_CTL_PORT`` and ``RMR_RTG_SVC`` be defined. In the
 269           case where both variables are defined, RMR will behave
 270           exactly as is communicated with the variable's values.
 271
 272       * - **RMR_RTREQ_FREQ**
 273         -
 274           When RMR needs a new route table it will send a request once
 275           every ``n`` seconds. The default value for ``n`` is 5, but
 276           can be changed if this variable is set prior to invoking the
 277           process. Accepted values are between 1 and 300 inclusive.
 278
 279       * - **RMR_RTG_SVC**
 280         -
 281           The value of this variable depends on the Route Manager in
 282           use.
 283
 284           When the Route Manager is expecting to connect to an xAPP and
 285           push route tables, this variable must indicate the
 286           ``port`` which RMR should use to listen for these
 287           connections.
 288
 289           When the Route Manager is expecting RMR to connect and
 290           request a table update during initialisation, the variable
 291           should be the ``host`` of the Route Manager process.
 292
 293           The ``RMR_CTL_PORT`` variable (added with the support of
 294           sending table update requests to Route manager), controls the
 295           behaviour if this variable is not set. See the description of
 296           that variable for details.
 297
 298       * - **RMR_HR_LOG**
 299         -
 300           By default RMR writes messages to standard error (incorrectly
 301           referred to as log messages) in human readable format. If
 302           this environment variable is set to 0, the format of standard
 303           error messages might be written in some format not easily
 304           read by humans. If missing, a value of 1 is assumed.
 305
 306       * - **RMR_LOG_VLEVEL**
 307         -
 308           This is a numeric value which corresponds to the verbosity
 309           level used to limit messages written to standard error. The
 310           lower the number the less chatty RMR functions are during
 311           execution. The following is the current relationship between
 312           the value set on this variable and the messages written:
 313
 314
 315               .. list-table::
 316                 :widths: auto
 317                 :header-rows: 0
 318                 :class: borderless
 319
 320                 * - **0**
 321                   -
 322                     Off; no messages of any sort are written.
 323
 324                 * - **1**
 325                   -
 326                     Only critical messages are written (default if this variable
 327                     does not exist)
 328
 329                 * - **2**
 330                   -
 331                     Errors and all messages written with a lower value.
 332
 333                 * - **3**
 334                   -
 335                     Warnings and all messages written with a lower value.
 336
 337                 * - **4**
 338                   -
 339                     Informational and all messages written with a lower value.
 340
 341                 * - **5**
 342                   -
 343                     Debugging mode -- all messages written, however this requires
 344                     RMR to have been compiled with debugging support enabled.
 345
 346
 347
 348       * - **RMR_RTG_ISRAW**
 349         -
 350           **Deprecated.** Should be set to 1 if the route table
 351           generator is sending "plain" messages (not using RMR to send
 352           messages), 0 if the RTG is using RMR to send. The default is
 353           1 as we don't expect the RTG to use RMR.
 354
 355           This variable is only recognised when using the NNG transport
 356           library as it is not possible to support NNG "raw"
 357           communications with other transport libraries. It is also
 358           necessary to match the value of this variable with the
 359           capabilities of the Route Manager; at some point in the
 360           future RMR will assume that all Route Manager messages will
 361           arrive via an RMR connection and will ignore this variable.
 362
 363       * - **RMR_SEED_RT**
 364         -
 365           This is used to supply a static route table which can be used
 366           for debugging, testing, or if no route table generator
 367           process is being used to supply the route table. If not
 368           defined, no static table is used and RMR will not report
 369           *ready* until a table is received. The static route table may
 370           contain both the route table (between newrt start and end
 371           records), and the MEID map (between meid_map start and end
 372           records).
 373
 374       * - **RMR_SRC_ID**
 375         -
 376           This is either the name or IP address which is placed into
 377           outbound messages as the message source. This will used when
 378           an RMR based application uses the rmr_rts_msg() function to
 379           return a response to the sender. If not supplied RMR will use
 380           the hostname which in some container environments might not
 381           be routable.
 382
 383           The value of this variable is also used for Route Manager
 384           messages which are sent via an RMR connection.
 385
 386       * - **RMR_VCTL_FILE**
 387         -
 388           This supplies the name of a verbosity control file. The core
 389           RMR functions do not produce messages unless there is a
 390           critical failure. However, the route table collection thread,
 391           not a part of the main message processing component, can
 392           write additional messages to standard error. If this variable
 393           is set, RMR will extract the verbosity level for these
 394           messages (0 is silent) from the first line of the file.
 395           Changes to the file are detected and thus the level can be
 396           changed dynamically, however RMR will only suss out this
 397           variable during initialisation, so it is impossible to enable
 398           verbosity after startup.
 399
 400       * - **RMR_WARNINGS**
 401         -
 402           If set to 1, RMR will write some warnings which are
 403           non-performance impacting. If the variable is not defined, or
 404           set to 0, RMR will not write these additional warnings.
 405
 406
 407
 408
 409 SEE ALSO
 410 --------
 411
 412 rmr_alloc_msg(3), rmr_tralloc_msg(3), rmr_call(3),
 413 rmr_free_msg(3), rmr_init(3), rmr_init_trace(3),
 414 rmr_get_meid(3), rmr_get_src(3), rmr_get_srcip(3),
 415 rmr_get_trace(3), rmr_get_trlen(3), rmr_get_xact(3),
 416 rmr_payload_size(3), rmr_rcv_msg(3), rmr_rcv_specific(3),
 417 rmr_rts_msg(3), rmr_ready(3), rmr_fib(3), rmr_has_str(3),
 418 rmr_tokenise(3), rmr_mk_ring(3), rmr_realloc_payload(3),
 419 rmr_ring_free(3), rmr_set_trace(3), rmr_torcv_msg(3),
 420 rmr_wh_open(3), rmr_wh_send_msg(3)