summaryrefslogtreecommitdiffstats
path: root/xpa/doc/inet.html
diff options
context:
space:
mode:
Diffstat (limited to 'xpa/doc/inet.html')
-rw-r--r--xpa/doc/inet.html260
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>