1APRSDIGI(8)                 System Manager's Manual                APRSDIGI(8)
2
3
4

NAME

6       aprsdigi - APRS(™) digipeater
7

SYNOPSIS

9       aprsdigi options
10

DESCRIPTION

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
21       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
26       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
36       · Single-interface conventional UI-frame digipeating.
37
38       · Cross-interface digipeating (also known as bridging, routing or gate‐
39         waying) and one-to-many fanout.
40
41       · Substitution of a digipeated  alias  with  the  interface's  callsign
42         (typically used to substitute RELAY, WIDE or TRACE aliases).
43
44       · WIDEn-n flooding algorithim.
45
46       · TRACEn-n route recording.
47
48       · 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
53       · TheNet X1J4 node beacon text translation (removal of the “TheNet X1J4
54         (alias)” prefix from the btext).
55

GENERAL OPTIONS

57       -v --verbose
58                 Produce verbose debugging output.
59
60       -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
65       -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
73       -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
82       -V --version
83                 Print program version and exit.
84
85       -n|s|e|w --north|south|east|west
86                 Set North|South|East|West SSID directional path.
87
88       -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
92       -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
97       -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
102       -k --keep secs
103                 Remember  old  packets  for  this  long  for duplicate packet
104                 detection.  Default is 28 seconds.
105
106       -l --logfile file
107                 Log digipeated packets to this file.
108

PER-INTERFACE OPTIONS

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
116       -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
121       -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
127       -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
133       -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
141       -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
147       -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
154       -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
164       -o r --norx
165                 Disable receiving on the following interface(s).
166
167       -o R --rx Enable receiving on the following interface(s).
168
169       -o t --notx
170                 Disable transmitting on the following interface(s).
171
172       -o T --tx Enable transmitting on the following interface(s).
173
174       -o s --notxsame
175                 Disable  retransmitting  a received packet on the same inter‐
176                 face.
177
178       -o S --txsame
179                 Enable retransmitting a received packet on  the  same  inter‐
180                 face.
181
182       -o d --duplicate intf
183                 Duplicate  received packets without modification to the given
184                 interface (port).
185
186       -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
191       -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
196       -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
203       -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
212       --bud  ax25:callsign-ssid  matches only a given digipeater callsign and
213                 SSID.  For example, -B ax25:n0clu-14.
214
215       --bud ax25:callsign matches all SSIDs  for  the  given  callsign.   For
216                 example -B ax25:n0clu.
217
218       --bud  ip:hostname  matches one Internet host name (IPv6 or IPv4).  For
219                 example -B ip:n0clu.ampr.net
220
221       --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

RUNTIME CONTROLS

229       aprsdigi responds to the following signals:
230
231       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
240
241       SIGUSR2   Prints the statistics and then resets all counters to zero.
242
243       All other normal termination signals cause final  statistics  to  print
244       before aprsdigi exits.
245
246

SSID-BASED ROUTING

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
257       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
276       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
284       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

FLOODING ALIASES

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
300       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

TRACE and TRACEn-n ALIASES

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

MULTI PORT OPERATION

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
320       · Mic-E TO-call SSID-based route.
321
322       · WIDEn-n/TRACEn-n flooding.
323
324       or a conventional next-hop (non-repeated) digipeater matching the call‐
325       sign or one of the aliases for the interface.
326
327       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
331       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
337       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

DUPLICATING PACKETS

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

TRACE vs. TRACEN-N

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

KILLING LOOPING PACKETS

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

EXAMPLES

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
404       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
412       # 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
459       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
470       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
478

BUGS

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

FILES

488       /etc/ax25/axports
489

SEE ALSO

491       call(1), listen(1),  beacon(1),  ax25(4),  kissattach(8),  ifconfig(8),
492       aprsmon(1), http://www.tapr.org
493

AUTHORS

495       Alan Crosswell, n2ygk@weca.org
496       APRS and the Mic-Encoder are Trademarks of APRS Engineering LLC.
497
498
499
500                               25 February 2004                    APRSDIGI(8)
Impressum