diff options
Diffstat (limited to 'xpa/man/mann/xpainet.n')
| -rw-r--r-- | xpa/man/mann/xpainet.n | 396 |
1 files changed, 396 insertions, 0 deletions
diff --git a/xpa/man/mann/xpainet.n b/xpa/man/mann/xpainet.n new file mode 100644 index 0000000..4847654 --- /dev/null +++ b/xpa/man/mann/xpainet.n @@ -0,0 +1,396 @@ +.\" Automatically generated by Pod::Man 2.22 (Pod::Simple 3.13) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" Set up some character translations and predefined strings. \*(-- will +.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left +.\" double quote, and \*(R" will give a right double quote. \*(C+ will +.\" give a nicer C++. Capital omega is used to do unbreakable dashes and +.\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, +.\" nothing in troff, for use with C<>. +.tr \(*W- +.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' +.ie n \{\ +. ds -- \(*W- +. ds PI pi +. if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch +. if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch +. ds L" "" +. ds R" "" +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds -- \|\(em\| +. ds PI \(*p +. ds L" `` +. ds R" '' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is turned on, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.ie \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. nr % 0 +. rr F +.\} +.el \{\ +. de IX +.. +.\} +.\" +.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2). +.\" Fear. Run. Save yourself. No user-serviceable parts. +. \" fudge factors for nroff and troff +.if n \{\ +. ds #H 0 +. ds #V .8m +. ds #F .3m +. ds #[ \f1 +. ds #] \fP +.\} +.if t \{\ +. ds #H ((1u-(\\\\n(.fu%2u))*.13m) +. ds #V .6m +. ds #F 0 +. ds #[ \& +. ds #] \& +.\} +. \" simple accents for nroff and troff +.if n \{\ +. ds ' \& +. ds ` \& +. ds ^ \& +. ds , \& +. ds ~ ~ +. ds / +.\} +.if t \{\ +. ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u" +. ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u' +. ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u' +. ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u' +. ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u' +. ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u' +.\} +. \" troff and (daisy-wheel) nroff accents +.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V' +.ds 8 \h'\*(#H'\(*b\h'-\*(#H' +.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#] +.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H' +.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u' +.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#] +.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#] +.ds ae a\h'-(\w'a'u*4/10)'e +.ds Ae A\h'-(\w'A'u*4/10)'E +. \" corrections for vroff +.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u' +.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u' +. \" for low resolution devices (crt and lpr) +.if \n(.H>23 .if \n(.V>19 \ +\{\ +. ds : e +. ds 8 ss +. ds o a +. ds d- d\h'-1'\(ga +. ds D- D\h'-1'\(hy +. ds th \o'bp' +. ds Th \o'LP' +. ds ae ae +. ds Ae AE +.\} +.rm #[ #] #H #V #F C +.\" ======================================================================== +.\" +.IX Title "xpainet n" +.TH xpainet n "July 23, 2013" "version 2.1.15" "SAORD Documentation" +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH "NAME" +\&\fBXPAInet: \s-1XPA\s0 Communication Between Hosts\fR +.SH "SYNOPSIS" +.IX Header "SYNOPSIS" +\&\s-1XPA\s0 uses standard inet sockets to support communication between two or +more host computers. +.SH "DESCRIPTION" +.IX Header "DESCRIPTION" +When the Communication Method is set to +\&\fBinet\fR (as it is by default), \s-1XPA\s0 can be used to communicate +between different computers on the Internet. \s-1INET\s0 sockets utilize the +\&\s-1IP\s0 address of the given machine and a (usually random) port number to +communicate between processes on the same machine or between different +machines on the Internet. These standard Internet sockets are also +used by programs such as Netscape, ftp. etc. +.PP +\&\s-1XPA\s0 supports a host-based Access Control mechanism +to prevent unauthorized access of \s-1XPA\s0 access points by other computers +on the Net. By default, only the machine on which the \s-1XPA\s0 server is +running can access \s-1XPA\s0 services. Therefore, setting up communication +between a local \s-1XPA\s0 server machine and a remote client machine +requires a two-part registration process: +.IP "\(bu" 4 +the \s-1XPA\s0 service on the local machine must be made known to the +remote machine +.IP "\(bu" 4 +the remote machine must be given permission to access the local +\&\s-1XPA\s0 service +.PP +Three methods by which this remote registration can be accomplished +are described below. +.PP +\&\fBManual Registration\fR +.PP +The first method is the most basic and does not require the remote +client to have xpans running. To use it, the local server simply +gives a remote client machine access to one or more \s-1XPA\s0 access points +using xpaset and the \fB\-acl\fR sub-command. For example, +consider the \s-1XPA\s0 test program \*(L"stest\*(R" running on a local machine. By +default the access control for the access point named \*(L"xpa\*(R" is +restricted to that machine: +.PP +.Vb 3 +\& [sh]$ xpaget xpa \-acl +\& *:* 123.456.78.910 gisa +\& *:* localhost gisa +.Ve +.PP +Using xpaset and the \fB\-acl\fR sub-command, a remote client +machine can be given permission to perform xpaget, xpaset, xpaaccess, +or xpainfo operations. For example, to allow the xpaget operation, the +following command can be issued on the local machine: +.PP +.Vb 1 +\& [sh]$ xpaset \-p xpa \-acl "remote_machine g" +.Ve +.PP +This results in the following access permissions on the local machine: +.PP +.Vb 4 +\& [sh]$ xpaget xpa \-acl +\& XPA:xpa 234.567.89.012 g +\& *:* 123.456.78.910 gisa +\& *:* localhost gisa +.Ve +.PP +The remote client can now use the local server's xpans name server to +establish communication with the local \s-1XPA\s0 service. This can be done +on a call-by-call basis using the \fB\-i\fR switch on xpaset, xpaget, etc: +.PP +.Vb 6 +\& [sh]$ xpaget \-i "local_machine:12345" xpa +\& class: XPA +\& name: xpa +\& method: 88877766:2778 +\& sendian: little +\& cendian: big +.Ve +.PP +Alternatively, the \s-1XPA_NSINET\s0 variable on the remote machine can be +set to point directly to xpans on the local machine, removing +the need to override this value each time an \s-1XPA\s0 program is run: +.PP +.Vb 7 +\& [csh]$ setenv XPA_NSINET \*(Aqkarapet:$port\*(Aq +\& [csh]$ xpaget xpa +\& class: XPA +\& name: xpa +\& method: 88877766:2778 +\& sendian: little +\& cendian: big +.Ve +.PP +Here, '$port' means to use the default \s-1XPA\s0 name service port (14285). +not a port environment variable. +.PP +Access permission for remote client machines can be stored in a file +on the local machine pointed to by the \fB\s-1XPA_ACLFILE\s0\fR environment +variable or using the \fB\s-1XPA_DEFACL\s0\fR environment variable. See <A +HREF=\*(L"./acl.html\*(R">\s-1XPA\s0 Access Control for more information. +.PP +\&\fBRemote Registration\fR +.PP +If xpans is running on the remote client machine, then a local xpaset +command can be used with the \fB\-remote\fR sub-command to +register the local \s-1XPA\s0 service in the remote name service, while at +the same time giving the remote machine permission to access the local +service. For example, assume again that \*(L"stest\*(R" is running on the +local machine and that xpans is also running on the remote machine. +To register access of this local xpa on the remote machine, use +the xpaset and the \fB\-remote\fR sub-command: +.PP +.Vb 1 +\& [sh]$ ./xpaset \-p xpa \-remote \*(Aqremote_machine:$port\*(Aq + +.Ve +.PP +To register the local xpa access point on the remote machine with xpaget +access only, execute: +.PP +.Vb 1 +\& [sh]$ ./xpaset \-p xpa \-remote \*(Aqremote_machine:$port\*(Aq g +.Ve +.PP +Once the remote registration command is executed, the remote client +machine will have an entry such as the following in its own xpans name +service: +.PP +.Vb 2 +\& [csh]$ xpaget xpans +\& XPA xpa gs 88877766:2839 eric +.Ve +.PP +The xpa access point can now be utilized on the remote machine without +further setup: +.PP +.Vb 6 +\& [csh]$ xpaget xpa +\& class: XPA +\& name: xpa +\& method: 838e2f68:2839 +\& sendian: little +\& cendian: big +.Ve +.PP +To unregister remote access from the local machine, use the same +command but with a '\-' argument: +.PP +.Vb 1 +\& [sh]$ xpaset \-p xpa \-remote \*(Aqremote_machine:$port\*(Aq \- +.Ve +.PP +The benefit of using remote registration is that communication with +remote access points can be mixed with that of other access points +on the remote machine. Using Access Point +Names and Templates, one \s-1XPA\s0 command can be used to send or +receive messages to the remote and local services. +.PP +\&\fB\s-1XPANS\s0 Proxy Registration\fR +.PP +The two methods described above are useful when the local and remote +machines are able to communicate freely to one another. This would be +the case on most Local Area Networks (LANs) where all machines are +behind the same firewall and there is no port blocking between +machines on the same \s-1LAN\s0. The situation is more complicated when the +\&\s-1XPA\s0 server is behind a firewall, where outgoing connections are +allowed, but incoming port blocking is implemented to prevent machines +outside the firewall from connecting to machines inside the +firewall. Such incoming port blocking will prevent xpaset and xpaget +from connecting to an \s-1XPA\s0 server inside a firewall. +.PP +To allow locally fire-walled \s-1XPA\s0 services to register with remote +machines, we have implemented a proxy service within the xpans name +server. To register remote proxy service, xpaset and the +\&\fB\-remote\fR sub-command is again used, but with an additional +\&\fB\-proxy\fR argument added to the end of the command: +.PP +.Vb 1 +\& [sh]$ ./xpaset \-p xpa \-remote \*(Aqremote_machine:$port\*(Aq g \-proxy +.Ve +.PP +Once a remote proxy registration command is executed, the remote +machine will have an entry such as the following in its own xpans name +service: +.PP +.Vb 2 +\& [csh]$ xpaget xpans +\& XPA xpa gs @88877766:2839 eric +.Ve +.PP +The '@' sign in the name service entry indicates that xpans proxy +processing is being used for this access point. Other than that, from +the user's point of view, there is no difference in how this \s-1XPA\s0 +access point is contacted using \s-1XPA\s0 programs (xpaset, xpaget, etc.) or +libraries: +.PP +.Vb 6 +\& [csh]$ xpaget xpa +\& class: XPA +\& name: xpa +\& method: 88877766:3053 +\& sendian: little +\& cendian: big +.Ve +.PP +Of course, the underlying processing of the \s-1XPA\s0 requests is very much +different when xpans proxy is involved. Instead of an \s-1XPA\s0 program such +contacting the \s-1XPA\s0 service directly, it contacts the local xpans. +Acting as a proxy server, xpans communicates with the \s-1XPA\s0 service +using the command channel established at registration time. Commands +(including establishing a new data channel) are sent between xpans and +the \s-1XPA\s0 service to set up a new message transfer, and then data is fed +to/from the xpa request, through xpans, from/to the \s-1XPA\s0 service. In +this way, it can be arranged so that connections between the +fire-walled \s-1XPA\s0 service and the remote client are always initiated by +the \s-1XPA\s0 service itself. Thus, incoming connections that would be +blocked by the firewall are avoided. Note that there is a performance +penalty for using the xpans/proxy service. Aside from extra overhead +to set up proxy communication, all data must be sent through the +intermediate proxy process. +.PP +The xpans proxy scheme requires that the remote client allow the local +\&\s-1XPA\s0 server machine to connect to the remote xpans/proxy server. If the +remote client machine also is behind a port-blocking firewall, such +connections will be disallowed. In this case, the only solution is to +open up some ports on the remote client machine to allow incoming +connections to xpans/proxy. Two ports must be opened (for command and +data channel connections). By default, these two ports are 14285 and +14287. The port numbers can be changed using the \fB\s-1XPA_NSINET\s0\fR +environment variable. This variable takes the form: +.PP +.Vb 1 +\& setenv XPA_NSINET machine:port1[,port2[,port3]] +.Ve +.PP +where port1 is the main connecting port, port2 is the \s-1XPA\s0 access port, +and port3 is the secondary data connecting port. The second and third +ports are optional and default to port1+1 and port1+2, respectively. +It is port1 and port3 that must be left open for incoming connections. +.PP +For example, to change the port assignments so that xpans listens +for registration commands on port 12345 and data commands on port 28573: +.PP +.Vb 1 +\& setenv XPA_NSINET myhost:12345 +.Ve +.PP +Alternatively, all three ports can be assigned explicitly: +.PP +.Vb 1 +\& setenv XPA_NSINET remote:12345,3000,12346 +.Ve +.PP +In this case 12345 and 12346 should be open for incoming connections. +The \s-1XPA\s0 access port (which need not be open to the outside +world) is set to 3000. +.PP +Finally, note that we currently have no mechanism to cope with +Internet proxy servers (such as \s-1SOCKS\s0 servers). If an \s-1XPA\s0 service is +running on a machine that cannot connect directly to outside machines, +but goes through a proxy server instead, there currently is no way to +register that \s-1XPA\s0 service with a remote machine. We hope to implement +support for \s-1SOCKS\s0 proxy in a future release. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +See xpa(n) for a list of \s-1XPA\s0 help pages |