Debian Codegraph @

cextern/xpa/man/man1/xpans.1

raw
1 .\" Automatically generated by Pod::Man 2.22 (Pod::Simple 3.13)
2 .\"
3 .\" Standard preamble:
4 .\" ========================================================================
5 .de Sp \" Vertical space (when we can't use .PP)
6 .if t .sp .5v
7 .if n .sp
8 ..
9 .de Vb \" Begin verbatim text
10 .ft CW
11 .nf
12 .ne \\$1
13 ..
14 .de Ve \" End verbatim text
15 .ft R
16 .fi
17 ..
18 .\" Set up some character translations and predefined strings. \*(-- will
19 .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
20 .\" double quote, and \*(R" will give a right double quote. \*(C+ will
21 .\" give a nicer C++. Capital omega is used to do unbreakable dashes and
22 .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff,
23 .\" nothing in troff, for use with C<>.
24 .tr \(*W-
25 .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
26 .ie n \{\
27 . ds -- \(*W-
28 . ds PI pi
29 . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
30 . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch
31 . ds L" ""
32 . ds R" ""
33 . ds C` ""
34 . ds C' ""
35 'br\}
36 .el\{\
37 . ds -- \|\(em\|
38 . ds PI \(*p
39 . ds L" ``
40 . ds R" ''
41 'br\}
42 .\"
43 .\" Escape single quotes in literal strings from groff's Unicode transform.
44 .ie \n(.g .ds Aq \(aq
45 .el .ds Aq '
46 .\"
47 .\" If the F register is turned on, we'll generate index entries on stderr for
48 .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
49 .\" entries marked with X<> in POD. Of course, you'll have to process the
50 .\" output yourself in some meaningful fashion.
51 .ie \nF \{\
52 . de IX
53 . tm Index:\\$1\t\\n%\t"\\$2"
54 ..
55 . nr % 0
56 . rr F
57 .\}
58 .el \{\
59 . de IX
60 ..
61 .\}
62 .\"
63 .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
64 .\" Fear. Run. Save yourself. No user-serviceable parts.
65 . \" fudge factors for nroff and troff
66 .if n \{\
67 . ds #H 0
68 . ds #V .8m
69 . ds #F .3m
70 . ds #[ \f1
71 . ds #] \fP
72 .\}
73 .if t \{\
74 . ds #H ((1u-(\\\\n(.fu%2u))*.13m)
75 . ds #V .6m
76 . ds #F 0
77 . ds #[ \&
78 . ds #] \&
79 .\}
80 . \" simple accents for nroff and troff
81 .if n \{\
82 . ds ' \&
83 . ds ` \&
84 . ds ^ \&
85 . ds , \&
86 . ds ~ ~
87 . ds /
88 .\}
89 .if t \{\
90 . ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
91 . ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
92 . ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
93 . ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
94 . ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
95 . ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
96 .\}
97 . \" troff and (daisy-wheel) nroff accents
98 .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
99 .ds 8 \h'\*(#H'\(*b\h'-\*(#H'
100 .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
101 .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
102 .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
103 .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
104 .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
105 .ds ae a\h'-(\w'a'u*4/10)'e
106 .ds Ae A\h'-(\w'A'u*4/10)'E
107 . \" corrections for vroff
108 .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
109 .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
110 . \" for low resolution devices (crt and lpr)
111 .if \n(.H>23 .if \n(.V>19 \
112 \{\
113 . ds : e
114 . ds 8 ss
115 . ds o a
116 . ds d- d\h'-1'\(ga
117 . ds D- D\h'-1'\(hy
118 . ds th \o'bp'
119 . ds Th \o'LP'
120 . ds ae ae
121 . ds Ae AE
122 .\}
123 .rm #[ #] #H #V #F C
124 .\" ========================================================================
125 .\"
126 .IX Title "xpans 1"
127 .TH xpans 1 "July 23, 2013" "version 2.1.15" "SAORD Documentation"
128 .\" For nroff, turn off justification. Always turn off hyphenation; it makes
129 .\" way too many mistakes in technical documents.
130 .if n .ad l
131 .nh
132 .SH "NAME"
133 \&\fBxpans: the \s-1XPA\s0 Name Server\fR
134 .SH "SYNOPSIS"
135 .IX Header "SYNOPSIS"
136 .Vb 1
137 \& xpans [\-h] [\-e] [\-k sec] [\-p port] [\-l log] [\-s security log] [\-P n]
138 .Ve
139 .SH "OPTIONS"
140 .IX Header "OPTIONS"
141 .Vb 8
142 \& \-h print help message
143 \& \-e exit when there are no more XPA connections
144 \& \-k send keepalive messages every n sec
145 \& \-l log data base entries to specified file
146 \& \-p listen for connections on specified port
147 \& \-s log security info for each connection to specified file
148 \& \-P accept proxy requests (P=1) using separate thread (P=2)
149 \& \-\-version display version and exit
150 .Ve
151 .SH "DESCRIPTION"
152 .IX Header "DESCRIPTION"
153 The xpans name server is an XPA-enabled program that is used to
154 manage the names and ports of \s-1XPA\s0 access points. It is started
155 automatically when an \s-1XPA\s0 access point is registered. You can access
156 the name server using xpaget to get a list of registered access points.
157 .PP
158 The \fIxpans\fR name server provides a crucial link between \s-1XPA\s0
159 clients and servers. When an \s-1XPA\s0 server defines an access point using
160 \&\fIXPANew()\fR, \fIXPACmdNew()\fR, or \fIXPAInfoNew()\fR, the name of the access point
161 is registered in the name service, along with connection information.
162 The name server then matches class:name templates passed to it by \s-1XPA\s0
163 clients with these registered entries, so that the clients can
164 communicate with the appropriate servers.
165 .PP
166 The socket connection between an XPA-enabled program and
167 \&\fIxpans\fR is kept open until the former exits (or explicitly
168 closes the connection). Apparently, some Internet equipment (e.g. \s-1DSL\s0
169 modems) can cause such a connection to time-out after a period of
170 inactivity. To prevent this from happening, you can use the \-k
171 [sec] switch to send a short keep-alive message to each open
172 connection after the specified time delay. (Note that this
173 application level use of keep-alive is necessary only if you are
174 serving XPA-enabled clients over the Internet and have to deal with
175 long-term connections involving \s-1DSL\s0 or similar equipment. \s-1XPA\s0 uses
176 the ordinary socket-level keep-alive, which works for all other cases.)
177 \&\s-1NB\s0 (12/2/2009): Out-of-band (\s-1URG\s0) \s-1TCP\s0 data, used by xpans
178 keep-alive, is changed by some Cisco routers into in-band data.
179 Encountering such a router will break the keep-alive function and may
180 break your \s-1XPA\s0 server as well. Proceed with caution!
181 .PP
182 The \fIxpans\fR program will be started automatically (assuming it
183 can be found in the user's path) when the first \s-1XPA\s0 access point is
184 registered. It therefore need not be started explicitly. However,
185 when started automatically, the \fI\-e\fR switch is used, so that
186 the name server will exit when there are no more \s-1XPA\s0 access points
187 registered. If you wish to keep the name server running continually,
188 simply start it manually without the \fI\-e\fR switch.
189 .PP
190 The name server will keep a log of registered access points if the
191 \&\fI\-l [log]\fR switch is used on the command line (this is the
192 case for automatic start-up). The log contains enough name and connection
193 information to allow you to re-register all \s-1XPA\s0 access points in case
194 the name server process is terminated prematurely. For example, after
195 the ds9 access point is registered,the log will contain the entry:
196 .PP
197 .Vb 1
198 \& add 838e2f67:1863 ds9 ds9 gs eric
199 .Ve
200 .PP
201 If \fIxpans\fR is terminated but ds9 still is running, you
202 can re-register both access points for the ds9 process by running:
203 .PP
204 .Vb 1
205 \& xpaset \-p 838e2f67:1863 \-nsconnect
206 .Ve
207 .PP
208 Notice that the ip:port specifier is used with \fIxpaset\fR to bypass
209 the need for contacting the name server (which does not have the name
210 registered yet!)
211 .PP
212 The name server will keep a log of security information if the \-s
213 [security log] switch is used on the command line. For each
214 accepted connection, (including connections via the \fIxpaget\fR
215 command), information will be logged about the host issuing the
216 command and the parameters passed into the program. This is most
217 useful when \fIxpans\fR is accepting connections from untrusted
218 machines.
219 .PP
220 When an \s-1XPA\s0 access point is removed by a server using \fI\fIXPAFree()\fI\fR,
221 the access information is removed from the name server. If an
222 XPA-enabled process is terminated, all names registered by that process
223 will be removed automatically. The log file is always updated to
224 reflect the currently registered access points.
225 .PP
226 The name server itself has an \s-1XPA\s0 access point names \fIxpans\fR
227 registered through which you can find out information about currently
228 registered access points (assuming you have access to the name server;
229 see \s-1XPA\s0 Access Control for more information).
230 For each registered access point, the following information is returned:
231 .PP
232 .Vb 5
233 \& class # class of the access point
234 \& name # name of the access point
235 \& access # allowed access (g=xpaget,s=xpaset,i=xpainfo)
236 \& id # socket access method (host:port for inet, file for local/unix)
237 \& user # user name of access point owner
238 .Ve
239 .PP
240 For example, to display all currently registered access points, simply execute:
241 .PP
242 .Vb 1
243 \& xpaget xpans
244 .Ve
245 .PP
246 Continuing the example of ds9 above, this will return:
247 .PP
248 .Vb 1
249 \& DS9 ds9 gs 838e2f67:1863 eric
250 .Ve
251 .PP
252 If the same program has been started with different \s-1XPA\s0 access names,
253 you can look up only names matching a specified template. For example,
254 assume that ds9 has been started up using:
255 .PP
256 .Vb 3
257 \& ds9 &
258 \& ds9 \-title ds9\-1\-eric &
259 \& ds9 \-title ds9\-2\-eric &
260 .Ve
261 .PP
262 To lookup all ds9 access points which end in \*(L".eric\*(R" and which can
263 be accessed using \fIxpaset\fR, use:
264 .PP
265 .Vb 1
266 \& xpaget xpans "DS9:*.eric" "s" "*"
267 .Ve
268 .PP
269 This will return:
270 .PP
271 .Vb 2
272 \& DS9 ds9\-2\-eric gs 838e29d3:42102 eric
273 \& DS9 ds9\-1\-eric gs 838e29d3:42105 eric
274 .Ve
275 .PP
276 The third argument \*(L"*\*(R" requests all access points from all users.
277 You also can specify a specific user name and only access points
278 registered by that user will be returned.
279 .PP
280 The name server uses the \fI\s-1XPA_METHOD\s0\fR environment variable
281 to determine whether it should listen for requests on \s-1INET\s0 or \s-1LOCAL\s0
282 sockets. Since \s-1XPA\s0 access points also use this environment variable,
283 the choice of socket method will be consistent. Note that, when \s-1INET\s0
284 sockets are used, a local server can be accessed from remote machines
285 if the \fI\s-1XPA_NSINET\s0\fR environment variable is set to point to
286 the local machine. See
287 \&\s-1XPA\s0 Environment Variables
288 for more information.
289 .PP
290 An experimental feature of xpans is its ability to act as a proxy to
291 \&\s-1XPA\s0 servers behind firewalls that want to communicate with external
292 processes. The basic idea is the following: an \s-1XPA\s0 server (call it
293 \&\*(L"foo\*(R") on host1, possibly behind a firewall, makes a remote connection
294 to a proxy-enabled xpans program on host2 (specifying host2's \s-1XPA\s0 method).
295 For example:
296 .PP
297 .Vb 1
298 \& xpaset \-p foo \-remote \*(Aqhost2:28571\*(Aq + \-proxy # on host1
299 .Ve
300 .PP
301 When this is done, host2 can use xpaset, xpaget, and xpainfo calls to
302 communicate with the \s-1XPA\s0 server foo. All command communication is
303 performed via the xpans socket connection between foo on host1 and
304 xpans on host2 (which was initiated by foo from inside the firewall).
305 Data communication is similarly performed using a socket connection
306 initiated on host1 (usually with a port value two greater than the
307 port value of the main xpans socket connection). An xpaset or xpaget
308 call on host2 contacts xpans, which performs an \fIXPASet()\fR or \fIXPAGet()\fR
309 call to foo, passing commands and data back and forth between the two
310 programs.
311 .PP
312 By default, proxy connections are not allowed by xpans. If the \-P switch is
313 specified with a value of 1, proxy connection are allowed, but all proxy
314 communication is performed in the same thread as xpans processing. If
315 a value of 2 is specified, the proxy processing is performed in a
316 separate thread (assuming pthreads are supported on your system).
317 Because xpa callback processing of any type can take a long time and
318 therefore can interfere with normal xpans processing, threaded proxy
319 connections (\-P 2) are recommended. When using proxy connections, it
320 might also be useful to set the \s-1XPA_IOCALLSXPA\s0 environment variable, so
321 that multiple proxy requests can be handled at the same time, instead of
322 serially.
323 .PP
324 Note that this proxy interface to xpans is experimental. It is used
325 to provide remote data analysis capabilities on the Chandra-Ed system
326 using ds9. (See http://chandra\-ed.cfa.harvard.edu and
327 http://hea\-www.harvard.edu/saord/ds9 for more details). As always, please
328 contact us if you have problems or questions.
329 .SH "SEE ALSO"
330 .IX Header "SEE ALSO"
331 See xpa(n) for a list of \s-1XPA\s0 help pages