diff options
Diffstat (limited to 'xpa/doc/env.html')
| -rw-r--r-- | xpa/doc/env.html | 371 |
1 files changed, 0 insertions, 371 deletions
diff --git a/xpa/doc/env.html b/xpa/doc/env.html deleted file mode 100644 index 4a71e80..0000000 --- a/xpa/doc/env.html +++ /dev/null @@ -1,371 +0,0 @@ -<!-- =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> |