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