docs/config-deploy.rst

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