diff options
Diffstat (limited to 'xpa/doc/inet.html')
| -rw-r--r-- | xpa/doc/inet.html | 260 |
1 files changed, 260 insertions, 0 deletions
diff --git a/xpa/doc/inet.html b/xpa/doc/inet.html new file mode 100644 index 0000000..3155885 --- /dev/null +++ b/xpa/doc/inet.html @@ -0,0 +1,260 @@ +<!-- =defdoc xpainet xpainet n --> +<HTML> +<HEAD> +<TITLE>XPA Communication Between Hosts</TITLE> +</HEAD> +<BODY> + +<!-- =section xpainet NAME --> +<H2><A NAME="xpainet">XPAInet: XPA Communication Between Hosts</A></H2> + +<!-- =section xpainet SYNOPSIS --> +<H2>Summary</H2> +XPA uses standard inet sockets to support communication between two or +more host computers. + +<!-- =section xpainet DESCRIPTION --> +<H2>Description</H2> +<P> +When the <A HREF="./method.html">Communication Method</A> is set to +<B>inet</B> (as it is by default), XPA can be used to communicate +between different computers on the Internet. INET sockets utilize the +IP 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. + +<P> +XPA supports a host-based <A HREF="./acl.html">Access Control</A> mechanism +to prevent unauthorized access of XPA access points by other computers +on the Net. By default, only the machine on which the XPA server is +running can access XPA services. Therefore, setting up communication +between a local XPA server machine and a remote client machine +requires a two-part registration process: + +<UL> +<LI> the XPA service on the local machine must be made known to the +remote machine +<LI> the remote machine must be given permission to access the local +XPA service +</UL> + +Three methods by which this remote registration can be accomplished +are described below. + +<H2>Manual Registration</H2> + +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 XPA access points +using xpaset and the <B>-acl</B> sub-command. For example, +consider the XPA test program "stest" running on a local machine. By +default the access control for the access point named "xpa" is +restricted to that machine: +<PRE> + [sh]$ xpaget xpa -acl + *:* 123.456.78.910 gisa + *:* localhost gisa +</PRE> +Using xpaset and the <B>-acl</B> 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: +<PRE> + [sh]$ xpaset -p xpa -acl "remote_machine g" +</PRE> +This results in the following access permissions on the local machine: +<PRE> + [sh]$ xpaget xpa -acl + XPA:xpa 234.567.89.012 g + *:* 123.456.78.910 gisa + *:* localhost gisa +</PRE> + +The remote client can now use the local server's xpans name server to +establish communication with the local XPA service. This can be done +on a call-by-call basis using the <B>-i</B> switch on xpaset, xpaget, etc: +<PRE> + [sh]$ xpaget -i "local_machine:12345" xpa + class: XPA + name: xpa + method: 88877766:2778 + sendian: little + cendian: big +</PRE> +Alternatively, the XPA_NSINET 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 XPA program is run: +<PRE> + [csh]$ setenv XPA_NSINET 'karapet:$port' + [csh]$ xpaget xpa + class: XPA + name: xpa + method: 88877766:2778 + sendian: little + cendian: big +</PRE> +Here, '$port' means to use the default XPA name service port (14285). +not a port environment variable. + +<p> +Access permission for remote client machines can be stored in a file +on the local machine pointed to by the <B>XPA_ACLFILE</B> environment +variable or using the <B>XPA_DEFACL</B> environment variable. See <A +HREF="./acl.html">XPA Access Control</A> for more information. + +<H2>Remote Registration</H2> + +If xpans is running on the remote client machine, then a local xpaset +command can be used with the <B>-remote</B> sub-command to +register the local XPA 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 "stest" 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 <B>-remote</B> sub-command: +<PRE> + [sh]$ ./xpaset -p xpa -remote 'remote_machine:$port' + +</PRE> +To register the local xpa access point on the remote machine with xpaget +access only, execute: +<PRE> + [sh]$ ./xpaset -p xpa -remote 'remote_machine:$port' g +</PRE> +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: +<PRE> + [csh]$ xpaget xpans + XPA xpa gs 88877766:2839 eric +</PRE> +The xpa access point can now be utilized on the remote machine without +further setup: +<PRE> + [csh]$ xpaget xpa + class: XPA + name: xpa + method: 838e2f68:2839 + sendian: little + cendian: big +</PRE> +To unregister remote access from the local machine, use the same +command but with a '-' argument: +<PRE> + [sh]$ xpaset -p xpa -remote 'remote_machine:$port' - +</PRE> +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 <A HREF="./template.html">Access Point +Names and Templates</A>, one XPA command can be used to send or +receive messages to the remote and local services. + +<H2>XPANS Proxy Registration</H2> + +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 LAN. The situation is more complicated when the +XPA 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 XPA server inside a firewall. + +<P> +To allow locally fire-walled XPA 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 +<B>-remote</B> sub-command is again used, but with an additional +<B>-proxy</B> argument added to the end of the command: +<PRE> + [sh]$ ./xpaset -p xpa -remote 'remote_machine:$port' g -proxy +</PRE> +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: +<PRE> + [csh]$ xpaget xpans + XPA xpa gs @88877766:2839 eric +</PRE> +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 XPA +access point is contacted using XPA programs (xpaset, xpaget, etc.) or +libraries: +<PRE> + [csh]$ xpaget xpa + class: XPA + name: xpa + method: 88877766:3053 + sendian: little + cendian: big +</PRE> +<P> +Of course, the underlying processing of the XPA requests is very much +different when xpans proxy is involved. Instead of an XPA program such +contacting the XPA service directly, it contacts the local xpans. +Acting as a proxy server, xpans communicates with the XPA service +using the command channel established at registration time. Commands +(including establishing a new data channel) are sent between xpans and +the XPA service to set up a new message transfer, and then data is fed +to/from the xpa request, through xpans, from/to the XPA service. In +this way, it can be arranged so that connections between the +fire-walled XPA service and the remote client are always initiated by +the XPA 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. + +<P> +The xpans proxy scheme requires that the remote client allow the local +XPA 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 <B>XPA_NSINET</B> +environment variable. This variable takes the form: +<PRE> + setenv XPA_NSINET machine:port1[,port2[,port3]] +</PRE> +where port1 is the main connecting port, port2 is the XPA 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. + +<P> +For example, to change the port assignments so that xpans listens +for registration commands on port 12345 and data commands on port 28573: +<PRE> + setenv XPA_NSINET myhost:12345 +</PRE> +Alternatively, all three ports can be assigned explicitly: +<PRE> + setenv XPA_NSINET remote:12345,3000,12346 +</PRE> +In this case 12345 and 12346 should be open for incoming connections. +The XPA access port (which need not be open to the outside +world) is set to 3000. + +<P> +Finally, note that we currently have no mechanism to cope with +Internet proxy servers (such as SOCKS servers). If an XPA 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 XPA service with a remote machine. We hope to implement +support for SOCKS proxy in a future release. + +<!-- =section xpainet SEE ALSO --> +<!-- =text See xpa(n) for a list of XPA help pages --> +<!-- =stop --> + +<P> +<A HREF="./help.html">Go to XPA Help Index</A> + +<H5>Last updated: September 10, 2003</H5> +</BODY> +</HTML> |