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

			 Dial Up Networking
			 ------------------

		  This revision dated: 24th 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
~~~~~~~~~~~~
Dial-Up Networking (DUN) is a subsystem which allows Xrouter to connect
to other TCP/IP systems via a dial-up Public Switched Telephone Network
(PSTN) link.

This could be used for example to connect with an Internet Service
Provider (ISP), enabling Xrouter to link to other systems via the
Internet.  Or (if you have unmetered telephone calls) it could be used
for linking one Xrouter directly with another via the PSTN on demand.

DUN basically consists of:

	a) A script reader capable of configuring PPP, controlling a
	   modem and logging into a remote system.

	b) A system to invoke these scripts when required.

CAUTION: Due to other commitments, DUN development was halted abruptly
before it had been properly finalised, debugged and documented.  I
haven't had chance to pick up the pieces and finish the work, so you
are urged to use this system with caution.  I was intending to leave
it un-documented to discourage its use.  But I have now decided that
the best way to find the bugs and get the project completed is to let
others experiment with it and let me have their feedback.


Configuring DUN
~~~~~~~~~~~~~~~
Please see the interim documentation file MODEM.TXT for details of
how to configure Xrouter to use a modem.

Assuming you have a port configured for modem use, DUN requires at
least one dialler script, to control the dial and login sequence.

Dialler scripts are ordinary text files containing script commands
as detailed below, one per line.  Lines must not exceed 256 characters
in length.  The script file can be named as you wish, for example you
might like to name your AOL dial script "AOL.SCR".  You will need to
use this name later to identify the script, so it makes sense to call
it something meaningful, rather than "SCRIPT1.TXT".  Script files
must reside in the same director as XROUTER.EXE.

Next you must set up DUN to invoke your script whenever a connection
is required.  This is done by using the DUN ADD command (see below)
to record the peer's IP address and the name of the script used to
make the connection to that peer.  If you don't know the IP address
you may use a "dummy" address, e.g. "1.1.1.1", because it is simply
a handle used to invoke the appropriate script.  You should use one
DUN ADD command for each script.

Finally, you must add one or more entries to the IP routing table
whereby the "gateway" ip address is that of the peer (or the dummy
address as mentioned above).

For example, suppose my ISP is aol.com, and I want to route all
UK-bound IP traffic via them.  I have a modem connected to port
3, and I have created a suitable connection script named AOL.SCR.

a) I don't know the IP address of AOL's router, so I simply
   choose a dummy address of "192.168.1.1".

b) I then issue the command "DUN ADD 192.168.1.1 AOL.SCR", or
   include it in IPROUTE.SYS or BOOTCMDS.SYS.

c) Finally, I add a routing entry as follows:

   "IP ROUTE ADD 44.131.0.0/16  192.168.1.1  3  d"

   which means "route all 44.131.x.x (UK) traffic via (dummy)
   gateway 192.168.1.1 on port 3 (the modem port) using datagram
   mode.

Whenever Xrouter receives a frame with a destination address in the
44.131 series, it will now invoke the dial script AOL.SCR.


Script Commands Overview
~~~~~~~~~~~~~~~~~~~~~~~~

	CONTROL		Raise / lower RS232 DTR signal.
	MODE		Sets protocol to use upon sucessful login.
	PPP		PPP configuration commands.
	SEND		Send text.
	SLEEP		Temporary pause.
	WAIT		Wait for text in received data.


Script Commands In Detail
~~~~~~~~~~~~~~~~~~~~~~~~~

CONTROL - Raise / Lower RS232 DTR signal.

	Syntax: C[ontrol] <up | down>

	Example: CONTROL UP

	The CONTROL command is used to raise or lower the RS232 DTR
	(Data Terminal Ready) line.  Most modems require the DTR
	signal to be "up", and will disconnect or reset when the
	DTR signal goes down.  Those modems which do not do this by
	default can usually be configured to do so by including
	"&D2" in the initialisation string.


MODE	- Set protocol to use upon sucessful login.

	Syntax: M[ode] <kiss | ppp | slip>

	Example: MODE PPP

	This command specifies which protocol should be used after
	your system has sucessfully logged into the remote host,
	i.e. when the script ends without error.  It must preceed
	the dialling and login sequence, and any protocol dependant
	commands, such as the PPP commands.


PPP	- PPP configuration commands.

	Syntax: P[pp] <idle | ipcp | lcp | log | pap> [arg]

	Example: PPP IDLE 300

	PPP commands are used to configure the PPP subsystem for
	the connection being established.  You may find that the
	default configuration is sufficient, or you may need to
	use the PPP PAP command to specify your PAP login details
	if your ISP requires the use of PAP.  See PPP documentation
	for details of PPP commands.


SEND	- Send a line of text.

	Syntax: S[end] <text>

	Example: SEND ATDT01674302153

	The SEND command sends one line of text to the modem or the
	remote host, for example modem initialisation and dial commands,
	or login commands.  The <text> argument may contain spaces,
	and the system will append a carriage return/line feed.


SLEEP	- Temporary pause.

	Syntax: SL[eep] <millisecs>

	Example: SLEEP 5000

	The SLEEP command causes the script to pause for the specified
	interval.  For example, you would need a short delay after
	issuing a modem reset command, before any more command would
	be accepted by the modem.  When the pause is complete, script
	execution continues on the next line.


WAIT	- Wait for received text.

	Syntax: W[ait] <millisecs> <string> [exiterr]

	Example: WAIT 5000 Password: exiterr

	The WAIT command causes Xrouter to wait for specific responses
	from the modem or remote host.  The <millisecs> argument
	specifies the maximum wait interval.  The <string> argument
	specifies the string of characters for which the system must
	wait. It must not contain spaces, and must not exceed 20
	characters in length.  When the string is seen in the received
	data stream, the next script command is executed.

	If the "exiterr" argument is present, the script will abort
	if the string is not seen before the interval expires. If the
	argument is not present, the next script command will be
	executed if timeout occurs.


DUN Commands
~~~~~~~~~~~~
Dial up networking may be adminstered "on the fly" using the DUN
command.  The subcommands are:

	ADD	- Add a peer to the list
	DROP	- Remove a peer
	LIST	- List the peers
	LOG	- Display / set logging level.

The DUN subcommands are explained in more detail below:

ADD  -	Add a peer to the DUN peer list.

	Syntax: DUN A[dd] <callsign | ip_address> <script>

	Examples: DUN ADD gb7tyr	gb7tyr.scr
		  DUN ADD 62.31.176.22	pipex.scr

	Creates an association between a callsign (for KISS links)
	or gateway IP address (for PPP or SLIP links) and a DUN
	script.


DROP -	Remove a peer from the DUN peer list.

	Syntax: DUN D[rop] <callsign | ip_address>

	Example: DUN DROP 62.31.176.22

	Removes a previously created association between a callsign
	or gateway IP address and a DUN script.


LIST -	List the DUN peers.

	Syntax: DUN L[ist]

	Lists the peers to whom a dial-up connection may be
	established, and the names of the scripts used to make
	the connections.


LOG  -	Display or set logging level.

	Syntax: DUN LO[g] [0-255]

	The DUN LOG command sets the level of logging, for
	diagnostic purposes.  The argument is a flag field,
	comprising the sum of the following values:

		1	Log starts, stops and errors.
		2	Log all script lines.
		4	Log responses from modem or host.

	A value of 0 disables all logging.  If no arguments are
	given, the current logging level is reported.


The DUN ADD and DUN LOG commands may also be used in IPROUTE.SYS
and / or BOOTCMDS.SYS to set up the system at boot time.

