Linux Amateur Radio AX.25 HOWTO

1.1. Changes from the previous version

• Updated IPIP tunnelling section to reflect iproute2 package (thanks to Milan Kalina).

1.2. Where to obtain new versions of this document

The best place to obtain the latest version of this document is from a Linux Documentation Project archive. The Linux Documentation Project runs a web server and this document appears there as the AX25-HOWTO. This document is also available in various formats from the Linux Documentation Project.

You can always contact me, but I pass new versions of the document directly to the LDP HOWTO coordinator, so if it isn't there then chances are I haven't finished it.

1.3. Other related documentation

There is a lot of related documentation. There are many documents that relate to Linux networking in more general ways and I strongly recommend you also read these as they will assist you in your efforts and provide you with deeper insight into other possible configurations. They are:

• Linux Networking HOWTO

• Linux Ethernet HOWTO

• Linux Firewall and Proxy Server HOWTO

• Linux 2.4 Advanced Routing HOWTO

• Netrom-Node mini-Howto

You may come across references to a Linux HAM HOWTO. This document is obsolete and has been replaced by the Hamsoft Linux Ham Radio Applications and Utilities Database web site. More general Linux information may be found by referencing other Linux HOWTO documents.

2.1. How it all fits together

The Linux AX.25 implementation is a brand new implementation. While in many ways it may looks similar to NOS, or BPQ or other AX.25 implementations, it is none of these and is not identical to any of them. The Linux AX.25 implementation is capable of being configured to behave almost identically to other implementations, but the configuration process is very different.

To assist you in understanding how you need to think when configuring this section describes some of the structural features of the AX.25 implementation and how it fits into the context of the overall Linux structure.

Simplified Protocol Layering Diagram

 _____________________________________________
|         |           |             |         |
| AF_AX25 | AF_NETROM |  AF_INET    | AF_ROSE |
|=========|===========|=============|=========|
|         |           |             |         |
|         |           |    TCP/IP   |         |
|         |           |________     |         |
|         |   NET/ROM          |    | ROSE    |
|         |____________________|____|_________|
|            AX.25                            |
|_____________________________________________|

This diagram simply illustrates that NET/ROM, ROSE and TCP/IP all run directly on top of AX.25, but that each of these protocols is treated as a separate protocol at the programming interface. The `_' names are simply the names given to the `Address Family' of each of these protocols when writing programs to use them. The important thing to note here is the implicit dependence on the configuration of your AX.25 devices before you can configure your NET/ROM, ROSE or TCP/IP devices.

Software Module Diagram of Linux Network Implementation

 ___________________________________________________________________________
|         |           |                       ||          |                 |
| User    | Programs  |   call        node    ||  Daemons | ax25d  mheardd  |
|         |           |   pms         mheard  ||          | inetd  netromd  |
|_________|___________|_______________________||__________|_________________|
|         | Sockets   |open(), close(), listen(), read(), write(), connect()|
|         |           |_____________________________________________________|
|         |           |   AF_AX25   |  AF_NETROM  |   AF_ROSE   |  AF_INET  |
|         |___________|_____________|_____________|_____________|___________|
|Kernel   | Protocols |   AX.25     |   NetRom    |     ROSE    | IP/TCP/UDP|
|         |___________|_____________|_____________|_____________|___________|
|         | Devices   |   ax0,ax1   |  nr0,nr1    | rose0,rose1 | eth0,ppp0 |
|         |___________|_____________|_____________|_____________|___________|
|         | Drivers   | Kiss   PI2   PacketTwin   SCC   BPQ     | slip ppp  |
|         |           |     Soundmodem      Baycom              | ethernet  |
|_________|___________|_________________________________________|___________|
|Hardware | PI2 Card, PacketTwin Card, SCC card, Serial port, Ethernet Card |
|_________|_________________________________________________________________|

This diagram is a little more general than the first. This diagram attempts to show the relationship between user applications, the kernel and the hardware. It also shows the relationship between the Socket application programming interface, the actual protocol modules, the kernel networking devices and the device drivers. Anything in this diagram is dependent on anything underneath it, and in general you must configure from the bottom of the diagram upwards. So for example, if you want to run the call program you must also configure the hardware, then ensure that the kernel has the appropriate device driver, that you create the appropriate network device, that the kernel includes the desired protocol that presents a programming interface that the call program can use. I have attempted to lay out this document in roughly that order.

3.1. Finding the kernel, tools and utility packages

---

3.1.2. The network tools

The latest release of the standard Linux network tools support AX.25 and NET/ROM and can be found at http://www.tazenda.demon.co.uk/phil/net-tools.

The latest ipchains package can be found at http://netfilter.filewatcher.org/ipchains.

It is usually not necessary to download and install these as any recent Linux distribution should include them.

4.1. Compiling the kernel

If you are already familiar with the process of compiling the Linux kernel then you can skip this section, just be sure to select the appropriate options when compiling the kernel. If you are not, then read on. You may also want to read the Linux Kernel HOWTO.

The normal place for the kernel source to be unpacked to is the /usr/src directory into a subdirectory called linux. To do this you should be logged in as root and execute a series of commands similar to the following:

# cd /usr/src
# mv linux linux.old
# tar xzvf linux-2.4.9.tar.gz
# cd linux

After you have unpacked the kernel source, you need to run the configuration script and choose the options that suit your hardware configuration and the options that you wish built into your kernel. You do this by using the command:

# make menuconfig

If you are running X you can get a graphical interface using:

# make xconfig

You might also try:

# make config

I'm going to describe the full screen method (menuconfig) because it is easier to move around, but use whichever you are most comfortable with.

In either case you will be offered a range of options at which you must answer `Y' or `N'. (Note you may also answer `M' if you are using modules. For the sake of simplicity I will assume you are not, please make appropriate modifications if you are).

The options most relevant to an AX.25 configuration are:

Code maturity level options  --->
    [*] Prompt for development and/or incomplete code/drivers
    ...
General setup  --->
    ...
    [*] Networking support
    ...
Networking options  --->
    <*> UNIX domain sockets
    ...
    [*] TCP/IP networking
    ...
    [?] IP: tunneling
    ...
Amateur Radio Support --->
    --- Packet Radio protocols
    [*]   Amateur Radio AX.25 Level 2 protocol
    [?]     AX.25 DAMA Slave support
    [?]     Amateur Radio NET/ROM protocol
    [?]     Amateur Radio X.25 PLP (Rose)
    AX.25 network device drivers  --->
    <?> Serial port KISS driver
    <?> Serial port 6PACK driver
    <?> BPQ Ethernet driver
    <?> High-speed (DMA) SCC driver for AX.25
    <?> Z8530 SCC driver
    <?> BAYCOM ser12 fullduplex driver for AX.25
    <?> BAYCOM ser12 halfduplex driver for AX.25
    <?> BAYCOM picpar and par96 driver for AX.25
    <?> BAYCOM epp driver for AX.25
    <?> Soundcard modem driver
    [?]   soundmodem support for Soundblaster and compatible cards
    [?]   soundmodem support for WSS and Crystal cards
    [?]   soundmodem support for 1200 baud AFSK modulation
    [?]   soundmodem support for 2400 baud AFSK modulation (7.3728MHz crystal)
    [?]   soundmodem support for 2400 baud AFSK modulation (8MHz crystal)
    [?]   soundmodem support for 2666 baud AFSK modulation
    [?]   soundmodem support for 4800 baud HAPN-1 modulation
    [?]   soundmodem support for 4800 baud PSK modulation
    [?]   soundmodem support for 9600 baud FSK G3RUH modulation
    <?> YAM driver for AX.25

The options I have flagged with a `*' are those that you must must answer `Y' to. The rest are dependent on what hardware you have and what other options you want to include. Some of these options are described in more detail later on, so if you don't know what you want yet, then read ahead and come back to this step later.

After you have completed the kernel configuration you should be able to cleanly compile your new kernel:

# make dep
# make clean
# make zImage

Make sure you move your arch/i386/boot/zImage file wherever you want it and then edit your /etc/lilo.conf file and rerun lilo to ensure that you actually boot from it.

---

4.1.1. A word about kernel modules

Compiling drivers as modules is useful if you only use AX.25 occasionally and want to be able to load and unload them on demand to save system resources. However, some people have problems getting the modularized drivers working because they are more complicated to configure. If you've chosen to compile any drivers as modules, then you'll also need to run the commands:

# make modules # make modules_install

to install your modules in the appropriate location.

You will also need to add some entries into your /etc/modules.conf file to ensure that the kerneld program knows how to locate the kernel modules. You should add/modify the following:

alias net-pf-3 ax25 alias net-pf-6 netrom alias net-pf-11 rose alias tty-ldisc-1 slip alias tty-ldisc-3 ppp alias tty-ldisc-5 mkiss alias bc0 baycom alias nr0 netrom alias pi0a pi2 alias pt0a pt alias scc0 optoscc (or one of the other scc drivers) alias sm0 soundmodem alias tunl0 newtunnel alias char-major-4 serial alias char-major-5 serial alias char-major-6 lp

On Debian-based Linux systems these entries should go into the file /etc/modutils/aliases and then you need to run /sbin/update-mpodules.

4.2. The AX.25 library, tools, and application programs

After you have successfully compiled and booted your new kernel you need to compile and install the ax25 library, tools, and application programs.

To compile and install libax25 you should use a series of commands similar to the following:

# cd /usr/src
# tar xzvf libax25-0.0.7.tar.gz
# cd libax25-0.0.7
# ./configure --exec_prefix=/usr --sysconfdir=/etc --localstatedir=/var
# make
# make install

The arguments to the configure command ensure that the files will be installed in the "standard" places under the directory /usr in subdirectories bin, sbin, etc and man. If you simply run configure with no options it will default to putting all files under /usr/local. This can cause the situation where you have configuration files in both /usr and /usr/local. If you want to ensure that this can't happen you can make /usr/local/etc/ax25 a symbolic link to /etc/ax25 at the very beginning of the install process and then you won't have to worry about it.

If this is a first time installation, that is you've never installed any ax25 code on your machine before, you should also use the:

# make installconf

command to install some sample configuration files into the /etc/ax25/ directory from which to work.

You can now build install the AX.25 tools in a similar fashion:

# cd /usr/src
# tar xzvf ax25-tools-0.0.6.tar.gz
# cd ax25-tools-0.0.6
# ./configure --prefix=/usr  --sysconfdir=/etc --localstatedir=/var
# make
# make install
# make installconf (if you want to install the configuration files)

And finally you can install the AX.25 applications:

# cd /usr/src
# tar xzvf ax25-apps-0.0.4.tar.gz
# cd ax25-apps-0.0.4
# ./configure --prefix=/usr  --sysconfdir=/etc --localstatedir=/var
# make
# make install
# make installconf (if you want to install the configuration files)

If you get messages something like:

gcc -Wall -Wstrict-prototypes -O2 -I../lib -c call.c
call.c: In function `statline':
call.c:268: warning: implicit declaration of function `attron'
call.c:268: `A_REVERSE' undeclared (first use this function)
call.c:268: (Each undeclared identifier is reported only once
call.c:268: for each function it appears in.)

then you should double check that you have the ncurses package properly installed on your system. The configuration script attempts to locate your package in the common locations, but some installations have it badly installed and it is unable to locate them.

5.1. What are all those T1, T2, N2 and things ?

Not every AX.25 implementation is a TNC2. Linux uses nomenclature that differs in some respects from that you will be used to if your sole experience with packet is a TNC. The following table should help you interpret what each of the configurable items are, so that when you come across them later in this text you'll understand what they mean.

5.2. Run time configurable parameters

The kernel allows you to change many parameters at run time. If you take a careful look at the /proc/sys/net/ directory structure you will see many files with useful names that describe various parameters for the network configuration. The files in the /proc/sys/net/ax25/ directory each represent one configured AX.25 port. The name of the file relates to the name of the port.

The structure of the files in /proc/sys/net/ax25/portname/ is as follows:

In the table T1, T2 and T3 are given in seconds, and the Idle Timeout is given in minutes. But please note that the values used in the sysctl interface are given in internal units where the time in seconds is multiplied by 10, this allows resolution down to 1/10 of a second. With timers that are allowed to be zero, e.g. T3 and Idle, a zero value indicates that the timer is disabled.

The structure of the files in /proc/sys/net/netrom/ is as follows:

The structure of the files in /proc/sys/net/rose/ is as follows:

To set a parameter all you need to do is write the desired value to the file itself, for example to check and set the ROSE window size you'd use something like:

# cat /proc/sys/net/rose/window_size
3
# echo 4 >/proc/sys/net/rose/window_size
# cat /proc/sys/net/rose/window_size
4

6.1. Creating the AX.25 network device

The network device is what is listed when you use the `ifconfig' command. This is the object that the Linux kernel sends and receives network data from. Nearly always the network device has a physical port associated with it, but there are occasions where this isn't necessary. The network device does relate directly to a device driver.

In the Linux AX.25 code there are a number of device drivers. The most common is probably the KISS driver, but others are the SCC driver(s), the Baycom driver and the Soundmodem driver.

Each of these device drivers will create a network device when it is started.

Amateur Radio support  --->
    [*] Amateur Radio support
    --- Packet Radio protocols
    <*>   Amateur Radio AX.25 Level 2 protocol
    ...
    AX.25 network device drivers  --->
    --- AX.25 network device drivers
    <*> Serial port KISS driver
    ...

# /usr/sbin/kissattach /dev/ttyS0 radio 44.135.96.242
# kissparms -p radio -t 100 -s 100 -r 25

# /usr/sbin/mkiss -s 9600 /dev/ttyS0 /dev/ptyq0 /dev/ptyq1
# /usr/sbin/kissattach /dev/ttyq0 port1 44.135.96.242
# /usr/sbin/kissattach /dev/ttyq1 port2 44.135.96.242

Amateur Radio support  --->
    [*] Amateur Radio support
    --- Packet Radio protocols
    <*>   Amateur Radio AX.25 Level 2 protocol
    ...
    AX.25 network device drivers  --->
    --- AX.25 network device drivers
    ...
    <*> Serial port 6PACK driver
    ...

Amateur Radio support  --->
    [*] Amateur Radio support
    --- Packet Radio protocols
    <*>   Amateur Radio AX.25 Level 2 protocol
    ...
    AX.25 network device drivers  --->
    --- AX.25 network device drivers
    ...
    <?> BAYCOM ser12 fullduplex driver for AX.25
    <?> BAYCOM ser12 halfduplex driver for AX.25
    <?> BAYCOM picpar and par96 driver for AX.25
    <?> BAYCOM epp driver for AX.25
    ...

# setserial /dev/ttyS0 uart none
# insmod hdlcdrv
# insmod baycom mode="ser12*" iobase=0x3f8 irq=4

# insmod hdlcdrv
# insmod baycom mode="par96" iobase=0x378 irq=7 options=0

# insmod hdlcdrv
# insmod baycom

# sethdlc -p -i bc0 mode par96 io 0x378 irq 7

# sethdlc -p -i bc1 mode "ser12*" io 0x3f8 irq 4

# sethdlc -i bc0 -a txd 200 slot 100 ppersist 40 half

# /sbin/ifconfig bc0 hw ax25 VK2KTJ-15 up

# ifconfig bc0 up
# axparms -setcall bc0 vk2ktj-15

---

6.1.5. Creating a kernel Soundmodem device

Kernel Compile Options:

Amateur Radio support ---> [*] Amateur Radio support --- Packet Radio protocols <*> Amateur Radio AX.25 Level 2 protocol ... AX.25 network device drivers ---> --- AX.25 network device drivers ... <*> Soundcard modem driver [?] soundmodem support for Soundblaster and compatible cards [?] soundmodem support for WSS and Crystal cards [?] soundmodem support for 1200 baud AFSK modulation [?] soundmodem support for 2400 baud AFSK modulation (7.3728MHz crystal) [?] soundmodem support for 2400 baud AFSK modulation (8MHz crystal) [?] soundmodem support for 2666 baud AFSK modulation [?] soundmodem support for 4800 baud HAPN-1 modulation [?] soundmodem support for 4800 baud PSK modulation [?] soundmodem support for 9600 baud FSK G3RUH modulation ...

Thomas Sailer has built a driver for the kernel that allows you to use your soundcard as a modem. Connect your radio directly to your soundcard to play packet! Thomas recommends at least a 486DX2/66 if you want to use this software as all of the digital signal processing is done by the main CPU.

The driver currently emulates 1200 bps AFSK, 4800 HAPN and 9600 FSK (G3RUH compatible) modem types. The only sound cards currently supported are SoundBlaster and Windows Sound System Compatible models. If you have a sound card of another type, you can try the user-mode soundmodem described later in this document.

The sound cards require some circuitry to help them drive the Push-To-Talk circuitry, and information on this is available from Thomas's Soundmodem PTT circuit web page. There are quite a few possible options, they are: detect the sound output from the soundcard, or use output from a parallel port, serial port or MIDI port. Circuit examples for each of these are on Thomas's site.

The Soundmodem driver creates network devices called: sm0, sm1, sm2 etc when it is configured.

The Soundmodem driver competes for the same resources as the Linux sound driver, so if you wish to use the Soundmodem driver you must ensure that the Linux sound driver is not installed. You can, of course, compile them both as modules and insert and remove them as you wish.

---

6.1.5.1. Configuring the sound card

The Soundmodem driver does not initialize the sound card. The ax25-utils package includes a utility to do this called `setcrystal' that may be used for sound cards based on the Crystal chip set. If you have some other card then you will have to use some other software to initialize it. Its syntax is fairly straightforward:

setcrystal [-w wssio] [-s sbio] [-f synthio] [-i irq] [-d dma] [-c dma2]

So, for example, if you wished to configure a SoundBlaster card at i/o base address 0x388, irq 10 and DMA 1 you would use:

# setcrystal -s 0x388 -i 10 -d 1

To configure a Window Sound System card at i/o base address 0x534, irq 5, DMA 3 you would use:

# setcrystal -w 0x534 -i 5 -d 3

The [-f synthio] parameter is the set the synthesizer address, and the [-c dma2] parameter is to set the second DMA channel to allow full duplex operation.

---

6.1.5.2. Configuring the Soundmodem driver

When you have configured the soundcard you need to configure the driver telling it where the sound card is located and what sort of modem you wish it to emulate.

The sethdlc utility allows you to configure the driver with these parameters, or, if you have only one soundcard installed you may specify the parameters on the insmod command line when you load the Soundmodem module.

For example, a simple configuration, with one SoundBlaster soundcard configured as described above emulating a 1200 bps modem:

# insmod hdlcdrv # insmod soundmodem mode="sbc:afsk1200" iobase=0x220 irq=5 dma=1

This is not really the preferred way to do it. The sethdlc utility works just as easily with one device as with many.

The sethdlc man page has the full details, but a couple of examples will illustrate the most important aspects of this configuration. The following examples assume you have already loaded the Soundmodem modules using:

# insmod hdlcdrv # insmod soundmodem

or that you compiled the kernel with the driver inbuilt.

Configure the driver to support the Windows Sound System card we configured above to emulate a G3RUH 9600 compatible modem as device sm0 using a parallel port at 0x378 to key the Push-To-Talk:

# sethdlc -p -i sm0 mode wss:fsk9600 io 0x534 irq 5 dma 3 pario 0x378

Configure the driver to support the SoundBlaster card we configured above to emulate a 4800 bps HAPN modem as device sm1 using the serial port located at 0x2f8 to key the Push-To-Talk:

# sethdlc -p -i sm1 mode sbc:hapn4800 io 0x388 irq 10 dma 1 serio 0x2f8

Configure the driver to support the SoundBlaster card we configured above to emulate a 1200 bps AFSK modem as device sm1 using the serial port located at 0x2f8 to key the Push-To-Talk:

# sethdlc -p -i sm1 mode sbc:afsk1200 io 0x388 irq 10 dma 1 serio 0x2f8

---

6.1.5.3. Configuring the AX.25 channel access parameters

The AX.25 channel access parameters are the equivalent of the KISS ppersist, txdelay and slottime type parameters. You use the sethdlc utility for this as well.

Again the sethdlc man page is the source of the most complete information but another example of two won't hurt:

Configure the sm0 device with TxDelay of 100 mS, SlotTime of 50mS, PPersist of 128 and full duplex:

# sethdlc -i sm0 -a txd 100 slot 50 ppersist 128 full

Note that the timing values are in milliseconds.

---

6.1.5.4. Setting the audio levels and tuning the driver

It is very important that the audio levels be set correctly for any radio based modem to work. This is equally true of the Soundmodem. Thomas has developed some utility programs that make this task easier. They are called smdiag and smmixer.

smdiag

provides two types of display, either an oscilloscope type display or an eye pattern type display.

smmixer

allows you to actually adjust the transmit and receive audio levels.

To start the smdiag utility in 'eye' mode for the Soundmodem device sm0 you would use:

# smdiag -i sm0 -e

To start the smmixer utility for the Soundmodem device sm0 you would use:

# smmixer -i sm0

---

6.1.5.5. Configuring the Kernel AX.25 to use the Soundmodem

The Soundmodem driver creates standard network devices that the AX.25 Kernel code can use. Configuration is much the same as that for a PI or PacketTwin card.

The first step is to configure the device with an AX.25 callsign. The ifconfig utility may be used to perform this.

# /sbin/ifconfig sm0 hw ax25 VK2KTJ-15 up

will assign the Soundmodem device sm0 the AX.25 callsign VK2KTJ-15. Alternatively you can use the axparms command, but you still need the ifconfig utility to bring the device up:

# ifconfig sm0 up # axparms -setcall sm0 vk2ktj-15

The next step is to create an entry in the /etc/ax25/axports file as you would for any other device. The entry in the axports file is associated with the network device you've configured by the callsign you configure. The entry in the axports file that has the callsign that you configured the Soundmodem device with is the one that will be used to refer to it.

You may then treat the new AX.25 device as you would any other. You can configure it for TCP/IP, add it to ax25d and run NET/ROM or ROSE over it as you please.

Amateur Radio support  --->
    [*] Amateur Radio support
    --- Packet Radio protocols
    <*>   Amateur Radio AX.25 Level 2 protocol
    ...
    AX.25 network device drivers  --->
    --- AX.25 network device drivers
    ...
    <?> YAM driver for AX.25
    ...

General setup  --->
    [*] Networking support
Network device support  --->
    [*] Network device support
    ...
    [*] Radio network interfaces
    [*] Ottawa PI and PI/2 support for AX.25

# /sbin/ifconfig pi0a hw ax25 VK2KTJ-15 up

General setup  --->
    [*] Networking support
Network device support  --->
    [*] Network device support
    ...
    [*] Radio network interfaces
    [*] Gracilis PackeTwin support for AX.25

# /sbin/ifconfig pt0a hw ax25 VK2KTJ-15 up

General setup  --->
    [*] Networking support
Network device support  --->
    [*] Network device support
    ...
    [*] Radio network interfaces
    [*] Z8530 SCC KISS emulation driver for AX.25

# cd /usr/src
# gzip -dc z8530drv-2.4a.dl1bke.tar.gz | tar xvpofz -
# cd z8530drv
# make clean
# make dep
# make module         # If you want to build the driver as a module
# make for_kernel     # If you want the driver to built into your kernel
# make install

# sccinit

# gencfg 2 0x150 4 2 0 1 0x168 9 4915200

# kissattach -s 4800 /dev/scc0 VK2KTJ

attach asy scc0 0 ax25 scc0 256 256 4800

# sccstat /dev/scc0

# sccparam /dev/scc0 txtail 0x8

General setup  --->
    [*] Networking support
Network device support  --->
    [*] Network device support
    ...
    [*] Radio network interfaces
    [*] BPQ Ethernet driver for AX.25

# /sbin/ifconfig bpq0 hw ax25 vk2ktj-14 up

LINK SUPPORT

        MAX STACKS 1
        MAX BOARDS 1

LINK DRIVER E2000                    ; or other MLID to suit your card

        INT 10                       ;
        PORT 300                     ; to suit your card

        FRAME ETHERNET_II

        PROTOCOL BPQ 8FF ETHERNET_II ; required for BPQ - can change PID

BPQPARAMS                            ; optional - only needed if you want
                                     ; to override the default target addr

        ETH_ADDR  FF:FF:FF:FF:FF:FF  ; Target address

6.2. Creating the /etc/ax25/axports file

The /etc/ax25/axports is a simple text file that you create with a text editor. The format of the /etc/ax25/axports file is as follows:

portname  callsign  baudrate  paclen  window  description

where:

In my case, mine looks like:

radio    VK2KTJ-15       4800        256     2       4800bps 144.800 MHz
ether    VK2KTJ-14       10000000    256     2       BPQ/ethernet device

Remember, you must assign unique callsign/ssid to each AX.25 port you create. Create one entry for each AX.25 device you want to use, this includes KISS, Baycom, SCC, PI, PT and Soundmodem ports. Each entry here will describe exactly one AX.25 network device. The entries in this file are associated with the network devices by the callsign/ssid. This is at least one good reason for requiring unique callsign/ssid.

6.3. Configuring AX.25 routing

You may wish to configure default digipeaters paths for specific hosts. This is useful for both normal AX.25 connections and also IP based connections. The axparms command enables you to do this. Again, the man page offers a complete description, but a simple example might be:

# /usr/sbin/axparms -route add radio VK2XLZ VK2SUT

This command would set a digipeater entry for VK2XLZ via VK2SUT on the AX.25 port named radio.

8.1. Configuring /etc/ax25/nrports

The first is the /etc/ax25/nrports file. This file describes the NET/ROM ports in much the same way as the /etc/ax25/axports file describes the AX.25 ports. Each NET/ROM device you wish to create must have an entry in the /etc/ax25/nrports file. Normally a Linux machine would have only one NET/ROM device configured that would use a number of the AX.25 ports defined. In some situations you might wish a special service such as a BBS to have a separate NET/ROM alias and so you would create more than one.

This file is formatted as follows:

name callsign  alias  paclen   description

Where:

An example would look something like the following:

netrom  VK2KTJ-9        LINUX   236     Linux Switch Port

This example creates a NET/ROM port known to the rest of the NET/ROM network as `LINUX:VK2KTJ-9'.

This file is used by programs such as the call program.

8.2. Configuring /etc/ax25/nrbroadcast

The second file is the /etc/ax25/nrbroadcast file. This file may contain a number of entries. There would normally be one entry for each AX.25 port that you wish to allow NET/ROM traffic on.

This file is formatted as follows:

axport min_obs def_qual worst_qual verbose

Where:

An example would look something like the following:

radio    1       200      100         1

8.3. Creating the NET/ROM Network device

When you have the two configuration files completed you must create the NET/ROM device in much the same way as you did for the AX.25 devices. This time you use the nrattach command. The nrattach works in just the same way as the axattach command except that it creates NET/ROM network devices called `nr[0-9]'. Again, the first time you use the nrattach command it creates the `nr0' device, the second time it creates the `nr1' network devices etc. To create the network device for the NET/ROM port we've defined we would use:

# nrattach netrom

This command would start the NET/ROM device (nr0) named netrom configured with the details specified in the /etc/ax25/nrports file.

8.4. Starting the NET/ROM daemon

The Linux kernel does all of the NET/ROM protocol and switching, but does not manage some functions. The NET/ROM daemon manages the NET/ROM routing tables and generates the NET/ROM routing broadcasts. You start NET/ROM daemon with the command:

# /usr/sbin/netromd -i

You should soon see the /proc/net/nr_neigh file filling up with information about your NET/ROM neighbours.

Remember to put the /usr/sbin/netromd command in your rc files so that it is started automatically each time you reboot.

8.5. Configuring NET/ROM routing.

You may wish to configure static NET/ROM routes for specific hosts. The nrparms command enables you to do this. Again, the man page offers a complete description, but a simple example might be:

# /usr/sbin/nrparms -nodes VK2XLZ-10 + #MINTO 120 5 radio VK2SUT-9

This command would set a NET/ROM route to #MINTO:VK2XLZ-10 via a neighbour VK2SUT-9 on my AX.25 port called `radio'.

You can manually create entries for new neighbours using the nrparms command as well. For example:

# /usr/sbin/nrparms -routes radio VK2SUT-9 + 120

This command would create VK2SUT-9 as a NET/ROM neighbour with a quality of 120 and this will be locked and will not be deleted automatically.

10.1. Configuring /etc/ax25/rsports

The file where you configure your ROSE interfaces is the /etc/ax25/rsports file. This file describes the ROSE port in much the same way as the /etc/ax25/axports file describes the AX.25 ports.

This file is formatted as follows:

name  address  description

Where:

An example would look something like the following:

rose  5050294760  Rose Port

Note that ROSE will use the default callsign/ssid configured on each AX.25 port unless you specify otherwise.

To configure a separate callsign/ssid for ROSE to use on each port you use the rsparms command as follows:

# /usr/sbin/rsprams -call VK2KTJ-10

This example would make Linux listen for and use the callsign/ssid VK2KTJ-10 on all of the configured AX.25 ports for ROSE calls.

10.2. Creating the ROSE Network device

When you have created the /etc/ax25/rsports file you may create the ROSE device in much the same way as you did for the AX.25 devices. This time you use the rsattach command. The rsattach command creates network devices named `rose[0-5]'. The first time you use the rsattach command it create the `rose0' device, the second time it creates the `rose1' device etc. For example:

# rsattach rose

This command would start the ROSE device (rose0) configured with the details specified in the /etc/ax25/rsports file for the entry named `rose'.

10.3. Configuring ROSE Routing

The ROSE protocol currently supports only static routing. The rsparms utility allows you to configure your ROSE routing table under Linux.

For example:

# rsparms -nodes add 5050295502 radio vk2xlz

would add a route to ROSE node 5050295502 via an AX.25 port named `radio' in your /etc/ax25/axports file to a neighbour with the callsign VK2XLZ.

You may specify a route with a mask to capture a number of ROSE destinations into a single routing entry. The syntax looks like:

# rsparms -nodes add 5050295502/4 radio vk2xlz

which would be identical to the previous example except that it would match any destination address that matched the first four digits supplied, in this case any address commencing with the digits 5050. An alternate form for this command is:

# rsparms -nodes add 5050/4 radio vk2xlz

which is probably the less ambiguous form.

12.1. Creating the /etc/ax25/ax25d.conf file

This file is the configuration file for the ax25d AX.25 daemon which handles incoming AX.25, NET/ROM and ROSE connections.

The file is a little cryptic looking at first, but you'll soon discover it is very simple in practice, with a small trap for you to be wary of.

The general format of the ax25d.conf file is as follows:

# This is a comment and is ignored by the ax25d program.
[port_name] || <port_name> || {port_name}
<peer1>    window T1 T2 T3 idle N2 <mode> <uid> <cmd> <cmd-name> <arguments>
<peer2>    window T1 T2 T3 idle N2 <mode> <uid> <cmd> <cmd-name> <arguments>
parameters window T1 T2 T3 idle N2 <mode>
<peer3>    window T1 T2 T3 idle N2 <mode> <uid> <cmd> <cmd-name> <arguments>
   ...
default    window T1 T2 T3 idle N2 <mode> <uid> <cmd> <cmd-name> <arguments>

Where:

You need one section in the above format for each AX.25, NET/ROM or ROSE interface you want to accept incoming AX.25, NET/ROM or ROSE connections on.

There are two special lines in the paragraph, one starts with the string `parameters' and the other starts with the string `default' (yes there is a difference). These lines serve special functions.

The `default' lines purpose should be obvious, this line acts as a catch-all, so that any incoming connection on the <interface_call> interface that doesn't have a specific rule will match the `default' rule. If you don't have a `default' rule, then any connections not matching any specific rule will be disconnected immediately without notice.

The `parameters' line is a little more subtle, and here is the trap I mentioned earlier. In any of the fields for any definition for a peer you can use the `*' character to say `use the default value'. The `parameters' line is what sets those default values. The kernel software itself has some defaults which will be used if you don't specify any using the `parameters' entry. The trap is that the these defaults apply only to those rules below the `parameters' line, not to those above. You may have more than one `parameters' rule per interface definition, and in this way you may create groups of default configurations. It is important to note that the `parameters' rule does not allow you to set the `uid' or `command' fields.

12.2. A simple example ax25d.conf file

Okay, an illustrative example:

# ax25d.conf for VK2KTJ - 02/03/97
# This configuration uses the AX.25 port defined earlier.

# <peer> Win T1  T2  T3  idl N2 <mode> <uid> <exec> <argv[0]>[<args....>]

[VK2KTJ-0 via radio]
parameters 1    10  *  *  *   *   *
VK2XLZ     *     *  *  *  *   *   *    root  /usr/sbin/axspawn axspawn %u +
VK2DAY     *     *  *  *  *   *   *    root  /usr/sbin/axspawn axspawn %u +
NOCALL     *     *  *  *  *   *   L
default    1    10  5 100 180 5   *    root  /usr/sbin/pms pms -a -o vk2ktj

[VK2KTJ-1 via radio]
default    *     *    *   *   *   0    root /usr/sbin/node node

<netrom>
parameters 1    10  *  *  *   *   *
NOCALL     *     *  *  *  *   *   L
default    *     *  *  *  *   *   0        root /usr/sbin/node node

{VK2KTJ-0 via rose}
parameters 1    10  *  *  *   *   *
VK2XLZ     *     *  *  *  *   *   *    root  /usr/sbin/axspawn axspawn %u +
VK2DAY     *     *  *  *  *   *   *    root  /usr/sbin/axspawn axspawn %u +
NOCALL     *     *  *  *  *   *   L
default    1    10  5 100 180 5   *    root  /usr/sbin/pms pms -a -o vk2ktj

{VK2KTJ-1 via rose}
default    *     *    *   *   *   0    root /usr/sbin/node node radio

This example says that anybody attempting to connect to the callsign `VK2KTJ-0' heard on the AX.25 port called `radio' will have the following rules applied:

Anyone whose callsign is set to `NOCALL' should be locked out, note the use of mode `L'.

The parameters line changes two parameters from the kernel defaults (Window and T1) and will run the /usr/sbin/axspawn program for them. Any copies of /usr/sbin/axspawn run this way will appear as axspawn in a ps listing for convenience. The next two lines provide definitions for two stations who will receive those permissions.

The last line in the paragraph is the `catch all' definition that everybody else will get (including VK2XLZ and VK2DAY using any other SSID other than -1). This definition sets all of the parameters implicitly and will cause the pms program to be run with a command line argument indicating that it is being run for an AX.25 connection, and that the owner callsign is VK2KTJ. (See the `Configuring the PMS' section below for more details).

The next configuration accepts calls to VK2KTJ-1 via the radio port. It runs the node program for everybody that connects to it.

The next configuration is a NET/ROM configuration, note the use of the greater-then and less-than braces instead of the square brackets. These denote a NET/ROM configuration. This configuration is simpler, it simply says that anyone connecting to our NET/ROM port called `netrom' will have the node program run for them, unless they have a callsign of `NOCALL' in which case they will be locked out.

The last two configurations are for incoming ROSE connections. The first for people who have placed calls to `vk2ktj-0' and the second for `VK2KTJ-1 at the our ROSE node address. These work precisely the same way. Not the use of the curly braces to distinguish the port as a ROSE port.

This example is a contrived one but I think it illustrates clearly the important features of the syntax of the configuration file. The configuration file is explained fully in the ax25d.conf man page. A more detailed example is included in the ax25-utils package that might be useful to you too.

12.3. Starting ax25d

When you have the two configuration files completed you start ax25d with the command:

# /usr/sbin/ax25d

When this is run people should be able to make AX.25 connections to your Linux machine. Remember to put the ax25d command in your rc files so that it is started automatically when you reboot each time.

13.1. Creating the /etc/ax25/node.conf file

The node.conf file is where the main configuration of the node takes place. It is a simple text file and its format is as follows:

# /etc/ax25/node.conf
# configuration file for the node(8) program.
#
# Lines beginning with '#' are comments and are ignored.

# Hostname
# Specifies the hostname of the node machine
hostname	radio.gw.vk2ktj.ampr.org

# Local Network
# allows you to specify what is consider 'local' for the
# purposes of permission checking using nodes.perms.
localnet	44.136.8.96/29

# Hide Ports
# If specified allows you to make ports invisible to users. The
# listed ports will not be listed by the (P)orts command.
hiddenports	rose netrom

# Node Identification.
# this will appear in the node prompt
NodeId		LINUX:VK2KTJ-9

# NET/ROM port
# This is the name of the NET/ROM port that will be used for
# outgoing NET/ROM connections from the node.
NrPort		netrom

# Node Idle Timeout
# Specifies the idle time for connections to this node in seconds.
idletimout	1800

# Connection Idle Timeout
# Specifies the idle timer for connections made via this node in
# seconds.
conntimeout	1800

# Reconnect
# Specifies whether users should be reconnected to the node
# when their remote connections disconnect, or whether they
# should be disconnected complete.
reconnect	on

# Command Aliases
# Provide a way of making complex node commands simple.
alias		CONV	"telnet vk1xwt.ampr.org 3600"
alias		BBS	"connect radio vk2xsb"

# External Command Aliases
# Provide a means of executing external commands under the node.
# extcmd <cmdname> <flag> <userid> <command>
# Flag == 1 is the only implemented function.
# <command> is formatted as per ax25d.conf
extcmd		PMS	1	root	/usr/sbin/pms pms -u %U -o VK2KTJ

# Logging
# Set logging to the system log. 3 is the noisiest, 0 is disabled.
loglevel	3

# The escape character
# 20 = (Control-T)
EscapeChar      20

13.2. Creating the /etc/ax25/node.perms file

The node allows you to assign permissions to users. These permissions allow you to determine which users should be allowed to make use of options such as the (T)elnet, and (C)onnect commands, for example, and which shouldn't. The node.perms file is where this information is stored and contains five key fields. For all fields an asterisk `*' character matches anything. This is useful for building default rules.

A sample nodes.perms might look like:

# /etc/ax25/node.perms
#
# The node operator is VK2KTJ, has a password of 'secret' and
# is allowed all permissions by all connection methods
vk2ktj	*	*	secret	255

# The following users are banned from connecting
NOCALL	*	*	*	0
PK232	*	*	*	0
PMS	*	*	*	0

# INET users are banned from connecting.
*	inet	*	*	0

# AX.25, NET/ROM, Local, Host and AMPR users may (C)onnect and (T)elnet
# to local and ampr hosts but not to other IP addresses.
*	ax25	*	*	159
*	netrom	*	*	159
*	local	*	*	159
*	host	*	*	159
*	ampr	*	*	159

13.3. Configuring node to run from ax25d

The node program would normally be run by the ax25d program. To do this you need to add appropriate rules to the /etc/ax25/ax25d.conf file. In my configuration I wanted users to have a choice of either connecting to the node or connecting to other services. ax25d allows you to do this by cleverly creating port aliases. For example, given the ax25d configuration presented above, I want to configure node so that all users who connect to VK2KTJ-1 are given the node. To do this I add the following to my /etc/ax25/ax25d.conf file:

[vk2ktj-1 via radio]
default    *     *    *   *   *   0    root /usr/sbin/node node

This says that the Linux kernel code will answer any connection requests for the callsign `VK2KTJ-1' heard on the AX.25 port named `radio', and will cause the node program to be run.

13.4. Configuring node to run from inetd

If you want users to be able to telnet a port on your machine and obtain access to the node you can go this fairly easily. The first thing to decide is what port users should connect to. In this example I've arbitrarily chosen port 4000, though Tomi gives details on how you could replace the normal telnet daemon with the node in his documentation.

You need to modify two files.

To /etc/services you should add:

node	3694/tcp	#OH2BNS's node software

and to /etc/inetd.conf you should add:

node	stream	tcp	nowait	root	/usr/sbin/node node

When this is done, and you have restarted the inetd program any user who telnet connects to port 3694 of your machine will be prompted to login and if configured, their password and then they will be connected to the node.

14.1. Creating the /etc/ax25/axspawn.conf file

You can alter the behaviour of axspawn in various ways by use of the /etc/ax25/axspawn.conf file. This file is formatted as follows:

# /etc/ax25/axspawn.conf
#
# allow automatic creation of user accounts
create    yes
#
# guest user if above is 'no' or everything else fails. Disable with "no"
guest     no
#
# group id or name for autoaccount
group     ax25
#
# first user id to use
first_uid 2001
#
# maximum user id
max_uid   3000
#
# where to add the home directory for the new users
home      /home/ax25
#
# user shell
shell     /bin/bash
#
# bind user id to callsign for outgoing connects.
associate yes

The eight configurable characteristics of axspawn are as follows:

15.1. Create the /etc/ax25/pms.motd file

The /etc/ax25/pms.motd file contains the `message of the day' that users will be presented with after they connect and receive the usual BBS id header. The file is a simple text file, any text you include in this file will be sent to users.

15.2. Create the /etc/ax25/pms.info file

The /etc/ax25/pms.info file is also a simple text file in which you would put more detailed information about your station or configuration. This file is presented to users in response to their issuing of the Info command from the PMS> prompt.

15.3. Associate AX.25 callsigns with system users

When a connected user sends mail to an AX.25 callsign, the pms expects that callsign to be mapped, or associated with a real system user on your machine. This is described in a section of its own.

15.4. Add the PMS to the /etc/ax25/ax25d.conf file

Adding the pms to your ax25d.conf file is very simple. There is one small thing you need to think about though. Dave has added command line arguments to the PMS to allow it to handle a number of different text end-of-line conventions. AX.25 and NET/ROM by convention expect the end-of-line to be carriage return, linefeed while the standard UNIX end-of-line is just newline. So, for example, if you wanted to add an entry that meant that the default action for a connection received on an AX.25 port is to start the PMS then you would add a line that looked something like:

default  1  10 5 100 5   0    root  /usr/sbin/pms pms -a -o vk2ktj

This simply runs the pms program, telling it that it is an AX.25 connection it is connected to and that the PMS owner is vk2ktj. Check the man page for what you should specify for other connection methods.

15.5. Test the PMS

To test the PMS, you can try the following command from the command line: # /usr/sbin/pms -u vk2ktj -o vk2ktj Substitute your own callsign for mine and this will run the pms, telling it that it is to use the UNIX end-of-line convention, and that user logging in is vk2ktj. You can do all the things connected users can.

Additionally you might try getting some other node to connect to you to confirm that your ax25d.conf configuration works.

17.1. Configuring a ROSE downlink

To configure your Linux machine to accept a ROSE connection and establish an AX.25 connection to any destination callsign that is not being listened for on your machine you need to add an entry to your /etc/ax25/ax25d.conf file. Normally you would configure this entry to be the default behaviour for incoming ROSE connections. For example you might have ROSE listeners operating for destinations like NODE-0 or HEARD-0 that you wish to handle locally, but for all other destination calls you may want to pass them to the rsdwnlink command and assume they are AX.25 users.

A typical configuration would look like:

#
{* via rose}
NOCALL   * * * * * *  L
default  * * * * * *  - root  /usr/sbin/rsdwnlnk rsdwnlnk 4800 vk2ktj-5
#

With this configuration any user who established a ROSE connection to your Linux nodes address with a destination call of something that you were not specifically listening for would be converted into an AX.25 connection on the AX.25 port named 4800 with a digipeater path of VK2KTJ-5.

17.2. Configuring a ROSE uplink

To configure your Linux machine to accept AX.25 connections in the same way that a ROM ROSE node would you must add an entry into your /etc/ax25/ax25d.conf file that looks similar to the following:

#
[VK2KTJ-5* via 4800]
NOCALL   * * * * * *  L
default  * * * * * *  - root  /usr/sbin/rsuplnk rsuplnk rose
#

Note the special syntax for the local callsign. The `*' character indicates that the application should be invoked if the callsign is heard in the digipeater path of a connection.

This configuration would allow an AX.25 user to establish ROSE calls using the example connect sequence presented in the introduction. Anybody attempting to digipeat via VK2KTJ-5 on the AX.25 port named 4800 would be handled by the rsuplnk command.

21.1. The address families

Network programming for AX.25, NET/ROM and ROSE is quite similar to programming for TCP/IP under Linux. The major differences being the address families used, and the address structures that need to be mangled into place.

The address family names for AX.25, NET/ROM and ROSE are AF_AX25, AF_NETROM and AF_ROSE respectively.

21.2. The header files

You must always include the `netax25/ax25.h' header file, and also the `netrom/netrom.h' or `netrose/rose.h' header files if you are dealing with those protocols. Simple top level skeletons would look something like the following:

For AX.25:

#include <netax25/ax25.h>
int s, addrlen = sizeof(struct full_sockaddr_ax25);
struct full_sockaddr_ax25 sockaddr;
sockaddr.fsa_ax25.sax25_family = AF_AX25

For NET/ROM:

#include <netax25/ax25.h>
#include <netrom/netrom.h>
int s, addrlen = sizeof(struct full_sockaddr_ax25);
struct full_sockaddr_ax25 sockaddr;
sockaddr.fsa_ax25.sax25_family = AF_NETROM;

For ROSE:

#include <netax25/ax25.h>
#include <netrose/rose.h>
int s, addrlen = sizeof(struct sockaddr_rose);
struct sockaddr_rose sockaddr;
sockaddr.srose_family = AF_ROSE;

21.3. Callsign mangling and examples

There are routines within the lib/ax25.a library built in the AX.25 utilities package that manage the callsign conversions for you. You can write your own of course if you wish.

The user_call utilities are excellent examples from which to work. The source code for them is included in the AX.25 utilities package. If you spend a little time working with those you will soon see that ninety percent of the work is involved in just getting ready to open the socket. Actually making the connection is easy, the preparation takes time.

The examples are simple enough to not be very confusing. If you have any questions, you should feel to direct them to the linux-hams mailing list and someone there will be sure to help you.

22.1. Small Ethernet LAN with Linux as a router to Radio LAN

Many of you may have small local area networks at home and want to connect the machines on that network to your local radio LAN. This is the type of configuration I use at home. I arranged to have a suitable block of addresses allocated to me that I could capture in a single route for convenience and I use these on my Ethernet LAN. Your local IP coordinator will assist you in doing this if you want to try it as well. The addresses for the Ethernet LAN form a subset of the radio LAN addresses. The following configuration is the actual one for my linux router on my network at home:

                                         . . . . . .
  ___               _________         .
   | Network       /         \     .    Network
   | 44.136.8.96/29|         |    .     44.136.8/24        \ | /
   |               | Linux   |   .                          \|/
   |               |         |  .   _____      __________    |
   |          eth0 | Router  |  .  /     \    /          \   |
   |_______________|         |_____| TNC |____|  Radio   |__/
   |   44.136.8.97 |  and    |  .  \_____/    \__________/
   |               |         | sl0
   |               | Server  | 44.136.8.5
   |               |         |   .
   |               |         |     .
   |               \_________/        .
  _|_                                    . . . . . .

#!/bin/sh
# /etc/rc.net
# This configuration provides one KISS based AX.25 port and one
# Ethernet device.

echo "/etc/rc.net"
echo "  Configuring:"

echo -n "    loopback:"
/sbin/ifconfig lo 127.0.0.1
/sbin/route add 127.0.0.1
echo " done."

echo -n "    ethernet:"
/sbin/ifconfig eth0 44.136.8.97 netmask 255.255.255.248 \
		broadcast 44.136.8.103 up
/sbin/route add 44.136.8.97 eth0
/sbin/route add -net 44.136.8.96 netmask 255.255.255.248 eth0
echo " done."

echo -n "    AX.25: "
kissattach -i 44.136.8.5 -m 512 /dev/ttyS1 4800
ifconfig sl0 netmask 255.255.255.0 broadcast 44.136.8.255
route add -host 44.136.8.5 sl0
route add -net 44.136.8.0 window 1024 sl0

echo -n "    NET/ROM: "
nrattach -i 44.136.8.5 netrom

echo "  Routing:"
/sbin/route add default gw 44.136.8.68 window 1024 sl0
echo "    default route."
echo done.

# end

/etc/ax25/axports

# name  callsign        speed   paclen  window  description
4800    VK2KTJ-0        4800    256     2       144.800 MHz

/etc/ax25/nrports

# name  callsign        alias   paclen  description
netrom  VK2KTJ-9        LINUX   235     Linux Switch Port

/etc/ax25/nrbroadcast

# ax25_name     min_obs def_qual        worst_qual      verbose
4800            1       120             10              1

Note the following:

• You must have IP_FORWARDING enabled in your kernel.

• The AX.25 configuration files are pretty much those used as examples in the earlier sections, refer to those where necessary.

• I've chosen to use an IP address for my radio port that is not within my home network block. I needn't have done so, I could have easily used 44.136.8.97 for that port too.

• 44.136.8.68 is my local IPIP encapsulated gateway and hence is where I point my default route.

• Each of the machines on my Ethernet network have a route:

  route add -net 44.0.0.0 netmask 255.0.0.0 \ gw 44.136.8.97 window 512 mss 512 eth0

  The use of the mss and window parameters means that I can get optimum performance from both local Ethernet and radio based connections.

• I also run my smail, http, ftp and other daemons on the router machine so that it needs to be the only machine to provide others with facilities.

• The router machine is a lowly 386DX20 with a 20Mb hard drive and a very minimal linux configuration.

22.2. IPIP encapsulated gateway configuration

Linux is now very commonly used for TCP/IP encapsulated gateways around the world. The 2.2 and 2.4 kernels provide a new method, making the old ipip configuration obsolete. The ip command contained in the IPROUTE2 package is now the main tool, as described in the Linux 2.4 Advanced Routing HOWTO.

A typical configuration would look similar to the following:

   __________                      _________
  /          \      Internet      /         \ 44.177.155.0/24
  |          |                    |         |     ______
  |   UCSD   |                    |  Linux  |    /      \
  |          |                    |         |    |      |
  | ampr.org | eth1          eth0 |  IPIP   |    |  PR  |
  |          |____________________|         |____| Node |
  |44.0.0.0/8|                    | Gateway |    |      |
  |          |y.y.y.y      x.x.x.x|         |    |      |
  |          |                    |         |    \______/
  |          |                    |         |
  \__________/                    \_________/

The configuration file for this example is the following:

# /etc/rc.d/rc.tunnel
# This file is a simple configuration that provides the IPIP encapsulation,
# commonly used when utilising the ampr.org (44.0.0.0/8) routing via UCSD.
# The script is located on IPIP gateway with eth0 interface, connected directly
# to the internet and other (e.g. sl0) interface, connected to packet radio
# subnet, e.g. 44.177.155/24.
#
IP_eth0=x.x.x.x
IP_eth1=y.y.y.y
echo "  Configuring:"
#
ip tunnel add ucsd remote $IP_eth1 mode ipip
# 'ucsd' is (any suitable) tunnel name
ifconfig ucsd $IP_eth0 up
# tunnel initialisation
ip route add 44/8 dev ucsd via $IP_eth1 onlink
# tells that tunnel should be used when sending packets to ampr.org network
# onlink is the magic word, do not forget
echo " done."
#
# end.

In any case, the tunnel must be set up on both sides of the route. The tunnelling interface configured above is used for both encapsulation and decapsulation. However, the same principle can be used for one of those tasks, exclusively. When needed, the standard routing (via UCSD), used in previous example, can be avoided by setting the IPIP tunneling between two PR stations, where only one of them has its own internet (public) non-ampr IP address. The task is then to set up the one-way IPIP tunnel, to achieve a quicker and more stable route from non-ampr IP address to ampr IP address station. In this case, the setup, mentioned above, is used for encapsulation. The other side of the route can leave out the route setting, due to its pure decapsulation task.

22.3. AXIP encapsulated gateway configuration

Many Amateur Radio Internet gateways encapsulate AX.25, NET/ROM and ROSE in addition to tcp/ip. Encapsulation of AX.25 frames within IP datagrams is described in RFC-1226 by Brian Kantor. Mike Westerhof wrote an implementation of an AX.25 encapsulation daemon for UNIX in 1991. The ax25-utils package includes a marginally enhanced version of it for Linux.

An AXIP encapsulation program accepts AX.25 frames at one end, looks at the destination AX.25 address to determine what IP address to send them to, encapsulates them in a tcp/ip datagram and then transmits them to the appropriate remote destination. It also accepts tcp/ip datagrams that contain AX.25 frames, unwraps them and processes them as if it had received them directly from an AX.25 port. To distinguish IP datagrams containing AX.25 frames from other IP datagrams which don't, AXIP datagrams are coded with a protocol id of 4 (or 94 which is now deprecated). This process is described in RFC-1226.

The ax25ipd program included in the ax25-utils package presents itself as a program supporting a KISS interface across which you pass AX.25 frames, and an interface into the tcp/ip protocols. It is configured with a single configuration file called /etc/ax25/ax25ipd.conf.

#
# ax25ipd configuration file for station floyd.vk5xxx.ampr.org
#
# Select axip transport. 'ip' is what you want for compatibility
# with most other gateways.
#
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/ttyq0
#
# 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 AX.25 frame trace
# loglevel 4 - all events
# log 0 for the moment, syslog not working yet ...
#
loglevel 2
#
# If we are in digi mode, we might have a real tnc here, so use param to
# set the tnc parameters ...
#
#param 1 20
#
# Broadcast Address definition. Any of the addresses listed will be forwarded
# to any of the routes flagged as broadcast capable routes.
#
broadcast QST-0 NODES-0
#
# ax.25 route definition, define as many as you need.
# format is route (call/wildcard) (ip host at destination)
# ssid of 0 routes all ssid's
#
# route <destcall> <destaddr> [flags]
#
# Valid flags are:
#         b  - allow broadcasts to be transmitted via this route
#         d  - this route is the default route
#
route vk2sut-0 44.136.8.68 b
route vk5xxx 44.136.188.221 b
route vk2abc 44.1.1.1
#
#

22.4. Linking NOS and Linux using a pipe device

Many people like to run some version of NOS under Linux because it has all of the features and facilities they are used to. Most of those people would also like to have the NOS running on their machine capable of talking to the Linux kernel so that they can offer some of the linux capabilities to radio users via NOS.

Brandon S. Allbery, KF8NH, contributed the following information to explain how to interconnect the NOS running on a Linux machine with the kernel code using the Linux pipe device.

Since both Linux and NOS support the slip protocol it is possible to link the two together by creating a slip link. You could do this by using two serial ports with a loopback cable between them, but this would be slow and costly. Linux provides a feature that many other Unix-like operating systems provide called `pipes'. These are special pseudo devices that look like a standard tty device to software but in fact loopback to another pipe device. To use these pipes the first program must open the master end of the pipe, and the open then the second program can open the slave end of the pipe. When both ends are open the programs can communicate with each other simply by writing characters to the pipes in the way they would if they were terminal devices.

To use this feature to connect the Linux Kernel and a copy of NOS, or some other program you first must choose a pipe device to use. You can find one by looking in your /dev directory. The master end of the pipes are named: ptyq[1-f] and the slave end of the pipes are known as: ttyq[1-f]. Remember they come in pairs, so if you select /dev/ptyqf as your master end then you must use /dev/ttyqf as the slave end.

Once you have chosen a pipe device pair to use you should allocate the master end to you linux kernel and the slave end to the NOS program, as the Linux kernel starts first and the master end of the pipe must be opened first. You must also remember that your Linux kernel must have a different IP address to your NOS, so you will need to allocate a unique address for it if you haven't already.

You configure the pipe just as if it were a serial device, so to create the slip link from your linux kernel you can use commands similar to the following:

# /sbin/slattach -s 38400 -p slip /dev/ptyqf &
# /sbin/ifconfig sl0 broadcast 44.255.255.255 pointopoint 44.70.248.67 /
	mtu 1536 44.70.4.88
# /sbin/route add 44.70.248.67 sl0
# /sbin/route add -net 44.0.0.0 netmask 255.0.0.0 gw 44.70.248.67

In this example the Linux kernel has been given IP address 44.70.4.88 and the NOS program is using IP address 44.70.248.67. The route command in the last line simply tells your linux kernel to route all datagrams for the amprnet via the slip link created by the slattach command. Normally you would put these commands into your /etc/rc.d/rc.inet2 file after all your other network configuration is complete so that the slip link is created automatically when you reboot. Note: there is no advantage in using cslip instead of slip as it actually reduces performance because the link is only a virtual one and occurs fast enough that having to compress the headers first takes longer than transmitting the uncompressed datagram.

To configure the NOS end of the link you could try the following:

# you can call the interface anything you want; I use "linux" for convenience.
attach asy ttyqf - slip linux 1024 1024 38400
route addprivate 44.70.4.88 linux

These commands will create a slip port named `linux' via the slave end of the pipe device pair to your linux kernel, and a route to it to make it work. When you have started NOS you should be able to ping and telnet to your NOS from your Linux machine and vice versa. If not, double check that you have made no mistakes especially that you have the addresses configured properly and have the pipe devices around the right way.

24.1. Packet Radio

You can get general information about Packet Radio from these sites:

• American Radio Relay League

• Radio Amateur Teleprinter Society

• Tucson Amateur Packet Radio Group

24.2. Protocol Documentation

• AX.25, NET/ROM - Jonathon Naylor has collated a variety of documents that relate to the packet radio protocols themselves. This documentation has been packaged up into ax25-doc-1.0.tar.gz

24.3. Hardware Documentation

• Information on the PI2 Card is provided by the Ottawa Packet Radio Group.

• Information on Baycom hardware is available at the Baycom Web Page.

24.4. Linux Ham Radio Software

John Ackermann has a web site with information related to configuring AX.25 on Linux at http://www.febo.com/linux-ax25/index.html.

The Hamsoft Linux Ham Radio Applications and Utilities Database attempts to maintain a complete list of Amateur Radio related applications for Linux. It can be found at http://radio.linux.org.au.