docs/config-deploy.rst

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