1xpaenv(n) SAORD Documentation xpaenv(n)
2
6 XPAEnv: Environment Variables for XPA Messaging
7
9 Describes the environment variables which can be used to tailor the
10 overall XPA environment.
11
13 The following environment variables are supported by XPA:
14 · XPA_ACL
16 If XPA_ACL is true, then host-based XPA Access Control is turned on
18 and only specified machines can access specified access points. If
19 false, then access control is turned off and any machine can access
20 point. The default is turn turn access control on.
21 · XPA_ACLFILE
23 If XPA Access Control is turned on, this variable specifies the
25 name of the file containing access control information for all
26 access points started by this user. The default file name is:
27 $HOME/acls.xpa.
28 · XPA_CONNECT_TIMEOUT
30 When an XPA server first starts up, it immediately tries to connect
32 to the XPA name server program (xpans) on the host specified by the
33 XPA_NSINET variable. (If this connection fails on the local host,
34 and if xpans can be found in the path, then the name server is
35 started automatically.) Unfortunately, a mis-configured network
36 can cause this connect attempt to hang for many seconds while the
37 connect() system call times out. Therefore, an alarm is started to
38 interrupt the connect() call and prevent a long hang. The initial
39 value of the alarm timeout is 10 seconds, but can be changed by
40 setting this environment variable. If you want to disable the alarm
41 and allow the initial connect() to time out, set the value of this
42 variable to 0. Normally, users would not change this variable at
43 all.
44 · XPA_CLIENT_DOXPA
46 Normally, an XPA client (xpaget, xpaset, etc.) will process incom‐
48 ing XPA server requests while awaiting the completion of the client
49 request. Setting this variable to "false" will prevent XPA server
50 requests from being processed by the client.
51 · XPA_DEFACL
53 If XPA Access Control is turned on, this variable specifies the
55 default access control condition for all access points, if the
56 XPA_ACLFILE file does not exist. The default acl is: $host:* $host
57 +, meaning that all processes on the host machine have full access
58 to all access points.
59 · XPA_HOST
61 For the INET socket method, XPA utilizes the canonical hostname (as
63 returned by the gethostname() routine) to construct the IP part of
64 the method id. Under some circumstances, this might not be a cor‐
65 rect choice of name and IP. For example, if an XPA server is
66 started on a machine running VPN, you might want to use the VPN
67 name and IP instead of the canonical host name, so that other
68 machines in the VPN network can access the server. In this case,
69 you can set the XPA_HOST to be the VPN name (if resolvable) or,
70 more easily, the VPN IP.
71 · XPA_IOCALLSXPA
73 Setting this variable causes all XPA socket IO calls to process
75 outstanding XPA requests whenever the primary socket is not ready
76 for IO. This means that a server making a client call will (recur‐
77 sively) process incoming server requests while waiting for client
78 completion. This inter-IO XPA processing avoids a rare XPA Race
79 Condition: two or more XPA servers sending messages to one another
80 using an XPA client routine such as XPASet() can deadlock while
81 each waits for the other server to respond. This can happen, for
82 example, if the servers call XPAPoll() with a time limit, and send
83 messages in between the polling call.
84 By default, this option is turned off, because we judge that the
86 added code complication and overhead involved will not be justified
87 by the amount of its use. Moreover, processing XPA requests within
88 socket IO can lead to non-intuitive results, since incoming server
89 requests will not necessarily be processed to completion in the
90 order in which they are received.
91 · XPA_LOGNAME
93 XPA preferentially uses the de facto standard environment variable
95 LOGNAME to determine the username when registering an access point
96 in the name server. If this environment variable has been used for
97 something other than the actual user name (such as a log file
98 name), unexpected results can ensue. In such cases, use the
99 XPA_LOGNAME variable to set the user name. (If neither exists, then
100 getpwuid(geteuid()) is used as a last resort).
101 · XPA_LONG_TIMEOUT
103 XPA is designed to allow data to be sent from one process to
105 another over a long period of time (i.e., a program that generates
106 image data sends that data to an image display, but slowly) but it
107 also seeks to prevent hangs. This is done by supporting 2 timeout
108 periods: a short timeout for protocol communication and a long for
109 data communication.
110 The XPA_LONG_TIMEOUT variable controls the long timeout and is used
112 to prevent hangs in cases where communication between the client
113 and server that is not controlled by the XPA interface itself.
114 Transfer of data between client and server, or a client's wait for
115 a status message after completion of the server callback, are two
116 examples of this sort of communication. By default, the long time‐
117 out is set to 180 seconds. Setting the value to -1 will disable
118 long timeouts and allow an infinite amount of time.
119 · XPA_MAXHOSTS
121 The maximum number of access points that the programs xpaset,
123 xpaget, and xpainfo will communicate with at one time. The default
124 is 64, meaning, for example, that the xpaset program will not send
125 a message to more than 100 access points at one time and xpaget
126 will not retrieve from more than 100 access points at one time.
127 · XPA_METHOD
129 Determines the socket connection method used by this session of
131 XPA. The choices are: inet (to use INET or Internet-based sock‐
132 ets), localhost (to use the machines localhost inet socket), or
133 local (unix) (to use UNIX sockets). The default is INET. Using the
134 inet method will allow access from other machines (subject to
135 access controls) but using localhost or local will not. Localhost
136 is most useful for private access and when the machine in question
137 is not connected to the Internet. The unix method also can be used
138 for private access and non-Internet connections (Unix platforms
139 only).
140 Once defined, the first registration of an XPA access point will
142 ensure that an instance of the XPA Name Server (xpans) is running
143 that handles that connection method. All new access points will use
144 the new connection method but existing access points will use the
145 original method.
146 · XPA_NSINET
148 For the inet method of socket connection, this variable specifies
150 the host and port on which the XPA Name Server (xpans) is listens
151 for new access points. The default is $host:$port, meaning that the
152 default XPA port (14285) on the current machine (as returned by
153 gethostname()) is used. If several machines were all accessing the
154 same XPA access points, you would use this variable to specify that
155 they all use the same name server to find out about these access
156 points. For example, a value of myhost:$port would mean that the
157 xpans name server is running on myhost and uses the default port
158 12345. All machines would then get the XPA access points regis‐
159 tered with that name server, subject to access controls.
160 The port used by xpans to register its XPA access point normally is
162 taken to be one greater than the port on which it receives new
163 access points from XPA servers. You can specify a specific access
164 point port using the syntax machine:port1,port2, i.e., the access
165 point port is specified after the comma. For example,
166 $host:12345,23456 will listen for new access ports on 12345 and
167 will accept XPA commands on 23456.
168 · XPA_NSREGISTER
170 This boolean variable specifies whether a server registers its XPA
172 access point with the specified xpans name server. The default is
173 true. If set to false, the access point still is set up but it is
174 not registered with xpans and therefore cannot be accessed by name.
175 (It can be accessed by method, if the latter is known.) Note that
176 an access point can be registered later on (using -remote or
177 -proxy, for example). This variable mainly is useful in cases where
178 the Internet configuration is broken (so that registration causes a
179 DNS hang) but you still wish to and can use the server with a
180 remote xpans (e.g., ds9's Virtual Observatory capability).
181 · XPA_NSUNIX
183 For the local method of socket connection, this variable specifies
185 the name of the Unix file that will be used to access the XPA Name
186 Server (xpans). The default is xpans_unix. This variable is not
187 usually needed. Note that is the local socket method is used, then
188 remote machines will not be able to access the xpans name server or
189 the registered XPA access points.
190 · XPA_NSUSERS
192 This variable specifies whether other users' access points will be
194 returned by the XPA Name Server (xpans) for use by xpaget, xpaset,
195 etc. Generally speaking, it is sufficient to run one xpans name
196 server per machine and register the access points for all users
197 with that xpans. This means, for example, that if you request
198 information from ds9 by running:
199 xpaget ds9 colormap
201 you might get information from your own ds9 as well as from another
203 user running ds9 on the same machine. The XPA_NSUSERS variable
204 controls whether you want such access to the access points of other
205 users. By default, only your own access points are returned, so
206 that, in the example above, you would only get the colormap infor‐
207 mation from the ds9 you registered. If, however, you had set the
208 value of the XPA_NSUSERS variable to eric,fred, then you would be
209 able to communicate with both eric and fred's access points. Note
210 that this variable can be overridden using the -u switch on the
211 xpaget, xpaset, and xpainfo programs.
212 · XPA_PORT
214 A semi-colon delimited list of user specified ports to use for spe‐
216 cific XPA access points. The format is each specification is:
217 class:template port1[ port2]
219 where port1 is the main (command) port for the access point and
221 port2 is the (secondary) data port. If port2 is not specified, it
222 defaults to a value of 0 (meaning the system assigns the port).
223 Specification of specific ports is useful, for example, when a
225 machine outside a firewall needs to communicate with a machine
226 inside a firewall. In such a case, the firewall should be config‐
227 ured to allow socket connections to both the command and data port
228 from the outside machine, and the inside XPA program should be
229 started up with the outside machine in its ACL list. Then, when the
230 inside program is started with specified ports, outside XPA pro‐
231 grams can use "machine:port" to contact the inside access points,
232 instead of the access point names. That is, the machine outside the
233 firewall does not need access to the XPA name server:
234 export XPA_PORT="DS9:ds9 12345 12346" # on machine "inside" cat
236 foo.fits ⎪ xpaset inside:12345 fits # on machine "outside"
237 Note that 2 ports are required for full XPA communication and
239 therefore 2 ports should be specified to go through a firewall.
240 The second port assignment is not important if you simply are
241 assigning the command port in order to communicate commands with a
242 known port (e.g., to bypass the xpans name server). If only one
243 (command) port is specified, the system will negotiate a random
244 data port and everything will work properly.
245 This support is somewhat experimental. If you run into problems,
247 please let us know.
248 · XPA_PORTFILE
250 A list of user-specified port to use for specific xpa access
252 points. The format of the file is:
253 class:template port1 [port2]
255 where port1 is the main port for the access point and port2 is the
257 data port. If port2 is not specified, it defaults to a value of 0
258 (meaning the system assigns the port). See XPA_PORT above for an
259 explanation of user-specified ports.
260 · XPA_SHORT_TIMEOUT
262 XPA is designed to allow data to be sent from one process to
264 another over a long period of time (i.e., a program that generates
265 image data sends that data to an image display, but slowly) but it
266 also seeks to prevent hangs. This is done by supporting 2 timeout
267 periods: a short timeout for protocol communication and a long for
268 data communication.
269 The XPA_SHORT_TIMEOUT variable controls the short timeout and is
271 used to prevent hangs in cases where the XPA protocol requires
272 internal communication between the client and server that is con‐
273 trolled by the XPA interface itself. Authentication is an example
274 of this sort of communication, as is the establishment of a data
275 channel between the two processes. The default value for the short
276 is 30 seconds (which is a pretty long time, actually). Setting the
277 value to -1 will disable short timeouts and allow an infinite
278 amount of time.
279 · XPA_SIGUSR1
281 If the value of this variable is true, then XPA will catch SIGUSR1
283 signals when performing an I/O operation in order to curtail that
284 operation. This facility allows users to send a SIGUSR1 signal to
285 an XPA server if a client is hanging up the server by sending or
286 receiving data too slowly (timeouts also can be used -- see above).
287 When enabled in this way, the SIGUSR1 signal is ignored at all
288 other times, so that its safe to send the signal at any time. If
289 the variable is set to false, then SIGUSR1 is not used at all.
290 Turning off SIGUSR1 would be desired in cases there the program
291 uses SIGUSR1 for some other reason and does not want XPA interfer‐
292 ing. The default is to use the signal.
293 · XPA_TIMESTAMP_ERRORS
295 If XPA_TIMESTAMP_ERRORS is true, then error messages will include a
297 date/time string. This can be useful when XPA errors are being
298 saved in an error log (e.g. Web/CGI use). The default is false.
299·
302This variable specifies the directory into which XPA logs, Unix socket files
304(when XPA_METHOD is local), etc. are stored. The default is /tmp/.xpa.
305·
308Specify the verbosity level of error messages. If the value is set to 0,
313almost always can be ignored.
314·
317Specify whether a new access point should check its major and minor XPA ver‐
319sion number against the version used by the xpans name server at registration
320time. The default is true. When checking is performed, a warning is issued if
321the server major version is found to be greater than the xpans version. Note
322that the check is performed both by the XPA server and by the xpans process
323and warnings will be issued by each. Also, instead of the values of true or
325sion checking process (i.e., the XPA-enabled server or xpans) will print out a
326maximum of n warning messages (after which version warnings are silently swal‐
327lowed).
328In general, it is a bad idea to run an XPA-enabled server program using a ver‐
330sion of XPA newer than the basic xpaset, xpaget, xpaaccess, xpans programs.
331This sort of mismatch usually will not work due to protocol changes.
332
334 See xpa(n) for a list of XPA help pages
335version 2.1.12 January 26, 2010 xpaenv(n)