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

			   PSTN Modem Support
			   ------------------

		  This revision dated: 20th 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
~~~~~~~~~~~~
Xrouter may be connected to one or more Public Switched Telephone
Network (PTSN) modems, for dial-in and dial-out operations.

Dial-in would, for example, allow users and/or sysops to connect to
the router and operate it using a dumb terminal or a standard
terminal package such as Telix or Hyperterm.  Alternatively, after
login, the link may be switched into SLIP or PPP mode for TCP/IP
operations, in exactly the same way as a dial-up Internet Service
Provider.

Dial-out allows Xrouters to be linked with each other or with an
Internet service provider, for the purposes of on-demand wired
routing, or Internet Connection Sharing.

A single modem may be used for both dial-in and dial-out operations
on the same port, although not at the same time of course!


Suitable Modem Types
~~~~~~~~~~~~~~~~~~~~
Almost any external modem is suitable, providing it can be
initialised by a single string of characters and can be configured
to disconnect when DTR is dropped.

Internal modems should preferably be of the type where the COM number
IOADDR and IRQ can be preset by hardware jumpers.  I have no
experience of using other modem types.  The cheap "Winmodem" types
which require a Pentium processor are definitely not suitable.


Hardware Configuration
~~~~~~~~~~~~~~~~~~~~~~
External modems should be connected to a serial port using a cable
with at least 8 connections, namely TXD, RXD, RTS, CTS, DTR, DSR,
DCD and ground.  The RI (ring indicator) connection is not needed.

Internal modems should be configured to use a spare COM number and
IRQ.


Software Configuration
~~~~~~~~~~~~~~~~~~~~~~
Each modem requires an ASYNC interface definition in XROUTER.CFG,
with COM (or IOADDR & IRQ if non-standard) configured for the
appropriate serial port or modem card.  You should use PROTOCOL=MODEM,
and FLOW=1.  I would suggest setting MTU=576.

To each "modem" interface should be attached a PORT with at least
INTERFACENUM and ID specified.  If the modem requires an initialisation
string, add INITSTR=<initstring>, e.g. to set the modem into auto
answer mode use "INITSTR=ATS0=1".  If you don't include the INITSTR
keyword, the modem configuration is not altered.

If your modem does not, by default, hang up when the RS232 DTR signal
is dropped, you should configure it to do so by including "&D2" in the
initialisation string, for example: "INITSTR=ATM0S0=1&D2".

Example:
;
INTERFACE=5
	TYPE=ASYNC
	COM=3
	SPEED=57600
	PROTOCOL=MODEM
	FLOW=1
	MTU=576
ENDINTERFACE
;
PORT=2
	ID=PSTN Modem port
	INTERFACENUM=5
	INITSTR=ATS0=1
ENDPORT
;

If you will be allowing incoming calls, you must set up a callsign and
password entry for each user in USERPASS.SYS.


Dial-in Operation
~~~~~~~~~~~~~~~~~
If you have configured the modem for auto-answer, PSTN callers must
sucessfully complete a callsign and password challenge before they
are allowed to use the command line.

The callsign must be a proper amateur radio callsign, i.e. not a
username.  If a proper callsign is not given, or if the callsign is
not found in USERPASS.SYS, or if an incorrect password is given,
the user is immediately disconnected.  If this sounds unforgiving,
it's meant to be!  It will cost hackers the price and time delay of
a separate phone call for each attack.

If the callsign and password challenge is sucessfully completed, the
caller will be allowed to use the command shell exactly the same
as a radio caller.

Xrouter will disconnect the caller after 15 minutes of inactivity.
You may initialise the modem to disconnect after a shorter interval
if necessary.


The XLINK command
~~~~~~~~~~~~~~~~~
If the caller (e.g. using NOS) wishes to establish a TCP/IP link with
your router, the XLINK command is used to switch the ASCII link into
SLIP ("XLINK SLIP") or PPP ("XLINK PPP") mode.  Xrouter will respond
with "Entering SLIP mode" or "Entering PPP mode", and thereafter will
no longer respond to ASCII commands.  SLIP or PPP mode may only be
terminated by disconnection.

In order to use SLIP or PPP modes, Xrouter must have at least a global
IPADDRESS, and you must set up IP routing to the caller's IP address
on the modem port.  You could either allow each caller to use their
own IP address, and have one routing entry for each caller, or you
may choose to require all callers on a particular port to use the
same IP address (since only one may connect at any time) and set up
a single routing entry.

For example, you could tell each of your SLIP/PPP callers to set
their IP address to 192.168.73.88, which is one of the "unregistered"
addresses anyone can use.  If your modem is on port 2, you would
add the following entry to IPROUTE.SYS:

route add 192.168.73.88/32 * 2 d

Which means "route datagrams for 192.168.73.88 directly on port 2
using datagram mode".

No ARP entry is necessary for the caller, because SLIP and PPP do
not use "hardware addresses".


PPP mode
~~~~~~~~
SLIP mode requires no extra configuration, but PPP mode optionally
uses an extra file to configure the PPP system for receive
operations on the modem port.  For example, you may wish to use one
IP address when making outgoing connects and a different one when
receiving incoming connects.

The optional file is named "PPPHOST.n" where n is the number of the
modem port, e.g. "PPPHOST.2".  You may have a separate file with
a different configuration for each modem port if required.  The
file should be located in the same directory as Xrouter itself
and can contain any PPP configuration command.

Configuring PPP is outside the scope of this document.

The PPP link inactivity timeout defaults to 5 mins, but can be
overridden by including the PPP IDLE command in the PPPHOST.n file.

