1 files changed, 371 insertions, 0 deletions
diff --git a/xpa/doc/env.html b/xpa/doc/env.html
new file mode 100644
index 0000000..4a71e80
--- /dev/null
+++ b/xpa/doc/env.html
@@ -0,0 +1,371 @@
+<!-- =defdoc xpaenv xpaenv n -->
+<HTML>
+<HEAD>
+<TITLE>The XPA Environment</TITLE>
+</HEAD>
+<BODY>
+
+<!-- =section xpaenv NAME -->
+<H2><A NAME="xpaenvl">XPAEnv: Environment Variables for XPA Messaging</A></H2>
+
+<!-- =section xpaenv SYNOPSIS -->
+<H2>Summary</H2>
+Describes the environment variables which can be used to tailor the overall
+XPA environment.
+
+<!-- =section xpaenv DESCRIPTION -->
+<H2>Description</H2>
+<P>
+The following environment variables are supported by XPA:
+<DL>
+<P>
+<DT><B>XPA_ACL</B>
+<DD> If <EM>XPA_ACL</EM> is <EM>true</EM>, then 
+host-based <A HREF="./acl.html">XPA Access Control</A>
+is turned on and only specified machines can access specified access
+points.  If <EM>false</EM>, then access control is turned off and any
+machine can access point. The default is turn turn access control on.
+
+<P>
+<DT><B>XPA_ACLFILE</B>
+<DD> If
+<A HREF="./acl.html">XPA Access Control</A>
+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: <EM>$HOME/acls.xpa</EM>.
+
+<P>
+<DT><B>XPA_CONNECT_TIMEOUT</B>
+<DD> 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 <em>XPA_NSINET</em> 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.
+
+<P>
+<DT><B>XPA_CLIENT_DOXPA</B>
+<DD> 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.
+
+<P>
+<DT><B>XPA_DEFACL</B>
+<DD> If
+<A HREF="./acl.html">XPA Access Control</A>
+is turned on, this variable specifies the default access control
+condition for all access points, if the <EM>XPA_ACLFILE</EM> file does
+not exist.  The default acl is: <EM>$host:* $host +</EM>, meaning that
+all processes on the host machine have full access to all access points.
+
+<P>
+<DT><B>XPA_HOST</B>
+<DD>
+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.
+
+<P>
+<DT><B>XPA_IOCALLSXPA</B>
+<DD> 
+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
+<A HREF="./server.html#race">XPA Race Condition</A>: 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.
+
+<P>
+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.
+
+<P>
+<DT><B>XPA_LOGNAME</B>
+<DD>
+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).
+
+<P>
+<DT><B>XPA_LONG_TIMEOUT</B>
+<DD> 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 <EM>short</EM> timeout for protocol communication
+and a <EM>long</EM> for data communication.
+<P>
+The <EM>XPA_LONG_TIMEOUT</EM> variable controls the <EM>long</EM>
+timeout and is used to prevent hangs in cases where communication
+between the client and server that is <EM>not</EM> 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 <EM>long</EM> timeout is set to 180 seconds.
+Setting the value to -1 will disable <EM>long</EM> timeouts and allow
+an infinite amount of time.
+
+<P>
+<DT><B>XPA_MAXHOSTS</B>
+<DD> The maximum number of access points that the programs 
+<EM>xpaset</EM>, <EM>xpaget</EM>, and <EM>xpainfo</EM> will
+communicate with at one time. The default is 64, meaning, for
+example, that the <EM>xpaset</EM> program will not send a message
+to more than 100 access points at one time and <EM>xpaget</EM> will
+not retrieve from more than 100 access points at one time.
+
+<P>
+<DT><B>XPA_METHOD</B>
+<DD>
+Determines the socket connection method used by this session of XPA.
+The choices are: <EM>inet</EM> (to use INET or Internet-based
+sockets), <EM>localhost</EM> (to use the machines localhost inet
+socket), or <EM>local (unix)</EM> (to use UNIX sockets). The default
+is <EM>INET</EM>.  Using the <EM>inet</EM> method will allow access
+from other machines (subject to access controls) but using
+<EM>localhost</EM> or <EM>local</EM> 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).
+<P>
+Once defined, the first registration of an XPA access point will
+ensure that an instance of the
+<A HREF="./xpans.html">XPA Name Server (xpans)</A>
+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.
+
+<P>
+<DT><B>XPA_NSINET</B>
+<DD> For the <EM>inet</EM> method of socket connection, this variable
+specifies the host and port on which the 
+<A HREF="./xpans.html">XPA Name Server (xpans)</A>
+is listens for new access points. The default is <EM>$host:$port</EM>,
+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 <EM>myhost:$port</EM> 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.
+<P>
+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.
+
+<P>
+<DT><B>XPA_NSREGISTER</B>
+<DD>
+This boolean variable specifies whether a server registers its XPA
+access point with the specified xpans name server. The default is
+<em>true</em>.  If set to <em>false</em>, 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).
+
+<P>
+<DT><B>XPA_NSUNIX</B>
+<DD> For the <EM>local</EM> method of socket connection, this variable
+specifies the name of the Unix file that will be used to access the
+<A HREF="./xpans.html">XPA Name Server (xpans)</A>. The default is
+<EM>xpans_unix</EM>. This variable is not usually needed. Note that
+is the <EM>local</EM> socket method is used, then remote machines will
+not be able to access the xpans name server or the registered XPA access
+points.
+
+<P>
+<DT><B>XPA_NSUSERS</B>
+<DD>
+This variable specifies whether other users' access points will be
+returned by the
+<A HREF="./xpans.html">XPA Name Server (xpans)</A> for use by
+<EM>xpaget</EM>, <EM>xpaset</EM>, 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:
+<PRE>
+  xpaget ds9 colormap
+</PRE>
+you might get information from your own ds9 as well as
+from another user running ds9 on the same machine.  The
+<EM>XPA_NSUSERS</EM> 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
+<EM>XPA_NSUSERS</EM> variable to <EM>eric,fred</EM>, then you would be
+able to communicate with both eric and fred's access points. Note that
+this variable can be overridden using the <EM>-u</EM> switch on the
+<EM>xpaget</EM>, <EM>xpaset</EM>, and <EM>xpainfo</EM> programs.
+
+<P>
+<DT><B>XPA_PORT</B>
+<DD> 
+A semi-colon delimited list of user specified ports to use for specific
+XPA access points. The format is each specification is:
+<PRE>
+class:template port1[ port2]
+</PRE>
+where <B>port1</B> is the main (command) port for the access point and
+<B>port2</B> is the (secondary) data port. If port2 is not specified,
+it defaults to a value of 0 (meaning the system assigns the port).
+
+<P>
+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:
+<PRE>
+export XPA_PORT="DS9:ds9 12345 12346"   # on machine "inside"
+cat foo.fits | xpaset inside:12345 fits # on machine "outside"
+</PRE>
+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.
+
+<P>
+This support is somewhat experimental. If you run into problems, please
+let us know.
+
+<P>
+<DT><B>XPA_PORTFILE</B>
+<DD> 
+A list of user-specified port to use for specific xpa access points.
+The format of the file is:
+<PRE>
+class:template port1 [port2]
+</PRE>
+where <B>port1</B> is the main port for the access point and
+<B>port2</B> is the data port. If port2 is not specified, it defaults
+to a value of 0 (meaning the system assigns the port).  See
+<B>XPA_PORT</B> above for an explanation of user-specified ports.
+
+<P>
+<DT><B>XPA_SHORT_TIMEOUT</B>
+<DD> 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 <EM>short</EM> timeout for protocol communication
+and a <EM>long</EM> for data communication.
+<P>
+The <EM>XPA_SHORT_TIMEOUT</EM> variable
+controls the <EM>short</EM> 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 <EM>short</EM> is 30 seconds (which is
+a pretty long time, actually). Setting the value to -1 will disable
+<EM>short</EM> timeouts and allow an infinite amount of time.
+
+<P>
+<DT><B>XPA_SIGUSR1</B>
+<DD> If the value of this variable is <EM>true</EM>, 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 <EM>false</EM>, 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.
+
+<P>
+<DT><B>XPA_TIMESTAMP_ERRORS</B>
+<DD> If <EM>XPA_TIMESTAMP_ERRORS</EM> is <EM>true</EM>, 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.
+</DL>
+
+<P>
+<DT><B>XPA_TMPDIR</B>
+<DD> This variable specifies the directory into which XPA logs, Unix
+socket files (when <EM>XPA_METHOD</EM> is <EM>local</EM>), etc. are
+stored. The default is <EM>/tmp/.xpa</EM>.
+
+<P>
+<DT><B>XPA_VERBOSITY</B>
+<DD> Specify the verbosity level of error messages. If the value is
+set to <EM>0</EM>, <EM>false</EM>, or <EM>off</EM>, then no error
+messages are printed to stderr.  If the value is <EM>1</EM>, then
+important XPA error messages will be output.  If the value is
+set to <EM>2</EM>, XPA warnings about out-of-sync messages will also
+be output.  These latter almost always can be ignored.
+
+<P>
+<DT><B>XPA_VERSIONCHECK</B>
+<DD> 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 <EM>true</EM>. 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 <EM>true</EM> or
+<em>false</em>, 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).
+<P>
+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.
+
+<!-- =section xpaenv SEE ALSO -->
+<!-- =text See xpa(n) for a list of XPA help pages -->
+<!-- =stop -->
+
+<P>
+<A HREF="./help.html">Go to XPA Help Index</A>
+
+<H5>Last updated: December 23, 2009</H5>
+
+</BODY>
+</HTML>