Add user manual source
[ric-plt/lib/rmr.git] / 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 in a containerised
29 environment, there are some underlying mechanics which the developer may need to know 
30 in order to properly provide a configuration specification to the container management 
31 system.
32 The following paragraphs briefly discuss these.
33
34 .sp .1
35 &h2(TCP Ports)
36 RMR requires two (2) TCP listen ports: one for general application to application communications
37 and one for route table updates.
38 The general communication port is specified by the application at the time RMR is initialised.
39 The port used to listen for route table updates is likely to be a constant port shared by all
40 applications provided they are running in separate containers.  
41 To that end, the port number defaults to 4561, but can be configured with an environment variable
42 (see later paragraph in this section).
43
44
45 &h2(Host Names)
46 RMR is typically host name agnostic.
47 Route table entries may contain endpoints defined either by host name or IP address. 
48 In the container world the concept of a &ital(service name) might exist, and likely is different
49 than a host name.
50 RMR's only requirement with respect to host names is that a name used on a route table entry must
51 be resolvable via the &cw(gethostbyname) system call.
52
53
54 &h2(Environment Variables)
55 Several environment variables are recognised by RMR which,
56 in general, are used to define interfaces and listen ports (e.g. the route table update
57 listen port), or debugging information.
58 Generally this information is system controlled and thus RMR expects this information to 
59 be defined in the environment rather than provided by the application.
60 The following is a list of the environment variables which RMR recognises:
61
62 &half_space
63 .st 8p
64 &indent
65 &beg_dlist( 1.25i &ditext )
66         &di(RMR_BIND_IF)        The interface to bind to listen ports to. If not defined 0.0.0.0 (all interfaces) is assumed.
67         &half_space
68
69         &di(RMR_RTG_SVC)        The port RMR will listen on for route manager connections. If not defined 4561 is used.
70         &half_space
71
72         &di(RMR_SEED_RT)        Where RMR expects to find the name of the seed (static) route table. If not defined no static table is read.
73         &half_space
74
75         &di(RMR_RTG_ISRAW)      If the value set to 0, RMR expects the route table manager messages to be messages with and RMR header. 
76                                                 If this is not defined messages are assumed to be "raw" (without an RMR header.
77         &half_space
78
79         &di(RMR_VCTL_FILE)      Provides a file which is used to set the verbose level of the route table collection thread. 
80                                                 The first line of the file is read and expected to contain an integer value to set the verbose level. 
81                                                 The value may be changed at any time and the route table thread will adjust accordingly.
82         &half_space
83
84         &di(RMR_SRC_NAMEONLY) If the value of this variable is greater than 0, RMR will not permit the IP address to be
85                                                 sent as the message source. Only the host name will be sent as the source in the message header.
86 &end_dlist
87 &uindent
88 .st &textsize
89 &space
90
91 &h2(Logging)
92 RMR does &bold(not) use any logging libraries; any error or warning messages are written to standard error. 
93 .if false 
94  &note .sm .
95 .cn l=&cn_line_len i=0 start &atbot Times-roman 8p .7i
96         This is standard practice for container based applications as it makes error output easily available to operations.
97 .cn end
98 .fi
99 RMR messages are written with one of three prefix strings:
100
101
102 &half_space
103 &indent
104 &beg_dlist( .6i &ditext )
105         &di(^[CRI]) The event is of a critical nature and it is unlikely that RMR will continue to operate correctly if at all.
106                                 It is almost certain that immediate action will be needed to resolve the issue.
107         &half_space
108
109         &di(^[ERR]) The event is not expected and RMR is not able to handle it.  There is a small chance that continued operation
110                                 will be negatively impacted. 
111                                 Eventual action to diagnose and correct the issue will be necessary.
112         &half_space
113
114         &di(^[WRN]) The event was not expected by RMR, but can be worked round. Normal operation will continue, but it is recommended
115                                 that the cause of the problem be investigated.
116 &end_dlist
117 &space
118 &uindent