
                      XROUTER INTERIM DOCUMENTATION
                      =============================

			   INTERNAL Interface
			   ------------------

		  This revision dated: 25th July 2002



Purpose Of This Document
~~~~~~~~~~~~~~~~~~~~~~~~
"Interim" documentation is that which hasn't yet been incorporated into
the sysop manual.  It is intended to provide easily-accessible and
printable guidance for the configuration and use of new and possibly
experimental features, and is not guaranteed to be complete, accurate,
or permanent.  As development proceeds and feedback is received, the
software and this documentation may be modified.  When the development
cycle is complete, the information herein will be incorporated into the
sysop manual, and this document will be discontinued soon afterwards.


Introduction
~~~~~~~~~~~~
A new INTERNAL interface type was added in version 174, allowing
applications using the BPQHOST API to interconnect with Xrouter
using HDLC, as if via a wire link.


So what?
~~~~~~~~
The BPQHOST Application Interface allows applications (e.g. a BBS)
running "above" the router to "connect" to the router's command
interface and issue plain text commands.  It also allows the
applications to receive incoming connects from users.  And lastly,
it allows applications to directly access the radio ports using raw
HDLC.

Unfortunately, BPQ's interface was designed a long time ago for a
pure AX25 system, and does not specifically cater for TCP/IP.

If the application (e.g. PZTBBS) has its own TCP/IP stack, it needs
a way of exchanging datagrams with Xrouter, to enable users
to telnet from BBS to router and vice versa, among other things.

For example, if Xrouter has an Ethernet port, the application may
need to route datagrams via it, but the host AI only allows the
application to talk HDLC to AX25 ports.

Unlike other interfaces, which connect Xrouter with the "outside" world,
the INTERNAL interface connects Xrouter with the "inside" world, i.e.
other applications on the machine.  It is similar in function to a
wired KISS link between two machines, except that it runs raw HDLC
not KISS.

Anything sent by Xrouter, on the port attached to the INTERNAL
interface, is sent to the host interface, and that port effectively
receives from the host interface.  Thus, if port 15 is an INTERNAL
port, any aplication which wants to talk HDLC to Xrouter can do so
by interacting with the BPQ "raw" host AI, using "radio port" 15.

The port number must be between 1 and 127 because BPQHOST application
interface only allows 7 bits for the port number.


Setting Up An INTERNAL Interface
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

The entries in XROUTER.CFG should be similar to this:

	;
	INTERFACE=5	
		TYPE=INTERNAL
		PROTOCOL=HDLC
		MTU=256
	ENDINTERFACE
	;
	PORT=7
		ID=Internal link with GB7PZT
		INTERFACENUM=5
	; etc...
	ENDPORT

The interface and port numbers are for illustration only, and you should
use the ones appropriate for your system.

The only PROTOCOL supported at present by INTERNAL interfaces is HDLC.
Other protocols will be added if anyone needs them.

Only one PORT may be attached to an INTERNAL interface, so the CHANNEL
keyword is not necessary.

In the above example, BBS application GB7PZT is configured to send its
TCP/IP traffic, encapsulated in AX25, to "radio port 7" on the
BPQHOST interface.  Xrouter receives it as if it came off-air, and
sends replies back to port 7 whereupon they are received by GB7PZT.


Copyright (c) Paula Dowie 2002
