docs/config-deploy.rst

   1
   2
   3 .. This work is licensed under a Creative Commons Attribution 4.0 International License.
   4 .. SPDX-License-Identifier: CC-BY-4.0
   5 .. CAUTION: this document is generated from source in doc/src/rtd.
   6 .. To make changes edit the source and recompile the document.
   7 .. Do NOT make changes directly to .rst or .md files.
   8
   9
  10
  11 RMR Configuration and Deployment
  12 ============================================================================================
  13
  14 The RIC Message Router (RMR) is a library for peer-to-peer
  15 communication. Applications use the library to send and
  16 receive messages where the message routing and endpoint
  17 selection is based on the message type rather than DNS host
  18 name-IP port combinations.
  19
  20 This document contains information regarding the
  21 configuration of RMR when it is embedded by a *user
  22 application* . RMR itself is a library, not a deployable
  23 entity.
  24
  25 Configuration
  26 --------------------------------------------------------------------------------------------
  27
  28 Many aspects of RMR behavior are controlled via environment
  29 variables. These values are read when a user application
  30 invokes the RMR initialization function. This allows these
  31 variables to be set before the application is started as a
  32 function of the true environment, or set by the application
  33 as a means for the application to influence RMR's behaviour.
  34 The following is a list of environment variables which RMR
  35 recognizes. Also see the main RMR manual page in the
  36 development package for more details.
  37
  38
  39 RMR_ASYNC_CONN
  40
  41   Allows the async connection mode to be turned off (by
  42   setting the value to 0). When set to 1, or missing from
  43   the environment, RMR will invoke the connection interface
  44   in the transport mechanism using the non-blocking (async)
  45   mode. This will likely result in many "soft failures"
  46   (retry) until the connection is established, but allows
  47   the application to continue unimpeded should the
  48   connection be slow to set up.
  49
  50
  51 RMR_BIND_IF
  52
  53   This provides the interface that RMR will bind listen
  54   ports to, allowing for a single interface to be used
  55   rather than listening across all interfaces. This should
  56   be the IP address assigned to the interface that RMR
  57   should listen on, and if not defined RMR will listen on
  58   all interfaces.
  59
  60
  61 RMR_CTL_PORT
  62
  63   This variable defines the port that RMR should open for
  64   communications with Route Manager, and other RMR control
  65   applications. If not defined, the port 4561 is assumed.
  66
  67   Previously, the RMR_RTG_SVC (route table generator service
  68   port) was used to define this port. However, a future
  69   version of Route Manager will require RMR to connect and
  70   request tables, thus that variable is now used to supply
  71   the Route Manager's well-known address and port.
  72
  73   To maintain backwards compatibility with the older Route
  74   Manager versions, the presence of this variable in the
  75   environment will shift RMR's behaviour with respect to the
  76   default value used when RMR_RTG_SVC is **not** defined.
  77
  78   When RMR_CTL_PORT is **defined:** RMR assumes that Route
  79   Manager requires RMR to connect and request table updates
  80   is made, and the default well-known address for Route
  81   manager is used (routemgr:4561).
  82
  83   When RMR_CTL_PORT is **undefined:** RMR assumes that Route
  84   Manager will connect and push table updates, thus the
  85   default listen port (4561) is used.
  86
  87   To avoid any possible misinterpretation and/or incorrect
  88   assumptions on the part of RMR, it is recommended that
  89   both the RMR_CTL_PORT and RMR_RTG_SVC be defined. In the
  90   case where both variables are defined, RMR will behave
  91   exactly as is communicated with the variable's values.
  92
  93
  94 RMR_RTG_SVC
  95
  96   The value of this variable depends on the Route Manager in
  97   use.
  98
  99   When the Route Manager is expecting to connect to an xAPP
 100   and push route tables, this variable must indicate the
 101   port which RMR should use to listen for these connections.
 102
 103   When the Route Manager is expecting RMR to connect and
 104   request a table update during initialisation, the variable
 105   should be the host of the Route Manager process.
 106
 107   The RMR_CTL_PORT variable (added with the support of
 108   sending table update requests to Route manager), controls
 109   the behaviour if this variable is not set. See the
 110   description of that variable for details.
 111
 112
 113 RMR_HR_LOG
 114
 115   By default RMR writes messages to standard error
 116   (incorrectly referred to as log messages) in human
 117   readable format. If this environment variable is set to 0,
 118   the format of standard error messages might be written in
 119   some format not easily read by humans. If missing, a value
 120   of 1 is assumed.
 121
 122
 123 RMR_LOG_VLEVEL
 124
 125   This is a numeric value which corresponds to the verbosity
 126   level used to limit messages written to standard error.
 127   The lower the number the less chatty RMR functions are
 128   during execution. The following is the current
 129   relationship between the value set on this variable and
 130   the messages written:
 131
 132
 133 0
 134
 135   Off; no messages of any sort are written.
 136
 137
 138 1
 139
 140   Only critical messages are written (default if this
 141   variable does not exist)
 142
 143
 144 2
 145
 146   Errors and all messages written with a lower value.
 147
 148
 149 3
 150
 151   Warnings and all messages written with a lower value.
 152
 153
 154 4
 155
 156   Informational and all messages written with a lower
 157   value.
 158
 159
 160 5
 161
 162   Debugging mode -- all messages written, however this
 163   requires RMR to have been compiled with debugging
 164   support enabled.
 165
 166
 167
 168 RMR_RTG_ISRAW
 169
 170   **Deprecated.** Should be set to 1 if the route table
 171   generator is sending "plain" messages (not using RMR to
 172   send messages), 0 if the RTG is using RMR to send. The
 173   default is 1 as we don't expect the RTG to use RMR.
 174
 175   This variable is only recognised when using the NNG
 176   transport library as it is not possible to support NNG
 177   "raw" communications with other transport libraries. It is
 178   also necessary to match the value of this variable with
 179   the capabilities of the Route Manager; at some point in
 180   the future RMR will assume that all Route Manager messages
 181   will arrive via an RMR connection and will ignore this
 182   variable.
 183
 184 RMR_SEED_RT
 185
 186   This is used to supply a static route table which can be
 187   used for debugging, testing, or if no route table
 188   generator process is being used to supply the route table.
 189   If not defined, no static table is used and RMR will not
 190   report *ready* until a table is received. The static route
 191   table may contain both the route table (between newrt
 192   start and end records), and the MEID map (between meid_map
 193   start and end records).
 194
 195 RMR_SRC_ID
 196
 197   This is either the name or IP address which is placed into
 198   outbound messages as the message source. This will used
 199   when an RMR based application uses the rmr_rts_msg()
 200   function to return a response to the sender. If not
 201   supplied RMR will use the hostname which in some container
 202   environments might not be routable.
 203
 204   The value of this variable is also used for Route Manager
 205   messages which are sent via an RMR connection.
 206
 207 RMR_VCTL_FILE
 208
 209   This supplies the name of a verbosity control file. The
 210   core RMR functions do not produce messages unless there is
 211   a critical failure. However, the route table collection
 212   thread, not a part of the main message processing
 213   component, can write additional messages to standard
 214   error. If this variable is set, RMR will extract the
 215   verbosity level for these messages (0 is silent) from the
 216   first line of the file. Changes to the file are detected
 217   and thus the level can be changed dynamically, however RMR
 218   will only suss out this variable during initialisation, so
 219   it is impossible to enable verbosity after startup.
 220
 221 RMR_WARNINGS
 222
 223   If set to 1, RMR will write some warnings which are
 224   non-performance impacting. If the variable is not defined,
 225   or set to 0, RMR will not write these additional warnings.
 226