pppoe: a PPP-over-Ethernet redirector for pppd
Copyright (C) 1999 Luke Stras

Introduction
============

This program can be used to enable PPPoE support using the pppd
daemon.  PPPoE is a technique for the encapsulation of PPP streams
inside of Ethernet frames.  This technology is being deployed by
high-speed Internet access providers (cable modems, xDSL, etc.) in
order to decouple the supply of bandwidth from ISP services.  In
particular, in Canada, the Bell Sympatico ADSL service is moving from
DHCP-based access control to PPPoE.  Further details on PPPoE can be
found in RFC2516.

Installation
============

Requirements
------------

Linux 2.0.0 or later (may work on other platforms, but untested)
                     has been tested on Intel platforms
OR
OpenBSD 2.5 or later (may work on other platforms, but untested)
                     has been tested on SparcStation IPX
pppd 2.3.7 or later

Note that older versions of pppd may work if you obtain the
'pty-redirect' program.  Various copies are available on the 'Net.  I
haven't tried this myself, though.

Compiling
---------

Compile and install pppd.  Then:

Unpack:

# tar xzvf pppoe-0.3.tar.gz

Edit the Makefile to set options.  Currently, you can set one option
which attempts to deal with buggy Access Concentrators that
occasionally send out duplicate packets.

Compile:

# make

Install to some convenient directory:

# cp pppoe /usr/local/sbin

Create an appropriate secrets file.  For example, Sympatico ADSL uses
PAP for authentication, so we need an /etc/ppp/pap-secrets file.  The
file consists of three columns, separated by whitespace.  The first
column is the user name.  For Sympatico, this is the Sympatico Member
ID (b1*).  This is case sensitive, and you must add '@sympatico.ca' to
the end.  The second entry is the server name.  This should be '*'.
The third entry is the secret.  For Sympatico users, this will be your
Sympatico password.  So a sample /etc/ppp/pap-secrets file might look
like:

b1aaaaaa@sympatico.ca * password

Make sure your ethernet interface is up:

ifconfig eth0 up

Then, start pppd like this:

pppd pty '/usr/local/sbin/pppoe -I eth0' noipdefault defaultroute \
     hide-password passive persist name b1aaaaaa@sympatico.ca

Options
=======

pppoe can take two run-time options:

-I if
  Specifies the ethernet interface to use.  The interface *must* be up
  before the program will start.

-L file
  Specifes a log file.  Note that pppd chroots to '/', so the path
  should be absolute.  Note that the log can get large.

-E file
  Specifies an error log file.  This is the file that diagnostic/error
  messages go to.  By default, it is stderr.  Note that the path must
  be absolute.

-Fa
  Specifies that partial packets should always be forwarded.  Default
  is no forwarding of partial packets.

-Fs
  Specifies that the program should search for start-of-packet data in
  the data stream from pppd.  Default is no forwarding of partial
  packets.

-V
  Prints the version number, and exits.

Masquarading and Stuff
======================

It seems that a lot of people are using this software to run on small,
cheap computers acting as firewalls or masquaraders for small
networks.  This section deals with some of the issues and problems
relating to this.

It appears that there is some kind of problem in the IP framgentation
code in the Linux networking chain -- either at the kernel level, or
in pppd.  When a Linux router receives a IP packet on an interface and
is asked to forward it to another interface which has an MTU smaller
than the packet size, something goes wrong.  pppd will spit out a
packet which is MTU bytes in size, and then it will output the rest of
the packet, BUT NOT ENCODED AS PER RFC1662.  The net result of this is
that pppoe will see this data, and will abort with an "invalid data"
message.  This behaviour has been modified in this version.

If no '-F' option is given, these overflow packets are silently
dropped.  This will likely cause problems with data not getting where
it's supposed to go; however, the connection should remain up.

If a '-Fa' option is given, then whatever gibberish pppd outputs will
be faithfully forwarded inside a PPPoE frame.

If a '-Fs' option is given, then the pppd output stream is searched for
the start of a valid RFC1662 packet, and that data is sent.  Note that
'-Fa' will over-ride '-Fs'.

However, to avoid problems altogether, it is best to set the MTU on
all machines behind the firewall.  The MTUs should be set to about
1400 or so.  The way this is done is as follows:

Under Linux (and, presumably other Unix-workalikes):

# /sbin/ifconfig eth0 mtu 1400

where eth0 is your Ethernet interface.

Under Windows (95/98; may work under W2K):

Using a registry editor, set

HKEY_LOCAL_MACHINE\System\CurrentControlSet\Services\Class\NetTrans\000X\
MaxMTU=1492

all on one line (note that the 1492 is a string value).  Registry
entries are case-sensitive.

The 'X' depends on what your interface is.

Under Windows NT (thanks to Shawn Sulma for this)

Using a registry editor, set 
HKEY_LOCAL_MACHINE/System/CurrentControlSet/Services/El90x1/Parameters/
Tcpip/MTU=1492<p>

(note that the 1492 is a DWORD)
The "El90x1" is replaced with your card entry.

Bugs
====

pppd will occasionally negotiate a connection, but refuse to transmit
any packets.  I've found that adding the 'debug' option to the pppd
command line seems to fix this problem.  Is this a race condition of
some kind?  I don't konw.

Occasionally, the ppp link negotiation enters an infinite loop.  The
cause is unknown, and the only solution is to try again.  I believe
this may have something to do with a bug in Access Concentrator used
by Bell, but I'm not sure.

Acknowledgements
================

Thanks go to:

Matt Robinson for the OpenBSD port and some major efficiency fixes.

Dave Wortman for telling me how to port it to libc 5

The teeming multitudes for testing and using this software, and
providing feedback.

And no thanks at all to Bell Nexxia and Sympatico, for using PPPoE in
the first place.  There *have* to be better solutions.  And don't get
me started on buggy RedBac hardware, either.
 
Author Information
==================

I can be reached via e-mail at <stras@ecf.toronto.edu>.  This program
can be found at http://www.ecf.toronto.edu/~stras/pppoe.html

README.BSD

This version of Luke Stras' PPPoE redirector includes support for OpenBSD.
Support for other BSD variants is possible but requires some porting.
To compile for BSD, you will need to add "-DUSE_BPF" in the DEFINES=
string in the Makefile.  You will also need to link against kvm library
(uncomment LIBS=-lkvm in the Makefile).

I am currently running this on a SPARCstation IPX running OpenBSD 2.5.
I get 50Kbytes/sec maximum throughput but only if I saturate the
machine with multiple connections to get around packet loss.  [Under
load BPF reports a number of lost packets.]  At this point, the CPU
on the machine is being fully used.  For Intel users, the IPX is roughly
on par with a fast 486 so anyone with a modern machine should be fine.

NOTE:  I have not run this on an Intel box yet, so there may be some
byte-ordering issues [SPARCs use the same endian as network ordering].
If you get the error message:

	BPF program is broken

after starting, try recompiling with -DSIMPLE_BPF.  If this works,
let me know - it means I've buggered up the byte-ordering in the 
more complex (and better performing) BPF program.

---

Look at the "start" script for an example of how to start this up.
I found the pty-redir program in another package but that package
did not credit it's author.  It is GPL'ed so I have no qualms about
redistributing it.  I've hacked it slightly but otherwise make no
claims on it.  If the author will speak up I'll more than happily 
attribute it.

Other than that, the instructions that came with the original package
more or less apply.  Note that the pppd in OpenBSD 2.5 does not support
the "pty" option, hence the pty-redir program.

---

The BSD specific stuff is made up mostly of 2 chunks:

1.  Berkeley Packet Filter code which handles the reading and writing
    of raw ethernet packets from and to the network.

2.  An ugly bit of kvm code to extract the ethernet address of the
    interface we are interested in.  This works on OpenBSD 2.5, may
    work on other OpenBSD kernels and is unlikely to work anywhere else.
    If it does work anywhere else or if anyone has any better ideas,
    please let me know.

Part 1 should work on any BSD variant or any platform supporting BPF.
Part 2 will require the most porting work.

Changes and comments about the BSD-specific parts are welcome at 
matt@cs.yorku.ca.

Please note:  this is not meant to be an elegant solution, just a stopgap
until something better (i.e. something that doesn't dive in and out
user-space and copy packets everywhere) can be worked out.

Thanks to Luke for writing the Linux version which made the task of
getting my gateway back online significantly easier.

Matt Robinson
Computer Development Manager
Dept. of Computer Science
York Univerity
Toronto, Ontario, Canada
matt@cs.yorku.ca

Indexes created Thu May 16 13:05:45 MDT 2024