NAME

       xpans -  the XPA Name Server

SYNOPSIS

         xpans [\-h] [\-e] [\-k sec] [\-p port] [\-l log] [\-s security log] [\-P n]

OPTIONS

         \-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

DESCRIPTION

       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.

       The xpans 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.

       The socket connection between an XPA-enabled program and xpans 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 \-k [sec] 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.)  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!

       The xpans 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 \-e 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 \-e switch.

       The name server will keep a log of registered access points if the \-l [log] 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:

         add 838e2f67:1863 ds9 ds9 gs eric

       If xpans is terminated but ds9 still is running, you can re-register both access points
       for the ds9 process by running:

         xpaset \-p 838e2f67:1863 \-nsconnect

       Notice that the ip:port specifier is used with xpaset to bypass the need for contacting
       the name server (which does not have the name registered yet!)

       The name server will keep a log of security information if the \-s [security log] switch
       is used on the command line. For each accepted connection, (including connections via the
       xpaget command), information will be logged about the host issuing the command and the
       parameters passed into the program. This is most useful when xpans is accepting
       connections from untrusted machines.

       When an XPA access point is removed by a server using XPAFree(), 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.

       The name server itself has an XPA access point names xpans registered through which you
       can find out information about currently registered access points (assuming you have
       access to the name server; see XPA Access Control for more information).  For each
       registered access point, the following information is returned:

         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

       For example, to display all currently registered access points, simply execute:

         xpaget xpans

       Continuing the example of ds9 above, this will return:

         DS9 ds9 gs 838e2f67:1863 eric

       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:

         ds9 &
         ds9 \-title ds9\-1\-eric &
         ds9 \-title ds9\-2\-eric &

       To lookup all ds9 access points which end in ".eric" and which can be accessed using
       xpaset, use:

         xpaget xpans "DS9:*.eric" "s" "*"

       This will return:

         DS9 ds9\-2\-eric gs 838e29d3:42102 eric
         DS9 ds9\-1\-eric gs 838e29d3:42105 eric

       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.

       The name server uses the XPA_METHOD 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
       XPA_NSINET environment variable is set to point to the local machine.  See XPA Environment
       Variables for more information.

       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:

         xpaset \-p foo \-remote 'host2:28571' + \-proxy   # on host1

       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.

       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.

       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.

SEE ALSO

       See xpa(7) for a list of XPA help pages