readme.linux

unix and linux net driver

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 compilation of the
drivers.


GENERAL NETWORK CONFIGURATION

Since many people don't use the Linux networking code at all until
they get a PPP link, this section describes generally what's needed to
get things running.  In principle none of this is special to PPP.  For
more details, you should consult the relevant Linux HOWTOs.  If you
already understand network setup, you can skip this section.

The first file that requires attention is the rc script that does
network configuration at boot time, called /etc/rc.net or
/etc/rc.d/rc.net.{1,2} or something similar, depending on your Linux
distribution.  This file should 'ifconfig' the loopback interface lo,
and should add an interface route for it.  These lines might look
something like this:

        $CONFIG lo 127.0.0.1
	$ROUTE add loopback
or
        /sbin/ifconfig lo 127.0.0.1
        /sbin/route add 127.0.0.1

However, it should *not* config an ethernet card or install any other
routes (unless you actually have an ethernet card, in which case I'll
assume you know what to do).  Many distributions will provide scripts
that expect you to have an ethernet card.

You also need to decide whether you want to allow incoming
telnet/ftp/finger, etc.  If so, you should have the rc startup script
run the 'inetd' daemon.

Next, you should set up /etc/hosts to have two lines.  The first
should just give the loopback or localhost address and the second
should give your own host name and the IP address your PPP connection
will use.  For example:

     127.0.0.1   loopback localhost                    # useful aliases
     192.1.1.17  billpc.president.whitehouse.gov bill  # my hostname
     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, 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
this:

     domain     president.whitehouse.gov
     search     president.whitehouse.gov  whitehouse.gov
     nameserver 192.1.2.1
     nameserver 192.1.2.10

Assuming there are nameservers at 192.1.2.1 and 192.1.2.10, then when
you get connected with PPP, you can reach hosts whose full names are
'hillarypc.president.whitehouse.gov' and 'chelseapc.whitehouse.gov' by
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

To use PPP, you invoke the pppd program with appropriate options.
Everything you need to know is contained in the pppd(8) manual page.
However, it's useful to see some examples:

Example 1: A simple dial-up connection.

Here's a command for connecting to a PPP server by modem.

  pppd connect 'chat -v "" ATDT5551212 CONNECT "" ogin: ppp word: whitewater' \
      /dev/cua1 38400 debug crtscts modem defaultroute 192.1.1.17

Going through pppd's options in order:
   connect 'chat etc...'  This gives a command to run to contact the
    PPP server.  Here the supplied 'chat' program is used to dial a
    remote computer.  The whole command is enclosed in single quotes
    because pppd expects a one-word argument for the 'connect' option.
    The options to 'chat' itself are:

         -v            verbose mode; log what we do to syslog
         ""            don't wait for any prompt, but instead...
         ATDT5551212   dial the modem, then
         CONNECT       wait for answer
         ""            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
   crtscts       use hardware flow control between computer and modem
                    (at 38400 this is a must)
   modem         indicate that this is a modem device; pppd will hang up the
                    phone before and after making the call
   defaultroute  once the PPP link is established, make it the default
                    route; if you have a PPP link to the Internet this
                    is probably what you want

   192.1.1.17  this is a degenerate case of a general option
        of the form  x.x.x.x:y.y.y.y  .  Here x.x.x.x is the local IP
        address and y.y.y.y is the IP address of the remote end of the
        PPP connection.  If this option is not specified, or if just
        one side is specified, then x.x.x.x defaults to the IP address
        associated with the local machine's hostname (in /etc/hosts),
        and y.y.y.y is determined by the remote machine.  So if this
        example had been taken from the fictional machine 'billpc',
        this option would actually be redundant.

pppd will write error messages and debugging logs to the syslogd
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

   daemon.*					/dev/console
           ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
           This is one or more tabs. Do not use spaces.

to syslog.conf; make sure to put one or more TAB characters between
the two fields.

Example 2: Connecting to PPP server over hard-wired link.

This is a slightly more complicated example.  This is the script I run
to make my own PPP link, which is over a hard-wired Gandalf link to an
Ultrix machine running Morningstar PPP.

  pppd connect /etc/ppp/ppp-connect defaultroute noipdefault debug \
      kdebug 0 /dev/cua0 9600

Here /etc/ppp/ppp-connect is the following script:
  #!/bin/sh
  /etc/ppp/sendbreak
  chat -v -t60 "" \; "service :" blackice ogin: callahan word: PASSWORD \
      black% "stty -echo; ppp" "Starting PPP now"  && sleep 5

This sends a break to wake up my terminal server, sends a semicolon
(which lets my terminal server do autobaud detection), then says we
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"
turned out to be very important for me; without it, my pppd would
sometimes start to send negotiation packets before the remote PPP
server had time to turn off echoing.  The negotiation packets would
then get sent back to my local machine, be rejected (PPP is able to
detect loopback) and pppd would fail before the remote PPP server even
got going.  The "stty -echo" command prevents this confusion.  This
kind of problem should only ever affect a *very* few people who
connect to a PPP server that runs as a command on a slow Unix machine,
but I wanted to mention it because it took me several frustrating
hours to figure out.

The pppd options are mostly familiar.  Two that are new are
"noipdefault" and "kdebug 1".  "noipdefault" tells pppd to ask the
remote end for the IP address to use; this is necessary if the PPP
server implements dynamic IP address assignment as mine does (i.e., I
don't know what address I'll get ahead of time).  "kdebug 1" sets the
kernel debugging level to 1, enabling slightly chattier messages from
the ppp kernel code.

Anyway, assuming your connection is working, you should see chat dial
the modem, then perhaps some messages from pppd (depending on your
syslog.conf setup), then some kernel messages like this:

	ppp: channel ppp0 mtu changed to 1500
	ppp: channel ppp0 open
	ppp: channel ppp0 going up for IP packets!

(These messages will only appear if you gave the option "kdebug 1" and
have kern.info messages directed to the screen.)  Simultaneously, pppd
is also writing interesting things to /usr/adm/messages (or other log
file, depending on syslog.conf).


IF IT WORKS

If you think you've got a connection, there are a number of things you
can do to test it.

First, type

	/sbin/ifconfig

     (ifconfig may live elsewhere, depending on your distribution.)
This should show you all the network interfaces that are 'UP'.  ppp0
should be one of them, and you should recognize the first IP address
as your own and the "P-t-P address" (or point-to-point address) the
address of your server.  Here's what it looks like on my machine:

lo        Link encap Local Loopback  
          inet addr 127.0.0.1  Bcast 127.255.255.255  Mask 255.0.0.0
          UP LOOPBACK RUNNING  MTU 2000  Metric 1
          RX packets 0 errors 0 dropped 0 overrun 0
          TX packets 0 errors 0 dropped 0 overrun 0

ppp0      Link encap Point-to-Point Protocol
          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

Now, type

	ping z.z.z.z

where z.z.z.z is the address of your name server.  This should work.
Here's what it looks like for me:

  waddington:~$ ping 129.67.1.165
  PING 129.67.1.165 (129.67.1.165): 56 data bytes
  64 bytes from 129.67.1.165: icmp_seq=0 ttl=255 time=268 ms
  64 bytes from 129.67.1.165: icmp_seq=1 ttl=255 time=247 ms
  64 bytes from 129.67.1.165: icmp_seq=2 ttl=255 time=266 ms
  ^C
  --- 129.67.1.165 ping statistics ---
  3 packets transmitted, 3 packets received, 0% packet loss
  round-trip min/avg/max = 247/260/268 ms
  waddington:~$

Try typing:

	netstat -nr

This should show three routes, something like this:

Kernel routing table
Destination     Gateway         Genmask         Flags Metric Ref Use    Iface
129.67.1.165    0.0.0.0         255.255.255.255 UH    0      0        6 ppp0
127.0.0.0       0.0.0.0         255.0.0.0       U     0      0        0 lo
0.0.0.0         129.67.1.165    0.0.0.0         UG    0      0     6298 ppp0

If your output looks similar but doesn't have the destination 0.0.0.0
line (which refers to the default route used for connections), you may
have run pppd without the 'defaultroute' option.

At this point you can try telnetting/ftping/fingering whereever you
want, bearing in mind that you'll have to use numeric IP addresses
unless you've set up your /etc/resolv.conf correctly.


IF IT DOESN'T WORK

If you don't seem to get a connection, the thing to do is to collect
'debug' output from pppd.  To do this, make sure you run pppd with the
'debug' option, and put the following two lines in your
/etc/syslog.conf file:

    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
field and the right-hand field must be separated by at least one TAB
character.  After modifying /etc/syslog.conf, you must execute the
command 'kill -HUP <pid>' where <pid> is the process ID of the
currently running syslogd process to cause it to re-read the
configuration file.

Some messages to look for: 
  - "pppd[NNN]: Connected..." means that the "connect" script has
    completed successfully.  
  - "pppd[NNN]: sent [LCP ConfReq"... means that pppd has attempted to
    begin negotiation with the remote end.  
  - "pppd[NNN]: recv [LCP ConfReq"... means that pppd has received a
    negotiation frame from the remote end.
  - "pppd[NNN]: ipcp up" means that pppd has reached the point where
    it believes the link is ready for IP traffic to travel across it.

If you never see a "recv" message then there may be serious problems
with your link.  (For example, the link may not be passing all 8
bits.)  If that's the case, it would be useful to collect a debug log
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