1xpans(1) SAORD Documentation xpans(1)
2
6 xpans: the XPA Name Server
7
9 xpans [-h] [-e] [-k sec] [-p port] [-l log] [-s security log] [-P n]
10
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
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 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 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 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 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 add 838e2f67:1863 ds9 ds9 gs eric
66 If xpans is terminated but ds9 still is running, you can re-register
68 both access points for the ds9 process by running:
69 xpaset -p 838e2f67:1863 -nsconnect
71 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 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 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 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 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 For example, to display all currently registered access points, simply
102 execute:
103 xpaget xpans
105 Continuing the example of ds9 above, this will return:
107 DS9 ds9 gs 838e2f67:1863 eric
109 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 ds9 &
115 ds9 -title ds9-1-eric &
116 ds9 -title ds9-2-eric &
117 To lookup all ds9 access points which end in ".eric" and which can be
119 accessed using xpaset, use:
120 xpaget xpans "DS9:*.eric" "s" "*"
122 This will return:
124 DS9 ds9-2-eric gs 838e29d3:42102 eric
126 DS9 ds9-1-eric gs 838e29d3:42105 eric
127 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 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 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 xpaset -p foo -remote 'host2:28571' + -proxy # on host1
148 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 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 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
178 See xpa(n) for a list of XPA help pages
179version 2.1.12 January 26, 2010 xpans(1)