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

		      Point to Point Protocol (PPP)
		      -----------------------------

		  This revision dated: 21st 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.


1) Introduction
~~~~~~~~~~~~~~~
Point to Point Protocol (PPP) is a protocol suite intended for use
over simple links which transport packets between two peers, such as
an RS232 link.

Unlike SLIP, it includes facilities for link control (e.g. management
of a dial up link), user authentication, negotiation of IP addresses,
and the multiplexing of several protocols across a common link.

It is designed to be self configuring.  Most of the options have
standard default values, and peers negotiate anything which differs
from the default.

Xrouter currently implements the most common PPP sub-protocols:

	- Link Control Protocol (LCP)
	- Password Authentication Protocol (PAP)
	- IP Control Protocol (IPCP)

Most sysops will have no need to remember these protocol names and
acronyms.  However, for those who wish to experiment, each protocol
has its own set of commands.

PPP has largely replaced SLIP for dial-up Internet access, and the
interconnection of peers via RS232.

If you want to know more about the internal workings of PPP, it is
specified in RFC1661.


2) Configuring Xrouter for PPP
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
There are three ways in which PPP may be used:

	- Wired links.
	- Dial-in.
	- Dial-out.

The first case requires an interface to be configured to use PPP, but
the other two cases temporarily establish a PPP link on a MODEM
interface.  Each case is described in more detail below:


2.1) Using PPP on Wire Links
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
In XROUTER.CFG, define an interface with TYPE=ASYNC and PROTOCOL=PPP.
For example:

INTERFACE=1
	TYPE=ASYNC
	COM=1			; 1-4 or specify INTNUM/IOADDR
	SPEED=19200		; Adjust as necessary
	PROTOCOL=PPP
	MTU=1600
ENDINTERFACE


Now "bind" a port to that interface thus:

PORT=1
	ID=PPP link to Win98	; Text to identify port
	INTERFACENUM=1		; Bind to PPP interface
	IPADDRESS=192.168.0.4	; Optional (see below)
ENDPORT


The use of IPADDRESS is optional.  If the keyword is omitted, Xrouter's
"global" IP address will be used on that port.  If the address is
specified as 0.0.0.0, it signifies that a "dynamic" IP address should
be obtained from the peer, otherwise the specified address will be used.

The port is now ready for PPP using the standard PPP defaults, but if
it requires any further configuration you may include the relevant
PPP configuration commands in the file BOOTCMDS.SYS, which is read
by Xrouter after it has finished executing XROUTER.CFG.


2.2) Using PPP on Dial-in links
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The interface and port should be configured for PROTOCOL=MODEM as
described in the interim documentation file "modem.txt".

When a logged-in caller issues the command XLINK PPP, Xrouter will
automatically re-configure the port to support PPP.  It will then
look for the file "PPPHOST.n", where n is the port number, and
if found, the PPP configuration commands within the file will be
executed.  The file may optionally contain NAT configuration commands
if required. The PPPHOST file is optional.  If not present, PPP will
be initialised to the standard defaults.

When the hardware link disconnects (e.g. user says goodbye or hangs
up, link times out, or sysop kills it), the port is reconfigured
to its original MODEM protocol.


2.3) Using PPP on Dial-out links
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The interface and port should be configured for PROTOCOL=MODEM as
described in the interim documentation file "modem.txt".  The local
IP address follows the same rules as case (2.1) above, but may be
overridden temporarily by IPCP commands as demonstrated below.

The dialler script (for description of dial-up-networking see
interim documentation file DUN.TXT) should contain the command
"MODE PPP" plus any required PPP configuration commands.  Here is
an extract from a typical connection script:

; Link will use PPP
mode ppp
;
; Configure my authentication username and password
ppp pap user gb7pzt bsfjflavs
;
; Set inactivity timeout to 2 minutes
ppp idle 120
;
; Enable ppp state logging
ppp log 1
;
; Set my (static) IP address for the duration of this call
ppp ipcp local address 194.123.110.4
;
; Now dial the host
send ATDT07979654234
;
etc...

The PPP configuration will persist until the call terminates, then
the port will revert back to MODEM protocol to await the next incoming
or outgoing call.


3) PPP Configuration Commands
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
All PPP configuration commands start with "PPP".

Syntax: PPP <port> <IDLE | IPCP | LCP | LOG | PAP> [arg]

IDLE [secs]		Display or set link inactivity timer
IPCP <cmd>		Execute an IPCP command
LCP <cmd>		Execute an LCP command
LOG [0-255]		Display or set PPP logging (ppplog.txt)
PAP <cmd>		Execute a PAP command

IMPORTANT: When used from the command line, or with a BOOTCMDS.SYS
file, the first argument must be a port number.  However, PPP
commands used within PPPHOST and dialler scripts *do not* include a
port number, because Xrouter knows which port is executing the script.

e.g. at the command line: PPP 3 IDLE 300
     in a dialler script: PPP IDLE 300


3.1) IPCP Subcommand:
~~~~~~~~~~~~~~~~~~~~~
Syntax: PPP <port> IPCP <LOCAL | REMOTE> <ADDRESS | DNS> [arg]

ADDRESS [n.n.n.n]	Display or set IP address (n = 0-255)
DNS [n.n.n.n]		Display or set Domain Name Server IP address


3.2) LCP Subcommand
~~~~~~~~~~~~~~~~~~~
Syntax: PPP <port> LCP <LOCAL | REMOTE> <AUTH | DEFAULT | MRU> [arg]

AUTH [PAP]		Display or set authentication protocol
DEFAULT			Restore LCP parameters to defaults
MRU [128 - 4096]	Display or set Maximum Receive Unit


3.3) PAP Subcommand
~~~~~~~~~~~~~~~~~~~
Syntax: PPP <port> PAP <USER> [arg]

USER [<username> <password>]	Display or set authentication details

Example: PPP 1 PAP USER g8pzt zedfrgc


4) IP Routing
~~~~~~~~~~~~~
When a PPP link opens, a route to the peer is automatically added to
Xrouter's IP routing table.  If the peer indicates that it knows the
addresses of a primary and secondary DNS, those are added to Xrouter's
DNS list.


5) PPP Logging
~~~~~~~~~~~~~~
PPP system activity can be recorded in file PPPLOG.TXT for diagnostic
purposes.  The amount of detail is controlled by number specified in
the "PPP <port> LOG n" command as follows:

	0	No logging
	1	PPP start / stop / timeout events
	2	As 1, plus layer up / down events
	3	As 2, plus layer start / stop events
	4	as 3, plus option accept / reject events
	5	as 4, plus hexdump of configuration packets

You are advised against using the higher levels other than on a
temporary basis because they can create very large logfiles.  On
a slow machine, the disk writes might take so long that
configuration timeouts could occur, with consequent retries and
failure.


Appendix: PPP Defaults
~~~~~~~~~~~~~~~~~~~~~~
LCP MRU		1500 octets
LCP AUTH	No authentication


Finally
~~~~~~~
If this document leaves questions unanswered, *please* tell me, either
by email: g8pzt@blueyonder.co.uk
or Packet: G8PZT @ GB7PZT.#24.GBR.EU

---------------------------------------------------------------------------
Copyright (c) 2002 Paula Dowie
