doc/src/man/env_var_list.im

   1 ).** vim: ts=4 noet sw=42
   2 .if false
   3 ==================================================================================
   4         Copyright (c) 2019 Nokia
   5         Copyright (c) 2018-2019 AT&T Intellectual Property.
   6
   7    Licensed under the Apache License, Version 2.0 (the "License");
   8    you may not use this file except in compliance with the License.
   9    You may obtain a copy of the License at
  10
  11        http://www.apache.org/licenses/LICENSE-2.0
  12
  13    Unless required by applicable law or agreed to in writing, software
  14    distributed under the License is distributed on an "AS IS" BASIS,
  15    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  16    See the License for the specific language governing permissions and
  17    limitations under the License.
  18 ==================================================================================
  19 .fi
  20
  21 .if false
  22         Mnemonic:       env_list_vars.im
  23         Abstract:       This is a list of environment variables which are recognised
  24                                 by RMR. This is an embed file as it is referenced by both
  25                                 manual pages and the 'read the docs' source (allowing a single
  26                                 point of maintenance).
  27
  28         Date:           6 November 2019 (broken from the main manual page)
  29         Author:         E. Scott Daniels
  30 .fi
  31
  32
  33 &beg_dlist(.75i : ^&bold_font )
  34 &ditem(RMR_ASYNC_CONN) Allows the async connection mode to be turned off (by setting the
  35         value to 0. When set to 1, or missing from the environment, RMR will invoke the
  36         connection interface in the transport mechanism using the non-blocking (async)
  37         mode.  This will likely result in many "soft failures" (retry) until the connection
  38         is established, but allows the application to continue unimpeeded should the
  39         connection be slow to set up.
  40         &half_space
  41
  42 &ditem(RMR_BIND_IF) This provides the interface that RMR will bind listen ports to allowing
  43         for a single interface to be used rather than listening across all interfaces.
  44         This should be the IP address assigned to the interface that RMR should listen
  45         on, and if not defined RMR will listen on all interfaces.
  46         &half_space
  47
  48 &ditem(RMR_CTL_PORT)
  49         This variable defines the port that RMR should open for communications
  50         with Route Manager, and other RMR control applications.
  51         If not defined, the port 4561 is assumed.
  52
  53         &space
  54         Previously, the &cw(RMR_RTG_SVC) (route table generator service port)
  55         was used to define this port.
  56         However, a future version of Route Manager will require RMR to connect
  57         and request tables, thus that variable is now used to supply the Route
  58         Manager well known address and port.
  59
  60         &space
  61         To maintain backwards compatablibility with the older Route Manager versions,
  62         the presence of this variable in the environment will shift RMR's behaviour
  63         with respect to the default value used when &cw(RMR_RTG_SVC) is &bold(not) defined.
  64
  65         &space
  66         When &cw(RMR_CTL_PORT) is &bold(defined^:)
  67         RMR assumes that Route Manager requires RMR to connect and request table
  68         updates is made, and the default well known address for Route manager
  69         is used (routemgr:4561).
  70
  71         &space
  72         When &cw(RMR_CTL_PORT) is &bold(undefined^:)
  73         RMR assumes that Route Manager will connect and push table updates, thus the
  74         default listen port (4561) is used.
  75
  76         &space
  77         To avoid any possible misinterpretation and/or incorrect assumptions on the part
  78         of RMR, it is recommended that both the  &cw(RMR_CTL_PORT) and &cw(RMR_RTG_SVC)
  79         be defined.
  80         In the case where both variables are defined, RMR will behave exactly as is
  81         communicated with the variable's values.
  82         &half_space
  83
  84 &ditem(RMR_RTG_SVC)
  85         The value of this variable depends on the Route Manager in use.
  86         &space
  87         When the Route Manager is expecting to connect to an xAPP and push
  88         route tables, this variable must indicate the &cw(port) which RMR should
  89         use to listen for these connections.
  90
  91         &space
  92         When the Route Manager is expecting RMR to connect and request a
  93         table update during initialisation, the variable should be the
  94         &cw(host:port) of the Route Manager process.
  95
  96         &space
  97         The &cw(RMR_CTL_PORT) variable (added with the support of sending table update
  98         requests to Route manager), controls the behaviour if this variable is not set.
  99         See the description of that variable for details.
 100         &half_space
 101
 102 &ditem(RMR_HR_LOG)
 103         By default RMR writes messages to standard error (incorrectly referred to as log messages)
 104         in human readable format.
 105         If this environment variable is set to 0, the format of standard error messages might
 106         be written in some format not easily read by humans.
 107         If missing, a value of 1 is assumed.
 108         &half_space
 109
 110 &ditem(RMR_LOG_VLEVEL)
 111         This is a numeric value which corresponds to the verbosity level used to limit messages
 112         written to standard error.
 113         The lower the number the less chatty RMR functions are during execution.
 114         The following is the current relationship between the value set on this variable and
 115         the messages written:
 116
 117         &beg_dlist(.25i : &bold_font )
 118                 &ditem(0)       Off; no messages of any sort are written.
 119                 &half_space
 120                 &ditem(1)       Only critical messages are written (default if this variable does not exist)
 121                 &half_space
 122                 &ditem(2)       Errors and all messages written with a lower value.
 123                 &half_space
 124                 &ditem(3)       Warnings and all messages written with a lower value.
 125                 &half_space
 126                 &ditem(4)       Informational and all messages written with a lower value.
 127                 &half_space
 128                 &ditem(5)       Debugging mode -- all messages written, however this requires RMR to have been compiled with debugging support enabled.
 129         &end_dlist
 130         &half_space
 131
 132 &ditem(RMR_RTG_ISRAW)
 133         &bold(Deprecated.)
 134         Should be set to 1 if the route table generator is sending "plain" messages
 135         (not using RMR to send messages, 0 if the rtg is using RMR to send. The default
 136         is 1 as we don't expect the rtg to use RMR.
 137         &half_space
 138         This variable is only recognised when using the NNG transport library as
 139         it is not possible to support NNG "raw" communications with other transport
 140         libraries.  It is also necessary to match the value of this variable
 141         with the capabilities of the Route Manager; at some point in the future
 142         RMR will assume that all Route Manager messages will arrive via an RMR
 143         connection and will ignore this variable.
 144
 145 &ditem(RMR_SEED_RT) This is used to supply a static route table which can be used for
 146         debugging, testing, or if no route table generator process is being used to
 147         supply the route table.
 148         If not defined, no static table is used and RMR will not report &ital(ready)
 149         until a table is received.
 150         The static route table may contain both the route table (between newrt start
 151         and end records), and the MEID map (between meid_map start and end records)
 152
 153 &ditem(RMR_SRC_ID) This is either the name or IP address which is placed into outbound
 154         messages as the message source. This will used when an RMR based application uses
 155         the rmr_rts_msg() function to return a response to the sender. If not supplied
 156         RMR will use the hostname which in some container environments might not be
 157         routable.
 158         &half_space
 159         The value of this variable is also used for Route Manager messages which are
 160         sent via an RMR connection.
 161
 162 &ditem(RMR_VCTL_FILE) This supplies the name of a verbosity control file. The core
 163         RMR functions do not produce messages unless there is a critical failure. However,
 164         the route table collection thread, not a part of the main message processing
 165         component, can write additional messages to standard error.  If this variable is
 166         set, RMR will extract the verbosity level for these messages (0 is silent) from
 167         the first line of the file. Changes to the file are detected and thus the level
 168         can be changed dynamically, however RMR will only suss out this variable during
 169         initialisation, so it is impossible to enable verbosity after startup.
 170
 171 &ditem(RMR_WARNINGS) If set to 1, RMR will write some warnings which are non-performance
 172         impacting. If the variable is not defined, or set to 0, RMR will not write these
 173         additional warnings.
 174
 175 &end_dlist