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.)
46 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 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 add 838e2f67:1863 ds9 ds9 gs eric
63 If xpans is terminated but ds9 still is running, you can re-register
65 both access points for the ds9 process by running:
66 xpaset -p 838e2f67:1863 -nsconnect
68 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 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 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 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 xpaget xpans
93 Continuing the example of ds9 above, this will return:
95 ds9 ds9 gs 838e2f67:1863 eric
97 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 ds9 &
103 ds9 -title ds9-1-eric &
104 ds9 -title ds9-2-eric &
105 To lookup all ds9 access points which end in ".eric" and which can be
107 accessed using xpaset, use:
108 xpaget xpans "DS9:*.eric" "s" "*"
110 This will return:
112 DS9 ds9-2-eric gs 838e29d3:42102 eric
114 DS9 ds9-1-eric gs 838e29d3:42105 eric
115 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 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 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 xpaset -p foo -remote 'host2:28571' + -proxy # on host1
136 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 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 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
166 See xpa(n) for a list of XPA help pages
167version 2.1.8 November 1, 2007 xpans(1)