diff options
Diffstat (limited to 'xpa/doc/xpans.html')
| -rw-r--r-- | xpa/doc/xpans.html | 212 |
1 files changed, 212 insertions, 0 deletions
diff --git a/xpa/doc/xpans.html b/xpa/doc/xpans.html new file mode 100644 index 0000000..a0aebb2 --- /dev/null +++ b/xpa/doc/xpans.html @@ -0,0 +1,212 @@ +<!-- =defdoc xpans xpans 1 --> +<HTML> +<HEAD> +<TITLE>The XPA Name Server (xpans)</TITLE> +</HEAD> +<BODY> + +<!-- =section xpans NAME --> +<H2><A NAME="xpans">xpans: the XPA Name Server</A></H2> + +<!-- =section xpans SYNOPSIS --> +<H2>Summary</H2> +<PRE> + xpans [-h] [-e] [-k sec] [-p port] [-l log] [-s security log] [-P n] +</PRE> + +<!-- =section xpans OPTIONS --> +<P> +<PRE> + -h print help message + -e exit when there are no more XPA connections + -k send keepalive messages every n sec + -l log data base entries to specified file + -p listen for connections on specified port + -s log security info for each connection to specified file + -P accept proxy requests (P=1) using separate thread (P=2) + --version display version and exit +</PRE> + +<!-- =section xpans DESCRIPTION --> +<P> +The xpans name server is an XPA-enabled program that is used to +manage the names and ports of XPA access points. It is started +automatically when an XPA access point is registered. You can access +the name server using xpaget to get a list of registered access points. +<P> +The <EM>xpans</EM> name server provides a crucial link between XPA +clients and servers. When an XPA server defines an access point using +XPANew(), XPACmdNew(), or XPAInfoNew(), the name of the access point +is registered in the name service, along with connection information. +The name server then matches class:name templates passed to it by XPA +clients with these registered entries, so that the clients can +communicate with the appropriate servers. + +<P> +The socket connection between an XPA-enabled program and +<EM>xpans</EM> is kept open until the former exits (or explicitly +closes the connection). Apparently, some Internet equipment (e.g. DSL +modems) can cause such a connection to time-out after a period of +inactivity. To prevent this from happening, you can use the <EM>-k +[sec]</EM> switch to send a short keep-alive message to each open +connection after the specified time delay. (Note that this +application level use of keep-alive is necessary only if you are +serving XPA-enabled clients over the Internet and have to deal with +long-term connections involving DSL or similar equipment. XPA uses +the ordinary socket-level keep-alive, which works for all other cases.) +<B>NB (12/2/2009): Out-of-band (URG) TCP data, used by xpans +keep-alive, is changed by some Cisco routers into in-band data. +Encountering such a router will break the keep-alive function and may +break your XPA server as well. Proceed with caution!</B> + +<P> +The <EM>xpans</EM> program will be started automatically (assuming it +can be found in the user's path) when the first XPA access point is +registered. It therefore need not be started explicitly. However, +when started automatically, the <EM>-e</EM> switch is used, so that +the name server will exit when there are no more XPA access points +registered. If you wish to keep the name server running continually, +simply start it manually without the <EM>-e</EM> switch. + +<P> +The name server will keep a log of registered access points if the +<EM>-l [log]</EM> switch is used on the command line (this is the +case for automatic start-up). The log contains enough name and connection +information to allow you to re-register all XPA access points in case +the name server process is terminated prematurely. For example, after +the ds9 access point is registered,the log will contain the entry: +<PRE> + add 838e2f67:1863 ds9 ds9 gs eric +</PRE> +If <EM>xpans</EM> is terminated but ds9 still is running, you +can re-register both access points for the ds9 process by running: +<PRE> + xpaset -p 838e2f67:1863 -nsconnect +</PRE> +Notice that the ip:port specifier is used with <EM>xpaset</EM> to bypass +the need for contacting the name server (which does not have the name +registered yet!) + +<P> +The name server will keep a log of security information if the <EM>-s +[security log]</EM> switch is used on the command line. For each +accepted connection, (including connections via the <EM>xpaget</EM> +command), information will be logged about the host issuing the +command and the parameters passed into the program. This is most +useful when <EM>xpans</EM> is accepting connections from untrusted +machines. + +<P> +When an XPA access point is removed by a server using <EM>XPAFree()</EM>, +the access information is removed from the name server. If an +XPA-enabled process is terminated, all names registered by that process +will be removed automatically. The log file is always updated to +reflect the currently registered access points. + +<P> +The name server itself has an XPA access point names <EM>xpans</EM> +registered through which you can find out information about currently +registered access points (assuming you have access to the name server; +see <A HREF="./acl.html">XPA Access Control</A> for more information). +For each registered access point, the following information is returned: +<PRE> + class # class of the access point + name # name of the access point + access # allowed access (g=xpaget,s=xpaset,i=xpainfo) + id # socket access method (host:port for inet, file for local/unix) + user # user name of access point owner +</PRE> + +<P> +For example, to display all currently registered access points, simply execute: +<PRE> + xpaget xpans +</PRE> +Continuing the example of ds9 above, this will return: +<PRE> + DS9 ds9 gs 838e2f67:1863 eric +</PRE> +If the same program has been started with different XPA access names, +you can look up only names matching a specified template. For example, +assume that ds9 has been started up using: +<PRE> + ds9 & + ds9 -title ds9-1-eric & + ds9 -title ds9-2-eric & +</PRE> +To lookup all ds9 access points which end in ".eric" and which can +be accessed using <EM>xpaset</EM>, use: +<PRE> + xpaget xpans "DS9:*.eric" "s" "*" +</PRE> +This will return: +<PRE> + DS9 ds9-2-eric gs 838e29d3:42102 eric + DS9 ds9-1-eric gs 838e29d3:42105 eric +</PRE> +The third argument "*" requests all access points from all users. +You also can specify a specific user name and only access points +registered by that user will be returned. + +<P> +The name server uses the <EM>XPA_METHOD</EM> environment variable +to determine whether it should listen for requests on INET or LOCAL +sockets. Since XPA access points also use this environment variable, +the choice of socket method will be consistent. Note that, when INET +sockets are used, a local server can be accessed from remote machines +if the <EM>XPA_NSINET</EM> environment variable is set to point to +the local machine. See +<A HREF="./env.html">XPA Environment Variables</A> +for more information. + +<P> +An experimental feature of xpans is its ability to act as a proxy to +XPA servers behind firewalls that want to communicate with external +processes. The basic idea is the following: an XPA server (call it +"foo") on host1, possibly behind a firewall, makes a remote connection +to a proxy-enabled xpans program on host2 (specifying host2's XPA method). +For example: +<PRE> + xpaset -p foo -remote 'host2:28571' + -proxy # on host1 +</PRE> +When this is done, host2 can use xpaset, xpaget, and xpainfo calls to +communicate with the XPA server foo. All command communication is +performed via the xpans socket connection between foo on host1 and +xpans on host2 (which was initiated by foo from inside the firewall). +Data communication is similarly performed using a socket connection +initiated on host1 (usually with a port value two greater than the +port value of the main xpans socket connection). An xpaset or xpaget +call on host2 contacts xpans, which performs an XPASet() or XPAGet() +call to foo, passing commands and data back and forth between the two +programs. + +<P> +By default, proxy connections are not allowed by xpans. If the -P switch is +specified with a value of 1, proxy connection are allowed, but all proxy +communication is performed in the same thread as xpans processing. If +a value of 2 is specified, the proxy processing is performed in a +separate thread (assuming pthreads are supported on your system). +Because xpa callback processing of any type can take a long time and +therefore can interfere with normal xpans processing, threaded proxy +connections (-P 2) are recommended. When using proxy connections, it +might also be useful to set the XPA_IOCALLSXPA environment variable, so +that multiple proxy requests can be handled at the same time, instead of +serially. + +<P> +Note that this proxy interface to xpans is experimental. It is used +to provide remote data analysis capabilities on the Chandra-Ed system +using ds9. (See http://chandra-ed.cfa.harvard.edu and +http://hea-www.harvard.edu/saord/ds9 for more details). As always, please +contact us if you have problems or questions. + +<!-- =section xpans 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: January 24, 2005</H5> +</BODY> +</HTML> |