diff options
Diffstat (limited to 'xpa/man/mann/xpaenv.n')
| -rw-r--r-- | xpa/man/mann/xpaenv.n | 482 |
1 files changed, 0 insertions, 482 deletions
diff --git a/xpa/man/mann/xpaenv.n b/xpa/man/mann/xpaenv.n deleted file mode 100644 index ead081c..0000000 --- a/xpa/man/mann/xpaenv.n +++ /dev/null @@ -1,482 +0,0 @@ -.\" 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' |