readme.linux

unix and linux net driver

PPP for Linux                                            Version 2.3.11
=============                                                  based on
                                                             ppp-2.3.11
                                                          December 1999

Paul Mackerras      [e-mail]
Al Longyear         [e-mail]
Michael Callahan    [e-mail]

  Contents:
    INTRODUCTION
    CREDITS
    INSTALLATION
    PROBLEMS WHICH MAY OCCUR WHILE BUILDING THE KERNEL
       A REFERENCE TO UNDEFINED _mod_use_count_
       BLOCK ON FREELIST AT nnnnnn ISN'T FREE
    GENERAL NETWORK CONFIGURATION
    CONNECTING TO A PPP SERVER
    IF IT WORKS
    IF IT DOESN'T WORK
    IF IT STILL DOESN'T WORK (OR, BUG REPORTS)
    DYNAMIC ADDRESS ASSIGNMENT
    SETTING UP A MACHINE FOR INCOMING PPP CONNECTIONS
    SETTING UP A MACHINE FOR INCOMING PPP CONNECTIONS WITH DYNAMIC IP
    ADDITIONAL INFORMATION
    DIP SUPPORT
    CONCLUSION


INTRODUCTION

This file is substantially derived from the previous version for the
pppd process 2.2.0, which itself was derived from earlier works by
Michael Callahan. This particular version was written, modified,
hacked, changed, whatever, by Al Longyear and Paul Mackerras. If you
find errors in this document, they are probably ours and not
Michael's.

This is a PPP driver for Linux.  It has been used by many people and
seems to be quite stable.  It is capable of being used either as a
'client'--for connecting a Linux machine to a local Internet provider,
for example--or as a 'server'--allowing a Linux machine with a modem
and an Ethernet connection to the Internet to provide dial-in PPP
links.  (In fact, the PPP protocol does not make the distinction
between client and server, but this is the way people often think
about it.)

The PPP protocol consists of two parts.  One is a scheme for framing
and encoding packets, the other is a series of protocols called LCP,
IPCP, PAP and CHAP, for negotiating link options and for
authentication.  This package similarly consists of two parts: a
kernel module which handles PPP's low-level framing protocol, and a
user-level program called pppd which implements PPP's negotiation
protocols.

The kernel module assembles/disassembles PPP frames, handles error
detection, and forwards packets between the serial port and either the
kernel network code or the user-level program pppd.  IP packets go
directly to the kernel network code.  So once pppd has negotiated the
link, it in practice lies completely dormant until you want to take
the link down, when it negotiates a graceful disconnect.


CREDITS

Michael Callahan wrote the original kernel driver from scratch.
Laurence Culhane and Fred van Kempen's slip.c was priceless as a model
(a perusal of the files will reveal that he often mimicked what slip.c
did).  Otherwise he just implemented what pppd needs, using RFC1331 as
a guide.  For the most part, the Linux driver provides the same
interface as the free 386BSD and SunOS drivers.  The exception is that
Linux had no support for asynchronous I/O, so he hacked an ioctl into
the PPP kernel module that provides a signal when packets appear and
made pppd use this instead.

Al Longyear ported version 2.0 of pppd (from the free package
ppp-2.0.0) to Linux.  He also provided several enhancements to both
the kernel driver and the OS-independent part of pppd.  His
contributions to Linux PPP have been immense, and so this release
is being distributed over both our names.

Paul Mackerras rewrote and restructured the code for improved
performance and to make a cleaner separation between the
network-interface and async TTY parts of the ppp driver.

Nick Walker added the code to pppd to query the peer for DNS server
addresses.


USING THE NEW PPP KERNEL DRIVER

As of kernel version 2.3.13, the development series of kernels contain
a new kernel PPP driver, rewritten from scratch by Paul Mackerras.
This package supports the new driver, although it doesn't include the
source for the new driver.

The new driver is divided into two files: ppp_generic.c and
ppp_async.c.  The old ppp.c is still present in the kernel sources but
is not used.  If you compile PPP as a module, you will get two
separate modules, called ppp_generic and ppp_async.
Another module ppp_synctty is used for synchronous tty devices
such as high-speed WAN adapters for leased T1/E1 lines.

To talk to the new driver, pppd needs to be able to open /dev/ppp,
character device (108,0).  If the special file node /dev/ppp is not
present, pppd will create it.  However, if you are running with /dev
on a read-only filesystem, pppd will not be able to create /dev/ppp.
In that instance you should manually create /dev/ppp using the command
`mknod /dev/ppp c 108 0'.

If you use module autoloading and have PPP as a module, you will need
to add the following to your /etc/modules.conf or /etc/conf.modules:

alias tty-ldisc-3    ppp_async
alias tty-ldisc-14   ppp_synctty
alias char-major-108 ppp_generic


INSTALLATION

This version of PPP has been tested on various Linux kernel versions
(most recently 2.2.10). It will not work on kernels before 2.0.0. If
you have an earlier kernel, please upgrade to the latest 2.2-series
kernel.

joining the PPP channel of linux-activists:

      This isn't really part of installation, but if you DO use
      Linux PPP you should do this.  Send a message with the line
	subscribe linux-ppp
      contained in the body to [e-mail]

      You may use

      subscribe linux-ppp [e-mail]

      if you wish the linux-ppp information sent to a different mail
      address.

      To leave the mail list, send 'unsubscribe linux-ppp' to the same
      mail address.

      You can send to the list by mailing to
      [e-mail]. This is a majordomo mailing list and
      is unlike the earlier version on hut.fi. There is no magic header
      required for this list. In addition, it is gated to the usenet
      group linux.dev.ppp. You may choose to read the few messages posted
      there.

Usenet News Groups

      There are three applicable usenet news groups for the PPP code. Please
      choose the group which applies the closest to the type of problem
      which you are experiencing.

      comp.os.linux.networking
       - Trouble setting routes, running name services, using telnet, ftp,
         news, etc.
       - It will not compile.

      comp.os.linux.setup
       - Trouble installing the package from BINARIES only. This does *NOT*
         include problems with compiling the package.

      comp.protocols.ppp
       - How do I use the package?
       - How do I connect to .... services?
       - Why does this not work?
       - All other types of questions on how to use just the PPP code.

      PLEASE don't assume that just because you are using PPP as your
      network device driver that all problems with your networking are a
      problem of PPP. PPP is *NOT* responsible for your modem disconnecting,
      routing to other servers, running telnet, etc. Calling the problem
      'ppp' on usenet may cause it to be ignored by the people who
      actually work on the networking code.

Installation procedure:

The installation procedure has been totally revised for this
version. Due to feedback from other users, it was felt that a more
automated installation procedure be performed.


1. Issue the command:

./configure

from the top level directory of pppd. This is the directory which
contains this README.linux file. The result of this will be to build a
set of symbolic links to the makefiles. They should link 'Makefile' to
'Makefile.linux' in each of the directories.


2. Update the kernel sources.

The 2.2.8 and later kernels contains the same PPP kernel driver as is
in this release.  In fact the driver in the kernel sources is slightly
different from the one in this package as it doesn't include the stuff
which enables the driver in this package to compile in either the 2.0
or 2.2 kernel environment, but the two are functionally equivalent.
If you are using a 2.2.8 or later kernel and your kernel is already
configured for PPP, then you only need to do steps 5 and 6.
Otherwise, continue at step 3.

If you are using a 2.3 series kernel, use the kernel driver that is in
the kernel sources.  For 2.3.13 and later, this is the new driver (see
above).

If you are using a kernel earlier than 2.2.8, you can either use the
driver in this package or upgrade your kernel to the current 2.2.x
series kernel (2.2.13, as of the release of ppp-2.3.11).  If you choose
to use the driver in this package, you will need a copy of the kernel
source tree to compile the driver.  Issue the command:

make kernel

from the top level directory. This will install the various include
files and source files into the proper directories in the linux kernel
source tree. If you don't have the kernel installed in the default
/usr/src/kernel directory then it will not work. Instead it will print
a message to the effect that you need to specify the kernel location
on the kinstall command.

The actual message will say:

There appears to be no kernel source distribution in /usr/src/linux.
Give the top-level kernel source directory as the argument to
this script.
usage: kinstall.sh [linux-source-directory]

If, and only if, you receive this message, do the following:

   a. Change to the 'linux' directory with the command:

cd linux

   b. Issue the command:

./kinstall.sh /usr/src/linux

or use the proper location for the kernel rather than
/usr/src/linux. For example, if you have the kernel installed in
/usr1/kernel then the command would be:

./kinstall.sh /usr1/kernel

The script will validate that the kernel is properly installed into
that directory and check the level of the kernel. The installation
will not be accepted if your kernel is too early.

The installation procedure will copy only the files which are
needed. It will not replace any file which should not be
replaced. Please don't second-guess the installation script and
attempt to do the procedure on your own. There are some very subtle
dependencies and if you are not careful, the installation will not
work.

You are free to run the installation script as many times as you
wish. The additional executions will only change the files which have
not been changed.


3. Build the kernel.

You should rebuild the kernel with this package.  If you use the
driver that comes with the current 2.0 kernels, it will not support
Deflate compression or demand-dialling, but apart from that the pppd
daemon should work.

If you don't know how to build a kernel, then you should read the
README file in the kernel source directory.

If you want module support then you need to have the 'modules-2.0.0'
package installed as the minimum version. Earlier versions of the
module support will not work properly. All of the later ones will.

Instructions on building the kernel with modules are given in the
README.modules in the kernel source directory.


4. Install the kernel

If you are using the Yggdrasil distribution then you need to 'install'
the kernel at this point. Refer to their documentation on the procedures
to install the kernel.

Distributions other than the Yggdrasil will normally install the
kernel when you build it.


5. Build the programs.

The programs are built next. The command to build the programs is fairly
simple. Just issue the command:

make

from the top level directory where this README.linux file is located.


6. Install the programs.

You may use the command

make install

(as root) to install the various programs.  They will be installed
into the /usr/sbin directory.  If you prefer to install the programs
elsewhere, you can change the definition of BINDIR in the file
linux/Makefile.top.

Earlier versions of the pppd package used /usr/lib/ppp as the
directory. This has been changed. If you still have code in
/usr/lib/ppp then you should remove it as it is probably the 2.1
version of the code. That version will not work with the current ppp.c
drivers in the kernel.


7. Reboot to the new kernel.

After building the new kernel, you will need to actually use it. Reboot
the Linux system and you may then use the new pppd program.


8. Load optional modules.

If you are using loadable modules for the ppp then you must load them
after the kernel has been started. The following relative order must