X-Git-Url: https://gerrit.o-ran-sc.org/r/gitweb?a=blobdiff_plain;f=doc%2Fsrc%2Fman%2Fenv_var_list.im;h=e8b1c4e41d884f28da89e59f42de57ee90be4e3f;hb=c113b0836f3ebd58911c30de1636a707174efe55;hp=1399e00e84e0e602598c6b62216948eeb55619d3;hpb=4d1f9bf4b14788f957964d93af940e84f8f01601;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 1399e00..e8b1c4e 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=42 .if false ================================================================================== - Copyright (c) 2019 Nokia - Copyright (c) 2018-2019 AT&T Intellectual Property. + Copyright (c) 2019 Nokia + Copyright (c) 2018-2019 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,157 +19,157 @@ .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 maintenance). - - 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 &beg_dlist(.75i : ^&bold_font ) &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 unimpeeded should the - connection be slow to set up. - &half_space - -&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_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 well known address and port. - - &space - To maintain backwards compatablibility 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. - &half_space - -&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. - &half_space - -&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 + 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. + &half_space + +&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_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. + &half_space + +&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. + &half_space + +&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(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) Informational 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(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. + 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) Informational 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(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. - &half_space - The value of this variable is also used for Route Manager messages which are - sent via an RMR connection. + 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. + &half_space + The value of this variable is also used for Route Manager messages which are + sent via an RMR connection. &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