X-Git-Url: https://gerrit.o-ran-sc.org/r/gitweb?a=blobdiff_plain;f=doc%2Fsrc%2Fman%2Fenv_var_list.im;h=a19cb227956700ef6c88a5dc6bef9a08ae1c7c1c;hb=d07cc97b4b5493a5fc67231ee09d1c931c993161;hp=a9d42978c7937c806186849a1c04faa4b6c805e1;hpb=0d4def6c7b673f3be486338ced65ccdd25a859ed;p=ric-plt%2Flib%2Frmr.git diff --git a/doc/src/man/env_var_list.im b/doc/src/man/env_var_list.im index a9d4297..a19cb22 100644 --- a/doc/src/man/env_var_list.im +++ b/doc/src/man/env_var_list.im @@ -1,8 +1,8 @@ -.** vim: ts=4 noet sw=4: +.** vim: ts=4 noet sw=42 .if false ================================================================================== - Copyright (c) 2019 Nokia - Copyright (c) 2018-2019 AT&T Intellectual Property. + Copyright (c) 2019-2020 Nokia + Copyright (c) 2018-2020 AT&T Intellectual Property. Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. @@ -19,97 +19,171 @@ .fi .if false - Mnemonic: env_list_vars.im - Abstract: This is a list of environment variables which are recognised - by RMR. This is an embed file as it is referenced by both - manual pages and the 'read the docs' source (allowing a single - point of maintenence). - - Date: 6 November 2019 (broken from the main manual page) - Author: E. Scott Daniels + Mnemonic: env_list_vars.im + Abstract: This is a list of environment variables which are recognised + by RMR. This is an embed file as it is referenced by both + manual pages and the 'read the docs' source (allowing a single + point of maintenance). + + Date: 6 November 2019 (broken from the main manual page) + Author: E. Scott Daniels .fi +&indent &beg_dlist(.75i : ^&bold_font ) -&ditem(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. - &half_space +&ditem(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. + +&ditem(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. + +&ditem(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. + + &space + Previously, the &cw(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. + + &space + 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 &cw(RMR_RTG_SVC) is &bold(not) defined. + + &space + When &cw(RMR_CTL_PORT) is &bold(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). + + &space + When &cw(RMR_CTL_PORT) is &bold(undefined^:) + RMR assumes that Route Manager will connect and push table updates, thus the + default listen port (4561) is used. + + &space + To avoid any possible misinterpretation and/or incorrect assumptions on the part + of RMR, it is recommended that both the &cw(RMR_CTL_PORT) and &cw(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. + +&ditem(RMR_RTREQ_FREQ) + When RMR needs a new route table it will send a request once every &cw(n) seconds. + The default value for &cw(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. + +&ditem(RMR_RTG_SVC) + The value of this variable depends on the Route Manager in use. + &space + When the Route Manager is expecting to connect to an xAPP and push + route tables, this variable must indicate the &cw(port) which RMR should + use to listen for these connections. + + &space + When the Route Manager is expecting RMR to connect and request a + table update during initialisation, the variable should be the + &cw(host:port) of the Route Manager process. + + &space + The &cw(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. + +&ditem(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. -&ditem(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. - &half_space +&ditem(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: -&ditem(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. &half_space + &indent + &beg_dlist(.25i : &bold_font ) + &ditem(0) Off; no messages of any sort are written. -&ditem(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. - &half_space + &ditem(1) Only critical messages are written (default if this variable does not exist) -&ditem(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: - - &beg_dlist(.25i : &bold_font ) - &ditem(0) Off; no messages of any sort are written. - &half_space - &ditem(1) Only critical messages are written (default if this variable does not exist) - &half_space - &ditem(2) Errors and all messages written with a lower value. - &half_space - &ditem(3) Warnings and all messages written with a lower value. - &half_space - &ditem(4) Informationional and all messages written with a lower value. - &half_space - &ditem(5) Debugging mode -- all messages written, however this requires RMR to have been compiled with debugging support enabled. - &end_dlist - &half_space + &ditem(2) Errors and all messages written with a lower value. + + &ditem(3) Warnings and all messages written with a lower value. + + &ditem(4) Informational and all messages written with a lower value. + + &ditem(5) Debugging mode -- all messages written, however this requires RMR to have + been compiled with debugging support enabled. + &end_dlist + &uindent -&ditem(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. +&ditem(RMR_RTG_ISRAW) + &bold(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. + &half_space + 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. &ditem(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. - 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) + 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. + 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). &ditem(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. + 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. + &space + The value of this variable is also used for Route Manager messages which are + sent via an RMR connection. + +&ditem(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 &cw(RMR_SEED_RT) variable + value and adding a &cw(.stash) suffix to the filename so as not to overwrite + the static table. &ditem(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 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. &ditem(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. + impacting. If the variable is not defined, or set to 0, RMR will not write these + additional warnings. &end_dlist +&uindent