$Id: HOW-TO-CONNECT,v 1.7 2000/01/10 22:50:25 dfs Exp $

This package lets you connect a Linux machine to Sympatico HSE or Magma's
high-speed service using a Nortel 1-meg modem.

Follow these steps and you should have your high-speed service up and running.

1. Set up your Ethernet hardware
--------------------------------

First, make sure the Ethernet card you intend to use with the modem is
visible to the Linux kernel.  Just how to do this is beyond the scope
of this document.  However, if the card is the only Ethernet card in
the system, executing:

	ifconfig eth0

should display something like this:

	eth0      Link encap:Ethernet  HWaddr 00:60:67:62:31:D4  

plust some more lines.  Your HWaddr will be different.  As long as you see
the HWaddr line, your card should be working.

DO NOT assign an IP address to the Ethernet card.  DO NOT configure the
card to come up at boot time.

2. Compile the PPPoE client
---------------------------

Type "./configure; make" to compile the "pppoe" program.  After "make" has
finished, you should have an executable called "pppoe".  Copy it to
/usr/local/bin/pppoe.  (You can copy it somewhere else, but the
connection script assumes it's in /usr/local/bin.)

3. Check your software
----------------------

I have tested this software with pppd version 2.3.10.  It may work
with older versions.  Then again, it may not.  Be safe and get the latest
pppd.  (I have had reports that it works with 2.3.7 or later.)

4. Edit pap-secrets
-------------------

Edit the "pap-secrets" file, inserting your proper user-ID and password.
Install the file (or copy the relevant lines) to /etc/ppp/pap-secrets.
Your ISP may use CHAP authentication.  In this case, add the line to
/etc/ppp/chap-secrets.

5. Edit the connection script
-----------------------------

The script "adsl-connect" brings up the high-speed connection.  You
need to edit the following items:

- Change ETH=eth1 to the correct Ethernet device for your modem.
- Change USER=bxxxnxnx@sympatico.ca to your proper Sympatico ID.
- If you didn't install pppoe in /usr/local/bin, change
  PPPOE=/usr/local/bin/pppoe appropriately.

Copy the edited script to /usr/local/bin/adsl-connect

6. Set up DNS
-------------

If you are using DNS servers supplied by your ISP, edit the file
/etc/resolv.conf to contain these lines:

	nameserver ip_addr_of_first_dns_server
	nameserver ip_addr_of_second_dns_server

For example:

	nameserver 204.101.251.1
	nameserver 204.101.251.2


7. Firewall your machine
------------------------

MAKE SURE YOU FIREWALL YOUR MACHINE.  A sample firewall script is given
in the shell script "firewall"  To install the script:

a) Copy it to /etc/rc.d/init.d/firewall
b) Type: chkconfig firewall on
c) Start the firewall: sh /etc/rc.d/init.d/firewall start

You may want to tweak the script somewhat.

8. Bring up the connection at boot time
---------------------------------------

To bring up the connection at boot time, add this line to the end
of /etc/rc.d/rc.local (on Red Hat-like systems):

	sh /usr/local/bin/adsl-connect > /dev/null 2>&1 &

9. Configure LAN Hosts
----------------------

If you have a LAN behind the firewall, you MUST set the MTU of their
Ethernet interfaces to 1492, or nothing will work!  (In fact, a far
safer value is 1412, leaving room for worst-case TCP and IP options in
their respective headers.)

In Linux, use: "ifconfig eth0 mtu 1412".  For best results, put this
in an /etc/rc.d/rc.local script.

For Windows, machines, see http://lan.cns.ksu.edu/OS/WIN95/slip95.htm.
Set the MaxMTU to 1412.

That's it!

--
David F. Skoll <dfs@roaringpenguin.com> | Roaring Penguin Software Inc.
http://www.roaringpenguin.com           | Linux and UNIX Specialists

PROBLEMS!  DAVE, IT DOESN'T WORK!
---------------------------------

Here are some problems PPPoE users have encountered.

-----------------------------------------------------------------------------
A) Can't see the Ethernet interface

Well, I can't really help you here.  To use these instructions, you must
have Linux working to the point where it recognizes your Ethernet card.
If you type "ifconfig ethx" and you get back a HWAddr value, your Ethernet
card is probably OK.  But I really can't help with hardware configuration
issues.

-----------------------------------------------------------------------------
B) Connection seems to work, but I can't browse the web

You probably don't have DNS set up.  See step 6.

-----------------------------------------------------------------------------
C) Can't compile PPPoE

I have only tested compilation on 2.2-kernel machines.  Make sure you have
"make", the C compiler and all development header files installed.

-----------------------------------------------------------------------------
D) pppd complains about "unknown option pty"

Your pppd is too old.  See step 3.

-----------------------------------------------------------------------------
E) pppoe dies with the log message "Message too long"

You set the MTU of the Ethernet interface connected to the ADSL modem
to less than 1500.  Don't do that.

-----------------------------------------------------------------------------
F) Internal hosts can't see the Internet

Do you have masquerading set up?  I can't help you in great detail, but
see the IPCHAINS-HOWTO and the IP-Masquerade mini-HOWTO.

-----------------------------------------------------------------------------
G) Authentication fails

Make sure you have the right secret in /etc/ppp/pap-secrets.  Your ISP
may be using CHAP; it won't hurt to copy the line to /etc/ppp/chap-secrets.

Also, MAKE SURE that /etc/ppp/options is EMPTY.  The "adsl-connect" script
supplies all required options on the command line; additional options
in /etc/ppp/options may mess things up.

-----------------------------------------------------------------------------
H) It doesn't work

Make sure the Ethernet card associated with the ADSL modem does NOT
have a valid IP address.  (NOTE: For 2.0 kernels, you may have to give
it a fake IP address which is not on your internal subnet.  Something
like 192.168.42.42 might work if you are not using 192.168.42.*)

If you are using synchronous PPP on a slow machine, try switching to
asynchronous PPP.

Make sure no entries in the routing table go through the Ethernet card
connected to the ADSL modem.  You might want to add these lines in
adsl-connect:

	ifconfig ethx down
	ifconfig ethx up mtu 1500

which should reset things to sane values.
