Provided by: aprsdigi_3.10.0-2_i386 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 General 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)