Debian Codegraph @

cextern/xpa/man/mann/xpainet.n

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 "xpainet n"
127 .TH xpainet n "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 \&\fBXPAInet: \s-1XPA\s0 Communication Between Hosts\fR
134 .SH "SYNOPSIS"
135 .IX Header "SYNOPSIS"
136 \&\s-1XPA\s0 uses standard inet sockets to support communication between two or
137 more host computers.
138 .SH "DESCRIPTION"
139 .IX Header "DESCRIPTION"
140 When the Communication Method is set to
141 \&\fBinet\fR (as it is by default), \s-1XPA\s0 can be used to communicate
142 between different computers on the Internet. \s-1INET\s0 sockets utilize the
143 \&\s-1IP\s0 address of the given machine and a (usually random) port number to
144 communicate between processes on the same machine or between different
145 machines on the Internet. These standard Internet sockets are also
146 used by programs such as Netscape, ftp. etc.
147 .PP
148 \&\s-1XPA\s0 supports a host-based Access Control mechanism
149 to prevent unauthorized access of \s-1XPA\s0 access points by other computers
150 on the Net. By default, only the machine on which the \s-1XPA\s0 server is
151 running can access \s-1XPA\s0 services. Therefore, setting up communication
152 between a local \s-1XPA\s0 server machine and a remote client machine
153 requires a two-part registration process:
154 .IP "\(bu" 4
155 the \s-1XPA\s0 service on the local machine must be made known to the
156 remote machine
157 .IP "\(bu" 4
158 the remote machine must be given permission to access the local
159 \&\s-1XPA\s0 service
160 .PP
161 Three methods by which this remote registration can be accomplished
162 are described below.
163 .PP
164 \&\fBManual Registration\fR
165 .PP
166 The first method is the most basic and does not require the remote
167 client to have xpans running. To use it, the local server simply
168 gives a remote client machine access to one or more \s-1XPA\s0 access points
169 using xpaset and the \fB\-acl\fR sub-command. For example,
170 consider the \s-1XPA\s0 test program \*(L"stest\*(R" running on a local machine. By
171 default the access control for the access point named \*(L"xpa\*(R" is
172 restricted to that machine:
173 .PP
174 .Vb 3
175 \& [sh]$ xpaget xpa \-acl
176 \& *:* 123.456.78.910 gisa
177 \& *:* localhost gisa
178 .Ve
179 .PP
180 Using xpaset and the \fB\-acl\fR sub-command, a remote client
181 machine can be given permission to perform xpaget, xpaset, xpaaccess,
182 or xpainfo operations. For example, to allow the xpaget operation, the
183 following command can be issued on the local machine:
184 .PP
185 .Vb 1
186 \& [sh]$ xpaset \-p xpa \-acl "remote_machine g"
187 .Ve
188 .PP
189 This results in the following access permissions on the local machine:
190 .PP
191 .Vb 4
192 \& [sh]$ xpaget xpa \-acl
193 \& XPA:xpa 234.567.89.012 g
194 \& *:* 123.456.78.910 gisa
195 \& *:* localhost gisa
196 .Ve
197 .PP
198 The remote client can now use the local server's xpans name server to
199 establish communication with the local \s-1XPA\s0 service. This can be done
200 on a call-by-call basis using the \fB\-i\fR switch on xpaset, xpaget, etc:
201 .PP
202 .Vb 6
203 \& [sh]$ xpaget \-i "local_machine:12345" xpa
204 \& class: XPA
205 \& name: xpa
206 \& method: 88877766:2778
207 \& sendian: little
208 \& cendian: big
209 .Ve
210 .PP
211 Alternatively, the \s-1XPA_NSINET\s0 variable on the remote machine can be
212 set to point directly to xpans on the local machine, removing
213 the need to override this value each time an \s-1XPA\s0 program is run:
214 .PP
215 .Vb 7
216 \& [csh]$ setenv XPA_NSINET \*(Aqkarapet:$port\*(Aq
217 \& [csh]$ xpaget xpa
218 \& class: XPA
219 \& name: xpa
220 \& method: 88877766:2778
221 \& sendian: little
222 \& cendian: big
223 .Ve
224 .PP
225 Here, '$port' means to use the default \s-1XPA\s0 name service port (14285).
226 not a port environment variable.
227 .PP
228 Access permission for remote client machines can be stored in a file
229 on the local machine pointed to by the \fB\s-1XPA_ACLFILE\s0\fR environment
230 variable or using the \fB\s-1XPA_DEFACL\s0\fR environment variable. See <A
231 HREF=\*(L"./acl.html\*(R">\s-1XPA\s0 Access Control for more information.
232 .PP
233 \&\fBRemote Registration\fR
234 .PP
235 If xpans is running on the remote client machine, then a local xpaset
236 command can be used with the \fB\-remote\fR sub-command to
237 register the local \s-1XPA\s0 service in the remote name service, while at
238 the same time giving the remote machine permission to access the local
239 service. For example, assume again that \*(L"stest\*(R" is running on the
240 local machine and that xpans is also running on the remote machine.
241 To register access of this local xpa on the remote machine, use
242 the xpaset and the \fB\-remote\fR sub-command:
243 .PP
244 .Vb 1
245 \& [sh]$ ./xpaset \-p xpa \-remote \*(Aqremote_machine:$port\*(Aq +
246 .Ve
247 .PP
248 To register the local xpa access point on the remote machine with xpaget
249 access only, execute:
250 .PP
251 .Vb 1
252 \& [sh]$ ./xpaset \-p xpa \-remote \*(Aqremote_machine:$port\*(Aq g
253 .Ve
254 .PP
255 Once the remote registration command is executed, the remote client
256 machine will have an entry such as the following in its own xpans name
257 service:
258 .PP
259 .Vb 2
260 \& [csh]$ xpaget xpans
261 \& XPA xpa gs 88877766:2839 eric
262 .Ve
263 .PP
264 The xpa access point can now be utilized on the remote machine without
265 further setup:
266 .PP
267 .Vb 6
268 \& [csh]$ xpaget xpa
269 \& class: XPA
270 \& name: xpa
271 \& method: 838e2f68:2839
272 \& sendian: little
273 \& cendian: big
274 .Ve
275 .PP
276 To unregister remote access from the local machine, use the same
277 command but with a '\-' argument:
278 .PP
279 .Vb 1
280 \& [sh]$ xpaset \-p xpa \-remote \*(Aqremote_machine:$port\*(Aq \-
281 .Ve
282 .PP
283 The benefit of using remote registration is that communication with
284 remote access points can be mixed with that of other access points
285 on the remote machine. Using Access Point
286 Names and Templates, one \s-1XPA\s0 command can be used to send or
287 receive messages to the remote and local services.
288 .PP
289 \&\fB\s-1XPANS\s0 Proxy Registration\fR
290 .PP
291 The two methods described above are useful when the local and remote
292 machines are able to communicate freely to one another. This would be
293 the case on most Local Area Networks (LANs) where all machines are
294 behind the same firewall and there is no port blocking between
295 machines on the same \s-1LAN\s0. The situation is more complicated when the
296 \&\s-1XPA\s0 server is behind a firewall, where outgoing connections are
297 allowed, but incoming port blocking is implemented to prevent machines
298 outside the firewall from connecting to machines inside the
299 firewall. Such incoming port blocking will prevent xpaset and xpaget
300 from connecting to an \s-1XPA\s0 server inside a firewall.
301 .PP
302 To allow locally fire-walled \s-1XPA\s0 services to register with remote
303 machines, we have implemented a proxy service within the xpans name
304 server. To register remote proxy service, xpaset and the
305 \&\fB\-remote\fR sub-command is again used, but with an additional
306 \&\fB\-proxy\fR argument added to the end of the command:
307 .PP
308 .Vb 1
309 \& [sh]$ ./xpaset \-p xpa \-remote \*(Aqremote_machine:$port\*(Aq g \-proxy
310 .Ve
311 .PP
312 Once a remote proxy registration command is executed, the remote
313 machine will have an entry such as the following in its own xpans name
314 service:
315 .PP
316 .Vb 2
317 \& [csh]$ xpaget xpans
318 \& XPA xpa gs @88877766:2839 eric
319 .Ve
320 .PP
321 The '@' sign in the name service entry indicates that xpans proxy
322 processing is being used for this access point. Other than that, from
323 the user's point of view, there is no difference in how this \s-1XPA\s0
324 access point is contacted using \s-1XPA\s0 programs (xpaset, xpaget, etc.) or
325 libraries:
326 .PP
327 .Vb 6
328 \& [csh]$ xpaget xpa
329 \& class: XPA
330 \& name: xpa
331 \& method: 88877766:3053
332 \& sendian: little
333 \& cendian: big
334 .Ve
335 .PP
336 Of course, the underlying processing of the \s-1XPA\s0 requests is very much
337 different when xpans proxy is involved. Instead of an \s-1XPA\s0 program such
338 contacting the \s-1XPA\s0 service directly, it contacts the local xpans.
339 Acting as a proxy server, xpans communicates with the \s-1XPA\s0 service
340 using the command channel established at registration time. Commands
341 (including establishing a new data channel) are sent between xpans and
342 the \s-1XPA\s0 service to set up a new message transfer, and then data is fed
343 to/from the xpa request, through xpans, from/to the \s-1XPA\s0 service. In
344 this way, it can be arranged so that connections between the
345 fire-walled \s-1XPA\s0 service and the remote client are always initiated by
346 the \s-1XPA\s0 service itself. Thus, incoming connections that would be
347 blocked by the firewall are avoided. Note that there is a performance
348 penalty for using the xpans/proxy service. Aside from extra overhead
349 to set up proxy communication, all data must be sent through the
350 intermediate proxy process.
351 .PP
352 The xpans proxy scheme requires that the remote client allow the local
353 \&\s-1XPA\s0 server machine to connect to the remote xpans/proxy server. If the
354 remote client machine also is behind a port-blocking firewall, such
355 connections will be disallowed. In this case, the only solution is to
356 open up some ports on the remote client machine to allow incoming
357 connections to xpans/proxy. Two ports must be opened (for command and
358 data channel connections). By default, these two ports are 14285 and
359 14287. The port numbers can be changed using the \fB\s-1XPA_NSINET\s0\fR
360 environment variable. This variable takes the form:
361 .PP
362 .Vb 1
363 \& setenv XPA_NSINET machine:port1[,port2[,port3]]
364 .Ve
365 .PP
366 where port1 is the main connecting port, port2 is the \s-1XPA\s0 access port,
367 and port3 is the secondary data connecting port. The second and third
368 ports are optional and default to port1+1 and port1+2, respectively.
369 It is port1 and port3 that must be left open for incoming connections.
370 .PP
371 For example, to change the port assignments so that xpans listens
372 for registration commands on port 12345 and data commands on port 28573:
373 .PP
374 .Vb 1
375 \& setenv XPA_NSINET myhost:12345
376 .Ve
377 .PP
378 Alternatively, all three ports can be assigned explicitly:
379 .PP
380 .Vb 1
381 \& setenv XPA_NSINET remote:12345,3000,12346
382 .Ve
383 .PP
384 In this case 12345 and 12346 should be open for incoming connections.
385 The \s-1XPA\s0 access port (which need not be open to the outside
386 world) is set to 3000.
387 .PP
388 Finally, note that we currently have no mechanism to cope with
389 Internet proxy servers (such as \s-1SOCKS\s0 servers). If an \s-1XPA\s0 service is
390 running on a machine that cannot connect directly to outside machines,
391 but goes through a proxy server instead, there currently is no way to
392 register that \s-1XPA\s0 service with a remote machine. We hope to implement
393 support for \s-1SOCKS\s0 proxy in a future release.
394 .SH "SEE ALSO"
395 .IX Header "SEE ALSO"
396 See xpa(n) for a list of \s-1XPA\s0 help pages