a0b69ee9ffb51428cd70cb1a3ecf2af2114c7c70
[ric-plt/lib/rmr.git] / doc / src / man / env_var_list.im
1 .** vim: ts=4 noet sw=42
2 .if false
3 ==================================================================================
4    Copyright (c) 2019-2020 Nokia
5    Copyright (c) 2018-2020 AT&T Intellectual Property.
6
7    Licensed under the Apache License, Version 2.0 (the "License");
8    you may not use this file except in compliance with the License.
9    You may obtain a copy of the License at
10
11        http://www.apache.org/licenses/LICENSE-2.0
12
13    Unless required by applicable law or agreed to in writing, software
14    distributed under the License is distributed on an "AS IS" BASIS,
15    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
16    See the License for the specific language governing permissions and
17    limitations under the License.
18 ==================================================================================
19 .fi
20
21 .if false
22     Mnemonic:    env_list_vars.im
23     Abstract:    This is a list of environment variables which are recognised
24                 by RMR. This is an embed file as it is referenced by both
25                 manual pages and the 'read the docs' source (allowing a single
26                 point of maintenance).
27
28     Date:        6 November 2019 (broken from the main manual page)
29     Author:        E. Scott Daniels
30 .fi
31
32
33 &indent
34 &beg_dlist(.75i : ^&bold_font )
35 &ditem(RMR_ASYNC_CONN) Allows the async connection mode to be turned off (by setting the
36     value to 0). When set to 1, or missing from the environment, RMR will invoke the
37     connection interface in the transport mechanism using the non-blocking (async)
38     mode.  This will likely result in many "soft failures" (retry) until the connection
39     is established, but allows the application to continue unimpeded should the
40     connection be slow to set up.
41
42 &ditem(RMR_BIND_IF) This provides the interface that RMR will bind listen ports to, allowing
43     for a single interface to be used rather than listening across all interfaces.
44     This should be the IP address assigned to the interface that RMR should listen
45     on, and if not defined RMR will listen on all interfaces.
46
47 &ditem(RMR_CTL_PORT)
48     This variable defines the port that RMR should open for communications
49     with Route Manager, and other RMR control applications.
50     If not defined, the port 4561 is assumed.
51
52     &space
53     Previously, the &cw(RMR_RTG_SVC) (route table generator service port)
54     was used to define this port.
55     However, a future version of Route Manager will require RMR to connect
56     and request tables, thus that variable is now used to supply the Route
57     Manager's well-known address and port.
58
59     &space
60     To maintain backwards compatibility with the older Route Manager versions,
61     the presence of this variable in the environment will shift RMR's behaviour
62     with respect to the default value used when &cw(RMR_RTG_SVC) is &bold(not) defined.
63
64     &space
65     When &cw(RMR_CTL_PORT) is &bold(defined^:)
66     RMR assumes that Route Manager requires RMR to connect and request table
67     updates is made, and the default well-known address for Route manager
68     is used (routemgr:4561).
69
70     &space
71     When &cw(RMR_CTL_PORT) is &bold(undefined^:)
72     RMR assumes that Route Manager will connect and push table updates, thus the
73     default listen port (4561) is used.
74
75     &space
76     To avoid any possible misinterpretation and/or incorrect assumptions on the part
77     of RMR, it is recommended that both the  &cw(RMR_CTL_PORT) and &cw(RMR_RTG_SVC)
78     be defined.
79     In the case where both variables are defined, RMR will behave exactly as is
80     communicated with the variable's values.
81
82 &ditem(RMR_RTG_SVC)
83     The value of this variable depends on the Route Manager in use.
84     &space
85     When the Route Manager is expecting to connect to an xAPP and push
86     route tables, this variable must indicate the &cw(port) which RMR should
87     use to listen for these connections.
88
89     &space
90     When the Route Manager is expecting RMR to connect and request a
91     table update during initialisation, the variable should be the
92     &cw(host:port) of the Route Manager process.
93
94     &space
95     The &cw(RMR_CTL_PORT) variable (added with the support of sending table update
96     requests to Route manager), controls the behaviour if this variable is not set.
97     See the description of that variable for details.
98
99 &ditem(RMR_HR_LOG)
100     By default RMR writes messages to standard error (incorrectly referred to as log messages)
101     in human readable format.
102     If this environment variable is set to 0, the format of standard error messages might
103     be written in some format not easily read by humans.
104     If missing, a value of 1 is assumed.
105
106 &ditem(RMR_LOG_VLEVEL)
107     This is a numeric value which corresponds to the verbosity level used to limit messages
108     written to standard error.
109     The lower the number the less chatty RMR functions are during execution.
110     The following is the current relationship between the value set on this variable and
111     the messages written:
112
113         &half_space
114         &indent
115     &beg_dlist(.25i : &bold_font )
116         &ditem(0)    Off; no messages of any sort are written.
117
118         &ditem(1)    Only critical messages are written (default if this variable does not exist)
119
120         &ditem(2)    Errors and all messages written with a lower value.
121
122         &ditem(3)    Warnings and all messages written with a lower value.
123
124         &ditem(4)    Informational and all messages written with a lower value.
125
126         &ditem(5)    Debugging mode -- all messages written, however this requires RMR to have
127                                                 been compiled with debugging support enabled.
128     &end_dlist
129         &uindent
130
131 &ditem(RMR_RTG_ISRAW)
132     &bold(Deprecated.)
133     Should be set to 1 if the route table generator is sending "plain" messages
134     (not using RMR to send messages), 0 if the RTG is using RMR to send. The default
135     is 1 as we don't expect the RTG to use RMR.
136     &half_space
137     This variable is only recognised when using the NNG transport library as
138     it is not possible to support NNG "raw" communications with other transport
139     libraries.  It is also necessary to match the value of this variable
140     with the capabilities of the Route Manager; at some point in the future
141     RMR will assume that all Route Manager messages will arrive via an RMR
142     connection and will ignore this variable.
143
144 &ditem(RMR_SEED_RT) This is used to supply a static route table which can be used for
145     debugging, testing, or if no route table generator process is being used to
146     supply the route table.
147     If not defined, no static table is used and RMR will not report &ital(ready)
148     until a table is received.
149     The static route table may contain both the route table (between newrt start
150     and end records), and the MEID map (between meid_map start and end records).
151
152 &ditem(RMR_SRC_ID) This is either the name or IP address which is placed into outbound
153     messages as the message source. This will used when an RMR based application uses
154     the rmr_rts_msg() function to return a response to the sender. If not supplied
155     RMR will use the hostname which in some container environments might not be
156     routable.
157     &space
158     The value of this variable is also used for Route Manager messages which are
159     sent via an RMR connection.
160
161 &ditem(RMR_VCTL_FILE) This supplies the name of a verbosity control file. The core
162     RMR functions do not produce messages unless there is a critical failure. However,
163     the route table collection thread, not a part of the main message processing
164     component, can write additional messages to standard error.  If this variable is
165     set, RMR will extract the verbosity level for these messages (0 is silent) from
166     the first line of the file. Changes to the file are detected and thus the level
167     can be changed dynamically, however RMR will only suss out this variable during
168     initialisation, so it is impossible to enable verbosity after startup.
169
170 &ditem(RMR_WARNINGS) If set to 1, RMR will write some warnings which are non-performance
171     impacting. If the variable is not defined, or set to 0, RMR will not write these
172     additional warnings.
173
174 &end_dlist
175 &uindent