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_RTG_SVC**
 273        -
 274          The value of this variable depends on the Route Manager in
 275          use.
 276
 277          When the Route Manager is expecting to connect to an xAPP and
 278          push route tables, this variable must indicate the
 279          ``port`` which RMR should use to listen for these
 280          connections.
 281
 282          When the Route Manager is expecting RMR to connect and
 283          request a table update during initialisation, the variable
 284          should be the ``host`` of the Route Manager process.
 285
 286          The ``RMR_CTL_PORT`` variable (added with the support of
 287          sending table update requests to Route manager), controls the
 288          behaviour if this variable is not set. See the description of
 289          that variable for details.
 290
 291      * - **RMR_HR_LOG**
 292        -
 293          By default RMR writes messages to standard error (incorrectly
 294          referred to as log messages) in human readable format. If
 295          this environment variable is set to 0, the format of standard
 296          error messages might be written in some format not easily
 297          read by humans. If missing, a value of 1 is assumed.
 298
 299      * - **RMR_LOG_VLEVEL**
 300        -
 301          This is a numeric value which corresponds to the verbosity
 302          level used to limit messages written to standard error. The
 303          lower the number the less chatty RMR functions are during
 304          execution. The following is the current relationship between
 305          the value set on this variable and the messages written:
 306
 307
 308              .. list-table::
 309                :widths: auto
 310                :header-rows: 0
 311                :class: borderless
 312
 313                * - **0**
 314                  -
 315                    Off; no messages of any sort are written.
 316
 317                * - **1**
 318                  -
 319                    Only critical messages are written (default if this variable
 320                    does not exist)
 321
 322                * - **2**
 323                  -
 324                    Errors and all messages written with a lower value.
 325
 326                * - **3**
 327                  -
 328                    Warnings and all messages written with a lower value.
 329
 330                * - **4**
 331                  -
 332                    Informational and all messages written with a lower value.
 333
 334                * - **5**
 335                  -
 336                    Debugging mode -- all messages written, however this requires
 337                    RMR to have been compiled with debugging support enabled.
 338
 339
 340
 341      * - **RMR_RTG_ISRAW**
 342        -
 343          **Deprecated.** Should be set to 1 if the route table
 344          generator is sending "plain" messages (not using RMR to send
 345          messages), 0 if the RTG is using RMR to send. The default is
 346          1 as we don't expect the RTG to use RMR.
 347
 348          This variable is only recognised when using the NNG transport
 349          library as it is not possible to support NNG "raw"
 350          communications with other transport libraries. It is also
 351          necessary to match the value of this variable with the
 352          capabilities of the Route Manager; at some point in the
 353          future RMR will assume that all Route Manager messages will
 354          arrive via an RMR connection and will ignore this variable.
 355
 356      * - **RMR_SEED_RT**
 357        -
 358          This is used to supply a static route table which can be used
 359          for debugging, testing, or if no route table generator
 360          process is being used to supply the route table. If not
 361          defined, no static table is used and RMR will not report
 362          *ready* until a table is received. The static route table may
 363          contain both the route table (between newrt start and end
 364          records), and the MEID map (between meid_map start and end
 365          records).
 366
 367      * - **RMR_SRC_ID**
 368        -
 369          This is either the name or IP address which is placed into
 370          outbound messages as the message source. This will used when
 371          an RMR based application uses the rmr_rts_msg() function to
 372          return a response to the sender. If not supplied RMR will use
 373          the hostname which in some container environments might not
 374          be routable.
 375
 376          The value of this variable is also used for Route Manager
 377          messages which are sent via an RMR connection.
 378
 379      * - **RMR_VCTL_FILE**
 380        -
 381          This supplies the name of a verbosity control file. The core
 382          RMR functions do not produce messages unless there is a
 383          critical failure. However, the route table collection thread,
 384          not a part of the main message processing component, can
 385          write additional messages to standard error. If this variable
 386          is set, RMR will extract the verbosity level for these
 387          messages (0 is silent) from the first line of the file.
 388          Changes to the file are detected and thus the level can be
 389          changed dynamically, however RMR will only suss out this
 390          variable during initialisation, so it is impossible to enable
 391          verbosity after startup.
 392
 393      * - **RMR_WARNINGS**
 394        -
 395          If set to 1, RMR will write some warnings which are
 396          non-performance impacting. If the variable is not defined, or
 397          set to 0, RMR will not write these additional warnings.
 398
 399
 400
 401
 402 SEE ALSO
 403 --------
 404
 405 rmr_alloc_msg(3), rmr_tralloc_msg(3), rmr_call(3),
 406 rmr_free_msg(3), rmr_init(3), rmr_init_trace(3),
 407 rmr_get_meid(3), rmr_get_src(3), rmr_get_srcip(3),
 408 rmr_get_trace(3), rmr_get_trlen(3), rmr_get_xact(3),
 409 rmr_payload_size(3), rmr_rcv_msg(3), rmr_rcv_specific(3),
 410 rmr_rts_msg(3), rmr_ready(3), rmr_fib(3), rmr_has_str(3),
 411 rmr_tokenise(3), rmr_mk_ring(3), rmr_realloc_payload(3),
 412 rmr_ring_free(3), rmr_set_trace(3), rmr_torcv_msg(3),
 413 rmr_wh_open(3), rmr_wh_send_msg(3)