KA9Q TCP is an implementation of TCP/IP for the PC.  This is a Unix
port based on a version from mid-1989.  Unfortunately the more recent
versions of KA9Q are harder to port to Linux.  This copy has been
tested with SLIP and with a WD8013-compatible Ethernet controller.
These instructions tell how to configure both.

I don't have a manual for this exact version.  There's builtin help.
The commands primarily set parameters (the ip and tcp commands), or
start services.  In general the same command is used to set and
examine parameters.  When you type the command with no value, it shows
the current value. 

To use KA9Q, put startup.net and possibly domain.txt in your home
directory, and run "net".  You will definitely need to tailor
startup.net for your configuration.  This directory contains two
examples: startup.net, which is an example SLIP configuration, and
startup.eth, which is an example Ethernet configuration.  (The actual
Ethernet configuration file would still be called startup.net.)  Se
the section at the end of this document on configuration.  Note that
you can give an argument to the "net" command.  It will be used as the
startup file in place of startup.net.  By default, startup.net and
other files are in your home directory (the value of the environment
variable HOME).  You can put them somewhere else by using the
environment variable NETHOME.

If you are using SLIP, note that you must first dial the modem and
establish a SLIP connection.  The exact details on doing this are
different at each site.  Unfortunately you're probably going to need
help from system or network support staff in order to use SLIP.
Because SLIP effectively connects you to someone's local network,
using it normally requires logging in with a password.  I recommend
using kermit's script facility to dial and set up SLIP.  It did not
seem work adding a similar facility to KA9Q.

If your site does not current support SLIP, they will probably have to
do a bit of systems work.  For Unix systems, typically this will
involve adding a SLIP device driver, and then enabling routing.  (An
appropriate driver is available for the Sun, although I don't know
where.  I believe it can be installed without Sun source.)  Many
terminal servers will support SLIP directly, so enabling it will
merely involve changing a configuration file.

Aside from configuration commands (which typically go into
startup.net), the most common commands are probably telnet and ftp.
Both take a host name.  Once you are connected, the "escape character"
(initially ^]) lets you do some special things.  You type it followed
by another character. Except for the escape character, the characters
are folded, so that c, C, and ^C are equivalent.  Here's a list of the
special characters:

  escape character (i.e. two in a row) - send a real escape character
  x or ^x - return to command mode
  b or ^b - send break
  c or ^c - send interrupt process
  o or ^c - abort output
  t or ^t - are you there?
  h or ^h - send telnet erase character
  u or ^u - send telnet erase line
  ?       - print this help message
  
Once you return to command mode, the "session" command can be used to
switch between connections.  With no arguments, it shows the current
sessions.  With a number, it will reconnect you to that session.
There's a disconnect command to kill a session (also some stronger
ways of doing it).

Telnet normally operates in full duplex, with the other system
echoing.  However if that system refuses echoing, or if you use the
command "echo refuse", KA9Q will echo locally.  In this case you have
the normal line editing functions.  Several control characters have
special functions.  Note that in local echo mode, you do not need to
hit the escape character first.

  escape character - return to command mode
  ^v - quote the next character
  ^b - send break
  ^c - send interrupt process
  ^o - abort output
  ^t - are you there?

Telnet will pass your TERM environment variable as the terminal type
if the other end asks for it.  It will implement flow control locally
if the other end understand the remote flow control option.  If the
other end does a "telnet sync" correctly, it will suppress output when
appropriate.  E.g. when talking to a Unix system, if you type ^C or ^O
in the middle of a large output, output should stop immediately.
However there may be a pause before getting the next prompt, as some
previously buffered data is probably still going to be transmitted.

With this distribution, there is also a separate program called
"telnet".  When KA9Q is running, this program can be used in another
window to open a telnet connection.  Several copies of this program
can be active, each in a different window.  In order to use the telnet
program, you must have "start telserv" in your startup.net.  The
separate telnet program takes the same arguments as the telnet
commnand within KA9Q.  If you need to exit from such a telnet
connection, use ^^x.  KA9Q will confirm that you really intend to
exit.

The "ip stat" and "tcp stat" commands are useful to get statistics.
"Ip stat" shows both the IP and SLIP level.  If header compression is
being used, it will show how many packets were compressed and how many
were oot.

FTP is sort of odd.  It looks like you are in an interactive
conversation with the FTP server at the other end, with no local
command prompt.  Most commands are passed directly to the remote
server, but in fact there is a local command parser, which will
intervene for a few commands:

   cd, dir, list, get, ls, mkdir, nlst, rmdir, put, type

get and put should be used to transfer files.  By default, files are
normally transfered in ASCII.  To tranfer a binary file, use the
command "type i".

There's very minimal support for X11.  If you are running under
X on your Linux system, you can use the command "start x".
This will cause KA9Q to front-end the Linux X11 software, so
that you can run X-based software on other hosts.  As usual,
you set a DISPLAY environment variable of the form 

   myhost:0.0

where myhost is the host name or IP address of your Linux system (i.e.
the address that KA9Q is using).  

If you simply say "start x", there will be no access control -- once
you've started X, anyone can connect to your display from anywhere on
the network.  I recommend that instead you use "start x ask".  This
will put up a prompt allowing you to accept or reject the connection.
This requires that you have xmessage installed.  Source and executable
for xmessage is included as part of this distribution.  Other
approaches to access control are: (1) use xauth, (2) turn on the X
server only when you actually want to start up X software.  You can do
"stop x".  This will not close down existing X connections.  It will
just prevent new ones, until the next "start x".

Unfortunately, X involves a lot of network traffic.  Over a 9600 bps
line -- which is the primary audience for this implementation -- it's
probably too slow to be useful.

It's possible to run a server which others can connect to, though I
haven't tried it except for ftp.  The command is "start ftp", etc.
For ftp, a login is required.  The file ftpusers, in your home
directory, contains a list of users and passwords.  Here's an example
file:

     anonymous * /net/public 3
     hedrick xxxx /net/public 1 /usr/hedrick 3

The first field is the user name.  The second field is the password.
* means that no password is required.  Following that are directory
names with protection codes.  (Up to 8 directories may be specified.
To change this, change MAXPATH in ftp.h.)  Requested file names must
match one of the directories in the list.  (Names are first normalized
to get rid of . and ..)  If a requested file name does not begin with
/, the last directory in the list is prepended to it.  The protection
codes contain the following bits OR'ed together:

   1 - read existing files
   2 - create new files
   4 - overwrite or delete existing files

Here's a list of commands:

   ! - call a recursive shell
   arp - set arp parameters
   ax25 - configure ham interface
   attach - define an interface - must be used for each interface
   bootp - request our IP address from a server
   connect - for AX25, define call sign for interface
   cd
   close
   disconnect
   dir - do a directory on the local system
   domain - configure domain name system
   eaglestat
   echo - refuse or accept - request to disable telnet remote echo
   eol - Unix or standard end of line options [standard is recommended,
	even for use on Unix systems]
   escape - change escape character
   etherstat
   exit
   finger
   forward - divert packets from one interface to another
   ftp - open an ftp connection
   hapnstat
   help - print command list
   hostname - set/examine host name
   kick
   log
   ip - set/examine IP level parameters
   memstat
   mbox, mode - AX25 commands
   mulport
   netrom
   nrstat
   param - set/examine interafce parameters
   ping - send ping to a host
   pwd 
   rdate [offset] [host] - set date/time from UDP time daemon.  see below
   record
   remote
   reset - kill connection
   route - set up routes
   session - see above: move to a different session
   shell - call a subshell
   smtp - mail handling
   start - start server
   stop - stop server
   tcp - set/examine tcp parameters
   telnet - open telnet connection
   trace - enable low-level debugging (no arguments - show current status)
	trace to <file> - put trace output on file (use "con" for console)
	trace <device> [<bits>] - trace packets on device
		device is typically "sl0" or "loopback"
		bits are in hex:
			1 - output, 10 - input (else no tracing)
			100 - dump data in ascii, 200 - hex (else headers only)
	trace cmdmode|allmode - show trace just when at command level?
	trace telnet [on | off] - show telnet options and urgent data
   udp - set/examine udp parameters
   upload
   wait - control mail select

The rdate command uses the old-style time protocol (often known as
"rdate"), on UDP port 37, to get the date and time, and then sets the
system clock.  Note that the protocol always gives time in GMT.  If
your system clock is running on GMT (which is the normal way Unix
should run), this is fine.  Otherwise, you'll need to specify the
offset in minutes.  For time zones west of GMT, this should be a
negative number. For the Eastern U.S., when not in daylight time, the
offset is -300, because EST is 5 hours (300 minutes) west of GMT.
If no host is specified, a UDP broadcast is used.

This configuration of KA9Q has been tested only with SLIP and
Ethernet.  Code is also included for the KISS device (for ham radio),
but I don't know whether anyone has ever tried it.  Past experience
suggests that users will prefer Kermit to SLIP unless you use SLIP
with header compression.

Note that this program depends up non-blocking I/O and the select
system call.  In Linux 0.12, these did not work.  There are patches,
nonblock.tar.Z and select.patch, on the major distribution machines.
Don't forget: after patching a kernel source file, you must do a make
in each directory where you changed a file.  The main make file
doesn't rebuild things all the time when it should.  Linux 0.95
and later has all the necessary patches.

For Ethernet, you will need to install a device driver.  This
distribution includes a device driver that will work with WD8003,
WD8013, and compatible controllers.  I believe drivers are available
for a few other controllers on tsx-11.mit.edu, but those drivers may
not have been updated to work with recent kernels.  To install the
WD80xx controller, see README.WD.  It's very easy, as long as you know
how to build a kernel from source.


CONFIGURATION:

Here's some advice on preparing a configuration file.  I assume you're
planning to use SLIP (dialup IP) or Ethernet.  I'm going to explain my
configuration file line by line, as it's likely to be close to what
you need:

   attach asy 0 /dev/tty64 cslip sl0 2048 1500 9600

You must include an attach command in every configuration file.  It
defines the device.  For SLIP, the line above should be about right.
Some variationos:
   - /dev/tty64 is the serial line.  Obviously you can adjust this
	to use a different line.
   - cslip specifies SLIP with Van Jacobsen header compression.
	If you're using normal slip, use "slip" instead of "cslip".
	In my opinion, response on normal SLIP is too slow for it
	to be very useful.
   - 9600 is the line speed.  Use whatever speed you are set for.
	If you have a "smart" modem, we recommend turning off
	any error correction or compression.  These features
	introduce enough delay to be objectionable.

The following attach command could be used for Linux generic
Ethernet (/dev/eth)
  attach linux arpa eth0 1500 1.2.3.fa.fb.fc
The last item is your Ethernet hardware address, in hex.  It should
be printed when your system boots.  E.g. if it prints 01 02 03 04 05 06
then you put in 1.2.3.4.5.6.  Each of the six numbers is in hex, and
may be one or two digits.

  wait 0

This should only be needed with older version of the kernel.  It
disables the select system call.  Instead, runs in a tight loop
continuously testing for input.  Unfortunately select has a history of
problems under Linux.  It appears to be fine in version 0.96.  However
in earlier version, select did not work properly when there was
another program running.  (In some cases it works OK unless the other
program uses select.  E.g.  if you enter emacs in another window, your
FTP comes to a halt.)  If you are trying to use KA9Q while another
program is running, and you find that the connection hangs, you might
try "wait 0".  Otherwise, you should leave the default setting, which
is "wait 100".  The argument to wait is in milliseconds.  It's the
amount of time to wait in the main loop.  The select will trigger if
input arrives on the serial line, or you hit a key.  Otherwise it
waits this amount of time.  I don't recommend values larger than 100.
Smaller values might possibly be useful in some siuations.

  route add default sl0

This says that all packets should be sent out the SLIP line.  Presumably
this is what you want.  If you are using Ethernet, of course you'd
use the name of your Ethernet device instead of sl0, e.g.
  route add default eth0

  bootp

This says that the system will find out its IP address by sending a
BOOTP request out the serial line.  Since dialups are normally in
"hunt groups", you will probably get a different line each time you
dial up.  Thus your IP address will probably not be the same.  BOOTP
is a way of asking the terminal server (or whatever else you're
connected to) to tell you your IP address.  If your terminal server
does not support BOOTP, or if you are using Ethernet, you explicitly
set your IP address using a command of the form
   ip address [1.2.3.4]
where 1.2.3.4 is your IP address.  You would use this command
instead of the BOOTP command.

  tcp mss 64
  tcp window 256

These commands set TCP performance parameters.  These control a
tradeoff between overall throughput, jerkiness of output, etc.  These
parameters seem to give good performance for interactive connectionos.
For FTP you might want larger values, particularly if you are going
over a long-haul network like the Internet.  For FTP the best value
for mss is at least 512, and probably more like 1024, with window
between 2 and 4 times mss.  However Linux has fairly small buffers for
the serial line, so you may not be able to get away with parameters
much larger than the ones shown here.  If you are using Ethernet,
of course you'll want larger values.  I suggest starting with
  tcp mss 1500
  tcp window 4500
This should work for traffic on the local Ethernet.  If your 
traffic tends to go through routers, a safer set of values is
  tcp mss 512
  tcp window 2048
Be careful about setting larger window sizes.  With the WD controller,
there probably isn't enough memory to go above 5 to 6K. 4500 should be
safe.  (I realize that most WD controllers have 16KB of memory.  I
haven't been able to get reliable results using more than 8KB.)

  domain suffix rutgers.edu
  domain add [128.6.4.4]

These parameters control the domain system.  That's the set of servers
you use to look up host names.  You'll need to adjust these for your
campus.  The suffix is tacked onto all host names you type, unless
they already have a dot in them.  This lets you type "athos" instead
of "athos.rutgers.edu".  Set it for the domain you most commonly use.
The address 128.6.4.4 should be the address of a domain server on your
campus.  All name lookups will be directed to that server.  You can
define more than one, by using several "domain add" lines.

If your campus does not support the domain system, you can use a host
table instead.  In that case you would omit the "domain" commands.
The host table is called "domain.txt", in your home directory.  It's
in the format of a domain master file.  The most important entries
look like
   athos.rutgers.edu. IN A 128.6.4.4
Note that IN and A must be in upper case, and the name must include
the whole suffix, and end in a dot. 

Note that this is a very old domain implementation, and is not up to
the level of the current MS/DOS version.  It does not use TTL's.
Every time you type a name, it first looks in domain.txt.  If there's
an entry there, it will be used.  Otherwise, it will query the domain
server you specified.  If it gets an answer, that information will be
added to domain.txt.  If a host changes its address, you'll be in
trouble, because you'll continue getting the old information from
domain.txt.  Thus it's probably a good idea to remove domain.txt now
and then.

  start finger
  start telnet

These start daemons to respond to incoming finger and telnet
connections.  This is optional, but most people will probably find
them useful to help people find you.  The finger server uses files
stored in a subdirectory "finger" of your home directory.  Files
should have names of the form xxx.txt, where xxx is a user name.
Finger with no arguments will list all users on the system (i.e.  it
will look for all files ~/finger/*.txt, and list the names).  Finger
with a specific user name will display the text of that file, i.e.
~/finger/xxx.txt.

The telnet server is really more like a talk link.  When someone
telnets to your machine, you'll get a message saying that there is an
incoming telnet connection.  At that point you should escape to the
coommand level (using ^] or whatever your escape character is), do
"session" to see the session number of the incoming connection and do
"session NN" to connect to it.  At that point you'll be in an
interactive link with the person.

  start telunix  

There is also a server designed to allow "real" telnet connections,
i.e. connections that create a real login session.  It is activated
with the command "start telunix".  Do not use "start telnet" and
"start telunix" at the same time.  For telunix to work properly, it
must be able to find getty or agetty in /etc or /bin.  When a telnet
connection comes in, telunix starts up getty on the first try pty.
Getty normally starts login.  /etc/utmp must be protected so that the
user running KA9Q can modify it.  (One approach would be to make ka9q
setgid to a group that can modify /etc/utmp.)  In principle there is a
security risk to allowing users to modify /etc/utmp.  However telunix
is probably going to be used on single-user systems or systems with
friendly users, so this is probably not an issue.

  start telserv

Allow the separate "telnet" program to be used in other windows.  Note
that this program does almost nothing.  The main copy of KA9Q actually
opens the tty on which "telnet" is run, and handles the telnet
protocol.

  start x ask

Starts the X server link.  Because of the "ask" option, whenever an
incoming connection is made, xmessage will be used to ask you whether
you want to accept it or not.
