X-Git-Url: https://gerrit.o-ran-sc.org/r/gitweb?a=blobdiff_plain;f=doc%2Fsrc%2Fman%2Frmr.7.xfm;h=ae4997700ee9352a182fde2371b5cdb2e570b36b;hb=0b79fc264eea2591ad6f645d0c90cc378ea5603b;hp=1d87f73f0b7f2769ac6f82e213042b72ea35125b;hpb=f23c7756b6c75f571e28346c6ee1466f108932c8;p=ric-plt%2Flib%2Frmr.git diff --git a/doc/src/man/rmr.7.xfm b/doc/src/man/rmr.7.xfm index 1d87f73..ae49977 100644 --- a/doc/src/man/rmr.7.xfm +++ b/doc/src/man/rmr.7.xfm @@ -49,11 +49,11 @@ applications. &space 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. +response relationship when needed. &h3(The Route Table) -The library is supplied with a route table which maps message numbers to +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 @@ -66,41 +66,109 @@ 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. +.sp +The following is a simple route table which causes message types 0 through 9 to +be routed to specific applications: + +&ex_start +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 +&ex_end +&space +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: + +&ex_start +meid_map | start + mme_ar | control1 | meid000 meid001 meid002 meid003 meid004 meid005 + mme_ar | control2 | meid100 meid101 meid102 meid103 +meid_map | end | 2 +&ex_end + +This table indicates that the application (endpoint) &ital(control1) "owns" 6 MEIDs +and &ital(control2) owns 4. +When message type 0 is sent, the MEID in the message will be used to select the +endpoint via this table. + +&space +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 &cw(mme_del) record to the table. +The following example illustrates how this might look: + +&ex_start +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 | 1 +&ex_end + +&h3(Route Table Syntax) +The following illustrates the syntax for both the route table. + +&space +&ex_start +newrt | start +mse | [,] | [;]... +newrt | end +&ex_end +&space +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 that should receive the message type. +If multiple round-robin groups are given, they must be separated by a semicolon, and + +&h3(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. + +&space +&ex_start +meid_map | start +mme_ar | | [...] +mme_del | [...] +meid_map | end | +&ex_end + +&space +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. + + &h3(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. +to the library. The following is a list of the various environment variables, what they control and the defaults which RMr uses if undefined. -&beg_dlist(.75i : ^&bold_font ) -&di(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) - mode. This will likely result in many "soft failures" (retry) until the connection - is established, but allows the application to continue unimpeeded should the - connection be slow to set up. - -&di(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. - -&di(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. - -&di(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. - -&di(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 &ital(ready) - until a table is received. -&end_dlist +&space +.** the list of environment vars supported +.im &{lib}/man/env_var_list.im &h2(SEE ALSO ) @@ -126,6 +194,7 @@ 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), @@ -134,4 +203,3 @@ rmr_wh_send_msg(3) .ju on -.qu