1xpans(1)                      SAORD Documentation                     xpans(1)
2
3
4

NAME

6       xpans: the XPA Name Server
7

SYNOPSIS

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

OPTIONS

12         -h            print help message
13         -e            exit when there are no more XPA connections
14         -k            send keepalive messages every n sec
15         -l            log data base entries to specified file
16         -p            listen for connections on specified port
17         -s            log security info for each connection to specified file
18         -P            accept proxy requests (P=1) using separate thread (P=2)
19         --version     display version and exit
20

DESCRIPTION

22       The xpans name server is an XPA-enabled program that is used to manage
23       the names and ports of XPA access points. It is started automatically
24       when an XPA access point is registered. You can access the name server
25       using xpaget to get a list of registered access points.
26
27       The xpans name server provides a crucial link between XPA clients and
28       servers.  When an XPA server defines an access point using XPANew(),
29       XPACmdNew(), or XPAInfoNew(), the name of the access point is regis‐
30       tered in the name service, along with connection information.  The name
31       server then matches class:name templates passed to it by XPA clients
32       with these registered entries, so that the clients can communicate with
33       the appropriate servers.
34
35       The socket connection between an XPA-enabled program and xpans is kept
36       open until the former exits (or explicitly closes the connection).
37       Apparently, some Internet equipment (e.g. DSL modems) can cause such a
38       connection to time-out after a period of inactivity. To prevent this
39       from happening, you can use the -k [sec] switch to send a short keep-
40       alive message to each open connection after the specified time delay.
41       (Note that this application level use of keep-alive is necessary only
42       if you are serving XPA-enabled clients over the Internet and have to
43       deal with long-term connections involving DSL or similar equipment.
44       XPA uses the ordinary socket-level keep-alive, which works for all
45       other cases.)  NB (12/2/2009): Out-of-band (URG) TCP data, used by
46       xpans keep-alive, is changed by some Cisco routers into in-band data.
47       Encountering such a router will break the keep-alive function and may
48       break your XPA server as well. Proceed with caution!
49
50       The xpans program will be started automatically (assuming it can be
51       found in the user's path) when the first XPA access point is regis‐
52       tered.  It therefore need not be started explicitly.  However, when
53       started automatically, the -e switch is used, so that the name server
54       will exit when there are no more XPA access points registered. If you
55       wish to keep the name server running continually, simply start it manu‐
56       ally without the -e switch.
57
58       The name server will keep a log of registered access points if the -l
59       [log] switch is used on the command line (this is the case for auto‐
60       matic start-up).  The log contains enough name and connection informa‐
61       tion to allow you to re-register all XPA access points in case the name
62       server process is terminated prematurely. For example, after the ds9
63       access point is registered,the log will contain the entry:
64
65         add 838e2f67:1863 ds9 ds9 gs eric
66
67       If xpans is terminated but ds9 still is running, you can re-register
68       both access points for the ds9 process by running:
69
70         xpaset -p 838e2f67:1863 -nsconnect
71
72       Notice that the ip:port specifier is used with xpaset to bypass the
73       need for contacting the name server (which does not have the name reg‐
74       istered yet!)
75
76       The name server will keep a log of security information if the -s
77       [security log] switch is used on the command line. For each accepted
78       connection, (including connections via the xpaget command), information
79       will be logged about the host issuing the command and the parameters
80       passed into the program. This is most useful when xpans is accepting
81       connections from untrusted machines.
82
83       When an XPA access point is removed by a server using XPAFree(), the
84       access information is removed from the name server.  If an XPA-enabled
85       process is terminated, all names registered by that process will be
86       removed automatically.  The log file is always updated to reflect the
87       currently registered access points.
88
89       The name server itself has an XPA access point names xpans registered
90       through which you can find out information about currently registered
91       access points (assuming you have access to the name server; see XPA
92       Access Control for more information).  For each registered access
93       point, the following information is returned:
94
95         class         # class of the access point
96         name          # name of the access point
97         access        # allowed access (g=xpaget,s=xpaset,i=xpainfo)
98         id            # socket access method (host:port for inet, file for local/unix)
99         user          # user name of access point owner
100
101       For example, to display all currently registered access points, simply
102       execute:
103
104         xpaget xpans
105
106       Continuing the example of ds9 above, this will return:
107
108         DS9 ds9 gs 838e2f67:1863 eric
109
110       If the same program has been started with different XPA access names,
111       you can look up only names matching a specified template. For example,
112       assume that ds9 has been started up using:
113
114         ds9 &
115         ds9 -title ds9-1-eric &
116         ds9 -title ds9-2-eric &
117
118       To lookup all ds9 access points which end in ".eric" and which can be
119       accessed using xpaset, use:
120
121         xpaget xpans "DS9:*.eric" "s" "*"
122
123       This will return:
124
125         DS9 ds9-2-eric gs 838e29d3:42102 eric
126         DS9 ds9-1-eric gs 838e29d3:42105 eric
127
128       The third argument "*" requests all access points from all users.  You
129       also can specify a specific user name and only access points registered
130       by that user will be returned.
131
132       The name server uses the XPA_METHOD environment variable to determine
133       whether it should listen for requests on INET or LOCAL sockets.  Since
134       XPA access points also use this environment variable, the choice of
135       socket method will be consistent.  Note that, when INET sockets are
136       used, a local server can be accessed from remote machines if the
137       XPA_NSINET environment variable is set to point to the local machine.
138       See XPA Environment Variables for more information.
139
140       An experimental feature of xpans is its ability to act as a proxy to
141       XPA servers behind firewalls that want to communicate with external
142       processes.  The basic idea is the following: an XPA server (call it
143       "foo") on host1, possibly behind a firewall, makes a remote connection
144       to a proxy-enabled xpans program on host2 (specifying host2's XPA
145       method).  For example:
146
147         xpaset -p foo -remote 'host2:28571' + -proxy   # on host1
148
149       When this is done, host2 can use xpaset, xpaget, and xpainfo calls to
150       communicate with the XPA server foo. All command communication is per‐
151       formed via the xpans socket connection between foo on host1 and xpans
152       on host2 (which was initiated by foo from inside the firewall).  Data
153       communication is similarly performed using a socket connection initi‐
154       ated on host1 (usually with a port value two greater than the port
155       value of the main xpans socket connection). An xpaset or xpaget call on
156       host2 contacts xpans, which performs an XPASet() or XPAGet() call to
157       foo, passing commands and data back and forth between the two programs.
158
159       By default, proxy connections are not allowed by xpans. If the -P
160       switch is specified with a value of 1, proxy connection are allowed,
161       but all proxy communication is performed in the same thread as xpans
162       processing. If a value of 2 is specified, the proxy processing is per‐
163       formed in a separate thread (assuming pthreads are supported on your
164       system).  Because xpa callback processing of any type can take a long
165       time and therefore can interfere with normal xpans processing, threaded
166       proxy connections (-P 2) are recommended.  When using proxy connec‐
167       tions, it might also be useful to set the XPA_IOCALLSXPA environment
168       variable, so that multiple proxy requests can be handled at the same
169       time, instead of serially.
170
171       Note that this proxy interface to xpans is experimental. It is used to
172       provide remote data analysis capabilities on the Chandra-Ed system
173       using ds9.  (See http://chandra-ed.cfa.harvard.edu and
174       http://hea-www.harvard.edu/saord/ds9 for more details). As always,
175       please contact us if you have problems or questions.
176

SEE ALSO

178       See xpa(n) for a list of XPA help pages
179
180
181
182version 2.1.12                 January 26, 2010                       xpans(1)
Impressum