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.)
46
47       The xpans program will be started automatically (assuming it can be
48       found in the user's path) when the first XPA access point is regis‐
49       tered.  It therefore need not be started explicitly.  However, when
50       started automatically, the -e switch is used, so that the name server
51       will exit when there are no more XPA access points registered. If you
52       wish to keep the name server running continually, simply start it manu‐
53       ally without the -e switch.
54
55       The name server will keep a log of registered access points if the -l
56       [log] switch is used on the command line (this is the case for auto‐
57       matic start-up).  The log contains enough name and connection informa‐
58       tion to allow you to re-register all XPA access points in case the name
59       server process is terminated prematurely. For example, after the ds9
60       access point is registered,the log will contain the entry:
61
62         add 838e2f67:1863 ds9 ds9 gs eric
63
64       If xpans is terminated but ds9 still is running, you can re-register
65       both access points for the ds9 process by running:
66
67         xpaset -p 838e2f67:1863 -nsconnect
68
69       Notice that the ip:port specifier is used with xpaset to bypass the
70       need for contacting the name server (which does not have the name reg‐
71       istered yet!)
72
73       The name server will keep a log of security information if the -s
74       [security log] switch is used on the command line. For each accepted
75       connection, (including connections via the xpaget command), information
76       will be logged about the host issuing the command and the parameters
77       passed into the program. This is most useful when xpans is accepting
78       connections from untrusted machines.
79
80       When an XPA access point is removed by a server using XPAFree(), the
81       access information is removed from the name server.  If an XPA-enabled
82       process is terminated, all names registered by that process will be
83       removed automatically.  The log file is always updated to reflect the
84       currently registered access points.
85
86       The name server itself has an XPA access point names xpans registered
87       through which you can find out information about currently registered
88       access points (assuming you have access to the name server; see XPA
89       Access Control for more information). For example, to display all cur‐
90       rently registered access points, simply execute:
91
92         xpaget xpans
93
94       Continuing the example of ds9 above, this will return:
95
96         ds9 ds9 gs 838e2f67:1863 eric
97
98       If the same program has been started with different XPA access names,
99       you can look up only names matching a specified template. For example,
100       assume that ds9 has been started up using:
101
102         ds9 &
103         ds9 -title ds9-1-eric &
104         ds9 -title ds9-2-eric &
105
106       To lookup all ds9 access points which end in ".eric" and which can be
107       accessed using xpaset, use:
108
109         xpaget xpans "DS9:*.eric" "s" "*"
110
111       This will return:
112
113         DS9 ds9-2-eric gs 838e29d3:42102 eric
114         DS9 ds9-1-eric gs 838e29d3:42105 eric
115
116       The third argument "*" requests all access points from all users.  You
117       also can specify a specific user name and only access points registered
118       by that user will be returned.
119
120       The name server uses the XPA_METHOD environment variable to determine
121       whether it should listen for requests on INET or LOCAL sockets.  Since
122       XPA access points also use this environment variable, the choice of
123       socket method will be consistent.  Note that, when INET sockets are
124       used, a local server can be accessed from remote machines if the
125       XPA_NSINET environment variable is set to point to the local machine.
126       See XPA Environment Variables for more information.
127
128       An experimental feature of xpans is its ability to act as a proxy to
129       XPA servers behind firewalls that want to communicate with external
130       processes.  The basic idea is the following: an XPA server (call it
131       "foo") on host1, possibly behind a firewall, makes a remote connection
132       to a proxy-enabled xpans program on host2 (specifying host2's XPA
133       method).  For example:
134
135         xpaset -p foo -remote 'host2:28571' + -proxy   # on host1
136
137       When this is done, host2 can use xpaset, xpaget, and xpainfo calls to
138       communicate with the XPA server foo. All command communication is per‐
139       formed via the xpans socket connection between foo on host1 and xpans
140       on host2 (which was initiated by foo from inside the firewall).  Data
141       communication is similarly performed using a socket connection initi‐
142       ated on host1 (usually with a port value two greater than the port
143       value of the main xpans socket connection). An xpaset or xpaget call on
144       host2 contacts xpans, which performs an XPASet() or XPAGet() call to
145       foo, passing commands and data back and forth between the two programs.
146
147       By default, proxy connections are not allowed by xpans. If the -P
148       switch is specified with a value of 1, proxy connection are allowed,
149       but all proxy communication is performed in the same thread as xpans
150       processing. If a value of 2 is specified, the proxy processing is per‐
151       formed in a separate thread (assuming pthreads are supported on your
152       system).  Because xpa callback processing of any type can take a long
153       time and therefore can interfere with normal xpans processing, threaded
154       proxy connections (-P 2) are recommended.  When using proxy connec‐
155       tions, it might also be useful to set the XPA_IOCALLSXPA environment
156       variable, so that multiple proxy requests can be handled at the same
157       time, instead of serially.
158
159       Note that this proxy interface to xpans is experimental. It is used to
160       provide remote data analysis capabilities on the Chandra-Ed system
161       using ds9.  (See http://chandra-ed.cfa.harvard.edu and
162       http://hea-www.harvard.edu/saord/ds9 for more details). As always,
163       please contact us if you have problems or questions.
164

SEE ALSO

166       See xpa(n) for a list of XPA help pages
167
168
169
170version 2.1.8                  November 1, 2007                       xpans(1)
Impressum