                             +-----------------+
                             | 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.4	Added the use of AFS for firewalling with IP Chains
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 perl
/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         3274 Dec 22 01:45 afs.cfg
-rwx------   1 root     root         5817 Dec 22 01:45 afs.pl
-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?

afs.cfg:
	The configuration file for the Advanced Firewall System (see below).
Each line denotes a firewall that will be placed or removed when afs.pl is
executed.  Each line has from 3 to 5 paramaters.  Any time a '#' character
is encountered, the rest of the line is accounted as a comment.
	ACCESS -- This is what to do with this rule:
		ALLOW - will let packets matching this rule through
		DENY - will send back a DENY message and not allow a
		       connection if this matches.
		REJECT - will do the same as DENY, however it does not
			tell the other end that they have been denied.
		Only the first 3 characters in an ACCESS type are relivant.
		Putting a '+' in front of the access type will cause AFS
		to turn 'logging' on for any packet that matches it.
	IP - This is the starting DESTINATION IP address of the packet.
		This is used in conjunction with MASK to work out the
		destination ip range (this MUST be ip's on your end of
		the network, as all packets are filtered INBOUND).
	MASK - This is used in conjunction with IP to create a range of
		IP's to be firewalled.  This can be either a network
		bit (0-32) or a full netmask (0.0.0.0-255.255.255.255).
		Please look in the ppp-settings file for more help on this.
	PROTOCOL - This is a list of protocols that the rule applies to.
		This is an optional paramater.  More than one protocol
		may be specified on the same line, the options are TCP,
		UDP and ICMP.  When specifying more than one protocol,
		they must be seperated by a ':' (eg. TCP:UDP).
		Putting a '+' in front of the protocol turns the SYN
		bit on, meaning that this rule will match NON-ESTABLISHED
		connections (ie. ones that are initiated from the outside
		world, not from the end-destination).  This is often used
		with a DENY rule to only allow connections FROM the local
		host through, and deny anything TO the local host.
		The '+' option is only valid for TCP.
	PORTS - This is a port number or range of ports to apply the rule
		to.  This is an optional paramater.  If more than one port
		is specified, they must be seperated by a ':' (eg. 0:1024).
		You may only specify 2 ports (beginning and end of range),
		and they must have numbers between 0 and 65535 inclusive.
		PORTS are only valid for TCP and UDP protocols.
	TYPE - This is the type of ICMP packet to block.  The example
		configuration file has a list of all valid types, this list
		can also be gained by typing 'ipchains -h icmp'.  You may
		only specify 1 type per line, no checking is done on validity.
		This is an optional paramater, and only valid for the ICMP
		protocol.  A TYPE is used IN PLACE of PORTS, not aswell as.
NOTE:  Specifying PORTS/TYPE with multipal protocols that include
	ICMP will cause an error (as ICMP and TCP/UDP have different
	definitions for the 5th paramater).
NOTE:  If no protocol is supplied, the rule will apply to ALL.
NOTE:  If no PORTS/TYPE are supplied the rull will apply to ALL.
NOTE:  IP addresses and port numbers must be NUMERICAL ONLY.

afs.pl:
	Advanced Firewall System.  This is a perl front-end to IPCHAINS
specifically designed for building firewalls -- if you like, you can associate
it with a CISCO router's 'access list'.  It was written so that I wouldnt have
to have a series of commands, etc to build/drop a firewall in the ip-forwarding
file anymore, I could just have a logical configuration file, and just go '+'
or '-' to activate or deactivate (respectively) the firewall.  The script also
does full syntax checking on the options you give it (and it will skip any line
that has incorrect syntax or would perform an illegal function).
	SYNTAX: afs.pl <+|-><interface>

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
