PPPD for DOS 0.5 alpha              Copyright (c) 1997 Antonio Lopez Molero


CONTENTS

        OVERVIEW
        WHO AM I
        LICENSING
        CREDITS
        FILES
        FEATURES
        UNSUPPORTED FEATURES
        USAGE
        CONFIGURATION FILES
        PAP AUTHENTICATION
        REMOVING THE DRIVER
        ABOUT THE VARIOUS DRIVER EXECUTABLES
        BOOTP PROTOCOL SUPPORT
        ABOUT CHAT AND CHAT0
        CONFIGURING DOS INTERNET APPLICATIONS
        SITES WITH ADDITIONAL DOS INTERNET STUFF


OVERVIEW

    This is the first release of my DOS PPP packet driver. This work is
    derived from various sources. The bulk PPP code is taken from the
    ppp2.2.0f PPP daemon version, the serial port handling code is derived
    from the KA9Q network operating system and the packet driver interface
    code is derived from the CRYNWR packet driver collection.

    I did the tedious work of joining all these pieces and make it work as
    a TSR under our old friend DOS. I learned a lot about DOS TSR
    programming and the PPP protocol internals.

    I was pushed into developing this driver by the necessity of having
    something more stable an not so memory hungry than the available DOS
    PPP packet drivers. I also enjoy free software so I felt that
    contributing to it in some way would be a nice thing to do.

    DOS still alive and there are a number of applications for this driver.
    The most obvious is for surfing the NET, as there are a number of good
    DOS programs for do this. I enclose a list of locations where you can
    find such applications later in document. Another interesting field of
    application is in embedded PC computers used in industrial systems. For
    some palmtop computers that can't run the Windows CE version, this
    driver is a good alternative when used in conjunction with DOS internet
    programs.


WHO AM I

    My name is Antonio Lopez (Toni), I work at the R+D dept. of an
    Industrial Applications Development firm in Spain. Yo can contact me at
    the following e-mail addresses:

        tonilop@redestb.es
        tonilop@ibm.net

    My english is not as good as I would like, I apologize for this.

    This work was done at home, and has nothing to do with my actual job.
    I'm responsible of the entire project. Don't bother the authors of the
    original code with bug reports, ask to me.


LICENSING

    The TERMIN.COM program is copyright by Russell Nelson an is released
    under the GNU public license. I provided it only as a convenience for
    users. You can download it from many places.

    The COMTOOL.COM and COMTOOL.DOC are copyright by K.H. Weiss. It is
    freely distributable for non commercial use. Again, I provide this
    files only as a convenience for users.

    The CHAT source code is in the public domain, so CHAT.EXE and
    CHAT0.EXE are in the public domain too.

    The PPP code on which my work is based holds the following copyright:

    ***********************************************************************
    * Copyright (c) 1989 Carnegie Mellon University.                      *
    * All rights reserved.                                                *
    *                                                                     *
    * Redistribution and use in source and binary forms are permitted     *
    * provided that the above copyright notice and this paragraph are     *
    * duplicated in all such forms and that any documentation,            *
    * advertising materials, and other materials related to such          *
    * distribution and use acknowledge that the software was developed    *
    * by Carnegie Mellon University.  The name of the                     *
    * University may not be used to endorse or promote products derived   *
    * from this software without specific prior written permission.       *
    * THIS SOFTWARE IS PROVIDED ``AS IS'' AND WITHOUT ANY EXPRESS OR      *
    * IMPLIED WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED      *
    * WARRANTIES OF MERCHANTIBILITY AND FITNESS FOR A PARTICULAR PURPOSE. *
    ***********************************************************************

    I release the package under the following conditions:

          All products mentioned in this documentation which are
          patented, copyrighted or are trademarks are the property
          of their respective owners.

          The various source modules written from scratch for DOS
          support, the README.TXT file and the SAMPLES.TXT file are
          Copyright (c) 1997 by Antonio Lopez Molero.
          All applicable rights reserved.

          DOS PPPD can be freely distributed for non commercial use,
          provided you include this copyright notice in all the copies
          or derivative works. You can charge money for the process
          of copying/transferring the files, but not for the software
          itself.

          DOS PPPD IS PROVIDED "AS IS" WITHOUT WARRANTY OF ANY KIND,
          either expressed or implied, including, but not limited
          to, the implied warranties of merchantability and fitness
          for a particular purpose.  The entire risk as to the
          quality and performance of the product is with the user.
          This documentation explicitly states that DOS PPPD will not
          work properly in some circumstances; the user assumes the
          cost of all necessary servicing, repair or correction.

          In no event will Antonio Lopez Molero be liable for damages,
          including any general, special, incidental or consequential
          damages arising out of the use of, or inability to use,
          DOS PPPD (including but not limited to loss of data or data
          being rendered inaccurate or losses sustained by the user
          or third parties or a failure of the product to operate
          with any other programs), even if the author has been
          advised of the possibility of such damages.

          You may use DOS PPPD only if you have read, understood and
          accepted all of the above conditions.

          Please contact me to report bugs or errors in the document
          (even minor ones). If you are an application developer or
          packet driver programmer and have constructive suggestions
          for improving the performance of DOS PPPD I'd be glad to
          hear from you.

    Althought I have a real job, donations will be greatly appreciated if
    you feel the necessity to do so ;-)


CREDITS

    The PPP code credits will go to Al Longyear and Mike Callahan, the
    creators of the ppp2.2.0f package. The original PPP code was
    created by: Drew Perkins, Brad Clements, Karl Fox, Greg Christy, Brad
    Parker and Paul Mackerras.

    The serial port code credits will go to Phil Kharn, the creator of the
    excellent KA9Q Network Operating System.

    The packet driver code credits will go to Russell Nelson, the creator
    and maintainer of the superb CRYNWR packet driver collection.

    The BOOTP code credits will go to Bruce Campbell, the creator of the
    BOOTP packet driver add-on.

    I must mention Frank Molzahn, the creator of PPPPKT06. I used his
    techniques for netmask calculation based in remote/local IP addresses.


FILES

    The distribution comprises the following files:

        README.TXT      This file.

        SAMPLES.TXT     Some sample configurations for PPPD use. These are
                        the ones I'm using for connecting to my ISP.

        PPPD.MAN        A plain ASCII version of the UNIX pppd man page,
                        adapted for the DOS version.

        CHAT.MAN        A plain ASCII version of the UNIX chat man page,
                        adapted for the DOS version.

        PPPD.EXE        Class 6 (serial line) PPP driver without debug
                        capabilities, smallest.

        PPPDD.EXE       Class 6 (serial line) PPP driver with debug
                        capabilities.

        EPPPD.EXE       Class 1 (ethernet emulation) PPP driver without
                        debug capabilities. Emulates ARP and BOOTP replies
                        for helping configure DOS applications.

        EPPPDD.EXE      Same as above but with debug capabilities, largest.

        CHAT.EXE        Modem connection tool for use with the 'connect'
                        option from PPPD. It can not be used standalone.

        CHAT0.EXE       Modem connection tool for standalone use.

        TERMIN.COM      Packet driver terminator.

        COMTOOL.COM     Tiny serial port manipulation utility.

        COMTOOL.DOC     Documentation for COMTOOL.


FEATURES

    The code is compiled for 8088 CPU, so it must run in XT class
    machines. I have no access to any XT machine, so I was unable
    to test it.

    The 16550AFN UART is supported, allowing reliable communications
    up to 115200 baud speed. The chip is autodetected and the FIFO
    enabled with a 8 byte receiver threshold, the transmitter is
    set up for 16 byte output FIFO.

    The drivers conforms to FTP packet driver specification 1.09,
    same as the ones in the superb CRYNWR packet driver collection.

    Both class 1 (ethernet) and class 6 (serial line) drivers are
    included in the package.

    The class 1 drivers emulates a BOOTP server, so automatic
    configuration of DOS applications through BOOTP is possible.

    Automatic generation of a DOS batch file for setting up some
    environment variables with the actual connection TCP/IP data.

    Most of the original PPPD options are supported, including PAP
    authentication. The next section covers what is not supported.


UNSUPPORTED FEATURES

    CHAP style authentication, VJ compresion, CCP (compression control
    protocol, used for negotiating data field compression), IPX style
    packets, authentication of the peer (we can authenticate ourselves
    using PAP however), PPP server mode, PAP password encryption,
    defaultroute option, proxyarp option, noipdefault option.


USAGE

    I tried to mimic the original PPPD version as much as possible, so
    any experience you might have with it may prove useful here.

    For a complete reference of PPPD and CHAT options, look at the files
    PPPD.MAN and CHAT.MAN. These files were adapted from the original
    man pages. I will give an usage overview here.

    The process of establishing a PPP link can be divided in two clearly
    separate actions, connection of the physical serial line and execution
    of a PPP process responsible of the actual TCP/IP communications.

    The physical serial line connection would be different for modem links
    and for cable serial links. The former requires some mechanism for
    talking to the modem, making it dial and establish a connection with
    the other end modem. The later doesn't require this step, as the serial
    ports are directly attached via a cable.

    For modem links you have two ways of making the connection. One is to
    use some program prior PPPD execution that interacts with the modem and
    leaves the connection opened after exiting, then you run PPPD that
    takes over the link and begins its negotiations. On of such programs is
    KERMIT, a general purpose terminal emulator for the PC. You can also
    use the enclosed CHAT0.EXE program for this way of working.

    The second way is to use the 'connect' option from PPPD for
    especifiying a program that must be run for modem handling. At the
    moment you can only use the enclosed CHAT.EXE program for this, as the
    COM port is internally handled by PPPD and there is a private interface
    between the two programs that allows CHAT to use whatever port PPPD is
    configured to use. This is necessary because you can't do the serial
    port stuff under DOS the same way you do under *NIX. When running
    under this OS, CHAT uses the stdin/stdout for doing its I/O. These
    channels are redirected by PPPD to the serial port before invoking the
    'connect' script.

    In any case you specify the serial port to use and some other stuff via
    options to PPPD. These options can be given in the command line or
    taken from an options file. CHAT only supports command line options,
    the CHAT script can be in a file.

    A tiny sample usage of PPPD with modem follows:

        pppd com1 38400 connect "chat '' AT&F OK ATDP055 CONNECT"

    In this sample we are using the enclosed CHAT.EXE program for talking
    to the modem using the port settings inherited from PPPD.

    The PPPD program sets up COM1 at 38400 baud speed and then invokes CHAT
    for establishing the serial link. The chat script shown expects
    nothing, sends AT&F, expects OK, sends ATDP055 and expects CONNECT. If
    all of these expect/send pairs succeed, CHAT exits with a 0 exit code
    signaling to PPPD that it can proceed with PPP negotiation. If some
    error occured during the CHAT phase, the CHAT program returns a
    non-zero exit code that signals to PPPD that something was wrong with
    the connection.

    Assuming CHAT success, then PPPD next job is to negotiate a IP link
    establishment. Only when this link is successfully negotiated will PPPD
    stay resident in memory as a packet driver. In any other cases the
    program exits with a non-zero exit code and will not remain resident.

    A message showing the packet driver interrupt used by the driver will
    be displayed upon successful link establishement. In case the driver
    can't establish a successful PPP link, an error message is displayed.

    The PPPD exit code may be checked in DOS batch files in order to
    trigger the apropiate actions based in successful/unsuccessful
    connection.

    For directly attached computers, one would simply do:

        pppd com1 38400 local

    The 'local' option forces PPPD to ignore the CARRIER DETECT line, that
    maybe isn't available for the cable connection.


CONFIGURATION FILES

    The PPPD program looks for options in some places besides the command
    line. The names and search order for the files is as follows:

        PPPD.CFG                in the current directory.
        PPPD.CFG                in the same directory PPPD.EXE is located.
        PPPDRC.CFG              in the current directory.
        command line options
        pppd 'file' option      full path given.
        PPPDCOM?.CFG            in the current directory.

    PPPD.CFG can be viewed as a global options file, as it can be located
    under the same directory PPPD.EXE resides.

    The PPPDCOM?.CFG completes it name based in the COM port used, so
    invoking 'pppd com1' will look for a PPPDCOM1.CFG file.

    All the files excluding the one given with the 'file' option are
    optional, it doesn't need to exist for PPPD operation. However, the use
    of configuration files is practically a necessity due the DOS command
    line length restrictions

    These files can be given hidden/system/read-only DOS attributes, as the
    PAP passwords (if used) must be included in it. I know that this a very
    poor security implementation, but it is all that can be done under DOS
    until I implement password encryption.


PAP AUTHENTICATION

    This method of authentication is supported by the driver. There is no
    /etc/pap-secrets file under DOS, so I take the aproach of implementing
    a new PPPD option, 'passwd'. This one, in conjunction with the 'user'
    option, provides PPPD with the necessary data for authenticating
    ourselves with the peer.

    A typical use would be:

        pppd com1 38400 user self passwd blah connect "chat '' ATDP055 CONNECT"

    These options can be include in a configuration file that has hidden
    attributes, for example the file myppp.cfg contains:

        com1
        38400
        modem
        asyncmap 0
        connect "chat '' AT&F OK ATDP055 CONNECT"
        user someuser
        passwd blah2blah

    You can run PPPD with:

        pppd file myppp.cfg

    In fact, the above options could be in any of the automatic
    configuration files searched by PPPD and then you can forget the 'file'
    option.

    The 'user' and 'passwd' fields can be surrounded in double quotes in
    case threre are embedded blanks or characters that may be interpreted
    by PPPD options parser.

    An alternative source for PAP authentication data can be given with the
    '+ua' option. You give the name of a file that contains the user id and
    the password, for example assume a file called PAPLOGIN.DAT:

        pppuser
        pppuser_password

    Then invoke PPPD as:

        pppd com1 38400 +ua paplogin.dat

    The file can have the hidden attribute set.


REMOVING THE DRIVER

    For removing the driver, use the enclosed TERMIN.COM program. This is a
    general purpose packet driver terminator, part of the CRYNWR packet
    driver collection.

    Call it as:

        TERMIN 0xnn

    Where nn is the hex number of the interrupt vector used by the
    installed driver, i.e. TERMIN 0x60.

    The PPPD driver will send a Terminate request to the peer before being
    removed, so the TERMIN return to the command line will be delayed a
    little. This delay can be of maximum of 10 seconds, depending on how
    fast the peer responds to the terminate request.


ABOUT THE VARIOUS DRIVER EXECUTABLES

    As you noticed, there are four different PPPD executables. The ones
    called PPPD.EXE and PPPDD.EXE are class 6 packet drivers (serial line),
    the later including some debug capabilities that can be used for
    troubleshoting connection problems.

    The ones called EPPPD.EXE and EPPPDD.EXE are class 1 packet drivers
    (ethernet), EPPPDD.EXE contains aditional code for debugging connection
    problems. This ones emulates the behavior of a real ethernet driver,
    adding an ethernet header to incoming packets and removing it from sent
    packets. The need for emulation comes from the fact that many DOS
    internet applications were devised for ethernet only packet drivers,
    and can't handle class 6 packet drivers. The ethernet emulation
    versions supports BOOTP, a protocol used by TCP/IP networking code for
    auto-configuring workstations via a centralized server.

    The debugging capabilities generates various kinds of messages to the
    DOS standar output, and some other to the DOS standar error. You can
    use redirection for logging the standar output to a file, standar error
    can be redirected by the help of some third party utilities.

    The debug level is affected by the 'debug' and 'kdebug' options,
    supported only by the PPPDD.EXE and EPPPDD.EXE executables. Look in the
    PPPD.MAN file for a deeper explanation.

    The debugging output stops as soon as the driver goes resident,
    supporting disk I/O under DOS TSRs is a difficult task that isn't worth
    the time wasted to implement it.


BOOTP PROTOCOL SUPPORT

    Some DOS internet applications support a method for automatic TCP/IP
    configuration, called the BOOTP protocol. The ethernet emulation
    versions of the PPPD driver supports this form of configuration, acting
    as a fake BOOTP server that generates a reply whe it sees a BOOTP
    request.

    In order to fully support the BOOTP protocol, I added an option that
    doesn't exist in the original PPPD code. The option is 'namsrv' and is
    intended for specifiying up to two nameservers IP addresses that will
    be sent to the application doing a BOOTP request. The rest of BOOTP
    information is generated from the local/remote IPs negotiated by PPPD
    during the link establishment phase.

    The remote IP will be used for gateway address and for server address,
    the local IP will be used for 'your_ip' address. The netmask is
    calculated using the following method:

    First, a value is obtained based just on the class (i.e. class A, B or
    C) of the local IP, specifically:
    
    class A ==> 255.0.0.0
    class B ==> 255.255.0.0
    class C ==> 255.255.255.0

    If this value is consistent with the gateway's IP number, that is, if:

    ( <netmask> & <gateway> ) = ( <netmask> & <localIP> )

    [where & represents logical AND], then this value is used as the
    netmask.  (See RFC 950.) Otherwise, a different netmask value is
    chosen: it is the largest number which (a) is consistent in the above
    sense, and (b) has a binary form of 1's followed by 0's.

    This method is the same used by Frank Molzahn's PPPPKT06 driver. This
    calculated value is then binary ORed with any user suplied value
    through the 'netmask' option.

    This netmask calculation method applies to both the class 6 and class 1
    version of the drivers, regardless of the BOOTP support.


ABOUT CHAT AND CHAT0

    The CHAT program takes a serie of strings called the CHAT script and
    executes an expect/send sequence until it consumes all the script or
    any of the expectations fails.

    The CHAT script can be given in the command line or through a file. In
    the DOS world where command line length is restricted, the script file
    is the recommended way unless your CHAT script is very short.

    As noted somewhere else in this document, two CHAT versions are
    enclosed in the package. The CHAT.EXE version is intended to be used
    with the 'connect' option from PPPD. It access the serial port through
    a private interface in PPPD.EXE, so it doesn't requires options for COM
    port configuration. It uses the port for which PPPD is configured.

    The CHAT0.EXE version can be used standalone, as it incorporates its
    own routines for COM access. Having the two versions is convenient,
    because you can use CHAT0.EXE for testing your CHAT scripts before you
    actually use it wit CHAT.EXE and the PPPD 'connect' option. The
    CHAT0.EXE version will leave the DTR line high upon successful
    termination, so the modem connection will be active and you can run
    PPPD after that. This behavior is the same as if you were using some
    other dialing program, for example KERMIT.


CONFIGURING DOS INTERNET APPLICATIONS

    There a number of different schemes used by DOS applications for
    configuring the required TCP/IP parameters.

    Some of them support the BOOTP protocol, a feature that is supported by
    the EPPPD.EXE and EPPPDD.EXE drivers. WATTCP based applications will
    try BOOTP configuration if the WATTCP.CFG file (or equivalent) can't be
    found, or if you put a line: my_ip=bootp in such file. The POPMAIL and
    MINUET applications will use BOOTP if you leave the Network
    configuration dialog boxes blank. You must consult the application
    documentation for more info about how to use BOOTP.

    If your application doesn't support BOOTP or if you are using the
    PPPD.EXE or PPPDD.EXE drivers, the configuration should be done by
    another means. All the four drivers generates a .BAT file called
    IP-UP.BAT that is meant to be run after successful connection for
    setting some DOS environment variables. Then you can use these
    variables inside a DOS batch file for generating text configuration
    files, for example the WATTCP.CFG file required by WATTCP applications.

    The IP-UP.BAT generated by the PPP drivers looks like:

        SET MYIP=xxx.xxx.xxx.xxx
        SET REMIP=yyy.yyy.yyy.yyy
        SET NETMASK=zzz.zzz.zzz.zzz
        SET PEERMRU=nnnn

    Some of the samples in SAMPLES.TXT file will make use of these
    variables to show how to configure WATTCP applications (DOSLYNX) using
    this technique.

    For MINUET and POPMAIL, the environment is searched for a variable
    called MYIP if the corresponding field in the Network configuration
    dialogs is blank. It this variable can't be found, these applications
    tries the BOOTP method.

    If none of these methods is suitable, you are forced to enter the
    required configuration data every time you run the application. There
    are some cases in which command line arguments can be used for the
    TCP/IP configuration, like the PCGOPHER program (which supports BOOTP
    also).

    It happened to me that MINUET fails to configure through BOOTP with
    my drivers. It is the only one of the applications I tried that shows
    this behavior. WATTCP based programs, POPMAIL and PCGOPHER runs fine
    under my BOOTP emulation, so I'm unsure about where the problem is.

    The file SAMPLES.TXT contains some examples derived from my actual DOS
    applications configuration, including DOSLYNX and MINUET.


SITES WITH ADDITIONAL DOS INTERNET STUFF

    The following sites hold lots of good DOS Internet stuff, these are the
    places to go if you are looking for WEB browsers, mailers, etc.

    TVDog's DOS Internet page:

        http://www.agate.net/~tvdog/internet.html

    DOSLYNX home page:

        http://www.fdisk.com

    KERMIT:

        http://www.columbia.edu/kermit

    Althought not an Internet application in its own, kermit can be a
    invaluable terminal emulator and modem dialer. Recent versions
    incorporates the WATTCP TCP/IP kernel, so they can act as a good TELNET
    client when used with a packet driver.

    DOS Internet home page:

        http://www.wustl.edu/~hugh/dos-www.html

