-.** 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.
.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_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_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