1xpaenv(n)                     SAORD Documentation                    xpaenv(n)
2
3
4

NAME

6       XPAEnv: Environment Variables for XPA Messaging
7

SYNOPSIS

9       Describes the environment variables which can be used to tailor the
10       overall XPA environment.
11

DESCRIPTION

13       The following environment variables are supported by XPA:
14
15       ·   XPA_ACL
16
17           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
22       ·   XPA_ACLFILE
23
24           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
29       ·   XPA_CONNECT_TIMEOUT
30
31           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
45       ·   XPA_CLIENT_DOXPA
46
47           Normally, an XPA client (xpaget, xpaset, etc.) will process
48           incoming XPA server requests while awaiting the completion of the
49           client request.  Setting this variable to "false" will prevent XPA
50           server requests from being processed by the client.
51
52       ·   XPA_DEFACL
53
54           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
60       ·   XPA_HOST
61
62           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
65           correct 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
72       ·   XPA_IOCALLSXPA
73
74           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
77           (recursively) process incoming server requests while waiting for
78           client completion.  This inter-IO XPA processing avoids a rare XPA
79           Race Condition: two or more XPA servers sending messages to one
80           another using an XPA client routine such as XPASet() can deadlock
81           while each waits for the other server to respond. This can happen,
82           for example, if the servers call XPAPoll() with a time limit, and
83           send messages in between the polling call.
84
85           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
92       ·   XPA_LOGNAME
93
94           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
102       ·   XPA_LONG_TIMEOUT
103
104           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
111           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
117           timeout is set to 180 seconds.  Setting the value to -1 will
118           disable long timeouts and allow an infinite amount of time.
119
120       ·   XPA_MAXHOSTS
121
122           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
128       ·   XPA_METHOD
129
130           Determines the socket connection method used by this session of
131           XPA.  The choices are: inet (to use INET or Internet-based
132           sockets), 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
141           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
147       ·   XPA_NSINET
148
149           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
159           registered with that name server, subject to access controls.
160
161           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
169       ·   XPA_NSREGISTER
170
171           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
182       ·   XPA_NSUNIX
183
184           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
191       ·   XPA_NSUSERS
192
193           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
200             xpaget ds9 colormap
201
202           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
207           information from the ds9 you registered. If, however, you had set
208           the value of the XPA_NSUSERS variable to eric,fred, then you would
209           be able to communicate with both eric and fred's access points.
210           Note that this variable can be overridden using the -u switch on
211           the xpaget, xpaset, and xpainfo programs.
212
213       ·   XPA_PORT
214
215           A semi-colon delimited list of user specified ports to use for
216           specific XPA access points. The format is each specification is:
217
218           class:template port1[ port2]
219
220           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
224           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
227           configured to allow socket connections to both the command and data
228           port 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
231           programs can use "machine:port" to contact the inside access
232           points, instead of the access point names. That is, the machine
233           outside the firewall does not need access to the XPA name server:
234
235           export XPA_PORT="DS9:ds9 12345 12346"   # on machine "inside" cat
236           foo.fits | xpaset inside:12345 fits # on machine "outside"
237
238           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
246           This support is somewhat experimental. If you run into problems,
247           please let us know.
248
249       ·   XPA_PORTFILE
250
251           A list of user-specified port to use for specific xpa access
252           points.  The format of the file is:
253
254           class:template port1 [port2]
255
256           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
261       ·   XPA_SHORT_TIMEOUT
262
263           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
270           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
273           controlled by the XPA interface itself. Authentication is an
274           example of this sort of communication, as is the establishment of a
275           data channel between the two processes.  The default value for the
276           short is 30 seconds (which is a pretty long time, actually).
277           Setting the value to -1 will disable short timeouts and allow an
278           infinite amount of time.
279
280       ·   XPA_SIGUSR1
281
282           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
292           interfering.  The default is to use the signal.
293
294       ·   XPA_TIMESTAMP_ERRORS
295
296           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
300       ·   XPA_TMPDIR
301
302           This variable specifies the directory into which XPA logs, Unix
303           socket files (when XPA_METHOD is local), etc. are stored. The
304           default is /tmp/.xpa.
305
306       ·   XPA_VERBOSITY
307
308           Specify the verbosity level of error messages. If the value is set
309           to 0, false, or off, then no error messages are printed to stderr.
310           If the value is 1, then important XPA error messages will be
311           output.  If the value is set to 2, XPA warnings about out-of-sync
312           messages will also be output.  These latter almost always can be
313           ignored.
314
315       ·   XPA_VERSIONCHECK
316
317           Specify whether a new access point should check its major and minor
318           XPA version number against the version used by the xpans name
319           server at registration time. The default is true. When checking is
320           performed, a warning is issued if the server major version is found
321           to be greater than the xpans version. Note that the check is
322           performed both by the XPA server and by the xpans process and
323           warnings will be issued by each.  Also, instead of the values of
324           true or false, you can give this variable an integer value n. In
325           this case, each version checking process (i.e., the XPA-enabled
326           server or xpans) will print out a maximum of n warning messages
327           (after which version warnings are silently swallowed).
328
329           In general, it is a bad idea to run an XPA-enabled server program
330           using a version of XPA newer than the basic xpaset, xpaget,
331           xpaaccess, xpans programs. This sort of mismatch usually will not
332           work due to protocol changes.
333

SEE ALSO

335       See xpa(n) for a list of XPA help pages
336

POD ERRORS

338       Hey! The above document had some coding errors, which are explained
339       below:
340
341       Around line 458:
342           '=item' outside of any '=over'
343
344       Around line 509:
345           You forgot a '=back' before '=head1'
346
347
348
349version 2.1.15                   July 23, 2013                       xpaenv(n)
Impressum