OS/2 Professional

home *** CD-ROM | disk | FTP | other *** search

/ OS/2 Professional / OS2PRO194.ISO / os2 / network / slip / readme < prev next >

Wrap

Text File | 1993-08-18 | 23.2 KB | 578 lines

------------------------------------------------------------------------------ OS/2 2.0 SLIP Driver for IBM TCP/IP v1.2.1 Version 1.0 David Bolen - db3l@ans.net README ------------------------------------------------------------------------------ This file describes the contents of the SLIP20V1.ZIP archive, and presents a brief description of how to install the SLIP driver and get everything up and running. This file contains the following sections: Driver History Release history for SLIP Driver Archive Contents Description of the contents of the archive Installation Basic Installation Instructions Getting Connected Establishing the SLIP connection Attach scripts Using Rexx scripts to make a connection Executables Brief usage descriptions of executables Reporting Problems What procedure to follow to report problems Administrivia How to contact me I would appreciate if everyone could at least browse through this entire file prior to using the driver. Having at least a general idea of the contents of this file can prove helpful when dealing with problems, since some points (such as the potential need for the sldetach utility) do not occur until late in the file. +----------------+ | Driver History | +----------------+ Version 1.0 August 18, 1993 ----------- This is, finally, Version 1.0 of the driver. The entire development/alpha/beta/release cycle for version 1.0 took almost a year, but I think the end result is a very stable and functional driver that many people have been and will be able to use. There are some changes between the Beta-1 release and Version 1.0. Most are nothing more than reflecting the released status of the driver and utilities. The following changes are more significant: - Compression is now off by default, and the default MTU is 1006. This is in contrast to the previous defaults for these settings of "on" and 296 respectively. The change was made to simplify initial setup and to avoid the confusion that default compression caused for some. For those users previously using compression, the parameter "compression=on" will need to be added to the interface block in your slip.cfg file. As explained in the comments in slip.cfg, enabling compression will also automatically decrease the MTU back to 296, unless the MTU is explicitly specified in slip.cfg. - Priority queueing has been improved. The SLIP driver no longer allows its entire internal buffer (2k) to be filled and potentially delay interactive traffic. This should result in improved interactive performance during heavy background traffic (such as file transfers) when the transmitting side of the SLIP connection is running this driver. - The driver now dynamically determines the internal kernel serial unit number to assign to the SLIP interface. This should have little impact on users as this is the only current driver using the kernel serial interface, but it will allow this driver to behave nicely in the presence of other drivers using the interface in the future. It does also involve a new startup error, of the form: [MON ] Interface "sl0" is already attached (unit #). This message will normally only appear if another copy of the SLIP driver is already running, or if the previous execution of the driver was abruptly terminated, such as by a trap. If the latter, the "sldetach" utility should be used to detach the interface from the kernel. Beta-1 April 12, 1993 ------ Well, the alpha code turned out to be available for much longer and more widely distributed than I had originally intended. This release is mostly a recognition of the fact that the code has already been effectively tested as beta code. It should be a short beta. Note that I did perform an internal code clean-up on the whole package, and there are a few externally-visible changes: - All alpha/debugging output has been suppressed by default. A commmad line option of "-d" will re-enable all debugging messages as before. - A comma can now optionally be used in the slip.cfg configuration file to separate elements. - The Rexx script functions com_input and com_output have been renamed to slip_com_input and slip_com_output. - The return code from Rexx scripts now determines if the driver exits. A zero return code indicates success while a non-zero value indicates failure. The last two items above represent differences that will require changes to any scripts that may have been written. If you are using the supplied slipup.cmd script, you can just use the new version from this package. Alpha-3 October 28, 1992 ------- After a bit of a hiatus, I've added much of the functionality that I want to go to beta with. The big two user-visible items are a new configuration file, and the support for calling a Rexx script to handle establishing the SLIP connection. Internally, the core forwarding path has not changed, but a number of improvements have been made to simplify handling multiple interfaces in the next update. Alpha-2 September 24, 1992 ------- This was a release solely of the SLIP Driver executable. The new executable contained a fix for the bug encountered when large packets were received by the driver that exceeded the interface mtu. Alpha-1 September 21 & 23, 1992 ------- This was the first public release of the OS/2 2.0 SLIP Driver code. The original release on 9/21 was augmented by a release of debugging versions of the driver on 9/23 to aid in problem reporting. +------------------+ | Archive Contents | +------------------+ The SLIP20V1.ZIP archive contains the following files: readme This file slip.exe Main SLIP Driver slipwait.exe Utility to wait until SLIP is up and running slipterm.exe Simple terminal program for making SLIP connections sliphold.exe Utility to hold a COM port open sldetach.exe Utility for forceably detaching a SLIP interface slcfg.exe Utility to test parsing SLIP configuration files slip.cfg Sample SLIP configuration file (store in ETC directory) slipup.cmd Sample SLIP attach script (keep somewhere in path) ifndisnl.sys "Null" version of ifndis.sys. This can be used in place of the standard ifndis.sys if you are only using the SLIP interface (no LAN interfaces) +--------------+ | Installation | +--------------+ NOTE: In order to be able to use this SLIP driver, you must be running OS/2 2.0, and you must have v1.2.1 of the IBM TCP/IP package, with a corrective service of at least UB02252 installed. This is critical! If you have an earlier version, depending on the level, SLIP may simply not run, or it may crash your system. Or if it doesn't, some utilites, like "netstat" - may... The most common indication that you are not running an appropriate version is the message "Error 22 during DosDevIOCtl(SLATTACH)" during the startup of the SLIP driver. You can check your current TCP/IP level by using the SYSLEVEL command, and the latest CSD for TCP/IP is available from ftp-os2.nmsu.edu, ftp-os2.cdrom.com, or software.watson.ibm.com. Step 1 - CONFIG.SYS ------------------- Presuming you have used ICAT to install TCP/IP, your CONFIG.SYS should already be pretty well set up. However, it's not absolutely necessary to use ICAT, and in fact if you are just copying TCP/IP off of an already installed machine to set up a SLIP machine, it may prove easier to just do the setup manually. Also, if you use ICAT but configure no other interfaces beyond SLIP, it does not add the necessary statements to your CONFIG.SYS file. The important pieces of the puzzle are to have at least the following in your CONFIG.SYS: DEVICE=\path\INET.SYS DEVICE=\path\IFNDIS.SYS (or IFNDISNL.SYS - see below) RUN=\path\CNTRL.EXE where "\path" is the location where you installed the TCP/IP binaries If you are only using the SLIP interface (ie: a home machine), besides not requiring the protocol manager and assorted baggage, this SLIP driver does not really even require the ifndis.sys device driver. If you like, you can replace ifndis.sys with the ifndisnl.sys (IFNDIS "Null") driver that is supplied as part of this package. This will save both the memory involved with ifndis.sys (all of the LAN interfaces and NDIS code), as well as several threads and 40-50K of stack in cntrl.exe. Step 2 - SLIP.CFG ----------------- You must place a file called SLIP.CFG in your ETC directory (pointed to by the ETC environment variable - normally \tcpip_root\ETC - where tcpip_root is where you installed TCP/IP). A sample SLIP.CFG is supplied in the archive that describes in detail the format of the file and each of the parameters that you can use within the file. For the most part, it is recommended that you start off with a default SLIP.CFG, and then experiment if you like after you have a running system. Two common parameters that you might need or wish to change are: device Set this to the COM device to run the SLIP interface over (if something other than COM1) compression Set this to ON if the far end of the SLIP link supports VJ header compression. This will yield significantly better performance for interactive applications such as telnet and other TCP-based protocols such as FTP. So for an interface with compression using COM3, you would change the supplied SLIP.CFG file interface line from: interface sl0 { } to interface sl0 { device=com3, compression=on } Note that by default, the MTU of the SLIP interface is set to 1006, which is the older SLIP default MTU for an uncompressed link. If you turn compression on, the MTU will be automatically decreased to the newer default of 296. This can be overridden by explicitly setting the MTU within slip.cfg. Also, if at any point while the driver is running, a packet is received that is larger than the MTU of the SLIP interface, a message of the form: Warning: Received packet (#1) > MTU (#2) will be displayed in the SLIP driver's window (#1 is the packet size received, and #2 is the MTU of the SLIP link). You should verify with the remote end of the SLIP link that both ends are configured for the same MTU, and if not, fix one or both of the configurations. Step 3 - SLIP Executables ------------------------- You should load the remaining SLIP executables into whatever directory you would like, and place that directory in your PATH for easy access to the utilities. The sample script (SLIPUP) and any other scripts you may write should also be located either in the directory where you start the SLIP driver (SLIP.EXE) or somewhere along your PATH. +-------------------+ | Getting Connected | +-------------------+ In general the following steps are the simplest for getting a SLIP connection up and running. If you want to use the Rexx scripting capability for automating this process, see the next section. 1. Configure your COM port appropriate for baud/parity, etc.. For example, mode com1: 38400,n,8,1,buffer=auto,rts=hs (Adjust the port number, baud rate, etc.. as appropriate. If you have a 16550 UART, I'd strongly suggest trying buffer=on for improved performance) This can also be put in your CONFIG.SYS via a CALL= command if you like. 2. In a separate OS/2 command process (window or full-screen), start the SLIP driver (slip.exe). You can also put it in its own window by using the "start" command (ie: "start slip"). In theory, the SLIP driver can be run as a background driver, as CNTRL.EXE is, and could be started from config.sys. However, in general I'd recommend leaving it in a window you can see, although you can certainly minimize it, in case diagnostic messages are displayed. 3. If you need to dial a number and perhaps log into a system to start SLIP, run SLIPTERM at this point. SLIPTERM will put up a banner, request access to the COM port from SLIP, and then allow you to talk to the modem directly. SLIPTERM is just a very simple communications program. You will have to enter any dialing commands manually (ie: ATDT), but it will allow you to perform any operations (such as logging in and issuing some initial startup commands) that you may need to create an active SLIP link. Press F10 (or ESC) when done. 4. Configure the SLIP interface with your SLIP address, and with the address of the far end. Note: Unlike IBM's driver, my SLIP driver sets up serial interface "sl0", not just "sl": > ifconfig sl0 147.225.2.15 147.225.2.1 (you) (far end) If you are configuring an office machine to perform routing from a SLIP link to an office LAN (such as an ethernet), the easiest thing to do is to get a local LAN address assigned to the far end of the SLIP link and to reuse the LAN address of your office host as the local address of the SLIP link. 5. Configure other routes: * For a home machine with no other network interface, you will likely want to add a default route through the far end of the SLIP link: > route add default 147.225.2.1 1 (far end) * For an office machine with a LAN interface (such as an ethernet), you will probably already have a default route. However, if you have assigned the SLIP interface a remote address from the network on the LAN, you will have to publish an "arp" entry for the SLIP host. This is done with the following command: > arp -s 147.225.2.1 xx:xx:xx:xx:xx:xx pub (far end) The "xx:xx..." number is the hardware address of your LAN interface. This can be determined after booting your machine by looking in the file LANTRAN.LOG in your C:\IBMCOM directory (or wherever you installed the LAPS lan drivers). Look for the "node address". At this point you should be all up and running. You can place all of this in a command file if you like. If you do this, the command file can check ERRORLEVEL after running SLIPTERM. If it is non-zero, then SLIPTERM exited via ESC, while if it is 0, F10 was used. This can be used to control whether the SLIP interface is actually configured. Also, if you are automating this process, you may want to use either SLIPWAIT or the "-w" option on SLIPTERM. SLIPWAIT takes a single numeric argument which is the # of seconds to wait for SLIP to complete starting up (and it defaults to 30). This can be used to pause a command script while waiting for SLIP.EXE to fully start up. Specifying "-w##" to SLIPTERM will cause it to also wait for SLIP to finish starting up. ## specifies the number of seconds to wait, or if not given (ie: you just use "-w") it defaults to 30 seconds. +----------------+ | Attach Scripts | +----------------+ One of the nicer features of this SLIP driver is the ability to use Rexx scripts to automate the attachment of a SLIP interface. The SLIP driver will automatically execute an attach script when it starts up and is creating the SLIP interface. Scripts are free to use the full power of Rexx and issue OS/2 commands as necessary. In addition, the SLIP driver defines Rexx functions that can be used to access the COM port that the driver is using for the interface. Defining a Script ----------------- In order to use a script for an interface, you need to set the "attachcmd" and "attachparms" parameters in the interface definition in the SLIP configuration file SLIP.CFG. For example, the entry: interface sl0 { attachcmd "slipcall", attachparms "these are parms" } would cause SLIP to run the script "slipcall.cmd" and pass in the parameters "sl# , these are parms". SLIP will always pass in the name of the interface for which the script is running as the first argument, with the attachparms value as the second argument. In this version of the driver, the script is only executed once, when SLIP first starts up and creates the interface. SLIP Rexx Functions ------------------- The following functions are available to Rexx scripts running beneath the SLIP driver: slip_com_input ( interface , [ max_characters ] , [ timeout ] ) Reads characters from an interface's COM port. interface The name of the interface (ie: sl0), and should be the same as the interface name supplied as the first argument to the script. max_characters The maximum number of characters to return with this call. It may return less. The default is to return up to 255. timeout How long to wait (in milliseconds) if no data is available on the port. If this is not specifed, or is given as 0, it will wait forever until some data arrives. slip_com_output ( interface , string ) Write characters to an interface's COM port. interface The name of the interface (ie: sl0), and should be the same as the interface name supplied as the first argument to the script. string Character string to be sent to COM port. Nothing is done to the string, nor is any automatic CR added, so you must specify exactly what characters to send. Note that even when this function returns to the Rexx script, not all of the characters may have been physically transmitted over the COM port. There are internal buffers within the SLIP driver that may hold the outgoing COM data while the port is busy or disconnected. slip_getch () Read a character (no echo) from the keyboard This function simply waits for the user to press a key and returns that key. It does not echo the keypress to the screen. It is designed to be used for when scripts need to prompt the user for a password or other sensitive information. This function will only work if the SLIP driver is running within an OS/2 command session where a user may interact with the driver. If it is running as a detached session, this function will always return an empty string. These functions are only available when a script is run automatically by the SLIP driver. If the scripts are started directly from the command line, these functions will not be resolved. Sample Attachment Script ------------------------ The file SLIPUP.CMD in the archive is a sample script that I have used to make a SLIP attachment through our Xylogics Annex Terminal Server. It may prove useful as an example on how to write such scripts for other environments. More detailed comments are available within the script itself, however its basic purpose is to issue a dial command, handle the Annex logon, issue a SLIP command, and then parse the answer to appropriately configure the sl0 interface with the right address. Comments -------- I'm very interested in feedback as to what sort of additional support the SLIP driver could provide to make it easier to write Rexx scripts for this sort of purpose. +-------------+ | Executables | +-------------+ slip.exe Main SLIP Driver Usage: slip [-d] -d enables debugging (voluminous) output. You'll probably want to redirect output to a file if you enable debugging. The SLIP driver requires the SLIP.CFG file to be accessible in the "ETC" directory. - - - - - slipwait.exe Utility to wait until SLIP is up and running Usage: slipwait [##] ## specifies # of seconds to wait (default = 30) - - - - - slipterm.exe Simple terminal program for making SLIP connections Usage: slipterm [-w[##]] [-d] -w says to wait for SLIP. ##=seconds and defaults to 30. -d is debugging mode - continue without SLIP SLIPTERM requires the SLIP.CFG file to be accessible in the "ETC" directory. It uses this file to determine the appropriate COM port. When the program is exited with the ESC key, the exit code (testable with ERRORLEVEL) is set to non-zero. If the program is exited by pressing F10, the exit code is zero. - - - - - sliphold.exe Utility to hold a COM port open Usage: sliphold This utility simply keeps the COM port open until the Enter key is pressed. OS/2 normally drops DTR when the COM port is closed, which terminates the connection on many modems. Running sliphold will allow you to stop and then restart the SLIP driver without losing the connection. - - - - - sldetach.exe Utility for force a detach of interface sl0 Usage: sldetach interface interface is the name of interface to detach - must be 'sl0' This utility is sometimes necessary if the SLIP driver terminates (or is terminated) abruptly - such as during a trap. In such a case, the TCP/IP kernel still believes the driver is running and has the SLIP interface sl0 attached. It must be manually detached (by running this program) prior to starting the driver again. If this is not done, the driver will display an error message of the form: [MON ] Interface "sl0" is already attached (unit #). - - - - - slcfg.exe Utility to test parsing SLIP configuration files Usage: slcfg config_file [-d] config_file is name of file to process. -d enables debugging mode (extra internal debugging output during parse) +--------------------+ | Reporting Problems | +--------------------+ Should anyone encounter problems - either usage problems or actual code problems (especially those that cause crashes), I'd appreciate the following being done, in order to best help me try to narrow down the problem. 1. Record whatever information you can as to the circumstances surrounding the crash, and any dump information. If possible, please see if the problem is reproduceable. 2. If you are using VJ compression, try disabling it (use the parameter "compression=off" in SLIP.CFG) and see if the problem can be reproduced. 4. Run SLIP with the -d (debug) option and try to reproduce the failure. Using debug mode will generate lots of debugging information to be output (and will slow down the driver). The best thing to do is to redirect the output to a log file. 5. If possible, try using the standard IBM SLIP driver in the same environment and see if the same result occurs. After doing this, please send me as much information about the crash and the resulting debug information as you can. Although I do follow the OS/2 newsgroups on the Internet, I don't currently following CompuServe or any BBS', so for an official response, please mail problem reports to me directly. Also, please be patient - it's a rare day that I'm not swamped with work, so any response may take a day or two. For crash information, please be as verbose as you can about the environment in which you are running. I may not need most of the information, but I may not automatically know up front what I do need. +---------------+ | Administrivia | +---------------+ Just to keep this in one place - I can be reached via the following: David Bolen E-Mail: db3l@ans.net Advanced Network & Services, Inc. Phone: +1 914 789-5327 100 Clearbook Road Fax: +1 914 789-5310 Elmsford, NY 10523