| .if false |
| ================================================================================== |
| Copyright (c) 2019 Nokia |
| Copyright (c) 2018-2019 AT&T Intellectual Property. |
| |
| Licensed under the Apache License, Version 2.0 (the "License"); |
| you may not use this file except in compliance with the License. |
| You may obtain a copy of the License at |
| |
| http://www.apache.org/licenses/LICENSE-2.0 |
| |
| Unless required by applicable law or agreed to in writing, software |
| distributed under the License is distributed on an "AS IS" BASIS, |
| WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. |
| See the License for the specific language governing permissions and |
| limitations under the License. |
| ================================================================================== |
| .fi |
| |
| .if false |
| Mnemonic: config.im |
| Abstract: Major section discussing for configuration. |
| Date: 2 August 2019 |
| Author: E. Scott Daniels |
| .fi |
| |
| &h1(Configuration and Control) |
| With the assumption that most RMR based applications will be executed |
| in a containerised environment, there are some underlying mechanics |
| which the developer may need to know in order to properly provide a |
| configuration specification to the container management system. The |
| following paragraphs briefly discuss these. |
| |
| .sp .1 |
| &h2(TCP Ports) |
| RMR requires two (2) TCP listen ports: one for general |
| application-to-application communications and one for route-table |
| updates. The general communication port is specified by the |
| application at the time RMR is initialised. The port used to listen |
| for route table updates is likely to be a constant port shared by all |
| applications provided they are running in separate containers. To |
| that end, the port number defaults to 4561, but can be configured with |
| an environment variable (see later paragraph in this section). |
| |
| |
| &h2(Host Names) |
| RMR is typically host name agnostic. Route table entries may contain |
| endpoints defined either by host name or IP address. In the container |
| world the concept of a &ital(service name) might exist, and likely is |
| different than a host name. RMR's only requirement with respect to |
| host names is that a name used on a route table entry must be |
| resolvable via the &cw(gethostbyname) system call. |
| |
| |
| &h2(Environment Variables) |
| Several environment variables are recognised by RMR which, in general, |
| are used to define interfaces and listen ports (e.g. the route table |
| update listen port), or debugging information. Generally this |
| information is system controlled and thus RMR expects this information |
| to be defined in the environment rather than provided by the |
| application. The following is a list of the environment variables |
| which RMR recognises: |
| |
| &half_space |
| .if false |
| &indent |
| &beg_dlist( 1.25i &ditext ) |
| &ditem(RMR_BIND_IF) The interface to bind to listen ports to. If not defined 0.0.0.0 (all interfaces) is assumed. |
| |
| &ditem(RMR_RTG_SVC) This variabe supplies the host:port (or address:port) of the Route Manager (route table generator) |
| process. RMR will attempt to connect to this address port combination and request a route table. |
| If it is desired to prevent RMR from attempting to request a dynamic route table, the value of this |
| variable should be set to "-1." If not set &cw(routemgr:4561) is assumed. |
| |
| &ditem(RMR_CTL_PORT) This is the port which RMR's route table collector thread will use to listen for RMR messages |
| from the route manager (route table generator). By default this is 4561, and must be unique for |
| each RMR process running on the host/container. |
| |
| &ditem(RMR_RTREQ_FREQ) When a new route table is needed, the frequency that RMR sends a route table request to the |
| Route Manager defaults to 5 seconds. This variable can be used to set the frequency to a value between |
| 1 and 300 seconds inclusive. |
| |
| &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. |
| |
| &ditem(RMR_RTG_ISRAW) If the value set to 0, RMR expects the route table manager messages to be messages with and RMR header. |
| If this is not defined messages are assumed to be "raw" (without an RMR header. |
| |
| &ditem(RMR_VCTL_FILE) Provides a file which is used to set the verbose level of the route table collection thread. |
| The first line of the file is read and expected to contain an integer value to set the verbose level. |
| The value may be changed at any time and the route table thread will adjust accordingly. |
| |
| &ditem(RMR_SRC_NAMEONLY) If the value of this variable is greater than 0, RMR will not permit the IP address to be |
| sent as the message source. Only the host name will be sent as the source in the message header. |
| &end_dlist |
| |
| &uindent |
| .st &textsize |
| .fi |
| |
| .** pull from man pages to avoid 2 places for maint |
| .im ../man/env_var_list.im |
| &space |
| |
| There are other, non-RMR, variables which may exist and are used by RMR. |
| These variable names are not under the control of RMR, so they are subject to change without potentiallyb being |
| reflected in either RMR's code, or this document. |
| The following is a list of these environment variables. |
| |
| &half_space |
| &indent |
| &beg_dlist( 1.25i &ditext ) |
| &ditem(ALARM_MANAGER_SERVICE_NAME) |
| This is the DNS name, or IP address, of the process which is listening for RMR alarm messages. |
| If this variable is missing, &cw(service-ricplt-alarmmanager-rmr) is assumed. |
| |
| &ditem(ALARM_MANAGER_SERVICE_PORT) |
| This is the port that the alarm manager is using to accept RMR messages. If the environment |
| variable is missing the value &cw(4560) is assumed. |
| &end_dlist |
| &uindent |
| .st &textsize |
| |
| |
| &h2(Logging and Alarms) |
| As with nearly all UNIX libraries, errors, warnings and informational messages are written in plain text to the |
| standard error device (stderr). |
| All RMR messages are prefixed with the current time (in milliseconds past the standard UNIX epoch), the process ID, |
| and a severity indicator. |
| .if false |
| RMR does &bold(not) use any logging libraries; any error or warning messages are written to standard error. |
| ¬e .sm . |
| .cn l=&cn_line_len i=0 start &atbot Times-roman 8p .7i |
| This is standard practice for container based applications as it makes error output easily available to operations. |
| .cn end |
| .fi |
| RMR messages are written with one of three severity strings: |
| |
| |
| &half_space |
| &indent |
| &beg_dlist( .6i &ditext ) |
| &ditem(^[CRI]) The event is of a critical nature and it is unlikely that RMR will continue to operate correctly if at all. |
| It is almost certain that immediate action will be needed to resolve the issue. |
| |
| &ditem(^[ERR]) The event is not expected and RMR is not able to handle it. There is a small chance that continued operation |
| will be negatively impacted. |
| Eventual action to diagnose and correct the issue will be necessary. |
| |
| &ditem(^[WRN]) The event was not expected by RMR, but can be worked round. Normal operation will continue, but it is recommended |
| that the cause of the problem be investigated. |
| &end_dlist |
| &space |
| &uindent |
| |
| &h3(Log message supression) |
| For the most part, the &ital(fast path) code in RMR does no logging; even when messages are squelched, there is a non-zero |
| cosst to check for the setting each time a potential message is to be written. |
| To that end, RMRM will log only severe errors once initialisation has completed. |
| An exception to this policy exists in the route table collection thread. |
| The thread of execution which collects route table updates does not need to be concerned with performance, and as such |
| has the potential to log its actions in a very verbose manner. |
| The environment variable &cw( RMR_VCTL_FILE ) can be used to define a file where the desired verbosity level (0 to 4 |
| where 0 is off) can be placed. |
| If the environment variable is not set when the process starts, RMR will assume that the file &cw(/tmp/rmr.v) will be used. |
| Beginning with version 4.6.0 this file does &bold(not) need to exist when the process is started. |
| To change the verbosity level, the desired value is written to the file on the first line. |
| |
| &h3(Alarms) |
| The route table colleciton thread is also responsible for watching for situations which need to be reported as alarms |
| to the platform's alarm management service. |
| When a state exists RMR will create and send an alarm (via RMR message) to the alarm service, and will send a &ital(clear) |
| message when the state no longer exists. |
| Currently RMR will alarm only when the application is not removing messages from the receive ring quicklye enough causing |
| RMR to drop messages as they are received. |