889670d7baf21061a2aef34e1e9e624867f1d70a
[ric-plt/lib/rmr.git] / 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)