** ** This file is a cobbling together of the various notes on ax25ipd. ** ax25ipd ======= This README files pertains to version 1.0.2 of ax25ipd. (this document is still incomplete -- the UDP features lack examples) Overview -------- RFC1226 describes a method of using TCP/IP based networks to transport AX.25 frames. The ax25ipd 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 ax25ipd 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. ax25ipd is the Linux incarnation of ax25ip by Mike Westerhof, and is not intended to support any OS other than Linux. Although getting it to run on BSD should not present too many issues, there has been no attempt to retain BSD(Sun) operability since it was updated in an environment where there was no access to BSD. ax25ipd 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 ax25ipd be started by root). ax25ipd 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 ax25ipd. 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 ax25ipd and through the IP network, although some basic rules always apply: A frame will never leave ax25ipd on the same interface it came in on. This fundamental rule eliminates much complexity and much confusion on how to set up ax25ipd. 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, ax25ipd 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, ax25ipd is assigned a callsign, and acts as a digipeater. If a frame arriving on the KISS interface has ax25ipd's callsign specified as the next digipeater, ax25ipd 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 ax25ipd. The file is usually named "ax25ipd.cfg" and should be located in the same directory ax25ipd is executed from. An example is probably the best way to become familiar with configuring ax25ipd. # Sample Configuration file for ax25ipd mode digi socket ip device /dev/ttya speed 9600 mycall KA9WSB-7 myalias ILSUN beacon every 540 btext ax25ipd -- 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 ax25ipd. 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 ax25ipd process will cause it to reread the configuration file and re-initialize itself (kill -HUP ). Sample Configuration - NOS-to-NOS --------------------------------- This example shows how to connect a pair of NOS-based PCs together using ax25ipd 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 ax25ipd 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. --------- We have added dual port capibility in DIGI MODE ONLY to allow us to use it with a Dataengine. Very little needed changing, but we did not document the changes. If you really need to know, diff the package against the original, which was/is at sunsite.unc.edu. To specify the second port, do something like this... #to use the second port, we need to be in digi mode mode digi # #port 0 on my tnc goes to vhf mycall ve3djf-12 myalias vhfdjf # #port 1 on my tnc goes to uhf. #The callsign and alias must be different for this to work right... mycall2 ve3djf-13 myalias2 uhfdjf # Everything else is the same. Note that if you leave out the mycall2 and myalias2 defines, it works just like the original in single port mode. For recieving on the KISS (dual) port, packets are checked against both callsigns and aliases. Whoever is on the other end of the AXIP link can find out what port it came from by looking at the who it got digi'd through, although I can't think of any reason to do that... For transmiting, you go out the port with the callsign matching the digi address. For example, to go out port 0 in the above example, digi through ve3djf-12 or vhfdjf. To go out port 1, digi through ve3djf-13 or uhfdjf. Deficencies: If you specify the same callsign on both ports, no error is generated, but the way the logic in the code works you always go out the upper port (port 1), not port 0. In TNC mode, there is really no way to specify which port to transmit on that I can think of, so there is no multiplexing there. Everything goes out port 0 in TNC mode still. Lastly, none of the dump routines know anything about ports on the KISS interface, so they look the same, with both ports lumped into one. Let us know if you like this hack, BTW. In retrospect, we should have written a KISSPlexor (tm:-) HIHI. I think we will do that next. 73! de Jeff / VE3DJF Jeff@lnx_rpi.ee.ryerson.ca VE3DJF@bbs.VE3RPI.ampr.org AXIP (IP encapsulation of AX.25 frames) daemon by Michael Westerhof. Network Working Group B. Kantor Request for Comments: 1226 Univ. of Calif San Diego May 1991 Internet Protocol Encapsulation of AX.25 Frames Status of this Memo This memo describes a method for the encapsulation of AX.25 (the Amateur Packet-Radio Link-Layer Protocol) frames within IP packets. This technique is an Experimental Protocol for the Internet community. Discussion and suggestions for improvement are requested. Please refer to the current edition of the "IAB Official Protocol Standards" for the standardization state and status of this protocol. Distribution of this memo is unlimited. The AX.25 Amateur Packet-Radio Link-Layer Protocol The AX.25 Amateur Packet-Radio Link-Layer Protocol is described in the publication by that name [1], incorporated here by reference. Each AX.25 packet ("frame") is encapsulated in one IP datagram. Normally no AX.25 frame will exceed 330 octets, so fragmentation at the IP layer should not be necessary. However, experiments with larger AX.25 frame sizes may require the use of standard IP fragmentation and reassembly procedures. When an AX.25 frame is encapsulated within an IP packet, HDLC framing elements (flags and zero-stuffing) are omitted, as the IP datagram adequately delimits the beginning and end of each AX.25 frame. The 16-bit CRC-CCITT frame check sequence (normally generated by the HDLC transmission hardware) is included. In all other respects, AX.25 frames are encapsulated unaltered. Each such IP datagram shall have a protocol number of 93. Reference [1] AX.25 Amateur Packet-Radio Link-Layer Protocol Version 2.0 October 1984. Available from the American Radio Relay League, Newington CT USA 06111, and other sources. Security Considerations Security issues are not discussed in this memo. Kantor [Page 1] RFC 1226 IP Encapsulation of AX.25 Frames May 1991 Author's Address Brian Kantor University of California at San Diego Network Operations C-024 La Jolla, CA 92093-0214 Phone: (619) 534-6865 EMail: brian@UCSD.EDU Kantor [Page 2] /etc/ax25/ax25ipd.conf for vk5xxx # # ax25ipd configuration file for station floyd.vk5xxx.ampr.org # # Select axip transport. 'ip' is what you want for compatibility # with most other gates ... # socket ip # # Set ax25ipd mode of operation. (digi or tnc) # mode tnc # # If you selected digi, you must define a callsign. If you selected # tnc mode, the callsign is currently optional, but this may change # in the future! (2 calls if using dual port kiss) # #mycall vk5xxx-4 #mycall2 vk5xxx-5 # # In digi mode, you may use an alias. (2 for dual port) # #myalias svwdns #myalias2 svwdn2 # # Send an ident every 540 seconds ... # beacon after 540 btext ax25ip -- tncmode rob/vk5xxx -- Experimental AXIP gateway # # Serial port, or pipe connected to a kissattach in my case # device /dev/ttyqd # # Set the device speed # speed 9600 # # loglevel 0 - no output # loglevel 1 - config info only # loglevel 2 - major events and errors # loglevel 3 - major events, errors, and AX25 frame trace # loglevel 4 - all events # log 0 for the moment, syslog not working yet ... # loglevel 0 # # If we are in digi mode, we might have a real tnc here, so use param to # set the tnc parameters ... # #param 1 20 # # ax.25 route definition, define as many as you need (< 128?) # format is route (call/wildcard) (ip host at destination) # route vk5zeu* 44.136.202.3 route vk5wsr-1 44.136.202.241 route vk5wsr-0 44.136.202.241 route vk5dj-15 44.136.202.241 route vk5ham* 44.136.202.241 # # a default route. Carefull here, all undefined traffic end's up here. # route default 44.136.202.241 # another ax25ipd.cfg # Sample ax25ipd configuration file # # First select the mode of operation. (digi or tnc) # socket ip # mode tnc # # If you selected digi, you must define a callsign. If you selected # tnc mode, the callsign is currently optional, but this may change # in the future! # mycall ve3rpi-14 mycall2 ve3rpi-15 # # In digi mode, you may use an alias. # myalias ryeha1 myalias2 ryeha2 # # ID every 10 minutes... # beacon after 540 btext ax25ipd -- digi jeff -- Experimental IP gateway # # The tnc or host system must be connected to a serial port. # device /dev/ttyS1 # # The line speed is set here # speed 9600 # # loglevel 0 - no output # loglevel 1 - config info only # loglevel 2 - major events and errors # loglevel 3 - major events, errors, and AX25 frame trace # loglevel 4 - all events # loglevel 4 # # If digi mode, we probably have a tnc on the other end of the serial # port. Use the param command to set the KISS parameters (like txdelay!) # You can specify as many as you need. # param 1 20 # # Define some routes. This example routes all traffic for callsign ka9wsb-7 # to a host named waveguide.central.sun.com. You can define as many as # required. # route ve3rpi bbs.ve3rpi.ampr.org route ve3rpi-2 ryeham.ee.ryerson.ca route qst ryeham.ee.ryerson.ca # # A catch-all is provided: this line sends all calls not specifically # noted in the routing tables to sunbird.central.sun.com. Use this feature # with great care -- the host on the other end may not appreciate all the # traffic! # #route default sunbird.central.sun.com # ax25ipd.cfg.n8qlb # Sample ax25ipd configuration file (0.4.2 version) # # First select the mode of operation. (digi or tnc) # mode tnc # # The normal mode of operation is using IP datagrams: # socket ip # # But you can also use UDP datagrams. If you don't specify a port number # to use, the default will be chosen (usually a Good Idea). # socket udp # # If you selected digi, you must define a callsign. If you selected # tnc mode, the callsign is currently optional, but this may change # in the future! # mycall N8QLB-1 # # In digi mode, you may use an alias. # myalias LINUXX # # Note that if you use an alias, in order to guarantee you will properly # ID every 10 minutes, you MUST specify "beacon every 540" (or so -- # don't beacon too often, but setting it to 600 might end up squeaking # past the 10 minute time if the channel is busy) # A possible future enhancement may allow an ID only if necessary (i.e. # a packet has been digipeated using the "myalias" id)... # beacon every 540 btext ax25ipd -- digi n8qlb -- Experimental IP gateway # # The tnc or host system must be connected to a serial port. # device /dev/tnc # # The line speed is set here # speed 9600 # # loglevel 0 - no output # loglevel 1 - config info only # loglevel 2 - major events and errors # loglevel 3 - major events, errors, and AX25 frame trace # loglevel 4 - all events # loglevel 0 # # If digi mode, we probably have a tnc on the other end of the serial # port. Use the param command to set the KISS parameters (like txdelay!) # You can specify as many as you need. # param 1 20 # # Define some routes. This example routes all traffic for callsign ka9wsb-6 # to a host named sales.central.sun.com, using udp instead of raw ip. The # next line sends all traffic for e3abc-5 to a host at ip address 11.22.33.44, # sending the datagrams to udp port 12345. The last example sends frames # addressed to y4xyz-9 and sends them to flim.flam.com, using the ip # encapsulation. You can define as many as required. # #route n8qlb linux.n8qlb #route e3abc-5 11.22.33.44 udp 12345 #route y4xyz-9 flim.flam.com # # A catch-all is provided: this line sends all calls not specifically # noted in the routing tables to fred.central.sun.com. Use this feature # with great care -- the host on the other end may not appreciate all the # traffic! # route default linux.n8qlb # ax25ipd.cfg.stock # Sample ax25ipd configuration file # # First select the mode of operation. (digi or tnc) # mode digi # # If you selected digi, you must define a callsign. If you selected # tnc mode, the callsign is currently optional, but this may change # in the future! # mycall ka9wsb-7 # # In digi mode, you may use an alias. # myalias sunord # # ID every 10 minutes... # beacon after 540 btext ax25ipd -- digi ka9wsb-7 -- Experimental IP gateway # # The tnc or host system must be connected to a serial port. # device /dev/ttyb # # The line speed is set here # speed 9600 # # loglevel 0 - no output # loglevel 1 - config info only # loglevel 2 - major events and errors # loglevel 3 - major events, errors, and AX25 frame trace # loglevel 4 - all events # loglevel 3 # # If digi mode, we probably have a tnc on the other end of the serial # port. Use the param command to set the KISS parameters (like txdelay!) # You can specify as many as you need. # param 1 20 # # Define some routes. This example routes all traffic for callsign ka9wsb-7 # to a host named waveguide.central.sun.com. You can define as many as # required. # route ka9wsb-6 salespuke.central.sun.com # # A catch-all is provided: this line sends all calls not specifically # noted in the routing tables to sunbird.central.sun.com. Use this feature # with great care -- the host on the other end may not appreciate all the # traffic! # #route default sunbird.central.sun.com # 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 ax25ipd 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 ax25ipd 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. -------------------------------------------------------------------------