diff options
Diffstat (limited to 'xpa/man/mann/xpaenv.n')
| -rw-r--r-- | xpa/man/mann/xpaenv.n | 482 |
1 files changed, 482 insertions, 0 deletions
diff --git a/xpa/man/mann/xpaenv.n b/xpa/man/mann/xpaenv.n new file mode 100644 index 0000000..ead081c --- /dev/null +++ b/xpa/man/mann/xpaenv.n @@ -0,0 +1,482 @@ +.\" Automatically generated by Pod::Man 2.22 (Pod::Simple 3.13) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" Set up some character translations and predefined strings. \*(-- will +.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left +.\" double quote, and \*(R" will give a right double quote. \*(C+ will +.\" give a nicer C++. Capital omega is used to do unbreakable dashes and +.\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, +.\" nothing in troff, for use with C<>. +.tr \(*W- +.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' +.ie n \{\ +. ds -- \(*W- +. ds PI pi +. if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch +. if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch +. ds L" "" +. ds R" "" +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds -- \|\(em\| +. ds PI \(*p +. ds L" `` +. ds R" '' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is turned on, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.ie \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. nr % 0 +. rr F +.\} +.el \{\ +. de IX +.. +.\} +.\" +.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2). +.\" Fear. Run. Save yourself. No user-serviceable parts. +. \" fudge factors for nroff and troff +.if n \{\ +. ds #H 0 +. ds #V .8m +. ds #F .3m +. ds #[ \f1 +. ds #] \fP +.\} +.if t \{\ +. ds #H ((1u-(\\\\n(.fu%2u))*.13m) +. ds #V .6m +. ds #F 0 +. ds #[ \& +. ds #] \& +.\} +. \" simple accents for nroff and troff +.if n \{\ +. ds ' \& +. ds ` \& +. ds ^ \& +. ds , \& +. ds ~ ~ +. ds / +.\} +.if t \{\ +. ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u" +. ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u' +. ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u' +. ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u' +. ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u' +. ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u' +.\} +. \" troff and (daisy-wheel) nroff accents +.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V' +.ds 8 \h'\*(#H'\(*b\h'-\*(#H' +.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#] +.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H' +.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u' +.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#] +.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#] +.ds ae a\h'-(\w'a'u*4/10)'e +.ds Ae A\h'-(\w'A'u*4/10)'E +. \" corrections for vroff +.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u' +.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u' +. \" for low resolution devices (crt and lpr) +.if \n(.H>23 .if \n(.V>19 \ +\{\ +. ds : e +. ds 8 ss +. ds o a +. ds d- d\h'-1'\(ga +. ds D- D\h'-1'\(hy +. ds th \o'bp' +. ds Th \o'LP' +. ds ae ae +. ds Ae AE +.\} +.rm #[ #] #H #V #F C +.\" ======================================================================== +.\" +.IX Title "xpaenv n" +.TH xpaenv n "July 23, 2013" "version 2.1.15" "SAORD Documentation" +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH "NAME" +\&\fBXPAEnv: Environment Variables for \s-1XPA\s0 Messaging\fR +.SH "SYNOPSIS" +.IX Header "SYNOPSIS" +Describes the environment variables which can be used to tailor the overall +\&\s-1XPA\s0 environment. +.SH "DESCRIPTION" +.IX Header "DESCRIPTION" +The following environment variables are supported by \s-1XPA:\s0 +.IP "\(bu" 4 +\&\fB\s-1XPA_ACL\s0\fR +.Sp +If \fI\s-1XPA_ACL\s0\fR is \fItrue\fR, then +host-based \s-1XPA\s0 Access Control +is turned on and only specified machines can access specified access +points. If \fIfalse\fR, then access control is turned off and any +machine can access point. The default is turn turn access control on. +.IP "\(bu" 4 +\&\fB\s-1XPA_ACLFILE\s0\fR +.Sp +If +\&\s-1XPA\s0 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: \fI\f(CI$HOME\fI/acls.xpa\fR. +.IP "\(bu" 4 +\&\fB\s-1XPA_CONNECT_TIMEOUT\s0\fR +.Sp +When an \s-1XPA\s0 server first starts up, it immediately tries to +connect to the \s-1XPA\s0 name server program (xpans) on the host specified by +the \fI\s-1XPA_NSINET\s0\fR 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 \fIconnect()\fR system call times out. Therefore, an alarm is started +to interrupt the \fIconnect()\fR 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 \fIconnect()\fR to time out, set the value of this variable to +0. Normally, users would not change this variable at all. +.IP "\(bu" 4 +\&\fB\s-1XPA_CLIENT_DOXPA\s0\fR +.Sp +Normally, an \s-1XPA\s0 client (xpaget, xpaset, etc.) will process incoming +\&\s-1XPA\s0 server requests while awaiting the completion of the client request. +Setting this variable to \*(L"false\*(R" will prevent \s-1XPA\s0 server requests from +being processed by the client. +.IP "\(bu" 4 +\&\fB\s-1XPA_DEFACL\s0\fR +.Sp +If +\&\s-1XPA\s0 Access Control +is turned on, this variable specifies the default access control +condition for all access points, if the \fI\s-1XPA_ACLFILE\s0\fR file does +not exist. The default acl is: \fI\f(CI$host:\fI* \f(CI$host\fI +\fR, meaning that +all processes on the host machine have full access to all access points. +.IP "\(bu" 4 +\&\fB\s-1XPA_HOST\s0\fR +.Sp +For the \s-1INET\s0 socket method, \s-1XPA\s0 utilizes the canonical hostname (as +returned by the \fIgethostname()\fR routine) to construct the \s-1IP\s0 part of the +method id. Under some circumstances, this might not be a correct choice +of name and \s-1IP\s0. For example, if an \s-1XPA\s0 server is started on a machine +running \s-1VPN\s0, you might want to use the \s-1VPN\s0 name and \s-1IP\s0 instead of the +canonical host name, so that other machines in the \s-1VPN\s0 network can +access the server. In this case, you can set the \s-1XPA_HOST\s0 to be +the \s-1VPN\s0 name (if resolvable) or, more easily, the \s-1VPN\s0 \s-1IP\s0. +.IP "\(bu" 4 +\&\fB\s-1XPA_IOCALLSXPA\s0\fR +.Sp +Setting this variable causes all \s-1XPA\s0 socket \s-1IO\s0 calls to process +outstanding \s-1XPA\s0 requests whenever the primary socket is not ready for +\&\s-1IO\s0. This means that a server making a client call will (recursively) +process incoming server requests while waiting for client completion. +This inter-IO \s-1XPA\s0 processing avoids a rare +\&\s-1XPA\s0 Race Condition: two or more +\&\s-1XPA\s0 servers sending messages to one another using an \s-1XPA\s0 client +routine such as \fIXPASet()\fR can deadlock while each waits for the other +server to respond. This can happen, for example, if the servers call +\&\fIXPAPoll()\fR with a time limit, and send messages in between the polling call. +.Sp +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 \s-1XPA\s0 requests within socket \s-1IO\s0 +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. +.IP "\(bu" 4 +\&\fB\s-1XPA_LOGNAME\s0\fR +.Sp +\&\s-1XPA\s0 preferentially uses the de facto standard environment variable +\&\s-1LOGNAME\s0 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 \s-1XPA_LOGNAME\s0 +variable to set the user name. (If neither exists, then getpwuid(\fIgeteuid()\fR) +is used as a last resort). +.IP "\(bu" 4 +\&\fB\s-1XPA_LONG_TIMEOUT\s0\fR +.Sp +\&\s-1XPA\s0 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 \fIshort\fR timeout for protocol communication +and a \fIlong\fR for data communication. +.Sp +The \fI\s-1XPA_LONG_TIMEOUT\s0\fR variable controls the \fIlong\fR +timeout and is used to prevent hangs in cases where communication +between the client and server that is \fInot\fR controlled by the +\&\s-1XPA\s0 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 \fIlong\fR timeout is set to 180 seconds. +Setting the value to \-1 will disable \fIlong\fR timeouts and allow +an infinite amount of time. +.IP "\(bu" 4 +\&\fB\s-1XPA_MAXHOSTS\s0\fR +.Sp +The maximum number of access points that the programs +\&\fIxpaset\fR, \fIxpaget\fR, and \fIxpainfo\fR will +communicate with at one time. The default is 64, meaning, for +example, that the \fIxpaset\fR program will not send a message +to more than 100 access points at one time and \fIxpaget\fR will +not retrieve from more than 100 access points at one time. +.IP "\(bu" 4 +\&\fB\s-1XPA_METHOD\s0\fR +.Sp +Determines the socket connection method used by this session of \s-1XPA\s0. +The choices are: \fIinet\fR (to use \s-1INET\s0 or Internet-based +sockets), \fIlocalhost\fR (to use the machines localhost inet +socket), or \fIlocal (unix)\fR (to use \s-1UNIX\s0 sockets). The default +is \fI\s-1INET\s0\fR. Using the \fIinet\fR method will allow access +from other machines (subject to access controls) but using +\&\fIlocalhost\fR or \fIlocal\fR 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). +.Sp +Once defined, the first registration of an \s-1XPA\s0 access point will +ensure that an instance of the +\&\s-1XPA\s0 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. +.IP "\(bu" 4 +\&\fB\s-1XPA_NSINET\s0\fR +.Sp +For the \fIinet\fR method of socket connection, this variable +specifies the host and port on which the +\&\s-1XPA\s0 Name Server (xpans) +is listens for new access points. The default is \fI\f(CI$host:\fI$port\fR, +meaning that the default \s-1XPA\s0 port (14285) on the current machine +(as returned by \fIgethostname()\fR) is used. If several machines were all +accessing the same \s-1XPA\s0 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 \fImyhost:$port\fR would +mean that the xpans name server is running on myhost and uses the +default port 12345. All machines would then get the \s-1XPA\s0 access points +registered with that name server, subject to access controls. +.Sp +The port used by xpans to register its \s-1XPA\s0 access point normally is +taken to be one greater than the port on which it receives new access +points from \s-1XPA\s0 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, \f(CW$host:12345\fR,23456 will listen +for new access ports on 12345 and will accept \s-1XPA\s0 commands on 23456. +.IP "\(bu" 4 +\&\fB\s-1XPA_NSREGISTER\s0\fR +.Sp +This boolean variable specifies whether a server registers its \s-1XPA\s0 +access point with the specified xpans name server. The default is +\&\fItrue\fR. If set to \fIfalse\fR, 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 \s-1DNS\s0 hang) but you still wish to and can use the server with a +remote xpans (e.g., ds9's Virtual Observatory capability). +.IP "\(bu" 4 +\&\fB\s-1XPA_NSUNIX\s0\fR +.Sp +For the \fIlocal\fR method of socket connection, this variable +specifies the name of the Unix file that will be used to access the +\&\s-1XPA\s0 Name Server (xpans). The default is +\&\fIxpans_unix\fR. This variable is not usually needed. Note that +is the \fIlocal\fR socket method is used, then remote machines will +not be able to access the xpans name server or the registered \s-1XPA\s0 access +points. +.IP "\(bu" 4 +\&\fB\s-1XPA_NSUSERS\s0\fR +.Sp +This variable specifies whether other users' access points will be +returned by the +\&\s-1XPA\s0 Name Server (xpans) for use by +\&\fIxpaget\fR, \fIxpaset\fR, 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: +.Sp +.Vb 1 +\& xpaget ds9 colormap +.Ve +.Sp +you might get information from your own ds9 as well as +from another user running ds9 on the same machine. The +\&\fI\s-1XPA_NSUSERS\s0\fR 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 +\&\fI\s-1XPA_NSUSERS\s0\fR variable to \fIeric,fred\fR, then you would be +able to communicate with both eric and fred's access points. Note that +this variable can be overridden using the \fI\-u\fR switch on the +\&\fIxpaget\fR, \fIxpaset\fR, and \fIxpainfo\fR programs. +.IP "\(bu" 4 +\&\fB\s-1XPA_PORT\s0\fR +.Sp +A semi-colon delimited list of user specified ports to use for specific +\&\s-1XPA\s0 access points. The format is each specification is: +.Sp +class:template port1[ port2] +.Sp +where \fBport1\fR is the main (command) port for the access point and +\&\fBport2\fR is the (secondary) data port. If port2 is not specified, +it defaults to a value of 0 (meaning the system assigns the port). +.Sp +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 \s-1XPA\s0 program should be started up with the +outside machine in its \s-1ACL\s0 list. Then, when the inside program is +started with specified ports, outside \s-1XPA\s0 programs can use +\&\*(L"machine:port\*(R" 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 \s-1XPA\s0 name server: +.Sp +export XPA_PORT=\*(L"DS9:ds9 12345 12346\*(R" # on machine \*(L"inside\*(R" +cat foo.fits | xpaset inside:12345 fits # on machine \*(L"outside\*(R" +.Sp +Note that 2 ports are required for full \s-1XPA\s0 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. +.Sp +This support is somewhat experimental. If you run into problems, please +let us know. +.IP "\(bu" 4 +\&\fB\s-1XPA_PORTFILE\s0\fR +.Sp +A list of user-specified port to use for specific xpa access points. +The format of the file is: +.Sp +class:template port1 [port2] +.Sp +where \fBport1\fR is the main port for the access point and +\&\fBport2\fR is the data port. If port2 is not specified, it defaults +to a value of 0 (meaning the system assigns the port). See +\&\fB\s-1XPA_PORT\s0\fR above for an explanation of user-specified ports. +.IP "\(bu" 4 +\&\fB\s-1XPA_SHORT_TIMEOUT\s0\fR +.Sp +\&\s-1XPA\s0 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 \fIshort\fR timeout for protocol communication +and a \fIlong\fR for data communication. +.Sp +The \fI\s-1XPA_SHORT_TIMEOUT\s0\fR variable +controls the \fIshort\fR timeout and is used to prevent hangs +in cases where the \s-1XPA\s0 protocol requires internal communication between +the client and server that is controlled by the \s-1XPA\s0 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 \fIshort\fR is 30 seconds (which is +a pretty long time, actually). Setting the value to \-1 will disable +\&\fIshort\fR timeouts and allow an infinite amount of time. +.IP "\(bu" 4 +\&\fB\s-1XPA_SIGUSR1\s0\fR +.Sp +If the value of this variable is \fItrue\fR, then \s-1XPA\s0 will +catch \s-1SIGUSR1\s0 signals when performing an I/O operation in order to +curtail that operation. This facility allows users to send a \s-1SIGUSR1\s0 +signal to an \s-1XPA\s0 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 \s-1SIGUSR1\s0 signal is ignored at all other +times, so that its safe to send the signal at any time. If the +variable is set to \fIfalse\fR, then \s-1SIGUSR1\s0 is not used at +all. Turning off \s-1SIGUSR1\s0 would be desired in cases there the program +uses \s-1SIGUSR1\s0 for some other reason and does not want \s-1XPA\s0 interfering. +The default is to use the signal. +.IP "\(bu" 4 +\&\fB\s-1XPA_TIMESTAMP_ERRORS\s0\fR +.Sp +If \fI\s-1XPA_TIMESTAMP_ERRORS\s0\fR is \fItrue\fR, then error +messages will include a date/time string. This can be useful when +\&\s-1XPA\s0 errors are being saved in an error log (e.g. Web/CGI use). The +default is false. +.IP "\(bu" 4 +\&\fB\s-1XPA_TMPDIR\s0\fR +.Sp +This variable specifies the directory into which \s-1XPA\s0 logs, Unix +socket files (when \fI\s-1XPA_METHOD\s0\fR is \fIlocal\fR), etc. are +stored. The default is \fI/tmp/.xpa\fR. +.IP "\(bu" 4 +\&\fB\s-1XPA_VERBOSITY\s0\fR +.Sp +Specify the verbosity level of error messages. If the value is +set to \fI0\fR, \fIfalse\fR, or \fIoff\fR, then no error +messages are printed to stderr. If the value is \fI1\fR, then +important \s-1XPA\s0 error messages will be output. If the value is +set to \fI2\fR, \s-1XPA\s0 warnings about out-of-sync messages will also +be output. These latter almost always can be ignored. +.IP "\(bu" 4 +\&\fB\s-1XPA_VERSIONCHECK\s0\fR +.Sp +Specify whether a new access point should check its major and minor \s-1XPA\s0 +version number against the version used by the xpans name server at +registration time. The default is \fItrue\fR. 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 \s-1XPA\s0 server and by the xpans process and warnings will be +issued by each. Also, instead of the values of \fItrue\fR or +\&\fIfalse\fR, 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). +.Sp +In general, it is a bad idea to run an XPA-enabled server program +using a version of \s-1XPA\s0 newer than the basic xpaset, xpaget, xpaaccess, +xpans programs. This sort of mismatch usually will not work due to +protocol changes. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +See xpa(n) for a list of \s-1XPA\s0 help pages +.SH "POD ERRORS" +.IX Header "POD ERRORS" +Hey! \fBThe above document had some coding errors, which are explained below:\fR +.IP "Around line 458:" 4 +.IX Item "Around line 458:" +\&'=item' outside of any '=over' +.IP "Around line 509:" 4 +.IX Item "Around line 509:" +You forgot a '=back' before '=head1' |