Provided by: aprsdigi_2.4.4-3.2_amd64 bug

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                             APRSDIGI(8)