$Id$ 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. 0. Install the rp-pppoe-software -------------------------------- You should have already done this by the time you're reading this. If not, go back and read README. 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. Configure various files -------------------------- Several files need editing. The easiest way to do this is to run the following command as root: adsl-setup Answer the questions and you should be all set. If you want to know what goes on behind the scenes, continue reading this document. If you don't care and your connection works, stop reading. :-) 3. 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. 4. Edit /etc/ppp/pppoe.conf ----------------------------- The file /etc/ppp/pppoe.conf contains configuration information for the ADSL 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 ADSL user-ID. Don't edit any of the other settings unless you're an expert. 5. 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 6. 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 (The above procedure works ONLY on Red Hat-like systems.) You may want to tweak the script somewhat. 7. Bring up the connection at boot time --------------------------------------- On a Red Hat system, the installation procedure should have installed a script called /etc/rc.d/init.d/adsl. To bring up the connection at boot time, just type this command as root: chkconfig --add adsl On non-Red-Hat systems, add this line to the end of /etc/rc.d/rc.local: /usr/sbin/adsl-start 8. Configure LAN Hosts ---------------------- If you have a LAN behind the firewall, you have to lower the TCP maximum segment size from the normal 1460 to 1452 (or better, 1412.) You have two options: Either set the MTU of all the interfaces on other hosts on the LAN to 1452, or use the "-m 1412" option to pppoe. The "-m" option for pppoe is far simpler and makes it easier to add hosts to the LAN, but consumes some extra CPU time. If you want to manually configure the LAN hosts, here's how: In Linux, use: "ifconfig eth0 mtu 1452". 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 1452. 9. Commands to control the ADSL link ------------------------------------ As root, bring up the link by typing: adsl-start As root, bring down the link by typing: adsl-stop That's it! -- David F. Skoll | 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 come up, but I can't browse the web or ping anything 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 (i) "unknown option pty" or (ii) "pty option precludes specifying device name" (i) Your pppd is too old. You need at least 2.3.7. (ii) Your /etc/ppp/options file is not empty. Empty it! ----------------------------------------------------------------------------- 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) VPN software does not work If you are using VPN software on a Windows or Linux machine with another Linux machine running PPPoE as the gateway, you MUST NOT use the "-m" option to pppoe. This alters IP packets, which will break any VPN which uses IPSec. In /etc/ppp/pppoe.conf, set CLAMPMSS to "no". You'll also have to reduce the MTU on the hosts behind the gateway to 1452. ----------------------------------------------------------------------------- I) I can browse some web sites just fine, but others stall forever. There is probably a buggy router or firewall between you and the Web server. One possible workaround: In /etc/ppp/pppoe.conf, find the line which reads: CLAMPMSS=1412 Try lowering the 1412 until it works (go down in steps of 100 or so.) Each time you lower the value, you have to restart your connection like this: adsl-stop; adsl-start This should work around buggy routers which do not support Path MTU discovery. ----------------------------------------------------------------------------- J) Whenever I connect using ADSL, my internal LAN no longer sees the gateway You are more than likely running a 2.0.X Linux kernel. To solve this problem, give the Ethernet card connected to the DSL modem a fake IP address. For example, if eth0 is your internal LAN card and eth1 goes to the DSL modem, do something like this: ifconfig eth1 10.0.0.1 netmask 255.255.255.0 (You may have to choose a different IP address; experiment.) ----------------------------------------------------------------------------- K) How can I run a script every time I connect and get a new IP address? Put the script in /etc/ppp/ip-up. See the pppd(8) man page. ----------------------------------------------------------------------------- L) Nothing works! You may need to put your Ethernet card in half-duplex, 10Mb/s mode to work with the DSL modem. You may have to run a DOS program to do this, or pass special parameters to the Linux driver. Some providers object to attempts to set the MRU or MTU. Try removing "mtu 1492 mru 1492" from PPP_STD_OPTIONS in the adsl-connect script. This problem has been seen with an ISP in Hong Kong. Your DSL provider may be using non-standard PPPoE frames or require something special in the Service-Name field. If you have two computers, you can try sniffing out these values with the "pppoe-sniff" program. Type "man pppoe-sniff" for details. If you don't have two computers, you'll have to ask your DSL provider if it uses non-standard PPPoE frames or special Service-Name fields. Good luck getting an answer... If pppoe-sniff indicates that nothing is amiss, 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. ####################################################################### # WHEN ALL ELSE FAILS: # ####################################################################### If you are completely unable to connect, run the adsl-start script in debugging mode. If you are using bash as your shell (if you don't know what your shell is, it's probably bash), type this: DEBUG=1 adsl-start In tcsh or csh, use: setenv DEBUG 1; adsl-start Then follow the instructions to mail the debugging file to me. PLEASE DON'T DO THIS until you have exhausted all other avenues; rp-pppoe is free software and it costs me time and money to help people with problems. While I don't mind doing this, I do mind it if you don't make an effort to fix the problem yourself first. WARNING: If you run adsl-start in debugging mode and you manage to connect, your connection will be extremely slow and huge amounts of data will quickly fill your /tmp directory. Do not use debugging mode unless you really cannot get your connection to work. Be aware that debugging mode produces hex dumps which potentially reveal your user name and password. If the debugging output includes packets labeled "PPPOE Session", you may wish to remove these packets from the dump before mailing it to me.