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: ( & ) = ( & ) [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