NAME
aprsdigi - APRS(™) digipeater
SYNOPSIS
aprsdigi options
DESCRIPTION
Aprsdigi is a specialized Amateur Packet Radio (AX.25) UI-frame
digipeater for the Automatic Position Reporting Systems, APRS(tm). It
uses the Linux kernel AX.25 network stack as well as the SOCK_PACKET
facility to listen for packets on one or more radio interfaces (ports)
and repeat those packets -- with several possible modifications -- on
the same or other interfaces. Aprsdigi can also use the Internet to
tunnel connections among other APRS digipeaters and nodes using IPv4 or
IPv6 UDP unicast or multicast.
Aprsdigi implements conventional packet radio AX.25 digipeating, in
which a packet is digipeated if the next hop (non-repeated) digipeater
("via") callsign matches the AX.25 port’s callsign and sub-station ID
(SSID) or an alias callsign and SSID.
There are a number of extensions to conventional digipeating that have
been proposed for use in the APRS community. Some of these features
have been adopted by Terminal Node Controller (TNC) manufacturers,
notably Paccomm and Kantronics. Aprsdigi implements most if not all of
the commercialy adopted and proposed features. See the APRS 1.0
Protocol Specification at www.tapr.org for protocol documentation.
Aprsdigi attempts to minimally comply with the protocol specification
as well as support experimental APRS features. Specific features
implemented include:
· Single-interface conventional UI-frame digipeating.
· Cross-interface digipeating (also known as bridging, routing or
gatewaying) and one-to-many fanout.
· Substitution of a digipeated alias with the interface’s callsign
(typically used to substitute RELAY, WIDE or TRACE aliases).
· WIDEn-n flooding algorithim.
· TRACEn-n route recording.
· Mic-Encoder(tm) support, including SSID-based digipeating,
decompression of packets into the conventional APRS MIM format. (The
Mic-Encoder compression is also used by other products such as the
Kenwood TH-D7A and D700, and TAPR PIC-Encoder).
· TheNet X1J4 node beacon text translation (removal of the “TheNet X1J4
(alias)” prefix from the btext).
GENERAL OPTIONS
-v --verbose
Produce verbose debugging output.
-T --testing
Test mode: listen to my packets too. This mode is useful for
off-air experimentation and configuration testing. Do not
use it on-air.
-D --kill_dupes
Suppress Duplicate packets. Remembers duplicate packets for
the number of seconds given by the -k option and will not
repeat them more than once. This reduces conjestion caused
when several digipeaters that share a common flooding alias
(e.g. WIDE) have overlapping footprints, causing geometric
duplication of packets addressed via “WIDE,WIDE” for example.
-L --kill_loops
Suppress Looping packets. Similar in function to duplicate
packet suppression, but looks back through the list of
already digipeated callsigns in the packet’s digipeat list
and kills any packets that list a callsign belonging to this
aprsdigi. Note that only real callsigns are compared.
Generic flooding aliases are not. Therefore, loop detection
is only useful when callsign substitution is used.
-V --version
Print program version and exit.
-n|s|e|w --north|south|east|west
Set North|South|East|West SSID directional path.
-d --digipath
Set SSID omnidirectional next-hops when operating in a non
flooding network (e.g. when WIDEn-n is not an option).
-f --flood
Set flooding alias. Use “-f WIDE” to enable WIDEn-n
flooding. Use -f multiple times to define several flooding
aliases.
-F --trace
Set flooding trace callsign. Use “-F TRACE” to enable TRACE
and TRACEn-n flooding. Use -F multiple times to define
several trace aliases.
-k --keep secs
Remember old packets for this long for duplicate packet
detection. Default is 28 seconds.
-l --logfile file
Log digipeated packets to this file.
PER-INTERFACE OPTIONS
Put these options before each -p --interface to set new values as
needed. The values you set are remembered for subsequent -p’s so
options you want to set for all interfaces need only be specified once,
before the first -p. But you have to remember to unset an option if
you don’t want it to apply to subsequent interfaces.
-C (-c) --[no]subst_mycall
Do (not) perform callsign substitution. When enabled,
aliases are replaced with the interface’s callsign when
repeated.
-M (-m) --[no]mice_xlate
Do (not) perform Mic-E to MIM translation. When enabled,
compressed Mic-E reports are expanded into one MIM-style
position report packet and optionally a second telemetry
packet if telemetry was supplied in the Mic-E packet.
-X (-x) --[no]x1j4_xlate
Do (not) perform X1J4 translation. When enabled, the leading
“TheNet X1J4 (alias)” text is removed when digipeated. This
allows non-compliant APRS implementations to detect an APRS
position report in an X1J4 beacon.
-i --idinterval secs
Seconds between ID transmissions. Set to 0 to disable IDs on
this interface. Default is 570 (9 minutes 30 seconds). IDs
are only sent if the interface transmitted anything since the
last ID. ID packets are addressed to the “ID” callsign, have
no digipeat path, and list the callsign and aliases for the
interface the ID is being transmitted on.
-t --tag text
Text to append to received packets. Use -t - to reset to
empty. Use this, for example, when gatewaying Mic-E packets
from a voice repeater to the APRS net frequency to indicate
where the report originated.
-3 --3rdparty
Enable 3rd party tunneling. Packets tunneled to a 3rd party
interface are sent with the unused digipeaters removed from
the digipeater list. Packets tunneled from a 3rd party
interface have the Source Path Header prepended to the packet
payload prefixed by the "}" character.
-0 --no3rdparty
Enable transparent tunneling. No special tricks are done when
sending to or receiving from a tunneled interface. If the
interface does not natively support AX.25 addresses (from-
call, to-call, and digipeater list), then the address header
is prepended to the payload in "cooked" format. Likewise, a
cooked prepended header is stripped from a cooked interface
and put back in the AX.25 address when going from a non-AX.25
to AX.25 interface.
-o r --norx
Disable receiving on the following interface(s).
-o R --rx Enable receiving on the following interface(s).
-o t --notx
Disable transmitting on the following interface(s).
-o T --tx Enable transmitting on the following interface(s).
-o s --notxsame
Disable retransmitting a received packet on the same
interface.
-o S --txsame
Enable retransmitting a received packet on the same
interface.
-o d --duplicate intf
Duplicate received packets without modification to the given
interface (port).
-p --interface ax25:port:alias1,alias2,...
AX25 interface name (port) and optional list of aliases. The
primary callsign is obtained from the interface’s
configuration. (See ifconfig(8)).
-p --interface udp:host/port/ttl:alias1,alias2,...
IP host name or address and list of aliases. IP addresses
may be IPv4 unicast or multicast or IPv6 unicast. The
primary callsign is obtained from the first alias.
-p --interface unix:filename:alias1,alias2,...
Unix file and list of aliases. Useful for debugging by
setting up a simulated APRS network on one machine. You may
want to make your FIFOs explicitly transmit- or receive-only
to avoid confusion. The primary callsign is obtained from
the first alias.
-B|b --[no]bud
addr Is similar to a TNC-2’s BUDLIST. Use -B --bud to accept
or -b --nobud to ignore packets from a sender or group of
senders. Budlists are attached to each interface and can be
reset with --bud -
You can set up a global budlist once, or per-interface
budlists. The format of addr varies based on the interface
type:
--bud ax25:callsign-ssid matches only a given digipeater callsign and
SSID. For example, -B ax25:n0clu-14.
--bud ax25:callsign matches all SSIDs for the given callsign. For
example -B ax25:n0clu.
--bud ip:hostname matches one Internet host name (IPv6 or IPv4). For
example -B ip:n0clu.ampr.net
--bud ip:address/maskbits matches all IP addresses that have the given
prefix. For example --bud ip:44.0.0.0/8 matches the entire
class-A network. --bud ip:192.168.0.0/16 matches the entire
class-B network. --bud ip:fe80::201:3ff:fe9a:38c6 matches a
single IPv6 host. --bud ip:2002:905::/32 matches the 32-bit
IPv6 prefix.
RUNTIME CONTROLS
aprsdigi responds to the following signals:
SIGUSR1 Print cumulative statistics. For each port, the following
counters are displayed: packets received and how many of
those where ignored, duplicates, loops, mic-E formatted;
packets transmitted and how many of those where conventional
digipeats, flooding digipeats (WIDEn-n), SSID-based
digipeats, and IDs. If a log file was specified with the -l
--logfile option, then the statistics are written to that
file. Otherwise they are written to stderr.
SIGUSR2 Prints the statistics and then resets all counters to zero.
All other normal termination signals cause final statistics to print
before aprsdigi exits.
SSID-BASED ROUTING
SSID-based routing uses a non-zero sub-station ID in the destination
callsign, an empty digipeater path to indicate that the APRS digipeater
should repeat the packet after filling in an appropriate digipeater
path. For example, a packet sent to “T1QS4W-3” would be repeated with
a modifed destination of “APRS VIA WIDE3-3” (in a network that supports
WIDEn-n flooding). A packet sent to “APRS-11” would be repeated to the
West unproto path, as defined with the --west option. A table of SSID
values and their paths follows:
SSID unproto path
---- ------------
0 none
1 WIDE1-1
2 WIDE2-2
3 WIDE3-3
4 WIDE4-4
5 WIDE5-5
6 WIDE6-6
7 WIDE7-7
8 NORTH UNPROTO path
9 SOUTH UNPROTO path
10 EAST UNPROTO path
11 WEST UNPROTO path
12 NORTH UNPROTO path + WIDE
13 SOUTH UNPROTO path + WIDE
14 EAST UNPROTO path + WIDE
15 WEST UNPROTO path + WIDE
SSID digipeating was first introduced with the Mic-Encoder but works
with any destination callsign with a non-zero SSID. The theory behind
destination SSID digipeating is described in more detail in the APRSdos
README, MIC-E.TXT. Basically, the idea is to minimize packet lengths
and to have the manager of the WIDE APRS digipeater determine the most
appropriate directional digipeat paths, removing the burden from the
mobile user.
Aprsdigi also fits into a non WIDEn-n network by using the same
algorithm for selection of subset of digipeaters from a list supplied
with the --digipath option as the MIC-E. That is, SSIDs of 1, 2 or 3
select that number of digipeaters from the first three digipeaters in
the --digipath list. SSIDs of 4, 5, 6, or 7, start at the fourth
digipeater in the list.
FLOODING ALIASES
APRS flooding (WIDEn-n) digipeating works by repeating any received
packet whose next hop digipeater has a flooding alias (specified with
the --flood option), and the SSID is 1 or greater. The SSID is
decremented by one, and the packet is repeated. Furthermore, to
prevent broadcast storms, recently transmitted packets are remembered
for a period of time specified by the --keep option and are not
repeated if they are heard within that time period.
Unlike conventional digipeating, in which the digipeater callsign/alias
is flagged as “repeated”, the flooding mode does not do this. Once the
SSID decrements to zero, then a flooding alias is treated just like any
other alias, and does get marked as repeated upon transmission.
TRACE and TRACEn-n ALIASES
“Flooding” Trace aliases (TRACEn-n; --trace option) are treated like
flooding aliases with the addition that, besides decrementing the SSID,
the current interface’s callsign is inserted in front of the trace
alias, providing a record-route function. “Plain” trace aliases
(TRACE; also --trace option) are simply substituted in the conventional
( --subst_mycall ) manner.
MULTI PORT OPERATION
In single port operation, there is only one interface specified with
--interface. All packets are received and some are retransmitted on
the same interface, depending on whether they match the criteria for
retransmission after translation of the digpeater path from one of the
APRS-specific formats:
· Mic-E TO-call SSID-based route.
· WIDEn-n/TRACEn-n flooding.
or a conventional next-hop (non-repeated) digipeater matching the
callsign or one of the aliases for the interface.
The decision to transmit is made by matching the next hop
callsign/alias with the table of callsigns and aliases you supply to
--interface.
In multi-port operation, this same technique simply extends to several
interfaces. Besides each interface’s unique callsign, you can give the
same alias to several interfaces. This results in a one-to-many fanout
which might be useful for dual frequency operation such as a general
use APRS net frequency and an event-specific frequency.
By using different flags for Mic-E expansions, etc. you can tailor
these fanouts differently on each of these interfaces, perhaps keeping
Mic-E packets compressed on one frequency while decompressing them on
another.
DUPLICATING PACKETS
The --dupe intf option will duplicate a packet received on one
interface to the interface name given. If you want to duplicate to
several other interface, repeat --dupe intf for each interface. The
packet is duplicated verbatim as received. No callsign substitution,
flooding or other processing or checking such as whether the packet
still has any non-repeated digipeaters in the list is checked. This
feature is meant to provide a means to simply repeat received packets
verbatim, on an RF interface, for example, out an interface that might
be an Ethernet, that has APRS client applications running on it (or
aprsd listening on a UDP interface). Digipeating without the normal
processing can be dangerous since the digipeater list is never used up.
Because of this, packets received on a given interface will never be
blindly duplicated back to the same interface, regardless of the option
setting.
TRACE vs. TRACEN-N
Note that TRACEn-n vs. plain TRACE do different things: TRACEn-n
*inserts* calls into the digipath while decrementing ssid, e.g.:
RELAY*,TRACE3-3
RELAY,N2YGK-7*,TRACE3-2
RELAY,N2YGK-7,WB2ZII*,TRACE3-1
RELAY,N2YGK-7,WB2ZII,N2MH-15*,TRACE3
RELAY,N2YGK-7,WB2ZII,N2MH-15,WA2YSM-14*
KILLING LOOPING PACKETS
Kill looping packets (--kill_loops option):
RELAY*,WIDE,WIDE,WIDE
RELAY,N2YGK-7*,WIDE,WIDE
RELAY,N2YGK-7,WIDE*,WIDE
Normally n2ygk-7 would respond to this, but, by finding one of mycall
earlier in the path, I know to ignore it.
EXAMPLES
Following is a sample invocation of aprsdigi running on two ports.
This is a contrived example that tries to show all the features.
Comments to the right describe each feature.
aprsdigi \
--verbose \ # verbose
--north "N2YGK-2 WB2ZII WA2YSM-14" \ # North digi path
--south "N2YGK-3 WB2ZII WA2JNF-4" \ # South ...
--east "N2YGK-3 WB2ZII KD1LY" \ # East ...
--west "N2YGK-2 WB2ZII N2MH-15" \ # West ...
--flood "WIDE" \ # WIDEn-n flooding
--trace "TRACE" \ # TRACEn-n tracing
--kill_dupes \ # kill dupes
--kill_loops \ # kill loops
--mice_xlate \ # do Mic-E translation
--subst_mycall \ # do callsign substituton
--tag " via 147.06 (WB2ZII/R)" \ # add this tag to rec’d pkts
--nobud "ax25:NOCALL" \ # ignore pkts from NOCALL
--dupe udp:233.0.14.100 \ # dupe everything heard
--int ax25:sm0:RELAY,WIDE,TRACE \ # ax25 soundmodem intf
--nomice_xlate \ # turn off Mic-E translation
--x1j4_xlate \ # do X1J4 translation
--nosubst_mycall \ # turn off callsign subst.
--tag - \ # clear the tag
--int ax25:ax0:RELAY,WIDE,FOO,TRACE \ # ax25 ax0 intf.
--bud - \ # clear the budlist
--bud ip:128.59.39.150/32 \ # allow only from this IP host
--int udp:233.0.14.99/12345/16:N2YGK-4,RELAY,WIDE,TRACE \ # multicast
--int udp:233.0.14.100/12345/16:N2YGK-5 # to this mcast group
opening UDP socket on 233.0.14.99/12345/16
UDP address info: family 2 type 2 proto 17 next 0x0
Linux APRS(tm) digipeater
Copyright (c) 1996,1997,1999,2001,2002,2003 Alan Crosswell, n2ygk@weca.org
Version: aprsdigi aprsdigi-2.4.3
This is free software covered under the GNU Public License.
There is no warranty. See the file COPYING for details.
# configuration:
budlist 1 deny NOCALL/48
budlist 2 permit 128.59.39.150/32
interface ax25:sm0
callsign N2YGK-2
alias RELAY
alias WIDE
alias TRACE
option SUBST_MYCALL on
option MICE_XLATE on
option X1J4_XLATE off
option I_TX on
option I_RX on
option I_TXSAME on
option idinterval 570 #(09:30)
option tag via 147.06 (WB2ZII/R)
budlist 1
interface ax25:ax0
callsign N2YGK-3
alias RELAY
alias WIDE
alias FOO
option SUBST_MYCALL off
option MICE_XLATE off
option X1J4_XLATE on
option I_TX on
option I_RX on
option I_TXSAME on
option idinterval 570 #(09:30)
option tag #(none)
budlist 2
interface udp:233.0.14.99
callsign N2YGK-4
alias RELAY
alias WIDE
alias FOO
option SUBST_MYCALL off
option MICE_XLATE off
option X1J4_XLATE on
option I_TX on
option I_RX on
option I_TXSAME off
option idinterval 570 #(09:30)
option tag #(none)
budlist 2
# end of configuration
My callsigns and aliases (routing table):
Callsign Interfaces...
N2YGK-2 sm0
RELAY sm0 ax0 233.0.14.99
WIDEn-n sm0 ax0 233.0.14.99
TRACEn-n sm0
N2YGK-3 ax0
FOO ax0 233.0.14.99
N2YGK-4 233.0.14.99
SSID-based directional routing:
N: N2YGK-2 WB2ZII WA2YSM-14
S: N2YGK-3 WB2ZII WA2JNF-4
E: N2YGK-3 WB2ZII KD1LY
W: N2YGK-2 WB2ZII N2MH-15
keep dupes for: 28 seconds
log file: (none)
kill dupes: ON loops: ON testing: OFF
BUGS
Aprsdigi should not be confused with a Wes Johnson’s DOS program of the
same name. This code has most recently been tested with the Linux
2.4.20 kernel under Red Hat Fedora Core 1. The command line syntax is
ugly and will eventually be replaced by a configuration file. Short
options are deprecated and will dissappear in a future release. Please
use long options.
FILES
/etc/ax25/axports
SEE ALSO
call(1), listen(1), beacon(1), ax25(4), kissattach(8), ifconfig(8),
aprsmon(1), http://www.tapr.org
AUTHORS
Alan Crosswell, n2ygk@weca.org
APRS and the Mic-Encoder are Trademarks of APRS Engineering LLC.
25 February 2004