Waterloo TCP

                            Installation Notes

                             by Erick Engelke



    Introduction

         TCP/IP is not a program, it is a set of protocols which have
         been  implemented on many machines.  All machines running an
         implementation  of TCP/IP  and connected  to the  world wide
         Internet are capable of communicating with each other.

         There    are    several   popular    non-commercial   TCP/IP
         implementations for MS-DOS computers.   Each offers  special
         features but with  varied drawbacks.  I  don't believe there
         is a clear choice  of one implementation for all  needs, but
         users  are free to pick the best or most useful applications
         from each offering.

         These  notes  describe  the various  applications  available
         today.    Please remember  that  the  applications are  free
         software, you  may use them and pass  them on to others, but
         there is no warranty  and the support is very  limited.  You
         also may not sell the included programs.


    Installation
         Waterloo  TCP  only works  if you  have  a packet  driver, a
         special program which allows  your network interface card to
         talk with the Waterloo TCP applications.

         Thanks to  some very  generous people,  particularly Russell
         Nelson, you probably will  not have to buy a  packet driver.
         If you are  using Ethernet  hardware you  can probably  find
         free  packet drivers  for  your cards  via anonymous  ftp to
         sun.soe.clarkson.edu in the pub/drivers subdirectory.

         Waterloo TCP supports Class 1 (DIX-Ethernet), class 6 (SLIP),
         class 18 (PPP) drivers. Class 3 (Token-ring) is untested.

         Other types of networks have drivers which make them emulate
         Ethernet hardware.  For example, any Novell system using IPX
         or any IBM compatible Token Ring  network can be made to act
         like Ethernet.

         To start using Waterloo TCP software you will need to get it
         configured.  There are three options, using BOOTP, DHCP or a
         configuration file.

         If you  think you may have a  BOOTP or  DHCP server  on your
         local subnet, copy  the file  TCPINFO.EXE  into a  new  sub-
         directory and  run the command  TCPINFO.  It  may take a few
         seconds. After a maximum of 30 seconds, TCPINFO  should tell
         you if it  could  get  configured via BOOTP  or DHCP.  If it
         could not, or BOOTP/DHCP is too slow, you will have to use a
         configuration file.

         You will  probably want a configuration file  anyways, as it
         allows some  extra things which  are not inherent  in BOOTP.
         Waterloo TCP lets  you use a config file,  and pick up extra
         things from BOOTP or DHCP.

         If you're unsure what you are  doing, continue on  with this
         section and make a config file or  modify the skeleton  file
         WATTCP.CFG distributed with Waterloo.

         First  you will  need  some important  information from  you
         local TCP/IP guru.   Do not merely guess, these  values must
         be correct or you may do some damage and get yourself on the
         death threat list from your local network people.


         IP address (eg. 129.97.128.123)


              my_ip =  ______.______.______.______


         local subnet mask (eg. 255.255.0.0, never 255.255.255.255)


              netmask = ______.______.______.______


         local gateway (eg. 129.97.128.2)


              gateway = ______.______.______.______


         primary name server (eg. 129.97.128.1)


              nameserver = ______.______.______.______


         alternate name servers (up to 9 more if so desired)
         just keep repeating this line with new addresses.


              nameserver = ______.______.______.______

         name domains list, (eg. UWaterloo.ca or edu)



              domainlist = ___________________________


         These  values must be  placed in  a file  called WATTCP.CFG.
         Below is a sample copy, remember, do  not use my values, get
         the correct ones!

              print = "using sample configuration" # sample comment
              print = "contact local network guru for more details"
              my_ip      = 129.97.176.99
              netmask    = 255.255.0.0             # sample comment
              nameserver = 129.97.128.24           ; sample comment
              nameserver = 129.97.128.196          # alt nameserver
              nameserver = 129.97.128.1            # 3rd nameserver
              gateway    = 129.97.128.2
              domainlist = "uwaterloo.ca"

         The rules are simple, directive = value. Directive and value
         (except strings inside quotes) are NOT case-sensitive.

         If quotes are not used in the value field, the value will be
         terminated by  the start of a  comment or by a  newline, and
         all white space (spaces and tabs) are removed.

         If you specify quotes around the value, only a second set of
         quotes  or a newline will  end the value  field and comments
         must  be preceded  by  an end  quote  mark.   Whitespace  is
         preserved inside quotes.

         The value can also be taken from  an environment variable.
         E.g. If you specify:
              my_ip = $(myip)
           or
              my_ip = $(MYIP)

         this will be expanded to the value of %myip%.  E.g. if you
         specify:

            set myip=129.97.176.99
        
         in your AUTOEXEC.BAT, the expansion in WATTCP.CFG will
         become:
            my_ip=129.97.176.99

         In this way the same  WATTCP.CFG file can be used throughout
         the local network. This trick is also handy if you are using
         DOS-PPP by Antonio Molero <tonilop@redestb.es>. DOS-PPP will
         write  the variable MYIP to the environment after it loads.

         NOTE: There can be only 1 environment variable per line.
               Specifying e.g. "ETHIP = $(GW_ETH), $(GW_IP)" will
               not work as intended.


         Place the  WATTCP.CFG file in  the same subdirectory  as the
         TCP  application programs.  If  the file is  not found there
         the programs automatically look for the file in the  current
         subdirectory of the current  disk.  Failing that, a  message
         will  be  displayed but  the  program  will not  necessarily
         abort.

         You may  override the above directory  choices by explicitly
         setting the path in an environment variable.

         eg.  set wattcp.cfg=c:\internet

         The environment  variable is  checked first,  and  if it  is
         defined, then that config file is used. This is particularly
         useful on installations  where the software is located on  a
         fileserver,  but individual  workstations will need separate
         configuration files.


    Testing


         First,  to  ensure  that  you  entered  all  the  parameters
         correctly, run  TCPINFO.  It will list all system constants.
         If one or more  of them seem incorrect, check  your spelling
         in the WATTCP.CFG file.

         Next  we will test the  PING command to  see that everything
         works  and asks  another computer  if it is  up.   The first
         argument to  PING is  the name of  the other computer.   The
         '-c' argument is the number of ping's to perform. Since your
         guru supplied the ip address of a nameserver,  we will first
         try that.

              ping -c5 129.97.128.1         don't  use  129.97.128.1,
                                            use  your   gateway's  IP
                                            address

         This will generate five attempts.  You should have more than
         0  % success.   Otherwise  your gateway is  down or  your ip
         address or gateway is wrong.

         If  you  had success,  try pinging  the  ip address  of your
         nameserver.

         eg.  ping  129.97.128.196  5

         Now check your nameserver by trying to resolve the name of a
         local machine.  Near me is a machine named 'cupid'.

              ping  cupid  5

         If that did  not work, your  various nameserver entries  are
         incorrect, your  gateway or network mask  is incorrect, your
         nameservers did not want to provide name service, or you did
         not specify a valid name.

         These tests will  help your  guru figure out  what might  be
         wrong.

    Applications

         TCPINFO
              Displays the current Ethernet/TCP configuration.  It is
              useful for  testing spelling and contents  of files and
              for determining ethernet addresses.


         PING

                   PING  [-vdfst] [-c count] [-w wait] [-p pattern]
                         hostname

              You  have already  seen PING  described briefly  in the
              installation section.  PING will not generate more than
              one  request  per second,  it  also  attempts to  block
              broadcast attempts.


              PING can be used in a debugging mode (-d or /d).
              eg.  PING -d 129.97.128.1

              If  you do  not specify  the number  of attempts  to be
              made, only one attempt will be made.
              eg.  PING 129.97.128.196

              Specifying '-s' will  ping  the other  machine once  per
              second for a very long time.
              eg.  PING -s 129.97.128.196

              Run PING -? for explanation of other options


         COOKIE

                   COOKIE [-da] [-s host]
              eg.  COOKIE
                   COOKIE -s conehead.uwaterloo.ca

              Print a witty saying from one of the cookie servers.


         DAYTIME
              Print the time of day using TCP

                   DAYTIME  host [-d]
              eg.  DAYTIME  129.97.128.1
                   DAYTIME  watmath.uwaterloo.ca

              If the  host supports TCP based  DAYTIME text services,
              the time of  day will  be displayed as  a text  string.
              See also NTIME


         FINGER
              Determine user or system information
                   FINGER  [-vdD] [user]@host
              eg.  FINGER  erick@sunee.uwaterloo.ca
                   FINGER  @sunee.uwaterloo.ca

              Finger returns  the remote computer's information  on a
              particular user.

              If no user  is specified, FINGER will return  the names
              of currently logged users on that machine.


         LPR
              Spool print jobs
         LPQ
              Query the print queue

                   Run these commands with no arguments for the exact
                   syntax.   Check to  see that the  appropriate host
                   privileges are extended to the pc.

                   An explanation beyond this  is beyond the scope of
                   this brief document, see your local UNIX guru with
                   HOSTS.LPR   or   whatever   s/he   feels   is
                   appropriate.


         NTIME
              Set DOS time from the Network.

              NTIME  host  [-dDv] [-a addminutes]

              NTIME contacts the host  and requests the current time.
              Computers are  supposed to  respond with the  number of
              seconds  since Jan 1, 1900 GMT.  Many simply return the
              current time adjusted to  the daylight savings time and
              time  zone.  I allow  you to use option 'a'  to specify
              addminutes  if you  need  to add or subtract a  certain
              number of minutes to the returned time. Option 'd' sets
              TCP-debugging to level 1.  Option 'D' sets debugging to
              level 2. Option 'v' prints version with which NTIME was
              compiled and the compilation date.

              I was considering using  a DST conversion algorithm but
              have not yet done so.

         TCPPORT
              Treat the serial port as a TCP connection

                   TCPPORT host port "program options"

              Host is the name  or ip address of the  remote computer
              and port is the TCP port number on that computer.

              You  may  specify  the  terminal  emulation desired  by
              setting the environment variable
                   set  tcpterm=termtype
              eg.  set  tcpterm=vt102

              See the section on TCPPORT below

         REXEC
              Execute the following command on a remote host

              REXEC  host  [user [pass]] cmd

              The  "cmd"  command  will  be executed  on  the  remote
              computer.  If  you fail to specify  either the password
              or the userid, you will be prompted for them.

              eg.  rexec  hq.iraq  "ls -l"
                   rexec  hq.iraq  saddam  "ls -l"
                   rexec  hq.iraq saddam white_flag_of_victory "ls"

              REXEC does not do terminal interpretation, you may wish
              to  have  NANSI.SYS  loaded  to  provide  the necessary
              emulation.  Waterloo TCP REXEC is good when you wish to
              redirect output to a file.


    Other WATTCP Programs

         The above  programs are relatively  simple demonstrations of
         the  capabilities of  the  WATTCP TCP/IP  kernal.   Advanced
         programs are usually distributed  separately as they tend to
         be  updated   in  a  different  schedule   from  the  kernal
         libraries.

         MSKERMIT 3.11
              One  of  the first  popular  uses  for WATTCP  was  its
              ability to make communication programs such as MSKERMIT
              act like  TELNET facilities.   So overwhelming  was the
              number of  requests that  MSKERMIT 3.11 now  includes a
              derivative  of   the  WATTCP  kernal  and  the  TCPPORT
              application.

         TELNETD
              The next  most popular use is easily TELNETD, a program
              which  allows you to TELNET into your pc and control it
              using  any  TELNET program  on  any  computer platform.
              TELNETD   can   be   found   via   anonymous   ftp   to
              sunee.uwaterloo.ca in pub/wattcp/telnetd.zip.


    Using Communications Programs with TCPPORT

         You may wish to use  a terminal communication program rather
         than TELNET.  Waterloo TCP  makes this very easy to do  with
         its  TCPPORT  program.    Now  that  TCPPORT  is built  into
         MSKermit I don't really have a good example, but here goes:

         Start by creating a configuration  file which tells your com
         program  to use the BIOS  ports rather than  hardware.  Then
        create a batch file which looks like:

         TNCOMM.BAT
              echo off
              tcpport %1 23 "c:\comm"

         Here I was assuming you kept comm.exe in the root  of C: and
         tcpport could be found somewhere in  the path.  Now you  can
         easily TELNET to any host by typing:

              TNCOMM  host
         eg.  TNCOMM  129.97.128.1
         or   TNCOMM  watmath.uwaterloo.ca

         After  you  log off,  Waterloo  TCP  returns the  characters
         forming  [??Host  closed   connection??]  or  some   similar
         message.  You simply need to exit your com program.  Exiting
         kermit without logging off  will simply close the connection
         and typically log you off.

         You may  select a specific terminal  emulation which TCPPORT
         should  try  to  run  by  setting  the  tcpterm  environment
         variable before running tcpterm:
         eg.  set tcpterm=vt102

   Advanced WATTCP.CFG Options
         This  section  is  useful  once  you  have  determined  that
         Waterloo TCP actually works for you.

         Including Sub-Config Files
              You may wish to use a combination of generic WATTCP.CFG
              file  and  a  smaller  sub-config file  which  will  be
              located  on  the  user's  private  subdirectory.    Any
              command which can be placed in the main config file may
              also be placed (or replaced) in the sub-command file.

              eg.
                   include = c:\local.cfg

              After the subcommand file  is parsed, Wattcp returns to
              the  main config  file.   The depth  of this  system is
              limited by  the number  of file  handles and  the stack
              size.

              If  the  subcommand  file  cannot be  found,  an  error
              message will  be printed.   To allow for  the possible,
              but not-essential existance of a file (i.e., include it
              if  it is there, but don't  complain otherwise) you may
              simply prepend the filename with a question mark.

              eg.
                   include = ?c:\local.cfg


         IP Addresses
              Most network  administrators would  prefer to  not have
              many  copies of  the configuration  file, but  rather a
              single  file  from   which  everyone   can  be   easily
              configured.

              As  demonstrated above,  Waterloo TCP  normally accepts
              the ip number from within the WATTCP.CFG file.

         BOOTP
              Many  sites prefer  to use  BOOTP, a  standard protocol
              which  requests  the  user's   ip  address  and   other
              information from a BOOTP server.

              To use BOOTP, you must specify the name 'bootp':

                   my_ip = bootp

              in the config file.  This will broadcast the request on
              the local subnet.   You  may specify  a specific  BOOTP
              server which need not be on the same subnet, by using:

                   bootp = host
              eg.  bootp = 129.97.128.1

              The  default  timeout value  is  30 seconds.    You may
              change that by using:

                   bootpto = seconds
              eg.  bootpto = 50

              If no  WATTCP.CFG file is found,  Waterloo TCP programs
              always resort to BOOTP.

         DHCP
              A  modern  replacement  for BOOTP is DHCP (Dynamic Host
              Configuration Protocol). Specify use of DHCP by:

                   my_ip = dhcp

              in the config file. See readme.3rd for other DHCP
              options


         ETHERNET to IP Table

              Another option currently  exists, I  allow multiple  IP
              numbers in WATTCP.CFG  with each  one being  tied to  a
              particular Ethernet address.  If your  Ethernet address
              is found in list, your IP address will be assigned.

                   ETHIP=ethaddr,ipaddr
              eg.  ETHIP=00:01:2F:BC:44:33,128.252.35.4

              In  this   case,  the  machine  with  Ethernet  address
              00:01:2F:BC:44:33  would  be  assigned  the  ip address
              128.252.35.4.    Note   that  Ethernet  addresses   are
              hexadecimal with intermediate  colons, ip addresses are
              dotted  decimal, and I use a comma to separate the two.
              Also, since  Waterloo TCP removes white  space, you may
              place  a space between any  of the fields  if you don't
              use quotes, and  you may  end the line  with a  comment
              describing  where  the  station  lives or  to  whom  it
              belongs.

              You can quickly find the Ethernet  address of a station
              by running the TCPINFO command.

         Subnets
              The Internet is comprised of many, many subnets.  There
              are several  protocols normally used to  help computers
              reach computers on other subnets.

              Most PC based  TCP kernals depend on  routing tables to
              manage the possible  routes, so I  elected to use  that
              strategy.

              A  routing  table  exists  in  memory  with  a  current
              capacity  for 32  different  routes.   Each route  must
              specify a gateway, an  optional destination subnet, and
              then an optional subnet mask.

                   gateway = gate_ip [, subnet [, subnet_mask ]]
              eg.  gateway = 129.97.176.1        # default
              eg.  gateway = 129.97.176.2, 129.97.0.0, 255.255,0,0


              The  first  example  shows  how a  default  gateway  is
              created.  A default gateway is used if no other choices
              exist.

              The second example shows how to specify a gateway for a
              particular subnet.  In this example, whenever the 'top'
              16 bits are 129.97, that gateway will be used.

              Yes,  you need not always  specify the mask,  but it is
              necessary for class B subnets, so I simply suggest that
              you always do specify the mask.

              You  may specify  the same  gateway several  times with
              different routes.

              Non-contiguous subnet bits are supported.

              To check  your configuration and to  see the precedence
              of gateways, run TCPINFO.EXE.

         Host Name
              Some applications will wish  to know your PC's name,  a
              short  textual  name.    This   may  be  set  with  the
              WATTCP.CFG line:

                   hostname = name
              eg.  hostname = mole


              Notice that  you do  not  specify the  domain, that  is
              found from the domain string.

         Timeouts
              Most Waterloo  TCP programs  have  a specified  timeout
              value between activity  before a timeout error  occurs.
              For  example,  the maximum  response  time  to an  open
              request  before the  connection is  given up  should be
              reasonably  long so  that distant  connections will  be
              usable, but short enough that the user will not believe
              the computer has hung.

              Applications may specify  their own timeout value,  but
              if  they  chose  to  use  the  system  default (all  my
              applications do), the default value may be set from the
              WATTCP.CFG file.

                   SOCKDELAY = seconds
              eg.  SOCKDELAY = 40

              The  default value is 30  seconds.  A  smaller value is
              unwise,   but  larger  values   may  be  necessary  for
              particularly bad connections.

         Maximum Transmit Unit
              If you understand MTU and know what you would like, you
              can change it:
                  MTU = bytes
              eg.  MTU = 1500   (default is 536)
              MTU and MSS (Maximum Segment Size) are related through
              the formula: MSS = MTU-40. MSS is only used by TCP.
              UDP has a maximum packet size of MTU-28.

            NOTE: Previous versions of WatTCP supported  defining MSS
                  in config-file. "MSS" is now  only  defined via the
                  "MTU" above. Default MTU is 576 and  hence  default
                  MSS would become 536.


         Cookie Server
              You may specify a cookie server in the  WATTCP.CFG file
              with the line:

                   cookie = server
              eg.  cookie = 129.97.128.1
              eg.  cookie = sunee.uwaterloo.ca

              Up to 10 separate cookie servers may be added.  TCPINFO
              will  list  them  all.    BOOTP will  also  add  cookie
              servers.

         BOOTP Features and Limitations
              BOOTP is not the greatest  method of configuration.  In
              fact  there  is   currently  a  committee   looking  at
              implementing its successor.

              Waterloo  TCP  programs  will  automatically  get  many
              configuration parameters from the BOOTP server if those
              values are returned:

              IP address
              netmask
              gateway        (only one will be added)
              nameservers    (all supplied will be added)
              cookieservers  (all supplied will be added)
              hostname

              The domain name cannot be specified currently.   Of the
              gateways,  only one is recorded by Waterloo TCP as they
              do not indicate subnets or anything else useful.

    Notes:
         The most up-to-date versions  of these files, their sources,
         and  new programs  are  available  on Sunee.uwaterloo.ca  by
         anonymous FTP.  Check out pub/wattcp.

         All  executables   there  are  copyrighted  but  are  freely
         available for use and non-commercial distribution.

         The library files which do the actual tcp communications are
         also there.   They too are copyrighted,  but may be used  in
         commercial and non-commercial work.   You are free to  do as
         you choose.   If you intend to program  with this package, I
         would  highly  recommend  the  developers  manual  described
         below.

         Developers  may wish to join  the Waterloo TCP mailing list,
         join by mailing to:

              wattcp@Development.Watstar.UWaterloo.ca

         The  programmers manual includes  examples, a full reference
         of the approximately 50 functions, notes on conversions from
         UNIX.  The  cost is $40 ($US if you live in USA, $Cdn if you
         live in  Canada.  $40 US  for anywhere else.   Make check or
         money order payable to :

              Erick Engelke
              1010-130 Lincoln Rd.
              Waterloo, Ont., Canada
              N2J-4N3

         The  proceeds are  entirely used  to offset  the cost  of my
         manuals  and  software  costs  necessary for  improving  the
         package.    The next  step is  Windows  DLL's, but  I cannot
         afford everything I need to do that.


         I have mentioned the  public domain CUTCP and NCSA  programs
         which  do  an  excellent  job  of  TELNET,  RSH  with  VT100
         emulation,  and  much more.   You  may  wish to  compare the
         programs and use the ones which work best for you.

         For their executables, use anonymous ftp to:
              omnigate.clarkson.edu    128.153.4.2     for CUTCP
         and  ????                     128.174.20.50   for NCSA


         I hope that this distribution helps you in some way, and I'd
         like to thank the contributors,

              Bruce  Campbell who  wrote  the original  program  from
                   which tcpport was  derived.  He also wrote the DOS
                   network I log onto every morning.
             Tim  Krauskopf's  NCSA Name  Domain  code  was used  to
                   develop Waterloo TCP's resolve function.

              Edmund J. Sutcliffe donated a good portion of BOOTP.

              Jim Martin made a  lot of extensions to  Edmund's BOOTP
                   work and was influential in the new nameserver and
                   new gateway code as well as the COOKIE stuff.

              Jason Dent found some bugs and helped optimize WATTCP's
                   performance.

              Dean Roth  found  some  low  level  bugs   and  greatly
                  improved the FTP program.

              Although countless others have  given me good ideas and
                   noticed an incorrect line  here or there, but none
                   have been  more  thorough or  helpful than  Tarjei
                   Jensen.

              If you would like  to add your name to  the programmers
              list,  send me a copy  of your program  and I'll gladly
              include it in the distribution with full credit.


    Erick Engelke
    Erick@development.watstar.uwaterloo.ca
    Waterloo TCP Architect
    July 8, 1992


    Gisle Vanem
    giva@bgnett.no
    August 20, 1999