X-Git-Url: https://gerrit.o-ran-sc.org/r/gitweb?a=blobdiff_plain;f=docs%2Frmr.7.rst;h=91730c3c2db65be3100d6a7bc266c4c689e90c24;hb=c8c5946b142c5cc04449edc49a599f282c6573e4;hp=e3df91c4643282f52510f3def6c5ed5408f01f8d;hpb=a3a121ca4a0426ec964fa684fb27c397f2ee9e24;p=ric-plt%2Flib%2Frmr.git diff --git a/docs/rmr.7.rst b/docs/rmr.7.rst index e3df91c..91730c3 100644 --- a/docs/rmr.7.rst +++ b/docs/rmr.7.rst @@ -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 | [,] | [;]... - mse | [,] | | [;]... - 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 | [,] | [;]... + mse | [,] | | [;]... + 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 | | [...] - mme_del | [...] - meid_map | end | | - - -The 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 - 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 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 | | [...] + mme_del | [...] + meid_map | end | | + + +The 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 + 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 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)