File: aprsdigi.8

package info (click to toggle)
aprsdigi 2.4.4-3.2
  • links: PTS
  • area: main
  • in suites: wheezy
  • size: 576 kB
  • sloc: ansic: 3,686; sh: 765; makefile: 58
file content (566 lines) | stat: -rw-r--r-- 19,931 bytes parent folder | download | duplicates (5)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
.TH APRSDIGI 8 "25 February 2004"
.SH NAME
aprsdigi \- APRS(\*(Tm) digipeater
.SH SYNOPSIS
.nf
.BI "aprsdigi " options
.fi
.SH DESCRIPTION
.PP
.I 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. 
.I Aprsdigi
can also use the Internet to tunnel connections among other APRS digipeaters
and nodes using IPv4 or IPv6 UDP unicast or multicast.
.PP
.I 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
.I alias
callsign and SSID.
.PP
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.
.I 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.  
.I Aprsdigi
attempts to minimally comply with the protocol specification as well
as support experimental APRS features.  Specific features implemented 
include:
.PP
.IP \(bu 2
Single-interface conventional UI-frame digipeating.
.IP \(bu 2
Cross-interface digipeating (also known as bridging, routing or gatewaying)
and one-to-many fanout.
.IP \(bu 2
Substitution of a digipeated alias with the interface's callsign
(typically used to substitute
.BI RELAY,
.BI WIDE
or
.BI TRACE
aliases).
.IP \(bu 2
.BI "WIDEn-n"
flooding algorithim.
.IP \(bu 2
.BI "TRACEn-n"
route recording.
.IP \(bu 2
.I 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).
.IP \(bu 2
TheNet X1J4 node beacon text translation (removal of the  
\(lqTheNet X1J4 (alias)\(rq prefix from the btext).
.PP
.SH "GENERAL OPTIONS"
.TP 10
.BI "\-v \--verbose"
Produce verbose debugging output.
.TP 10
.BI "\-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.
.TP 10
.BI "\-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 \(lqWIDE,WIDE\(rq for example.
.TP 10
.BI "\-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 
.I aprsdigi.
Note that only real callsigns are compared.  Generic flooding aliases are not.
Therefore, loop detection is only useful when callsign substitution is used.
.TP 10
.BI "\-V \--version"
Print program version and exit.
.TP 10
.BI "\-n|s|e|w \--north|south|east|west"
Set North|South|East|West SSID directional path.
.TP 10
.BI "\-d \--digipath"
Set SSID omnidirectional next-hops when operating in a non flooding
network (e.g. when WIDEn-n is not an option).
.TP 10
.BI "\-f \--flood"
Set flooding alias.  Use \(lq-f WIDE\(rq to enable WIDEn-n flooding.
Use -f multiple times to define several flooding aliases.
.TP 10
.BI "\-F \--trace"
Set flooding trace callsign.  Use \(lq-F TRACE\(rq to enable TRACE and
TRACEn-n flooding. Use -F multiple times to define several trace aliases.
.TP 10
.BI "\-k \--keep secs"
Remember old packets for this long for duplicate packet detection.
Default is 28 seconds.
.TP 10
.BI "\-l \--logfile file"
Log digipeated packets to this file.
.SH "PER-INTERFACE OPTIONS"
Put these options
.I before
each
.BI "\-p \--interface"
to set new values as needed.  The values you set are remembered for
subsequent 
.BI "\-p's"
so options you want to set for all interfaces need only be specified
once, before the first
.BI "\-p."
But you have to remember to unset an option if you don't want it to
apply to subsequent interfaces.
.TP 10
.BI "\-C (-c) \--[no]subst_mycall"
Do (not) perform callsign substitution.  When enabled, aliases are
replaced with the interface's callsign when repeated.
.TP 10
.BI "\-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.
.TP 10
.BI "\-X (-x) \--[no]x1j4_xlate"
Do (not) perform X1J4 translation.  When enabled, the leading 
\(lqTheNet X1J4 (alias)\(rq text is removed when digipeated.  This allows
non-compliant APRS implementations to detect an APRS position report in
an X1J4 beacon.
.TP 10
.BI "\-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 
\(lqID\(rq callsign, have no digipeat path, and list the callsign and aliases
for the interface the ID is being transmitted on.
.TP 10
.BI "\-t \--tag text"
Text to append to received packets.  Use 
.I "\-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.
.TP 10
.B "\-3 \--3rdparty"
Enable 3rd party tunneling.  Packets tunneled 
.I to
a 3rd party interface are sent with the unused digipeaters removed from
the digipeater list.  Packets tunneled
.I from
a 3rd party interface have the Source Path Header prepended to the
packet payload prefixed by the "}" character.
.TP 10
.B "\-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.
.TP 10
.BI "\-o r \--norx"
Disable receiving on the following interface(s).
.TP 10
.BI "\-o R \--rx"
Enable receiving on the following interface(s).
.TP 10
.BI "\-o t \--notx"
Disable transmitting on the following interface(s).
.TP 10
.BI "\-o T \--tx"
Enable transmitting on the following interface(s).
.TP 10
.BI "\-o s \--notxsame"
Disable retransmitting a received packet on the same interface.
.TP 10
.BI "\-o S \--txsame"
Enable retransmitting a received packet on the same interface.
.TP 10
.BI "\-o d \--duplicate intf"
Duplicate received packets without modification to the given interface (port).
.TP 10
.BI "-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)).
.TP 10
.BI "-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.
.TP 10
.BI "-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.
.TP 10
.BI "\-B|b \--[no]bud"
.I addr
Is similar to a TNC-2's BUDLIST.  Use 
.BI "\-B \--bud"
to accept or 
.BI "\-b \--nobud"
to ignore packets from a sender or group of senders.  Budlists are
attached to each interface and can be reset with
.BI "\--bud \-"
.br
You can set up a global budlist once, or per-interface budlists.
The format of
.I addr
varies based on the interface type:
.HP
.BI "\--bud ax25:callsign-ssid"
matches only a given digipeater callsign and SSID.  For example,
\-B ax25:n0clu-14.
.HP
.BI "\--bud ax25:callsign" 
matches all SSIDs for the given callsign.  For example
\-B ax25:n0clu.
.HP
.BI "\--bud ip:hostname" 
matches one Internet host name (IPv6 or IPv4).  For example
\-B ip:n0clu.ampr.net
.HP
.BI "\--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.
.PP
.SH "RUNTIME CONTROLS"
.PP
.I aprsdigi
responds to the following signals:
.TP 10
.B "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 
.B "\-l \--logfile"
option, then the statistics are written to that file.  Otherwise they are
written to stderr.

.TP 10
.B "SIGUSR2"
Prints the statistics and then resets all counters to zero.
.PP
All other normal termination signals cause final statistics to print before
.I aprsdigi
exits.

.SH "SSID-BASED ROUTING"
.PP
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
\(lqT1QS4W-3\(rq
would be repeated with a modifed destination of \(lqAPRS VIA WIDE3-3\(rq
(in a network that supports WIDEn-n flooding).
A packet sent to \(lqAPRS-11\(rq would be repeated to the West unproto
path, as defined with the
.B \--west
option.  A table of SSID values and their paths follows:
.sp
.nf
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
.fi
.sp
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.
.PP
.I 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
.B \--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 
.B \--digipath
list.  SSIDs of 4, 5, 6, or 7, start at the fourth digipeater in
the list.
.PP
.SH "FLOODING ALIASES"
APRS flooding (WIDEn-n) digipeating works by repeating any received packet
whose next hop digipeater has a flooding alias (specified with the 
.B \--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
.B \--keep
option and are not repeated if they are heard within that time period.
.PP
Unlike conventional digipeating, in which the digipeater callsign/alias is
flagged as \(lqrepeated\(rq, 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.
.PP
.SH "TRACE and TRACEn-n ALIASES"
\(lqFlooding\(rq Trace aliases (TRACEn-n; 
.B \--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.
\(lqPlain\(rq trace aliases (TRACE; also
.B \--trace
option) are simply substituted in the conventional (
.B \--subst_mycall
) manner.
.PP
.SH "MULTI PORT OPERATION"
In single port operation, there is only one interface specified with
.BI "\--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:
.IP \(bu 2
Mic-E TO-call SSID-based route.
.IP \(bu 2
WIDEn-n/TRACEn-n flooding.
.PP
or a conventional next-hop (non-repeated) digipeater matching the
callsign or one of the aliases for the interface.
.PP
The decision to transmit is made by matching the next hop
callsign/alias with the table of callsigns and aliases you supply to
.BI "\--interface."
.PP
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.
.PP
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.
.SH DUPLICATING PACKETS
The 
.B "\--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
.B "\--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 
.I 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.
.PP
.SH TRACE vs. TRACEN-N
.PP
Note that TRACEn-n vs. plain TRACE do
different things: TRACEn-n *inserts* calls into the digipath while
decrementing ssid, e.g.:
.nf
	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*
.fi
.PP
.SH KILLING LOOPING PACKETS
.PP
Kill looping packets (\--kill_loops option):
.nf
	RELAY*,WIDE,WIDE,WIDE
	RELAY,N2YGK-7*,WIDE,WIDE
	RELAY,N2YGK-7,WIDE*,WIDE
.fi
Normally n2ygk-7 would respond to this,
but, by finding one of mycall earlier in the path, I know to ignore it.
.PP
.SH EXAMPLES
.PP
Following is a sample invocation of 
.I aprsdigi
running on two ports.  This is a contrived example that tries to show
all the features.  Comments to the right describe each feature.
.nf
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

.fi
.SH BUGS
.I 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.
.PP
.SH FILES
.BR /etc/ax25/axports
.SH "SEE ALSO"
.BR call (1),
.BR listen (1),
.BR beacon (1),
.BR ax25 (4),
.BR kissattach (8),
.BR ifconfig (8),
.BR aprsmon (1),
.BR http://www.tapr.org
.SH AUTHORS
.nf
Alan Crosswell, n2ygk@weca.org
.br
APRS and the Mic-Encoder are Trademarks of APRS Engineering LLC.
.fi