X-Git-Url: https://gerrit.o-ran-sc.org/r/gitweb?a=blobdiff_plain;ds=sidebyside;f=docs%2Foverview.rst;h=f4454be078d0138fb74277769104432c5838f7ed;hb=refs%2Ftags%2F4.0.5;hp=d382e69542a71cce994b40929faeeed33cb40973;hpb=0b79fc264eea2591ad6f645d0c90cc378ea5603b;p=ric-plt%2Flib%2Frmr.git diff --git a/docs/overview.rst b/docs/overview.rst index d382e69..f4454be 100644 --- a/docs/overview.rst +++ b/docs/overview.rst @@ -1,4 +1,5 @@ + .. 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. @@ -6,28 +7,29 @@ .. Do NOT make changes directly to .rst or .md files. + RMR Overview ============================================================================================ -RMr Library +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 +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. Nanomsg) and without +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 +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 @@ -37,24 +39,56 @@ 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 +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 -numbers 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 consists of -worker1 and worker2, while group B consists only of logger1. +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 +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 @@ -88,7 +122,7 @@ as the one below: meid_map | start mme_ar | control1 | meid000 meid001 meid002 meid003 meid004 meid005 - mme_ar | control2 | meid100 meid101 meid102 meid103 + mme_ar | control2 | meid100 meid101 meid102 meid103 meid_map | end | 2 @@ -108,23 +142,24 @@ might look: meid_map | start mme_ar | control1 | meid000 meid001 meid002 meid003 meid004 meid005 - mme_ar | control2 | meid100 meid101 meid102 meid103 + mme_ar | control2 | meid100 meid101 meid102 meid103 mme_del| meid200 meid401 - meid_map | end | 1 + meid_map | end | 3 Route Table Syntax -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -The following illustrates the syntax for both the route -table. +The following illustrates the syntax for both types of route +table entries. :: newrt | start - mse | [,] | [;]... + rte | [,] | [;]... + mse | [,] | | [;]... newrt | end @@ -132,13 +167,13 @@ table. 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 the IP address and port (e.g. -192.158.4.30:8219) or DNS name and port of the application +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, and +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) @@ -151,7 +186,7 @@ the syntax for the MEID map. meid_map | start mme_ar | | [...] mme_del | [...] - meid_map | end | + meid_map | end | [| @@ -164,62 +199,179 @@ 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 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 +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 +variables, what they control and the defaults which RMR uses if undefined. RMR_ASYNC_CONN - Allows the asynch 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 (asynch) + 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 unimpeeded should the + 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. + 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 - RMr opens a TCP listen socket using the port defined by - this environment variable and expects that the route table - generator process will connect to this port. If not - supplied the port 4561 is used. + 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: + + +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 - Is 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. + **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 + 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) + start and end records). RMR_SRC_ID @@ -229,6 +381,9 @@ RMR_SRC_ID 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