1APRSDIGI(8) System Manager's Manual APRSDIGI(8)
2
6 aprsdigi - APRS(™) digipeater
7
9 aprsdigi options
10
12 Aprsdigi is a specialized Amateur Packet Radio (AX.25) UI-frame digi‐
13 peater for the Automatic Position Reporting Systems, APRS(tm). It uses
14 the Linux kernel AX.25 network stack as well as the SOCK_PACKET facil‐
15 ity to listen for packets on one or more radio interfaces (ports) and
16 repeat those packets -- with several possible modifications -- on the
17 same or other interfaces. Aprsdigi can also use the Internet to tunnel
18 connections among other APRS digipeaters and nodes using IPv4 or IPv6
19 UDP unicast or multicast.
20 Aprsdigi implements conventional packet radio AX.25 digipeating, in
22 which a packet is digipeated if the next hop (non-repeated) digipeater
23 ("via") callsign matches the AX.25 port's callsign and sub-station ID
24 (SSID) or an alias callsign and SSID.
25 There are a number of extensions to conventional digipeating that have
27 been proposed for use in the APRS community. Some of these features
28 have been adopted by Terminal Node Controller (TNC) manufacturers,
29 notably Paccomm and Kantronics. Aprsdigi implements most if not all of
30 the commercialy adopted and proposed features. See the APRS 1.0 Proto‐
31 col Specification at www.tapr.org for protocol documentation. Aprsdigi
32 attempts to minimally comply with the protocol specification as well as
33 support experimental APRS features. Specific features implemented
34 include:
35 · Single-interface conventional UI-frame digipeating.
37 · Cross-interface digipeating (also known as bridging, routing or gate‐
39 waying) and one-to-many fanout.
40 · Substitution of a digipeated alias with the interface's callsign
42 (typically used to substitute RELAY, WIDE or TRACE aliases).
43 · WIDEn-n flooding algorithim.
45 · TRACEn-n route recording.
47 · Mic-Encoder(tm) support, including SSID-based digipeating, decompres‐
49 sion of packets into the conventional APRS MIM format. (The Mic-
50 Encoder compression is also used by other products such as the Ken‐
51 wood TH-D7A and D700, and TAPR PIC-Encoder).
52 · TheNet X1J4 node beacon text translation (removal of the “TheNet X1J4
54 (alias)” prefix from the btext).
55
57 -v --verbose
58 Produce verbose debugging output.
59 -T --testing
61 Test mode: listen to my packets too. This mode is useful for
62 off-air experimentation and configuration testing. Do not
63 use it on-air.
64 -D --kill_dupes
66 Suppress Duplicate packets. Remembers duplicate packets for
67 the number of seconds given by the -k option and will not
68 repeat them more than once. This reduces conjestion caused
69 when several digipeaters that share a common flooding alias
70 (e.g. WIDE) have overlapping footprints, causing geometric
71 duplication of packets addressed via “WIDE,WIDE” for example.
72 -L --kill_loops
74 Suppress Looping packets. Similar in function to duplicate
75 packet suppression, but looks back through the list of
76 already digipeated callsigns in the packet's digipeat list
77 and kills any packets that list a callsign belonging to this
78 aprsdigi. Note that only real callsigns are compared.
79 Generic flooding aliases are not. Therefore, loop detection
80 is only useful when callsign substitution is used.
81 -V --version
83 Print program version and exit.
84 -n|s|e|w --north|south|east|west
86 Set North|South|East|West SSID directional path.
87 -d --digipath
89 Set SSID omnidirectional next-hops when operating in a non
90 flooding network (e.g. when WIDEn-n is not an option).
91 -f --flood
93 Set flooding alias. Use “-f WIDE” to enable WIDEn-n flood‐
94 ing. Use -f multiple times to define several flooding
95 aliases.
96 -F --trace
98 Set flooding trace callsign. Use “-F TRACE” to enable TRACE
99 and TRACEn-n flooding. Use -F multiple times to define sev‐
100 eral trace aliases.
101 -k --keep secs
103 Remember old packets for this long for duplicate packet
104 detection. Default is 28 seconds.
105 -l --logfile file
107 Log digipeated packets to this file.
108
110 Put these options before each -p --interface to set new values as
111 needed. The values you set are remembered for subsequent -p's so
112 options you want to set for all interfaces need only be specified once,
113 before the first -p. But you have to remember to unset an option if
114 you don't want it to apply to subsequent interfaces.
115 -C (-c) --[no]subst_mycall
117 Do (not) perform callsign substitution. When enabled,
118 aliases are replaced with the interface's callsign when
119 repeated.
120 -M (-m) --[no]mice_xlate
122 Do (not) perform Mic-E to MIM translation. When enabled,
123 compressed Mic-E reports are expanded into one MIM-style
124 position report packet and optionally a second telemetry
125 packet if telemetry was supplied in the Mic-E packet.
126 -X (-x) --[no]x1j4_xlate
128 Do (not) perform X1J4 translation. When enabled, the leading
129 “TheNet X1J4 (alias)” text is removed when digipeated. This
130 allows non-compliant APRS implementations to detect an APRS
131 position report in an X1J4 beacon.
132 -i --idinterval secs
134 Seconds between ID transmissions. Set to 0 to disable IDs on
135 this interface. Default is 570 (9 minutes 30 seconds). IDs
136 are only sent if the interface transmitted anything since the
137 last ID. ID packets are addressed to the “ID” callsign, have
138 no digipeat path, and list the callsign and aliases for the
139 interface the ID is being transmitted on.
140 -t --tag text
142 Text to append to received packets. Use -t - to reset to
143 empty. Use this, for example, when gatewaying Mic-E packets
144 from a voice repeater to the APRS net frequency to indicate
145 where the report originated.
146 -3 --3rdparty
148 Enable 3rd party tunneling. Packets tunneled to a 3rd party
149 interface are sent with the unused digipeaters removed from
150 the digipeater list. Packets tunneled from a 3rd party
151 interface have the Source Path Header prepended to the packet
152 payload prefixed by the "}" character.
153 -0 --no3rdparty
155 Enable transparent tunneling. No special tricks are done when
156 sending to or receiving from a tunneled interface. If the
157 interface does not natively support AX.25 addresses (from-
158 call, to-call, and digipeater list), then the address header
159 is prepended to the payload in "cooked" format. Likewise, a
160 cooked prepended header is stripped from a cooked interface
161 and put back in the AX.25 address when going from a non-AX.25
162 to AX.25 interface.
163 -o r --norx
165 Disable receiving on the following interface(s).
166 -o R --rx Enable receiving on the following interface(s).
168 -o t --notx
170 Disable transmitting on the following interface(s).
171 -o T --tx Enable transmitting on the following interface(s).
173 -o s --notxsame
175 Disable retransmitting a received packet on the same inter‐
176 face.
177 -o S --txsame
179 Enable retransmitting a received packet on the same inter‐
180 face.
181 -o d --duplicate intf
183 Duplicate received packets without modification to the given
184 interface (port).
185 -p --interface ax25:port:alias1,alias2,...
187 AX25 interface name (port) and optional list of aliases. The
188 primary callsign is obtained from the interface's configura‐
189 tion. (See ifconfig(8)).
190 -p --interface udp:host/port/ttl:alias1,alias2,...
192 IP host name or address and list of aliases. IP addresses
193 may be IPv4 unicast or multicast or IPv6 unicast. The pri‐
194 mary callsign is obtained from the first alias.
195 -p --interface unix:filename:alias1,alias2,...
197 Unix file and list of aliases. Useful for debugging by set‐
198 ting up a simulated APRS network on one machine. You may
199 want to make your FIFOs explicitly transmit- or receive-only
200 to avoid confusion. The primary callsign is obtained from
201 the first alias.
202 -B|b --[no]bud
204 addr Is similar to a TNC-2's BUDLIST. Use -B --bud to accept
205 or -b --nobud to ignore packets from a sender or group of
206 senders. Budlists are attached to each interface and can be
207 reset with --bud -
208 You can set up a global budlist once, or per-interface
209 budlists. The format of addr varies based on the interface
210 type:
211 --bud ax25:callsign-ssid matches only a given digipeater callsign and
213 SSID. For example, -B ax25:n0clu-14.
214 --bud ax25:callsign matches all SSIDs for the given callsign. For
216 example -B ax25:n0clu.
217 --bud ip:hostname matches one Internet host name (IPv6 or IPv4). For
219 example -B ip:n0clu.ampr.net
220 --bud ip:address/maskbits matches all IP addresses that have the given
222 prefix. For example --bud ip:44.0.0.0/8 matches the entire
223 class-A network. --bud ip:192.168.0.0/16 matches the entire
224 class-B network. --bud ip:fe80::201:3ff:fe9a:38c6 matches a
225 single IPv6 host. --bud ip:2002:905::/32 matches the 32-bit
226 IPv6 prefix.
227
229 aprsdigi responds to the following signals:
230 SIGUSR1 Print cumulative statistics. For each port, the following
232 counters are displayed: packets received and how many of
233 those where ignored, duplicates, loops, mic-E formatted;
234 packets transmitted and how many of those where conventional
235 digipeats, flooding digipeats (WIDEn-n), SSID-based digi‐
236 peats, and IDs. If a log file was specified with the -l
237 --logfile option, then the statistics are written to that
238 file. Otherwise they are written to stderr.
239 SIGUSR2 Prints the statistics and then resets all counters to zero.
242 All other normal termination signals cause final statistics to print
244 before aprsdigi exits.
245
248 SSID-based routing uses a non-zero sub-station ID in the destination
249 callsign, an empty digipeater path to indicate that the APRS digipeater
250 should repeat the packet after filling in an appropriate digipeater
251 path. For example, a packet sent to “T1QS4W-3” would be repeated with
252 a modifed destination of “APRS VIA WIDE3-3” (in a network that supports
253 WIDEn-n flooding). A packet sent to “APRS-11” would be repeated to the
254 West unproto path, as defined with the --west option. A table of SSID
255 values and their paths follows:
256 SSID unproto path
258 ---- ------------
259 0 none
260 1 WIDE1-1
261 2 WIDE2-2
262 3 WIDE3-3
263 4 WIDE4-4
264 5 WIDE5-5
265 6 WIDE6-6
266 7 WIDE7-7
267 8 NORTH UNPROTO path
268 9 SOUTH UNPROTO path
269 10 EAST UNPROTO path
270 11 WEST UNPROTO path
271 12 NORTH UNPROTO path + WIDE
272 13 SOUTH UNPROTO path + WIDE
273 14 EAST UNPROTO path + WIDE
274 15 WEST UNPROTO path + WIDE
275 SSID digipeating was first introduced with the Mic-Encoder but works
277 with any destination callsign with a non-zero SSID. The theory behind
278 destination SSID digipeating is described in more detail in the APRSdos
279 README, MIC-E.TXT. Basically, the idea is to minimize packet lengths
280 and to have the manager of the WIDE APRS digipeater determine the most
281 appropriate directional digipeat paths, removing the burden from the
282 mobile user.
283 Aprsdigi also fits into a non WIDEn-n network by using the same algo‐
285 rithm for selection of subset of digipeaters from a list supplied with
286 the --digipath option as the MIC-E. That is, SSIDs of 1, 2 or 3 select
287 that number of digipeaters from the first three digipeaters in the
288 --digipath list. SSIDs of 4, 5, 6, or 7, start at the fourth digi‐
289 peater in the list.
290
292 APRS flooding (WIDEn-n) digipeating works by repeating any received
293 packet whose next hop digipeater has a flooding alias (specified with
294 the --flood option), and the SSID is 1 or greater. The SSID is decre‐
295 mented by one, and the packet is repeated. Furthermore, to prevent
296 broadcast storms, recently transmitted packets are remembered for a
297 period of time specified by the --keep option and are not repeated if
298 they are heard within that time period.
299 Unlike conventional digipeating, in which the digipeater callsign/alias
301 is flagged as “repeated”, the flooding mode does not do this. Once the
302 SSID decrements to zero, then a flooding alias is treated just like any
303 other alias, and does get marked as repeated upon transmission.
304
306 “Flooding” Trace aliases (TRACEn-n; --trace option) are treated like
307 flooding aliases with the addition that, besides decrementing the SSID,
308 the current interface's callsign is inserted in front of the trace
309 alias, providing a record-route function. “Plain” trace aliases
310 (TRACE; also --trace option) are simply substituted in the conventional
311 ( --subst_mycall ) manner.
312
314 In single port operation, there is only one interface specified with
315 --interface. All packets are received and some are retransmitted on
316 the same interface, depending on whether they match the criteria for
317 retransmission after translation of the digpeater path from one of the
318 APRS-specific formats:
319 · Mic-E TO-call SSID-based route.
321 · WIDEn-n/TRACEn-n flooding.
323 or a conventional next-hop (non-repeated) digipeater matching the call‐
325 sign or one of the aliases for the interface.
326 The decision to transmit is made by matching the next hop call‐
328 sign/alias with the table of callsigns and aliases you supply to
329 --interface.
330 In multi-port operation, this same technique simply extends to several
332 interfaces. Besides each interface's unique callsign, you can give the
333 same alias to several interfaces. This results in a one-to-many fanout
334 which might be useful for dual frequency operation such as a general
335 use APRS net frequency and an event-specific frequency.
336 By using different flags for Mic-E expansions, etc. you can tailor
338 these fanouts differently on each of these interfaces, perhaps keeping
339 Mic-E packets compressed on one frequency while decompressing them on
340 another.
341
343 The --dupe intf option will duplicate a packet received on one inter‐
344 face to the interface name given. If you want to duplicate to several
345 other interface, repeat --dupe intf for each interface. The packet is
346 duplicated verbatim as received. No callsign substitution, flooding or
347 other processing or checking such as whether the packet still has any
348 non-repeated digipeaters in the list is checked. This feature is meant
349 to provide a means to simply repeat received packets verbatim, on an RF
350 interface, for example, out an interface that might be an Ethernet,
351 that has APRS client applications running on it (or aprsd listening on
352 a UDP interface). Digipeating without the normal processing can be
353 dangerous since the digipeater list is never used up. Because of this,
354 packets received on a given interface will never be blindly duplicated
355 back to the same interface, regardless of the option setting.
356
358 Note that TRACEn-n vs. plain TRACE do different things: TRACEn-n
359 *inserts* calls into the digipath while decrementing ssid, e.g.:
360 RELAY*,TRACE3-3
361 RELAY,N2YGK-7*,TRACE3-2
362 RELAY,N2YGK-7,WB2ZII*,TRACE3-1
363 RELAY,N2YGK-7,WB2ZII,N2MH-15*,TRACE3
364 RELAY,N2YGK-7,WB2ZII,N2MH-15,WA2YSM-14*
365
367 Kill looping packets (--kill_loops option):
368 RELAY*,WIDE,WIDE,WIDE
369 RELAY,N2YGK-7*,WIDE,WIDE
370 RELAY,N2YGK-7,WIDE*,WIDE
371 Normally n2ygk-7 would respond to this, but, by finding one of mycall
372 earlier in the path, I know to ignore it.
373
375 Following is a sample invocation of aprsdigi running on two ports.
376 This is a contrived example that tries to show all the features. Com‐
377 ments to the right describe each feature.
378 aprsdigi \
379 --verbose \ # verbose
380 --north "N2YGK-2 WB2ZII WA2YSM-14" \ # North digi path
381 --south "N2YGK-3 WB2ZII WA2JNF-4" \ # South ...
382 --east "N2YGK-3 WB2ZII KD1LY" \ # East ...
383 --west "N2YGK-2 WB2ZII N2MH-15" \ # West ...
384 --flood "WIDE" \ # WIDEn-n flooding
385 --trace "TRACE" \ # TRACEn-n tracing
386 --kill_dupes \ # kill dupes
387 --kill_loops \ # kill loops
388 --mice_xlate \ # do Mic-E translation
389 --subst_mycall \ # do callsign substituton
390 --tag " via 147.06 (WB2ZII/R)" \ # add this tag to rec'd pkts
391 --nobud "ax25:NOCALL" \ # ignore pkts from NOCALL
392 --dupe udp:233.0.14.100 \ # dupe everything heard
393 --int ax25:sm0:RELAY,WIDE,TRACE \ # ax25 soundmodem intf
394 --nomice_xlate \ # turn off Mic-E translation
395 --x1j4_xlate \ # do X1J4 translation
396 --nosubst_mycall \ # turn off callsign subst.
397 --tag - \ # clear the tag
398 --int ax25:ax0:RELAY,WIDE,FOO,TRACE \ # ax25 ax0 intf.
399 --bud - \ # clear the budlist
400 --bud ip:128.59.39.150/32 \ # allow only from this IP host
401 --int udp:233.0.14.99/12345/16:N2YGK-4,RELAY,WIDE,TRACE \ # multicast
402 --int udp:233.0.14.100/12345/16:N2YGK-5 # to this mcast group
403 opening UDP socket on 233.0.14.99/12345/16
405 UDP address info: family 2 type 2 proto 17 next 0x0
406 Linux APRS(tm) digipeater
407 Copyright (c) 1996,1997,1999,2001,2002,2003 Alan Crosswell, n2ygk@weca.org
408 Version: aprsdigi aprsdigi-2.4.3
409 This is free software covered under the GNU Public License.
410 There is no warranty. See the file COPYING for details.
411 # configuration:
413 budlist 1 deny NOCALL/48
414 budlist 2 permit 128.59.39.150/32
415 interface ax25:sm0
416 callsign N2YGK-2
417 alias RELAY
418 alias WIDE
419 alias TRACE
420 option SUBST_MYCALL on
421 option MICE_XLATE on
422 option X1J4_XLATE off
423 option I_TX on
424 option I_RX on
425 option I_TXSAME on
426 option idinterval 570 #(09:30)
427 option tag via 147.06 (WB2ZII/R)
428 budlist 1
429 interface ax25:ax0
430 callsign N2YGK-3
431 alias RELAY
432 alias WIDE
433 alias FOO
434 option SUBST_MYCALL off
435 option MICE_XLATE off
436 option X1J4_XLATE on
437 option I_TX on
438 option I_RX on
439 option I_TXSAME on
440 option idinterval 570 #(09:30)
441 option tag #(none)
442 budlist 2
443 interface udp:233.0.14.99
444 callsign N2YGK-4
445 alias RELAY
446 alias WIDE
447 alias FOO
448 option SUBST_MYCALL off
449 option MICE_XLATE off
450 option X1J4_XLATE on
451 option I_TX on
452 option I_RX on
453 option I_TXSAME off
454 option idinterval 570 #(09:30)
455 option tag #(none)
456 budlist 2
457 # end of configuration
458 My callsigns and aliases (routing table):
460 Callsign Interfaces...
461 N2YGK-2 sm0
462 RELAY sm0 ax0 233.0.14.99
463 WIDEn-n sm0 ax0 233.0.14.99
464 TRACEn-n sm0
465 N2YGK-3 ax0
466 FOO ax0 233.0.14.99
467 N2YGK-4 233.0.14.99
468 SSID-based directional routing:
469 N: N2YGK-2 WB2ZII WA2YSM-14
471 S: N2YGK-3 WB2ZII WA2JNF-4
472 E: N2YGK-3 WB2ZII KD1LY
473 W: N2YGK-2 WB2ZII N2MH-15
474 keep dupes for: 28 seconds
475 log file: (none)
476 kill dupes: ON loops: ON testing: OFF
477
480 Aprsdigi should not be confused with a Wes Johnson's DOS program of the
481 same name. This code has most recently been tested with the Linux
482 2.4.20 kernel under Red Hat Fedora Core 1. The command line syntax is
483 ugly and will eventually be replaced by a configuration file. Short
484 options are deprecated and will dissappear in a future release. Please
485 use long options.
486
488 /etc/ax25/axports
489
491 call(1), listen(1), beacon(1), ax25(4), kissattach(8), ifconfig(8),
492 aprsmon(1), http://www.tapr.org
493
495 Alan Crosswell, n2ygk@weca.org
496 APRS and the Mic-Encoder are Trademarks of APRS Engineering LLC.
497 25 February 2004 APRSDIGI(8)