Provided by: libxpa-dev_2.1.20-1_amd64 bug

NAME

       XPAEnv - Environment Variables for XPA Messaging

SYNOPSIS

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

DESCRIPTION

       The following environment variables are supported by XPA:

       •   XPA_ACL

           If XPA_ACL is true, then host-based XPA Access Control is turned on and only specified
           machines can access specified access points.  If false, then access control is turned
           off and any machine can access point. The default is turn turn access control on.

       •   XPA_ACLFILE

           If XPA Access Control is turned on, this variable specifies the name of the file
           containing access control information for all access points started by this user.  The
           default file name is: $HOME/acls.xpa.

       •   XPA_CONNECT_TIMEOUT

           When an XPA server first starts up, it immediately tries to connect to the XPA name
           server program (xpans) on the host specified by the XPA_NSINET variable. (If this
           connection fails on the local host, and if xpans can be found in the path, then the
           name server is started automatically.)  Unfortunately, a mis-configured network can
           cause this connect attempt to hang for many seconds while the connect() system call
           times out. Therefore, an alarm is started to interrupt the connect() call and prevent
           a long hang.  The initial value of the alarm timeout is 10 seconds, but can be changed
           by setting this environment variable. If you want to disable the alarm and allow the
           initial connect() to time out, set the value of this variable to 0. Normally, users
           would not change this variable at all.

       •   XPA_CLIENT_DOXPA

           Normally, an XPA client (xpaget, xpaset, etc.) will process incoming XPA server
           requests while awaiting the completion of the client request.  Setting this variable
           to "false" will prevent XPA server requests from being processed by the client.

       •   XPA_DEFACL

           If XPA Access Control is turned on, this variable specifies the default access control
           condition for all access points, if the XPA_ACLFILE file does not exist.  The default
           acl is: $host:* $host +, meaning that all processes on the host machine have full
           access to all access points.

       •   XPA_HOST

           For the INET socket method, XPA utilizes the canonical hostname (as returned by the
           gethostname() routine) to construct the IP part of the method id. Under some
           circumstances, this might not be a correct choice of name and IP. For example, if an
           XPA server is started on a machine running VPN, you might want to use the VPN name and
           IP instead of the canonical host name, so that other machines in the VPN network can
           access the server. In this case, you can set the XPA_HOST to be the VPN name (if
           resolvable) or, more easily, the VPN IP.

       •   XPA_IOCALLSXPA

           Setting this variable causes all XPA socket IO calls to process outstanding XPA
           requests whenever the primary socket is not ready for IO. This means that a server
           making a client call will (recursively) process incoming server requests while waiting
           for client completion.  This inter-IO XPA processing avoids a rare XPA Race Condition:
           two or more XPA servers sending messages to one another using an XPA client routine
           such as XPASet() can deadlock while each waits for the other server to respond. This
           can happen, for example, if the servers call XPAPoll() with a time limit, and send
           messages in between the polling call.

           By default, this option is turned off, because we judge that the added code
           complication and overhead involved will not be justified by the amount of its use.
           Moreover, processing XPA requests within socket IO can lead to non-intuitive results,
           since incoming server requests will not necessarily be processed to completion in the
           order in which they are received.

       •   XPA_LOGNAME

           XPA preferentially uses the de facto standard environment variable LOGNAME to
           determine the username when registering an access point in the name server. If this
           environment variable has been used for something other than the actual user name (such
           as a log file name), unexpected results can ensue. In such cases, use the XPA_LOGNAME
           variable to set the user name. (If neither exists, then getpwuid(geteuid()) is used as
           a last resort).

       •   XPA_LONG_TIMEOUT

           XPA is designed to allow data to be sent from one process to another over a long
           period of time (i.e., a program that generates image data sends that data to an image
           display, but slowly) but it also seeks to prevent hangs. This is done by supporting 2
           timeout periods: a short timeout for protocol communication and a long for data
           communication.

           The XPA_LONG_TIMEOUT variable controls the long timeout and is used to prevent hangs
           in cases where communication between the client and server that is not controlled by
           the XPA interface itself. Transfer of data between client and server, or a client's
           wait for a status message after completion of the server callback, are two examples of
           this sort of communication. By default, the long timeout is set to 180 seconds.
           Setting the value to -1 will disable long timeouts and allow an infinite amount of
           time.

       •   XPA_MAXHOSTS

           The maximum number of access points that the programs xpaset, xpaget, and xpainfo will
           communicate with at one time. The default is 64, meaning, for example, that the xpaset
           program will not send a message to more than 100 access points at one time and xpaget
           will not retrieve from more than 100 access points at one time.

       •   XPA_METHOD

           Determines the socket connection method used by this session of XPA.  The choices are:
           inet (to use INET or Internet-based sockets), localhost (to use the machines localhost
           inet socket), or local (unix) (to use UNIX sockets). The default is INET.  Using the
           inet method will allow access from other machines (subject to access controls) but
           using localhost or local will not. Localhost is most useful for private access and
           when the machine in question is not connected to the Internet. The unix method also
           can be used for private access and non-Internet connections (Unix platforms only).

           Once defined, the first registration of an XPA access point will ensure that an
           instance of the XPA Name Server (xpans) is running that handles that connection
           method. All new access points will use the new connection method but existing access
           points will use the original method.

       •   XPA_NSINET

           For the inet method of socket connection, this variable specifies the host and port on
           which the XPA Name Server (xpans) is listens for new access points. The default is
           $host:$port, meaning that the default XPA port (14285) on the current machine (as
           returned by gethostname()) is used. If several machines were all accessing the same
           XPA access points, you would use this variable to specify that they all use the same
           name server to find out about these access points.  For example, a value of
           myhost:$port would mean that the xpans name server is running on myhost and uses the
           default port 12345.  All machines would then get the XPA access points registered with
           that name server, subject to access controls.

           The port used by xpans to register its XPA access point normally is taken to be one
           greater than the port on which it receives new access points from XPA servers. You can
           specify a specific access point port using the syntax machine:port1,port2, i.e., the
           access point port is specified after the comma.  For example, $host:12345,23456 will
           listen for new access ports on 12345 and will accept XPA commands on 23456.

       •   XPA_NSREGISTER

           This boolean variable specifies whether a server registers its XPA access point with
           the specified xpans name server. The default is true.  If set to false, the access
           point still is set up but it is not registered with xpans and therefore cannot be
           accessed by name. (It can be accessed by method, if the latter is known.) Note that an
           access point can be registered later on (using -remote or -proxy, for example). This
           variable mainly is useful in cases where the Internet configuration is broken (so that
           registration causes a DNS hang) but you still wish to and can use the server with a
           remote xpans (e.g., ds9's Virtual Observatory capability).

       •   XPA_NSUNIX

           For the local method of socket connection, this variable specifies the name of the
           Unix file that will be used to access the XPA Name Server (xpans). The default is
           xpans_unix. This variable is not usually needed. Note that is the local socket method
           is used, then remote machines will not be able to access the xpans name server or the
           registered XPA access points.

       •   XPA_NSUSERS

           This variable specifies whether other users' access points will be returned by the XPA
           Name Server (xpans) for use by xpaget, xpaset, etc.  Generally speaking, it is
           sufficient to run one xpans name server per machine and register the access points for
           all users with that xpans.  This means, for example, that if you request information
           from ds9 by running:

             xpaget ds9 colormap

           you might get information from your own ds9 as well as from another user running ds9
           on the same machine.  The XPA_NSUSERS variable controls whether you want such access
           to the access points of other users.  By default, only your own access points are
           returned, so that, in the example above, you would only get the colormap information
           from the ds9 you registered. If, however, you had set the value of the XPA_NSUSERS
           variable to eric,fred, then you would be able to communicate with both eric and fred's
           access points. Note that this variable can be overridden using the -u switch on the
           xpaget, xpaset, and xpainfo programs.

       •   XPA_PORT

           A semi-colon delimited list of user specified ports to use for specific XPA access
           points. The format is each specification is:

           class:template port1[ port2]

           where port1 is the main (command) port for the access point and port2 is the
           (secondary) data port. If port2 is not specified, it defaults to a value of 0 (meaning
           the system assigns the port).

           Specification of specific ports is useful, for example, when a machine outside a
           firewall needs to communicate with a machine inside a firewall. In such a case, the
           firewall should be configured to allow socket connections to both the command and data
           port from the outside machine, and the inside XPA program should be started up with
           the outside machine in its ACL list. Then, when the inside program is started with
           specified ports, outside XPA programs can use "machine:port" to contact the inside
           access points, instead of the access point names. That is, the machine outside the
           firewall does not need access to the XPA name server:

           export XPA_PORT="DS9:ds9 12345 12346"   # on machine "inside" cat foo.fits | xpaset
           inside:12345 fits # on machine "outside"

           Note that 2 ports are required for full XPA communication and therefore 2 ports should
           be specified to go through a firewall.  The second port assignment is not important if
           you simply are assigning the command port in order to communicate commands with a
           known port (e.g., to bypass the xpans name server). If only one (command) port is
           specified, the system will negotiate a random data port and everything will work
           properly.

           This support is somewhat experimental. If you run into problems, please let us know.

       •   XPA_PORTFILE

           A list of user-specified port to use for specific xpa access points.  The format of
           the file is:

           class:template port1 [port2]

           where port1 is the main port for the access point and port2 is the data port. If port2
           is not specified, it defaults to a value of 0 (meaning the system assigns the port).
           See XPA_PORT above for an explanation of user-specified ports.

       •   XPA_SHORT_TIMEOUT

           XPA is designed to allow data to be sent from one process to another over a long
           period of time (i.e., a program that generates image data sends that data to an image
           display, but slowly) but it also seeks to prevent hangs. This is done by supporting 2
           timeout periods: a short timeout for protocol communication and a long for data
           communication.

           The XPA_SHORT_TIMEOUT variable controls the short timeout and is used to prevent hangs
           in cases where the XPA protocol requires internal communication between the client and
           server that is controlled by the XPA interface itself. Authentication is an example of
           this sort of communication, as is the establishment of a data channel between the two
           processes.  The default value for the short is 30 seconds (which is a pretty long
           time, actually). Setting the value to -1 will disable short timeouts and allow an
           infinite amount of time.

       •   XPA_SIGUSR1

           If the value of this variable is true, then XPA will catch SIGUSR1 signals when
           performing an I/O operation in order to curtail that operation. This facility allows
           users to send a SIGUSR1 signal to an XPA server if a client is hanging up the server
           by sending or receiving data too slowly (timeouts also can be used -- see above). When
           enabled in this way, the SIGUSR1 signal is ignored at all other times, so that its
           safe to send the signal at any time.  If the variable is set to false, then SIGUSR1 is
           not used at all. Turning off SIGUSR1 would be desired in cases there the program uses
           SIGUSR1 for some other reason and does not want XPA interfering.  The default is to
           use the signal.

       •   XPA_TIMESTAMP_ERRORS

           If XPA_TIMESTAMP_ERRORS is true, then error messages will include a date/time string.
           This can be useful when XPA errors are being saved in an error log (e.g. Web/CGI use).
           The default is false.

       •   XPA_TMPDIR

           This variable specifies the directory into which XPA logs, Unix socket files (when
           XPA_METHOD is local), etc. are stored. The default is /tmp/.xpa.

       •   XPA_VERBOSITY

           Specify the verbosity level of error messages. If the value is set to 0, false, or
           off, then no error messages are printed to stderr.  If the value is 1, then important
           XPA error messages will be output.  If the value is set to 2, XPA warnings about out-
           of-sync messages will also be output.  These latter almost always can be ignored.

       •   XPA_VERSIONCHECK

           Specify whether a new access point should check its major and minor XPA version number
           against the version used by the xpans name server at registration time. The default is
           true. When checking is performed, a warning is issued if the server major version is
           found to be greater than the xpans version. Note that the check is performed both by
           the XPA server and by the xpans process and warnings will be issued by each.  Also,
           instead of the values of true or false, you can give this variable an integer value n.
           In this case, each version checking process (i.e., the XPA-enabled server or xpans)
           will print out a maximum of n warning messages (after which version warnings are
           silently swallowed).

           In general, it is a bad idea to run an XPA-enabled server program using a version of
           XPA newer than the basic xpaset, xpaget, xpaaccess, xpans programs. This sort of
           mismatch usually will not work due to protocol changes.

SEE ALSO

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