
                             ax25ip
                             ======

This README files pertains to version 0.4 of ax25ip.
(this document is currently incomplete -- the UDP features lack examples)

Overview
--------

   RFC1226 describes a method of using TCP/IP based networks to transport
AX.25 frames.  The ax25ip utility uses this technique to transfer AX.25
frames in and out of TCP/IP environments.

   The interface to the AX.25 world is via KISS, with ax25ip emulating
either a standard KISS TNC or operating as a digipeater.  AX.25 frames
arriving on the KISS interface are routed to the IP interface and sent
to the appropriate IP host system.  Incoming frames from the IP interface
are filtered and sent out the KISS interface.  The operator controls the
mode (tnc or digipeater), the routing (callsign to ip host mapping), and
a few sundry controls via a configuration file, read at startup.

   In it's current implementation, ax25ip runs only on BSD UNIX machines
(SunOS 4.0.3 or greater, in particular).  It requires a serial port, and
uses a raw socket to gain access to the IP layer of the host's TCP/IP
implementation (this requires that ax25ip be started by root).  Ax25ip
also supports using a standard UDP socket in place of the raw socket,
although this does not adhere to RFC1226.


Modes and Routing
-----------------

   There are two interfaces into and out of ax25ip.  The KISS interface
is a standard serial port, running speeds up to 38400 baud.  The IP
interface reads and writes packets to an IP network in accordance with
the specifications in RFC1226.  Several factors determine how AX.25
frames route within ax25ip and through the IP network, although some
basic rules always apply:

   A frame will never leave ax25ip on the same interface it came in on.
This fundamental rule eliminates much complexity and much confusion on
how to set up ax25ip.

   A frame will never be sent to more than one IP host.  Using an IP
network as a broadcast media is probably not a good idea, especially
across the Internet!

  Most other routing factors involve user configuration, and depend
heavily on the mode of operation.

  In tnc mode, ax25ip emulates a KISS tnc, and behaves as one would
expect.  The next destination callsign (either the destination or the
next digipeater in line) is extracted from frames arriving on the KISS
interface, and looked up in a routing table (built by the operator in the
configuration file).  The routing table provides the IP address to which
this frame should be sent.  The standard CRC is computed, tacked onto the
frame, and the result is sent off to the target system.  Frames arriving
from the IP interface have the CRC checked and removed, and are forwarded
to the KISS interface.

   Digi mode is a little more complicated.  In this mode, ax25ip is
assigned a callsign, and acts as a digipeater.  If a frame arriving on
the KISS interface has ax25ip's callsign specified as the next digipeater,
ax25ip will mark the frame as digipeated by it, look up the next callsign
in the routing table, compute and append the CRC, and send the frame to
the specified IP host.  Frames arriving on the IP interface will be
handled in a similar fashion, but note that in no cases will the frame be
sent out the same port it arrived in on.


Configuration
-------------

   A single configuration file is used to tailor ax25ip.  The file is
usually named "ax25ip.cfg" and should be located in the same directory
ax25ip is executed from.  An example is probably the best way to become
familiar with configuring ax25ip.

# Sample Configuration file for ax25ip
mode digi
socket ip
device /dev/ttya
speed 9600
mycall KA9WSB-7
myalias ILSUN
beacon every 540
btext ax25ip -- digi ka9wsb-7 -- Experimental IP encapsulator
loglevel 2
route W1AW-13 handbook.arrl.com 
route WZ9ZZZ last.one.edu
param 1 20

The mode command selects the behavior of ax25ip.  The device line specifies
the tty device to use, and the speed line selects the baud rate.  Baud
rates up to 34800 can be used, but 9600 is probably the fastest safe
speed for serial cables of any distance (remember, KISS has no error
detection).  The mycall command is required only if you are in digi mode.
The loglevel command selects the amount of verbosity you want, ranging from
0 (no output) to 4 (streams of data).  The route command adds entries to
a static routing table, currently 128 entries deep.  In the example, AX.25
frames destined for W1AW-13 are forwarded to handbook.arrl.com, frames for
WZ9ZZZ are sent to last.one.edu, and all others go nowhere.  Specifying the
word "default" in place of a callsign sets up a default route, used when
the destination callsign cannot be found in the routing table.  Finally,
in digi mode, the device on the other end of the KISS interface is probably
a TNC.  The param command allows you to set the KISS parameters (txdelay,
slottime, etc).  As many param commands as required can be specified.

The myalias command allows you to specify an alias for this digipeater.
If you do this, you should probably use the beacon command to ensure
that you ID regularly.  The beacon every 540 command forces an ID message
to be sent out the KISS interface every 9 minutes.  Specifying beacon
after 540 will send the ID packet only if the channel has been idle for
9 minutes.

Sending a hang-up signal to the ax25ip process will cause it to reread
the configuration file and re-initialize itself  (kill -HUP <ax25ip-pid>).


Sample Configuration - NOS-to-NOS
---------------------------------

   This example shows how to connect a pair of NOS-based PCs together
using ax25ip to carry AX.25 traffic.


    KA9WSB-3         one.two.com
  .----------.      .----------.
  |          |      |          |
  |          | KISS | UNIX     |   |
  |  NOS     |------|  host    |---|
  |   on     |      |          |   |  TCP/IP network
  |    PC    |      |          |   |
  `----------'      `----------'   |
                                   |
                             (vast distance)
                                   |
                                   |   fish.sea.com        W1AW-5
                                   |   .----------.      .----------.
                                   |   |          |      |          |
                                   |   | UNIX     | KISS |          |
                                   |---|  host    |------|  NOS     |
                                   |   |          | 1200 |   on     |
                                       |          | baud |    PC    |
                                       `----------'      `----------'


     Config file:                        Config file:
      mode tnc                            mode tnc
      device /dev/ttya                    device /dev/ttya
      speed 9600                          speed 1200
      route W1AW-5 fish.sea.com           route KA9WSB-3 one.two.com
  
Using this setup, a user could run AX.25 connections between the two PCs.
Note that while NOS can digipeat, NOS will not automatically allow users
near W1AW-5 to digipeat through it to reach KA9WSB-3 (i.e. the command
"C KA9WSB-3 V W1AW-5" will not have the desired result).  This may or may
not be a problem.


Sample Configuration - digi-to-digi
-----------------------------------

   This example shows how to configure ax25ip as a pair of digipeaters.


                      (KA9WSB-3)
                     one.two.com
  .----------.      .----------.
  |          |      |          |
  | Standard | KISS | UNIX     |   |
  |   KISS   |------|  host    |---|
  |   TNC    |      |          |   |  TCP/IP network
  | & radio  |      |          |   |
  `----------'      `----------'   |
                                   |
                             (vast distance)
                                   |
                                   |    (W1AW-5)
                                   |   fish.sea.com        W1AW-5
                                   |   .----------.      .----------.
                                   |   |          |      |          |
                                   |   | UNIX     | KISS | Standard |
                                   |---|  host    |------|   KISS   |
                                   |   |          | 9600 |   TNC    |
                                       |          | baud | & radio  |
                                       `----------'      `----------'


     Config file:                        Config file:
      mode digi                           mode digi
      mycall KA9WSB-3                     mycall W1AW-5
      device /dev/ttya                    device /dev/ttya
      speed 9600                          speed 9600
      route W1AW-5 fish.sea.com           route KA9WSB-3 one.two.com
      param 1 20                          param 1 33  

In this setup, the UNIX hosts are "on the air".  No PCs or additional
hardware are required.  A user near W1AW-5 could read a user near KA9WSB-3
simply by providing the digipeater path: "c KA9WSB V W1AW-5 KA9WSB-3"
would work just fine.


Outstanding Issues
------------------

   There are many outstanding issues with this software.  A partial list,
in no particular order, appears below.

- Portability!  io.c currently uses BSD-style select but sys5-style termios!

- ICMP messages relating to ax25ip are ignored.

- Performance of the routing lookups is probably horrid.  Also, a static
  table is a crock.  Feedback from evaluations and test sites may help
  determine how this should work.

- Statistics should be added.

- A few more comments in the code would be nice.


Comments, Criticism, Enhancements, Problems, Bugs
-------------------------------------------------

   You can reach the person responsible for ax25ip at any of the following
   addresses:

   Mike.Westerhof@Central.Sun.COM

   KA9WSB@WB9YAE

   Mike Westerhof, 17 N Main St, Mt Prospect, IL 60056

-------------------------------------------------------------------------
Copyright 1991, Michael Westerhof, Sun Microsystems, Inc.
This software may be freely used, distributed, or modified, providing
this footer is not removed.
-------------------------------------------------------------------------
