                             +-----------------+
                             | PPP System v1.3 |
                             +-----------------+
                   By Preston Elder <prez@antisocial.com>
                    of Shadow Realm <www.srealm.net.au>.


1. INTRODUCTION

	One of the most common things people want to do with their UNIX
system is connect it to the Internet via. PPP.  This is not all that hard
to do really,  but it can be confusing.  Many people have Dynamic IP's
allocated to them by their ISP, or have multipal ISP's.  That is the reason
I have created this complete PPP system that anyone can edit and use within
5 minutes :)
	Basically this system is a re-vamped version of the PPP system in
the Linux HOWTO's with modifications for more than one PPP link at a time,
and multipal ISP definitions, and a couple of nice optimizations/extras.
Thanks a bundle to Al Longyear <longyear@netcom.com> for supplying these.
	This software is freely distributable under the GNU license.

2. WHATS NEW?

1.3d	Minor bugfixes (syntax errors mostly).
1.3c	Added dialacc as a dupe of account (ipchains) that will be zeroed
	    in ip-down, account is no longer flushed (so user can do hourly
	    accounting or whatever).
	chkup now checks to see if its running (so 2 redials doesnt kill
	    confuse the system!).
1.3b	Added ipchains support (kernels 2.1.102+)
1.3a	Added CHAP/PAP Authentication ability (and edited ISP-* files).
	Copied in new options file and optimised scripts for it!
	Added "DEBUG" option to settings file.
	Now able to pass extra manually-set PPPD and CHAT options.
	Fixed the 'modem' script, and ??firewall scripts (see 1.2g).
1.2g	Added feature that executing /etc/ppp-settings start [options]
	    will make it start PPP (if options are used, with those opts).
	Added MASQ veriable in ppp-settings for non-masq networks with
	    masq compiled into kernel.
	Changed firewalls to use PPP line instead of LOCAL IP.
1.2f	Added copying over of a resolv.conf (for each ISP or default).
	Fixed making of getln, and added port speed setting (baseSPEED).
1.2e	Made ip-forwarding a little more sensable (no more flushing).
	Added the ip-up.local and ip-down.local file availability.
	Removed kerneld restarting (do it yourself in .locals or something)
1.2d	Added ISP retry (ppp-retry) (and MAXDIAL veriable).
1.2c	Fixed a few redial bugs, and included getln source.
1.2b	Added ISP cycling (ppp-cycle).
1.2a	Added ppp-off -a, and fixed ppp-off as a whole.
1.1	Moved all settings to the ppp-settings file, to make more
	configurable, etc.
1.0	First release, FULL of bugs, and VERY unconfigurable.

3. WHAT YOU NEED

	To run this system you will need the following files:
/usr/sbin/pppd chat
/usr/bin/cut tail head grep
/sbin/route ifconfig (ipfwadm or ipchains for firewalling)
/bin/cat awk ps echo rm kill date
/usr/local/bin/getln (included)

	Also you will need in the kernel:
* IP Firewalling
* PPP
* IP Masquerading (If you wish to route to more
  than one system via. a dynamic or single IP)

4. INSTALLATION

Pretty simple ...

make
make install

If this doesnt work, see below for where to put all the files
contained in this package.

Other steps of installation include:

	- Edit the following files for your own config:
		ISP-data
		ISP-ppp-on-dialer
	- Create a DEFAULT (if no ISP- one found) resolv.conf (optional)
	- Create an ISP-resolv (optional)

5. THE PACKAGE

Just a make install should work, but if it doesnt, copy the files out of
the current directory with the following permissions into the following
directories:

/etc/ppp:
-rwx------   1 root     root          808 Dec 22 01:45 ISP-data
-rwx------   1 root     root          836 Dec 22 01:45 ISP-ppp-on-dialer
-rw-------   1 root     root        10354 Dec 22 01:45 README
-rw-------   1 root     root          989 Dec 22 01:45 README.1st
-rw-------   1 root     root           78 Dec 22 01:45 chap-secrets
-rwxr-xr-x   1 root     root          774 Dec 22 01:45 chk4net
-rwx------   1 root     root         1176 Dec 22 01:45 chkup
-rwxr-xr-x   1 root     root          518 Dec 22 01:45 curdef
-rwxr-xr-x   1 root     root          644 Dec 22 01:45 curhip
-rwxr-xr-x   1 root     root          639 Dec 22 01:45 curip
-rwx------   1 root     root         1885 Dec 22 01:45 ip-down
-rwx------   1 root     root         4327 Dec 22 01:45 ip-forwarding
-rwx------   1 root     root         1199 Dec 22 01:45 ip-up
-rwx------   1 root     root          825 Dec 22 01:45 mkfirewall
-rwx------   1 root     root         1895 Dec 22 01:45 modem
-rw-------   1 root     root           11 Dec 22 01:45 options
-rw-------   1 root     root           96 Dec 22 01:45 pap-secrets
-rwx------   1 root     root         1275 Dec 22 01:45 ppp-cycle
-rwx------   1 root     root         2345 Dec 22 01:45 ppp-off
-rwx------   1 root     root         2733 Dec 22 01:45 ppp-on
-rwx------   1 root     root         1404 Dec 22 01:45 ppp-retry
-rwx------   1 root     root          825 Dec 22 01:45 rmfirewall

/etc:
-rwx------   1 root     root         3340 Dec 22 01:45 ppp-settings

/usr/local/bin:
-rwxr-xr-x   1 root     root         5328 Dec 22 01:45 getln

NOTE: if make didnt work either, you will need to use the following election
rules to figure out the .chains, .nochains, .something and .nothing files.
	/proc/net/ip_fwchains exists, and /sbin/ipchains is executable:
		use *.chains and *.something
	/sbin/ipfwadm is executable:
		use *.nochains and *.something
	otherwise (disable firewall/masquerading):
		use *.nothing

6. THE FILES

ISP-data:
	This file is the most vital of all.  It contains the information
you use to dial into your ISP (ie. ISP's Phone number, Login name and
Password).

ISP-ppp-on-dialer:
	This file contains the dialing sequence to your ISP.  It is VERY
likely you will need to modify this file with the sequence to dial into
your own ISP.  If you need to use CHAP or PAP authentication, editing this
file is a necessity.  The default sequence with this system is as follows:
	Dial number
	Recieve prompt "sername:" and send your login name
	Recieve prompt "assword:" and send your password
	Then send "ppp" (without being prompted for anything"

ISP-resolv:
	This file replaces the default resolv.conf when connected to this ISP.

README:
	This file (duh!)

README.1st:
	Now, I DONT have to explain this too do I?

chap-secrets:
	Usernames, passwords and IP addresses for CHAP authentication.

chk4net:
	A little script to check if the internet is online.  This file accepts
an optional paramater, being the device you wish to check on (eg. ppp0). This
program will exit with 0 if connected, 1 if not.

chkup:
	This should not be executed manually ... This checks the PPP link
established correctly with ppp-on, and if not, call's ppp-cycle to redial.

curdef:
	This file outputs the current default routing device.

curhip:
	This file will output your host's IP. (ie. the system you are
connected to).  This script accepts an optional paramater being the device
to check on (eg. ppp0).

curip:
	This file will output your IP.  This script also accepts an option
paramater of what device to check (eg. ppp0).

getln:
	Little program to get a line, range of lines, or multipal lines from
a file or STDIN ... needed for ppp-cycling.

getln.c:
	Source code of above, included if the binary does not work (the binary
is made for Linux systems).  Compiled as: gcc -O2 -o getln getln.cpp

ip-down:
	This script is automatically executed by pppd when the link it was on
goes down. This does  things like Log and flush the ip-forwarding logging,
kill the old pppd and all lockfiles created by it and ip-up.

ip-down.local:
	This script is totally optional.  If this file exists in ${basePPP},
it will execute just before the redialing/cycling/aborting. (This file must
be executable, else it is skipped).  It should contain all your local tweaks,
so you can leave the PPP system as standard as possible.

ip-forwarding:
	This script is executed by ip-up to create a firewall / forwarding /
masquerading for your system.

ip-up:
	This script is automatically executed by pppd when the link is
established. This does things like execute ip-forwarding.

ip-up.local:
	This script is totally optional.  If this file exists in ${basePPP},
it will execute just after everything in ip-up is completed. (This file must
be executable, else it is skipped).  It should contain all your local tweaks,
so you can leave the PPP system as standard as possible.

mkfirewall:
	This is a handly little script to create a firewall on someone :)
This file accepts 1 or 2 paramaters ... the first is the IP to firewall,
and the second is the device to firewall them on.

modem:
	This will establish a ppp link on an existing dialup connection. This
accepts an optional 4 paramaters ... being TTY device, Remote IP, Local IP
and Netmask.

options:
	System default options for PPPD (read before command-line).

pap-secrets:
	Usernames, passwords and IP addresses for PAP authentication.

ppp-cycle:
	This file should not be executed manually.  This will re-call ppp-on
to redial.  This script accepts 1 paramater ... the TTY device it controls.
This is called ppp-cycle because it will look for a ${basePPP}/cycle.$1, and
will cycle to the next ISP in the list (or go back to top of list) if that
file exists, if not, it will simply redial the current ISP.  This is
disabled in favor of ppp-retry if the MAXDIAL in ppp-settings is set above
0. (see ppp-retry for more details).

ppp-off:
	This will sever any ppp connection.  You may specify which ppp links
to kill,  or -A for all of  them.

ppp-on:
	This is the main ppp dialing script ... it will auto-background
itself, and accepts an optional 2 paramaters.  The first is the ISP to connect
to (default is used if not specified) and the second is the device to connect
on (default used if not specified).  The ISP should have its own ISP-* files
with its name as a prefix instead of ISP.   eg. if you typed ppp-on SREALM,
then a SREALM-data and SREALM-ppp-on-dialer file should exist.
	New in v1.2, you can type - on the ISP and specify a tty line and it
will automatically choose the first ISP in cycle.<tty> if it exists, or use
the default ISP if it doesnt.  eg. ppp-on - ttyS1

ppp-retry:
	This file should not be executed manually.  This will re-call ppp-on
to redial.  This script accepts 1 paramater ... the TTY device it controls.
This is called ppp-retry because it will look for a ${basePID}/$1.attempt, and
check the dial attempt number, and abort if it has tried dialing too many
times without connect, otherwise it will simply redial to current ISP.  If
MAXDIAL in ppp-settings is set to 0 or not set, this will be disabled in
favour of ppp-cycle. (see ppp-cycle for more details).
NOTE: DO NOT create ${basePID}/$1.attempt manually!

resolv.conf:
	This file tells your system who to ask when resolving names such as
www.microsoft.com to IP's.  There are 3 common 'commands' in this file:
	- domain - This tells nslookup (or whatever) your local domain.
	  (eg. srealm.net.au)
	- search - This tells nslookup (or whatever) to search these domain
	  extensions if it is not found on its own - this is handy if you
	  want to be able to type 'nslookup castle' and it resolve to your
	  local machine castle which is actually castle.srealm.net.au.  You
	  can specify more than one search doman, they're searched in order.
	- nameserver - This designates who to resolve with - IP'S ONLY.  You
	  can specify up to three - If you are running a DNS for your local
	  network, the first would be the DNS machine, the next is your ISP's
	  DNS machine, and third is usually some 'guarenteed' host (eg.
	  internic), or your ISP's isp, or just left out. 
	
rmfirewall:
	This will remove a firewall made by mkfirewall.  The same 2 paramaters
are accepted by it.

7. THANKS TO
Lord Striker <striker@darker.net> for helping me test this system :)
Archangel <midnight@goth.net> for ppp-retry option idea :)
Everyone who uses this system and reports bugs if they are found :P
