Provided by: aprsdigi_2.4.4-1_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  -ps  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)