doc/src/library/config.im

   1 .if false
   2 ==================================================================================
   3         Copyright (c) 2019 Nokia
   4         Copyright (c) 2018-2019 AT&T Intellectual Property.
   5
   6    Licensed under the Apache License, Version 2.0 (the "License");
   7    you may not use this file except in compliance with the License.
   8    You may obtain a copy of the License at
   9
  10        http://www.apache.org/licenses/LICENSE-2.0
  11
  12    Unless required by applicable law or agreed to in writing, software
  13    distributed under the License is distributed on an "AS IS" BASIS,
  14    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  15    See the License for the specific language governing permissions and
  16    limitations under the License.
  17 ==================================================================================
  18 .fi
  19
  20 .if false
  21         Mnemonic:       config.im
  22         Abstract:       Major section discussing for configuration.
  23         Date:           2 August 2019
  24         Author:         E. Scott Daniels
  25 .fi
  26
  27 &h1(Configuration and Control)
  28 With the assumption that most RMR based applications will be executed
  29 in a containerised environment, there are some underlying mechanics
  30 which the developer may need to know in order to properly provide a
  31 configuration specification to the container management system.  The
  32 following paragraphs briefly discuss these.
  33
  34 .sp .1
  35 &h2(TCP Ports)
  36 RMR requires two (2) TCP listen ports: one for general
  37 application-to-application communications and one for route-table
  38 updates.  The general communication port is specified by the
  39 application at the time RMR is initialised.  The port used to listen
  40 for route table updates is likely to be a constant port shared by all
  41 applications provided they are running in separate containers.  To
  42 that end, the port number defaults to 4561, but can be configured with
  43 an environment variable (see later paragraph in this section).
  44
  45
  46 &h2(Host Names)
  47 RMR is typically host name agnostic.  Route table entries may contain
  48 endpoints defined either by host name or IP address.  In the container
  49 world the concept of a &ital(service name) might exist, and likely is
  50 different than a host name.  RMR's only requirement with respect to
  51 host names is that a name used on a route table entry must be
  52 resolvable via the &cw(gethostbyname) system call.
  53
  54
  55 &h2(Environment Variables)
  56 Several environment variables are recognised by RMR which, in general,
  57 are used to define interfaces and listen ports (e.g. the route table
  58 update listen port), or debugging information.  Generally this
  59 information is system controlled and thus RMR expects this information
  60 to be defined in the environment rather than provided by the
  61 application.  The following is a list of the environment variables
  62 which RMR recognises:
  63
  64 &half_space
  65 &indent
  66 &beg_dlist( 1.25i &ditext )
  67         &ditem(RMR_BIND_IF)     The interface to bind to listen ports to. If not defined 0.0.0.0 (all interfaces) is assumed.
  68
  69         &ditem(RMR_RTG_SVC)      This variabe supplies the host:port (or address:port) of the Route Manager (route table generator)
  70                                         process.  RMR will attempt to connect to this address port combination and request a route table.
  71                                         If it is desired to prevent RMR from attempting to request a dynamic route table, the value of this
  72                                         variable should be set to "-1."   If not set &cw(routemgr:4561) is assumed.
  73
  74         &ditem(RMR_CTL_PORT) This is the port which RMR's route table collector thread will use to listen for RMR messages
  75                                         from the route manager (route table generator).  By default this is 4561, and must be unique for
  76                                         each RMR process running on the host/container.
  77
  78         &ditem(RMR_RTREQ_FREQ) When a new route table is needed, the frequency that RMR sends a route table request to the
  79                                         Route Manager defaults to 5 seconds.  This variable can be used to set the frequency to a value between
  80                                         1 and 300  seconds inclusive.
  81
  82         &ditem(RMR_SEED_RT)     Where RMR expects to find the name of the seed (static) route table. If not defined no static table is read.
  83
  84         &ditem(RMR_RTG_ISRAW)   If the value set to 0, RMR expects the route table manager messages to be messages with and RMR header.
  85                                                 If this is not defined messages are assumed to be "raw" (without an RMR header.
  86
  87         &ditem(RMR_VCTL_FILE)   Provides a file which is used to set the verbose level of the route table collection thread.
  88                                                 The first line of the file is read and expected to contain an integer value to set the verbose level.
  89                                                 The value may be changed at any time and the route table thread will adjust accordingly.
  90
  91         &ditem(RMR_SRC_NAMEONLY) If the value of this variable is greater than 0, RMR will not permit the IP address to be
  92                                                 sent as the message source. Only the host name will be sent as the source in the message header.
  93 &end_dlist
  94 &uindent
  95 .st &textsize
  96 &space
  97
  98 &h2(Logging)
  99 RMR does &bold(not) use any logging libraries; any error or warning messages are written to standard error.
 100 .if false
 101  &note .sm .
 102 .cn l=&cn_line_len i=0 start &atbot Times-roman 8p .7i
 103         This is standard practice for container based applications as it makes error output easily available to operations.
 104 .cn end
 105 .fi
 106 RMR messages are written with one of three prefix strings:
 107
 108
 109 &half_space
 110 &indent
 111 &beg_dlist( .6i &ditext )
 112         &ditem(^[CRI]) The event is of a critical nature and it is unlikely that RMR will continue to operate correctly if at all.
 113                                 It is almost certain that immediate action will be needed to resolve the issue.
 114
 115         &ditem(^[ERR]) The event is not expected and RMR is not able to handle it.  There is a small chance that continued operation
 116                                 will be negatively impacted.
 117                                 Eventual action to diagnose and correct the issue will be necessary.
 118
 119         &ditem(^[WRN]) The event was not expected by RMR, but can be worked round. Normal operation will continue, but it is recommended
 120                                 that the cause of the problem be investigated.
 121 &end_dlist
 122 &space
 123 &uindent