added add_fd, remove_fd, removed wait_loop_output, wait_time.
[ppp.git] / README.linux
index f21a24484c72d0353b18b91071b1523b6d23f177..c43c3e7e0776b658d48ba4c6f563da4bc69c6492 100644 (file)
@@ -1,17 +1,20 @@
-PPP for Linux                                             Version 2.2.0
+PPP for Linux                                             Version 2.3.6
 =============                                                  based on
-                                                              ppp-2.2.0
-                                                               Mar 1995
+                                                              ppp-2.3.6
+                                                          February 1999
 
 Michael Callahan    callahan@maths.ox.ac.uk
 Al Longyear         longyear@netcom.com
+Paul Mackerras      Paul.Mackerras@cs.anu.edu.au
+Nick Walker         nickwalker@email.com
 
   Contents:
     INTRODUCTION
     CREDITS
-    CHANGES FROM THE PREVIOUS VERSION
-    FUTURE PLANS
     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
@@ -27,11 +30,12 @@ Al Longyear         longyear@netcom.com
 
 INTRODUCTION
 
-This file is substantially derived from the previous version for
-the pppd process 2.1.2. Michael Callahan wrote that version. This
-particular version was written, modified, hacked, changed, whatever,
-by Al Longyear. If you find errors in this document, they are probably
-mine and not Michael's.
+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
@@ -44,7 +48,7 @@ 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, UPAP and CHAP, for negotiating link options and for
+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
@@ -60,96 +64,35 @@ the link down, when it negotiates a graceful disconnect.
 
 CREDITS
 
-I (MJC) 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 I often mimicked what slip.c
-did).  Otherwise I just implemented what pppd needs, using RFC1331 as
+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 has no support for asynchronous I/O, so I hacked an ioctl into
+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.2 of pppd (from the free package
-ppp-2.2.0) to Linux.  He also provided several enhancements to both
+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.
 
-The pppd program comes from the free distribution of PPP for Suns and
-386BSD machines, maintained by Paul Mackerras.  This package lists
-"thanks to" Brad Parker, Greg Christy, Drew D. Perkins, Rick Adams and
-Chris Torek.
+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.
 
-Jim Freeman added the code to support a ppp module and to dynamically
-extend the number of ppp devices. The Space.c module should not have
-any devices defined for this logic to work.
-
-
-CHANGES FROM THE PREVIOUS VERSION
-
-- The number of devices for the PPP device has been made dynamic. It was
-  previously configured with the default value of four devices.
-
-- The problems dealing with other systems such as Windows NT and their
-  authenticiation has been corrected. It will now generate the proper
-  responses to allow the system to choose a valid authentication protocol.
-
-- The kernel debug value has changed. Previously it was a level. It is now
-  a bit map with various bits meaning certain types of debug information.
-
-     0 - No debug information is generated
-     1 - Debug messages
-     2 - Log incoming packets
-     4 - Log outgoing packets
-     8 - Log tty output buffers
-    16 - Log tty input buffers
-
-  If you wish to use any combination, add the values together. For example,
-  '7' will log debug messages and incoming packages and outgoing packets.
-
-  The default setting is 0.
-
-  The simple IP trace which ppp.c performed when 'kdebug' was greater than
-  127 has been removed. You should use tcpdump for this type of trace
-  actions.
-
-- Support is added for compression control protocol. At the present time
-  only the BSD-Compress compression protocol is supported.
-
-- There are two queues for output frames. This avoids some problems which
-  occured with the previous version and some PPP packages which exchanged
-  echo frames with Linux.
-
-- The echo frames are now proper. Previously, it would generate extra
-  characters and this caused some providers to not respond to the 'junk'.
-
-- The max-echo-failure option will now properly disconnect the line.
-
-- There are other changes which are listed in the general README file. Please
-  read that file as well for changes.
-
-- There is no limit to the number of ppp devices which you may use. Jim Freeman
-  has added code to create them upon demand and to re-use the ones which have
-  been closed. There is no code, nor plans to write code, to remove (delete)
-  the un-used devices. So, if your system goes to a spurt and uses 3000 ppp
-  devices, it will remain at that level until you next reload the kernel.
-
-
-FUTURE PLANS
-
-The IPX support is still minimal. There is code which will only work with
-the 1.3 version of the networking software. The pppd process will still
-require changes to support the IPXCP and a change to the driver to properly
-enable/disable the IPX frames. Jim Freeman is reportily working on the IPX
-support.
 
+Nick Walker added the code to query the peer for DNS server addresses.
 
 INSTALLATION
 
-This version of PPP has been tested on 1.1.x (x>=14) It will probably
-not work on kernels much earlier than this due to a change in the
-routing code.  If you have an earlier kernel, please upgrade.
+This version of PPP has been tested on various Linux kernel versions
+(most recently 2.0.36 and 2.2.1). It will not work on kernels before
+2.0.0. If you have an earlier kernel, please upgrade to the latest 2.0
+or 2.2 kernel.
 
 joining the PPP channel of linux-activists:
 
@@ -158,14 +101,21 @@ joining the PPP channel of linux-activists:
        subscribe linux-ppp
       contained in the body to majordomo@vger.rutgers.edu
 
+      You may use
+
+      subscribe linux-ppp myname@mail.address
+
+      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
       linux-ppp@vger.rutgers.edu. 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 mirrored to the usenet
-      group linux.act.ppp. You may choose to read the few messages posted
+      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
@@ -196,137 +146,184 @@ Usenet News Groups
       'ppp' on usenet may cause it to be ignored by the people who
       actually work on the networking code.
 
-kernel driver installation:
+Installation procedure:
 
-      This depends on the kernel version you're using.
+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.
 
-      Version 1.0.*
-        These versions are not supported.
 
-      Version 1.1.0 through 1.1.14
-        These versions are not supported.
+1. Issue the command:
 
-      Version 1.1.15 to 1.2.99
-      - Use the source to the ppp.c driver from the 'linux' directory and
-        replace the driver in the /usr/src/linux/drivers/net.
-      - Delete the file /usr/src/linux/drivers/net/ppp.h
-      - Add the following files to /usr/include/net:
-        if_ppp.h
-        if_pppvar.h
-        ppp_comp.h
-        ppp_defs.h
+./configure
 
-      - IF AND ONLY IF you are missing the following files then use the
-        copy provided in the 'linux' directory to supplement the files.
+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.
 
-        DO **NOT** REPLACE THE FILE IF IT CURRENTLY EXISTS.
 
-        if_arp.h
-        if_route.h
+2. Update the kernel sources.
 
-      Version 1.3.0 and later
-        The files have been properly updated.
+If you are using a 2.2.x kernel (or a recent 2.1.x kernel), you do not
+need to do this step.  If your kernel is already configured for PPP,
+then you only need to do steps 5 and 6.  Otherwise, continue at step 3.
 
-      Reboot with the new kernel.  At startup, you should see
-      something line this:
+If you are using a 2.0.x kernel, you need to update the kernel ppp
+driver to the version in this package.  You will need a copy of the
+kernel source tree to do this.  Issue the command:
 
-  PPP: version 2.2.0 (dynamic channel allocation)
-  TCP compression code copyright 1989 Regents of the University of California
-  Dynamic channel allocation code copyright 1995 Caldera, Inc.
-  PPP line discipline registered.
+make kernel
 
-pppd installation:
+from the top level directory. This will install the various include
+files and source files into the proper directory for the linux
+kernel. If you don't have the kernel installed in the /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.
 
-      First update /usr/include/net as described in the previous section.
+The actual message will say:
 
-      Then, in this directory, issue the command:
+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]
 
-       ./configure
+If, and only if, you receive this message, do the following:
 
-      Go to the 'pppd' directory and issue the commands:
+   a. Change to the 'linux' directory with the command:
 
-      make depend
-      make
+cd linux
 
-      This should build the program. If you have any errors then ensure
-      that you have the proper include files and haven't missed one.
+   b. Issue the command:
 
-      If you are using shadow passwords *AND* have it installed, then you
-      should use the command:
+./kinstall.sh /usr/src/linux
 
-      make shadow
+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:
 
-      rather than the non-shadow command listed earlier.
+./kinstall.sh /usr1/kernel
 
-      (Shadow library support will require the addition of some modules
-      to the shadow library. These were overlooked by the package author
-      and I will, or have already, notified him.)
-      
-      This code has been built with the 4.5 and 4.6 subroutine libraries
-      and include files. If your include files are too old then you should
-      upgrade them.
+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.
 
-      To install the package, issue the command:
+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.
 
-      make install
+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.
 
-      This will install the binary in /usr/sbin and the man page into
-      /usr/man/man8.
 
-      pppd needs to be run as root.  You can either make it setuid
-      root or just use it when you are root.  'make install' will try
-      to install it setuid root.  Making pppd setuid root is
-      convenient for a single-user machine, but has security
-      implications which you should investigate carefully before
-      making it available on a multiuser machine.
+3. Build the kernel.
 
-      The pppd process must have the following directories to work:
+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.
 
-      /var/run
-      /etc/ppp
+If you don't know how to build a kernel, then you should read the
+README file in the kernel source directory.
 
-      In addition, for the program to run, there must be a 'options' file
-      in the /etc/ppp directory. So, the following commands will accomplish
-      the required operations. They may have errors if the entries currently
-      exist.
+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.
 
-      Perform these commands as the 'root' user.
+Instructions on building the kernel with modules are given in the
+README.modules in the kernel source directory.
 
-      mkdir /var /etc
-      mkdir /var/run /etc/ppp
-      touch /etc/ppp/options
 
-chat installation:
+4. Install the kernel
 
-      If you have not already done so, run `./configure' in this directory.
+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.
 
-      To compile the chat program, go to the 'chat' directory and issue
-      the command:
+Distributions other than the Yggdrasil will normally install the
+kernel when you build it.
 
-      make
 
-      To install the package, issue the command:
+5. Build the programs.
 
-      make install
+The programs are built next. The command to build the programs is fairly
+simple. Just issue the command:
 
-      This will install the binary in /usr/sbin and the man page into
-      /usr/man/man8.
+make
 
-pppstats installation:
+from the top level directory where this README.linux file is located.
 
-      If you have not already done so, run `./configure' in this directory.
 
-      To compile the pppstats program, go to the 'pppstats' directory
-      and issue the command:
+6. Install the programs.
 
-      make
+You may use the command
 
-      To install the package, issue the command:
+make install
 
-      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.
 
-      This will install the binary in /usr/sbin and the man page into
-      /usr/man/man8.
+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
+be maintained.
+
+Sequence    Module      Description
+   1        slhc.o      VJ header compression
+   2        ppp.o       PPP driver
+   3        bsd_comp.o  BSD compression for PPP's compression protocol.
+
+If you only have the bsd comprssor as a module then you may load it without
+regard to any order. Likewise you may load the deflate compressor without
+regard to any order with the BSD one. The idea is that the ppp.o code must
+be loaded to use the compressor and the VJ header compression code must be
+loaded to use ppp.o.
+
+You may elect not to load the BSD compression module if you desire.
+The LZW compression algorithm (as used by BSD-Compress and the
+`compress' command) is claimed to be covered by a patent held by
+Unisys in the USA and other countries.
+
+In addition, if memory is a premium, do not run the compressors. It
+may take large amounts of memory (up to 2.6 meg) for high compression
+lengths to hold the compression dictionaries.
+
+Without the compression modules, the PPP driver will not accept PPP's
+compression control protocol for that type. If you have no compressors
+loaded then no compression will be performed. If you don't have the BSD
+compressor loaded then the BSD compression will not be performed, even
+if the peer system supports it. Likewise with the deflate compressor.
+
+Compressors are unique to their type. If you have the deflate compressor
+loaded and the peer system has the BSD version, still no compression must
+be loaded. BOTH systems must support the same compression protocols.
+
+
+PROBLEMS WHICH MAY OCCUR WHILE BUILDING THE KERNEL
+
+At this time there should not be a problem with the complication of the
+drivers.
 
 
 GENERAL NETWORK CONFIGURATION
@@ -369,10 +366,10 @@ will use.  For example:
      192.1.1.23  chelseapc.president.whitehouse.gov chelseapc
 
 where my IP address is 192.1.1.17 and my hostname is
-billpc.president.whitehouse.gov.  (Not really, you understand.)  If
-your PPP server does dynamic IP address assignment, give a guess as to
-an address you might get (see also "Dynamic Address Assignment"
-below).
+billpc.president.whitehouse.gov.  (Not really, but you should
+understand my meaning.)  If your PPP server does dynamic IP address
+assignment, give a guess as to an address you might get (see also
+"Dynamic Address Assignment" below).
 
 Finally, you need to configure the domain name system by putting
 appropriate lines in /etc/resolv.conf .  It should look something like
@@ -390,6 +387,11 @@ the names 'hillarypc' and 'chelseapc'.  You can probably find out the
 right domain name to use and the IP numbers of nameservers from
 whoever's providing your PPP link.
 
+Alternatively you may wish to use the option `usepeerdns' and then
+modify your `ip-up' and `ip-down' scripts to automate the process. Or 
+check your messages file to see if pppd recorded the DNS addresses
+supplied by the peer ppp server.
+
 
 CONNECTING TO A PPP SERVER
 
@@ -418,6 +420,9 @@ Going through pppd's options in order:
          ""            send a return (null text followed by usual return)
          ogin: ppp word: whitewater    log in.
 
+         Please refer to the chat man page, chat.8, for more information
+         on the chat utility.
+
    /dev/cua1     specify the callout serial port cua1
    38400         specify baud rate
    debug         log status in syslog
@@ -440,13 +445,12 @@ Going through pppd's options in order:
         this option would actually be redundant.
 
 pppd will write error messages and debugging logs to the syslogd
-daemon using the facility name "local2".  (Verbose output from chat is
-the same.)  These messages may already be logged to the console or to
-a file like /usr/adm/messages; consult your /etc/syslog.conf file to
-see.  If you want to make all pppd and chat messages go to the
-console, add the line
+daemon using the facility name "daemon". These messages may already be
+logged to the console or to a file like /usr/adm/messages; consult
+your /etc/syslog.conf file to see. If you want to make all pppd
+messages go to the console, add the line
 
-   local2.*                                    /dev/console
+   daemon.*                                    /dev/console
            ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
            This is one or more tabs. Do not use spaces.
 
@@ -474,6 +478,8 @@ want the service "blackice".  It logs in, waits for a shell prompt
 ("black%"), then starts PPP.  The -t60 argument sets the timeout to a
 minute, since things here are sometimes very slow.
 
+(The sendbreak program is not included in this package.)
+
 The "&& sleep 5" causes the script to pause for 5 seconds, unless chat
 fails in which case it exits immediately.  This is just to give the
 PPP server time to start (it's very slow).  Also, the "stty -echo"
@@ -532,7 +538,7 @@ lo        Link encap Local Loopback
           TX packets 0 errors 0 dropped 0 overrun 0
 
 ppp0      Link encap Point-to-Point Protocol
-          inet addr 192.76.32.2  P-t-P 129.67.1.165  Mask 255.255.255.0
+          inet addr 192.76.32.3  P-t-P 129.67.1.165  Mask 255.255.255.0
           UP POINTOPOINT RUNNING  MTU 1500  Metric 1
           RX packets 33 errors 0 dropped 0 overrun 0
           TX packets 42 errors 0 dropped 0 overrun 0
@@ -583,8 +589,8 @@ If you don't seem to get a connection, the thing to do is to collect
 'debug' option, and put the following two lines in your
 /etc/syslog.conf file:
 
-    local2.*                                   /dev/console
-    local2.*                                   /usr/adm/ppplog
+    daemon.*                                   /dev/console
+    daemon.*                                   /usr/adm/ppplog
 
 This will cause pppd's messages to be written to the current virtual
 console and to the file /usr/adm/ppplog.  Note that the left-hand
@@ -611,8 +617,8 @@ which contains all the bytes being passed between your computer and
 the remote PPP server.  To do this, alter your syslog.conf lines to
 look like this
 
-    local2.*,kern.*                            /dev/console
-    local2.*,kern.*                            /usr/adm/ppplog
+    daemon.*,kern.*                            /dev/console
+    daemon.*,kern.*                            /usr/adm/ppplog
 
 and HUP the syslog daemon as before.  Then, run pppd with the option
 "kdebug 25".  Whatever characters arrive over the PPP terminal line
@@ -648,7 +654,7 @@ possible; for example:
  - the version number of Linux PPP you are using
  - the exact command you use to start the PPP session
  - log output from a session run with the 'debug' option, captured
-   using local2.*,kern.* in your syslog.conf file
+   using daemon.*,kern.* in your syslog.conf file
  - the type of PPP peer that you are connecting to (eg, Xyzzy Corp
    terminal server, Morningstar PPP software, etc)
  - the kind of connection you use (modem, hardwired, etc...)
@@ -677,6 +683,7 @@ is to use ifconfig ppp0 to get the interface address and then edit
 /etc/hosts appropriately.
 
 
+
 SETTING UP A MACHINE FOR INCOMING PPP CONNECTIONS
 
 Suppose you want to permit another machine to call yours up and start
@@ -695,9 +702,9 @@ pieces of information:
 modem
 crtscts
 lock
-:192.1.2.23
+:192.1.2.33
 
-Here we will insist that the remote machine use IP address 192.1.2.23,
+Here we will insist that the remote machine use IP address 192.1.2.33,
 while the local PPP interface will use the IP address associated with
 this machine's hostname in /etc/hosts.  The '-detach' option is required
 for a server. It tells the pppd process not to terminate until the modem
@@ -731,7 +738,7 @@ to be on the local Ethernet segment and you should give the 'proxyarp'
 option to pppd on the server.  Suppose, for example, we have this
 setup:
 
- 192.1.2.23                        192.1.2.17
+ 192.1.2.33                        192.1.2.17
 +-----------+      PPP link       +----------+
 | chelseapc | ------------------- |  billpc  |
 +-----------+                    +----------+
@@ -752,18 +759,19 @@ piece of information:
 modem
 crtscts
 lock
-192.1.2.17:192.1.2.23
+192.1.2.17:192.1.2.33
 proxyarp
 
 When the link comes up, pppd will enter a "proxy arp" entry for
 chelseapc into the arp table on billpc.  What this means effectively
 is that billpc will pretend to the other machines on the 192.1.2.x
 Ethernet that its Ethernet interface is ALSO the interface for
-chelseapc (192.1.2.23) as well as billpc (192.1.2.17).  In practice
+chelseapc (192.1.2.33) as well as billpc (192.1.2.17).  In practice
 this means that chelseapc can communicate just as if it was directly
 connected to the Ethernet.
 
 
+
 SETTING UP A MACHINE FOR INCOMING PPP CONNECTIONS WITH DYNAMIC IP
 
 The use of dynamic IP assignments is not much different from that
@@ -797,10 +805,10 @@ the system via ftp. You would not want Joe Hacker using the ppp account
 via ftp.
 
 2. Ensure that the directory /etc/ppp is owned by 'root' and permits
-only write access to the root user.
+write access only to the root user.
 
-3. The files /etc/ppp/options must be owned by root and accessible only
-from that user. Never permit any other user access to this file.
+3. The files /etc/ppp/options must be owned by root and writable only
+by root.
 
 4. The files /etc/ppp/ip-up and /etc/ppp/ip-down will be executed by the
 pppd process while it is root. Ensure that these files are writable only
@@ -838,6 +846,11 @@ Then you may secure the binaries so that they are executable from the owner
 (which should be root) and the group only. All other users would be denied
 all access to the files and executables.
 
+d) Prevent the motd file from being sent to the ppp user.
+touch ~ppp/.hushlogin
+chown root ~ppp/.hushlogin
+chmod 444  ~ppp/.hushlogin
+
 
 ADDITIONAL INFORMATION