Provided by: aprx_2.08.svn593+dfsg-2_amd64 bug

NAME

       Aprx-2 - An APRS iGate application with integrated Digipeater.

SYNOPSIS

       aprx [-d[d[d]]] [-e] [-i] [-v] [-V] [-l syslogfacilityname] [-f /etc/aprx.conf]

DESCRIPTION

       The  aprx  program  is  a  special  purpose Ham-radio application supplying infrastructure
       services for APRS protocol use.

       A more detailed manual is available at:
       http://ham.zmailer.org/oh2mqk/aprx/aprx-manual.pdf

FEATURES

       The Aprx begun as a receive-only  APRS  iGate  application  with  minimum  system  support
       technology  requirements.   This  version has also multi-port digipeater support, transmit
       iGate, and experimental D-PRS-to-APRS RF/Rx-iGate.

       ·  The Aprx does not require machine to have any other software in it, than things in UNIX
          standard libc. In particular no special AX.25 libraries at all, nor widgets or even C++
          runtime.

       ·  Important goal has been to keep R/W memory footprint  as  small  as  possible,  and  on
          general purpose i386 Linux a single radio port iGate+digipeater is now around 250 kB of
          R/W memory allocations.

       ·  Any UNIX (and UNIX like) platform should work for the Aprx, or be trivially ported.

       ·  The Aprx can listen "TNC2 monitor" and "KISS" speaking TNCs on any serial ports.

       ·  For Aprx the serial port can be ordinary host computer port,  a  USB  serial  port,  or
          remote  port  on a remote server behind the internet, like cisco router AUX ports (port
          4001, TCP STREAM without TELNET escapes.)

       ·  The Aprx does not require machine to have AX.25  protocol  support  internally!   (Thus
          this works also on e.g. Solaris and BSD machines without PF_AX25 sockets.)

       ·  On Linux machine with kernel internal AX.25 protocol support, the Aprx can listen on it
          with promiscuous mode and in order to use that, the Aprx must be started as root  user,
          and  be  configured  to  list interface callsigns that APRS packets are coming in.  The
          AX.25 socket listening is not in itself configurable, it  is  always  exists  in  Linux
          systems,  and  related  configuration  parameters are ignored in other platforms.  This
          socket listening does not need auxiliary "libax25" to function.

       ·  The Aprx program can be run without root privileges at least against remote serial port
          servers.   One  must  change  local  serial port ownership or access-groups (if any are
          used) to userid that runs the program and possibly do several changes of file paths  in
          configuration  file  beginning with its location (startup parameter).  How that is done
          is up to the user or system integrator of this program.

       ·  The Aprx connects with one callsign-ssid pair to APRS-IS core for  all  received  radio
          ports.

       ·  The Aprx Rx-iGate knows that messages with following tokens in AX.25 VIA fields are not
          to be relayed into APRS-IS network:
                RFONLY, NOGATE, TCPIP, TCPXX

       ·  The Aprx Rx-iGate knows that following source  address  prefixes  are  bogus  and  thus
          messages with them are to be junked:
                WIDE, RELAY, TRACE, TCPIP, TCPXX, NOCALL, N0CALL

       ·  The Aprx Rx-iGate Drops all query messages ("?").

       ·  The  Aprx  Rx-iGate opens up all 3rd party messages ("}"), and checks the internal data
          if it is OK to be gated out to APRS-IS.

       ·  The Aprx has  built-in  "Erlang  monitor"  mechanism  that  telemeters  each  receiving
          interface  to APRS-IS. It can also syslog the interface specific channel occupancy, and
          optionally can output to STDOUT.

       ·  The Aprx (since version 1.91) can do digipeater functions.

       ·  The Aprx (since version 1.99) does have  experimental  D-STAR  D-PRS  to  APRS  gateway
          functionality.  See the aprx-manual.pdf for details.

       ·  The  Aprx can be run on systems without writable storage, even with very little memory,
          like on NSLU2, and OpenWrt platforms.  The experiments have shown that a  single  radio
          Tx-iGate+digipeater  works  with  less than 300 kB of writable RAM for the Aprx itself.
          Additional memory is necessary for operating system services of TCP/IP networking,  and
          serial port drivers.

OPTIONS

       The aprx has following runtime options:

       -i     Keep the program foreground without debugging outputs.

       -d     Turn on verbose debugging, outputs data to STDOUT.

       -dd    the  "more  debug"  mode shows also details of network interaction with the APRS-IS
              network service.

       -ddd   the "even more debug" mode shows also detail classification of every kind of  frame
              received in KISS variants.

       -e     Erlang  output prints 10 minute and 60 minute traffic accumulation byte counts, and
              guestimates on channel occupancy,  alias  "Erlang".   These  outputs  are  sent  to
              STDOUT,  which  system operator may choose to log elsewere.  This is independent if
              the "-l" option below.

       -f /etc/aprx.conf
              Configuration file, given path is built-in default, and can be  overridden  by  the
              program runner.

       -l syslogfacilityname
              Defines  syslog(3)  facility code used by the erlang reporter by defining its name.
              Default value is: NONE, and accepted  values  are:  LOG_DAEMON,  LOG_FTP,  LOG_LPR,
              LOG_MAIL,   LOG_NEWS,   LOG_USER,  LOG_UUCP,  LOG_LOCAL0,  LOG_LOCAL1,  LOG_LOCAL2,
              LOG_LOCAL3, LOG_LOCAL4, LOG_LOCAL5, LOG_LOCAL6, LOG_LOCAL7.  That list  is  subject
              to  actual  facility  code set in the system, and in any case if you specify a code
              that is not known, then the program will complain during the  startup,  and  report
              it.  This is independent of the "-e" option above.

       -v     Verbose  logging  of  received  traffic  to  STDOUT.   Lines  begin  with reception
              timestamp (UNIX time_t seconds), then TAB, and either data as is,  or  with  prefix
              byte:  "*"  for "discarded due to data content", or possibly "#" for "discarded due
              to APRS-IS being unreachable".

       -V     Print source version compiled to this binary, and exit.

   DEBUGGING SYSTEM
       Use parameter set -ddv (or -dddv) to test new configuration by running it synchronously to
       console.

   NORMAL OPERATION
       Running  the  aprx program without any of option flags: -d, -v, or -e reads possibly given
       configuration, then automatically backgrounds the process, and writes pidfile.   When  the
       process  whose  number  written in pidfile is then sent a SIGTERM signal, it automatically
       shuts down itself, and removes the pidfile.  The pidfile can be  runtime  configured  with
       the -f /etc/aprx.conf file, and it has default name of: /var/run/aprx.pid.

CONFIGURATION FILE

       The configuration file is used to setup the program to do its job.

       You can construct following configurations:

       ·  A receive-only iGate server.

       ·  A digipeater with bi-directional iGate server.

       ·  A single radio digipeater.  (The most common type of digipeater.)

       ·  A multi-interfaced digipeater relaying traffic in between multiple radios.  (On same or
          on separate frequencies.)

       ·  A viscuous digipeater, which relays a packet it heard from viscuous  source  after  the
          viscuous  delay,  unless  it  was heard more times than only once, or it was heard from
          non-viscuous source before the viscuous one was  digipeated.   This  allows  of  making
          fill-in  digipeaters  that  will not digipeat the packet, if that same packet was heard
          twice or more before the viscuos delay expired.

       In the configuration file a line ending backslash (\) character  concatenates  next  input
       line into itself. Combined result can be up to 8000 bytes long.  This combination can be a
       bit surprising:
          #beacon .... long text  \
                 continuation
       results in single  long  input  line  that  begins  with  '#'  (it  is  comment)  and  all
       continuations  following  it  have  been  folded  in.   Presented  line number of combined
       continuation is the line number of the last line segment in this type of multi-line input.

       In the configuration file there  is  special  treatment  for  quoted  strings.   They  are
       stripped  of  the outer quotes, and "\" character is processed within the source string to
       produce an output string.  The escapes are:

       \n     Produces newline character (Control-J) on the output string.

       \r     Produces carriage return character (Control-M) on the output string.

       \\     Places a back-slash on the output string.

       \"     Places a double-quote on the output string.

       \'     Places a single-quote on the output string.

       \xHH   Lower-case "x" precedes two hex digits which ensemble is then converted to a single
              byte in the output string.

       The  complex  encodings  are  for  possible  initstrings  of  the external devices, and in
       particular for initstrings even a nul byte ( \x00 ) is supported.

       A configuration token  without  surrounding  quotes  does  not  understand  the  backslash
       escapes.

       #
       #  Sample configuration file for the APRX -- an Rx-only APRS iGate with
       #  Digipeater functionality.
       #
       #
       # Simple sample configuration file for the APRX-2
       #
       # This configuration is structured with Apache HTTPD style tags
       # which then contain subsystem parameters.
       #

       #
       # For simple case, you need to adjust 4 things:
       #   - Mycall parameter
       #   - Select correct type of interface (ax25-device or serial-device)
       #   - Optionally set a beacon telling where this system is
       #   - Optionally enable digipeater with or without tx-igate
       #

       #
       #
       # Define the parameters in following order:
       #   1)  <aprsis>     ** zero to many
       #   2)  <logging>    ** zero or one
       #   3)  <interface>  ** one to many
       #   4)  <beacon>     ** zero to many
       #   5)  <telemetry   ** zero to many
       #   6)  <digipeater> ** zero to many (at most one for each Tx)
       #

       #
       # Global macro for simplified callsign definition:
       # Usable for 99+% of cases.
       #

       mycall  N0CALL-1

       #
       # Global macro for simplified "my location" definition in
       # place of explicit "lat nn lon mm" at beacons. Will also
       # give "my location" reference for "filter m/100".
       #
       #myloc lat ddmm.mmN lon dddmm.mmE

       <aprsis>
       # The  login  parameter:
       # Station call-id used for relaying APRS frames into APRS-IS.
       # Use this only to define other callsign for APRS-IS login.
       #
       #login      OTHERCALL-7  # login defaults to $mycall

       #
       # The passcode parameter:
       # Unique code for your callsign to allow transmitting packets
       # into the APRS-IS.
       #
       passcode -1

       # APRS-IS server name and portnumber.
       # Every reconnect does re-resolve the name to IP address.
       # Some alternates are shown below, choose something local to you.
       #
       server    rotate.aprs2.net    14580
       #server    noam.aprs2.net     14580
       #server    soam.aprs2.net     14580
       #server    euro.aprs2.net     14580
       #server    asia.aprs2.net     14580
       #server    aunz.aprs2.net     14580

       # Some APRS-IS servers tell every about 20 seconds to all contact
       # ports that they are there and alive. Others are just silent.
       # Recommended value 3*"heartbeat" + some  -> 120 (seconds)
       #
       #heartbeat-timeout  0  # Disabler of heartbeat timeout

       # APRS-IS server may support some filter commands.
       # See:  http://www.aprs-is.net/javAPRSFilter.aspx
       #
       # You can define the filter as single long quoted string, or as
       # many short segments with explaining comments following them.
       #
       # Usability of these filters for a Tx-iGate is dubious, but
       # they exist in case you for example want to Tx-iGate packets
       # from some source callsigns in all cases even when they are
       # not in your local area.
       #
       #filter "possibly multiple filter specs in quotes"
       #
       #filter "m/100"          # My-Range filter
       #filter "f/OH2XYZ-3/50"  # Friend-Range filter
       </aprsis>

       <logging>
       # pidfile is UNIX way to tell that others that this program is
       # running with given process-id number.  This has compiled-in
       # default value of:  pidfile /var/run/aprx.pid
       #
       #pidfile /var/run/aprx.pid

       # rflog defines a rotatable file into which all RF-received packets
       # are logged.
       #
       #rflog /var/log/aprx/aprx-rf.log

       # aprxlog defines a rotatable file into which most important
       # events on APRS-IS connection are logged, namely connects and
       # disconnects.
       #
       #aprxlog /var/log/aprx/aprx.log

       # erlangfile defines a mmap():able binary file, which stores
       # running sums of interfaces upon which the channel erlang
       # estimator runs, and collects data.
       # Depending on the system, it may be running on a filesystem
       # that actually retains data over reboots, or it may not.
       # With this backing store, the system does not loose cumulating
       # erlang data over the current period, if the restart is quick,
       # and does not stradle any exact minute.
       # (Do restarts at 15 seconds over an even minute..)
       # This file is around 0.7 MB per each interface talking APRS.
       # If this file is not defined and can not be created,
       # internal non-persistent in-memory storage will be used.
       #
       # Built-in default value is: /var/run/aprx.state
       #
       #erlangfile /var/run/aprx.state

       # erlang-loglevel is config file edition of the "-l" option
       # pushing erlang data to syslog(3).
       # Valid values are (possibly) following: NONE, LOG_DAEMON,
       # LOG_FTP, LOG_LPR, LOG_MAIL, LOG_NEWS, LOG_USER, LOG_UUCP,
       # LOG_LOCAL0, LOG_LOCAL1, LOG_LOCAL2, LOG_LOCAL3, LOG_LOCAL4,
       # LOG_LOCAL5, LOG_LOCAL6, LOG_LOCAL7.  If the parameter value is
       # not acceptable, list of accepted values are printed at startup.
       #
       #erlang-loglevel NONE

       # erlanglog defines a rotatable file into which erlang data
       # is written in text form.
       #
       #erlanglog /var/log/aprx/erlang.log

       # erlang-log1min option logs to syslog/file also 1 minute
       # interval data from the program. (In addition to 10m and 60m.)
       #
       #erlang-log1min
       </logging>

       # ***********  Multiple <interface> definitions can follow   *********

       # ax25-device  Lists AX.25 ports by their callsigns that in Linux
       #              systems receive APRS packets.  If none are defined,
       #              or the system is not Linux, the AX.25 network receiver
       #              is not enabled.  Used technologies need at least
       #              Linux kernel 2.4.x
       #
       # tx-ok        Boolean telling if this device is able to transmit.
       #
       #<interface>
       #   ax25-device $mycall  # Either $mycall macro, or actual callsign
       #   #tx-ok      false  # transmitter enable defaults to false
       #   #telem-to-is true # set to false to disable
       #</interface>

       # The  TNC serial  options.  Parameters are:
       #   - /dev/ttyUSB1    -- tty device
       #   - 19200           -- baud rate, supported ones are:
       #                        1200, 2400, 4800, 9600, 19200, 38400, ...
       #   - 8n1             -- 8-bits, no parity, one stop-bit,
       #                        no other supported modes
       #   - "KISS"                  - plain basic KISS mode
       #   - "XORSUM" alias "BPQCRC" - KISS with BPQ "CRC" byte
       #   - "SMACK"  alias "CRC16"  - KISS with real CRC
       #   - "FLEXNET"               - KISS with real CRC
       #   - "TNC2"                  - TNC2 monitor format
       #   - "DPRS"                  - DPRS (rx) Gateway
       #
       #<interface>
       #   serial-device /dev/ttyUSB0  19200 8n1    KISS
       #   #callsign     $mycall  # Either $mycall macro, or actual callsign
       #   #tx-ok        false    # transmitter enable defaults to false
       #   #telem-to-is true # set to false to disable
       #</interface>
       #
       #<interface>
       #   serial-device /dev/ttyUSB1  19200 8n1    TNC2
       #   #callsign     $mycall  # Either $mycall macro, or actual callsign
       #   #tx-ok        false    # TNC2 monitor can not have transmitter
       #   #telem-to-is true # set to false to disable
       #</interface>
       #
       #<interface>
       #   serial-device /dev/ttyUSB1  19200 8n1    DPRS
       #   callsign     dprsgwcallsign  # must define actual callsign
       #   #tx-ok        false    # DPRS monitor can not do transmit
       #   #telem-to-is true # set to false to disable
       #</interface>
       #

       # ***********  Multiple <beacon>  definitions can follow   *********
       <beacon>
       #
       #  Beacons are sent out to radio transmitters AND/OR APRSIS.
       #  Default is "both", other modes are settable.
       #
       #beaconmode { aprsis | both | radio }
       #
       #  Beacons are sent from a circullar transmission queue, total cycle time
       #  of that queue is 20 minutes by default, and beacons are "evenly"
       #  distributed along it.  Actual intervals are randomized to be anything
       #  in between 80% and 100% of the  cycle-size / number-of-beacons.
       #  First beacon is sent out 30 seconds after system start.
       #  Tune the cycle-size to be suitable to your number of defined beacons.
       #
       #cycle-size  20m
       #
       #
       # Basic beaconed thing is positional message of type "!":
       #
       #beacon symbol "R&" lat "0000.00N" lon "00000.00E" comment "Rx-only iGate"
       #beacon symbol "R&" $myloc comment "Rx-only iGate"
       #
       # Following are basic options:
       #  'symbol'    no default, must be defined!
       #  'lat'       coordinate latitude:   ddmm.mmN  (no default!)
       #  'lon'       coordinate longitude: dddmm.mmE  (no default!)
       #  '$myloc'    coordinate values taken from global 'myloc' entry,
       #              and usable in place of explicit 'lat'+'lon'.
       #  'comment'   optional tail part of the item, default is nothing
       #
       # Sample symbols:
       #   R&   is for "Rx-only iGate"
       #   I&   is for "Tx-iGate"
       #   /#   is for "Digipeater"
       #   I#   is for "Tx-iGate + Digipeater"
       #
       # Additional options are:
       # 'srccall'   parameter sets claimed origination address.
       # 'dstcall'   sets destination address, default "APRXnn"
       # 'interface' parameter picks an interface (must be "tx-ok true" type)
       # 'via'       sets radio distribution pattern, default: none.
       # 'timefix'  On APRS messages with HMS timestamp (hour:min:sec), the
       #            system fixes appropriate field with transmit time timestamp.
       #
       # Message type is by default '!', which is positional no timestamp format.
       # Other possible formats are definable with options:
       # 'type'   Single character setting type:  ! = / @
       # 'item'   Defines a name of Item (')') type beacons.
       # 'object' Defines a name of Object (';') type beacons.
       #
       # 'file' option tells a file at which a _raw_ APRS message content is
       #        expected to be found as first line of text. Line ending newline
       #        is removed, and no escapes are supported.  The timefix is
       #        available, though probably should not be used.
       #
       # 'exec' option defines program path for a program whose stdout is
       #        read up to first newline (which must be present), and then
       #        transmit as beacon content. No format helpers are supplied,
       #        although 'timefix' can be used.
       # 'timeout' option is associated with 'exec', and defines when the
       #        exec must by latest produce the output, or the subprogram
       #        execution is killed. Default value is 10 seconds.
       #
       # The parameter sets can vary:
       #  a) 'srccall nnn-n dstcall "string" symbol "R&" lat "ddmm.mmN" lon "dddmm.mmE" [comment "any text"]
       #  b) 'srccall nnn-n dstcall "string" raw "string"'
       #
       # The a) form flags on some of possible syntax errors in parameters.
       # It will also create only "!" type messages.  The dest parameter
       # defaults to "APRS", but can be used to give other destinations.
       # The via parameter can be used to add other keywords, like "NOGATE".
       #
       # Writing correct RAW format beacon message is very hard,
       # which is evidenced by the frequency of bad syntax texts
       # people so often put there...   If you can not be persuaded
       # not to do it, then at least VERIFY the beacon result on
       # web service like  findu.com,  or  aprs.fi
       #
       #beacon                 file /tmp/wxbeacon.txt
       #beacon srccall N0CALL-3 raw "!0000.00NR00000.00E&aprx - an Rx-only iGate"
       #beacon srccall N0CALL-3 raw "!0000.00NI00000.00E&aprx - an iGate"
       #beacon srccall $mycall symbol "R&" lat "0000.00N" lon "00000.00E"  \
                               comment "aprx - an Rx-only iGate"
       #beacon srccall $mycall symbol "I&" lat "0000.00N" lon "00000.00E"  \
                               comment "aprx iGate"
       </beacon>

       # ***********  <telemetry>  definition(s) follow   *********
       #
       # The system will always send telemetry for all of its interfaces
       # to APRSIS, but there is an option to define telemetry to be sent
       # to radio channel by using following sections for each transmitter
       # that is wanted to send out the telemetry.
       #
       #   transmitter   -  callsign referring to <interface>
       #   via           -  optional via-path, only 1 callsign!
       #   source        -  one or more of <interface> callsigns for which
       #                    the telemetry transmission is wanted for
       #
       #<telemetry>
       #    transmitter    $mycall
       #    via       TRACE1-1
       #    source         $mycall
       #</telemetry>

       # ***********  <digipeater>  definition(s) follow   *********
       #
       #  The digipeater definitions tell transmitters that receive
       #  AX.25 packets from possibly multiple sources, and then what
       #  to do on the AX.25 headers of those messages.
       #
       #  There is one transmitter per digipeater -- and inversely, there
       #  can be at most one digipeater for each transmitter.
       #
       #  In each digipeater there is at least one <source>, usually same
       #  as the transmitter.
       #
       #<digipeater>
       #    transmitter     $mycall
       #    #ratelimit      60 120      # default: average 60 packets/minute,
       #                                #          burst max 120 packets/minute
       #    #srcratelimit   10 20       # Example: by sourcecall:
       #                                #          average 10 packets/minute,
       #                                #          burst max 20 packets/minute
       #
       #    <source>
       #        source         $mycall
       #    #   ratelimit      60 120      # default: average 60 packets/minute,
       #    #                              #          burst max 120 packets/minute
       #    #   viscous-delay  0     # no viscous delay for RF->RF digipeat
       #    #   ratelimit      120   # default: max 120 packets/minute
       #    </source>
       #
       #    #<source>          # Adding APRSIS source makes this tx-igate
       #    #   source        APRSIS
       #    #   ratelimit      60 120      # default: average 60 packets/minute,
       #    #                              #          burst max 120 packets/minute
       #    #   relay-type    third-party  # Must define this for APRSIS source!
       #    #   viscous-delay  5 # Recommendation: 5 seconds delay to give
       #    #                    # RF delivery time make itself known.
       #    #   filter         t/m  # Tx-iGate only messages sent to me by APRSIS
       #    #</source>
       #
       #</digipeater>

GLOBAL MYCALL PARAMETER

       In  majority  of  usage  models,  system needs single configured callsign.  This is set by
       using the mycall configuration option, and latter referred to in configurations as $mycall
       parameter in place of callsigns.

GLOBAL MYLOC PARAMETER

       Usually  multiple  beacons,  and simple filter rules are wanted to be using same reference
       coordinate for this system.  This is set by using  the  myloc  configuration  option,  and
       latter  referred  to  in  configurations  as  $myloc parameter in place of "lat nn lon mm"
       coordinate pair of beacons.

APRSIS SECTION FOR APRSIS CONNECTIVITY

       Settings in the <aprsis> section define connectivity with the APRS-IS network service.

       Necessary option is server, and others are optional.

       Available options are:

       login $mycall
               The APRSIS network login.  Defaults to the mycall configuration entry.

       passcode -1
               Defining a small integer in range of 0 to 32767 authenticating your login to APRS-
               IS server. Ask for assistance from your APRS-IS managers, or calculate it yourself
               with aprspass program. (Web search engines do find several of them.)

       server server-name 14850
               Define which APRS-IS is being connected to.   Multiple  definitions  are  used  in
               round-robin style, if the connection with the previous one fails for some reason.

       filter 'filter specs in quotes' # comments
               Set  filter adjunct definitions on APRS-IS server.  Multiple entries are catenated
               together in entry order, when connecting to the server.

LOGGING SECTION

       The <logging> section defines miscellaneous file names and options for state tracking  and
       logging use.

       pidfile /var/run/aprx.pid
               The  pidfile  is  UNIX  way  to tell that others that this program is running with
               given  process-id  number.   This  has  compiled-in  default  value  of:   pidfile
               /var/run/aprx.pid

       rflog /var/log/aprx/aprx-rf.log
               The  rflog defines a rotatable file into which all RF-received packets are logged.
               There is no default.

       aprxlog /var/log/aprx/aprx.log
               The aprxlog defines a rotatable file into which most important events  on  APRS-IS
               connection are logged, namely connects and disconnects.  There is no default.

       erlangfile /var/run/aprx.state
               The  erlangfile  defines  a  mmap():able binary file, which stores running sums of
               interfaces upon which the  channel  erlang  estimator  runs,  and  collects  data.
               Depending  on  the system, it may be running on a filesystem that actually retains
               data over reboots, or it may not.  With this backing store, the  system  does  not
               loose cumulating erlang data over the current period, if the restart is quick, and
               does not stradle any exact minute.  This file is around 0.7 MB per each  interface
               talking  APRS.   If this file is not defined and can not be created, internal non-
               persistent  in-memory  storage  will  be  used.   Built-in   default   value   is:
               /var/run/aprx.state

       erlang-loglevel NONE
               The  erlang-loglevel is config file edition of the "-l" option pushing erlang data
               to syslog(3).  Valid values are (possibly) following: NONE,  LOG_DAEMON,  LOG_FTP,
               LOG_LPR,   LOG_MAIL,   LOG_NEWS,   LOG_USER,   LOG_UUCP,  LOG_LOCAL0,  LOG_LOCAL1,
               LOG_LOCAL2, LOG_LOCAL3, LOG_LOCAL4, LOG_LOCAL5, LOG_LOCAL6,  LOG_LOCAL7.   If  the
               parameter value is not acceptable, list of accepted values are printed at startup.

       erlanglog /var/log/aprx/erlang.log
               The  erlanglog  defines a rotatable file into which erlang data is written in text
               form.  There is no default.

       erlang-log1min
               The erlang-log1min option logs to syslog/file also 1 minute interval data from the
               program.  (In addition to 10m and 60m.)  Default is off.

INTERFACE SECTIONS FOR RADIO PORTS

       The <interface> sections define connections to radio modems.  Several different styles are
       available:

       · Local serial ports in the machine (device-serial /dev/ttyS0 speed encapsulation)

       · Local USB serial ports in the machine (device-serial /dev/ttyUSB0 speed encapsulation)

       · Remote served serial ports over a TCP stream.  Implemented to talk with Cisco AUX  ports
         on   "range   4000"  (TCP  STREAM,  no  TELNET  escapes)  (tcp-device  12.34.56.78  4001
         encapsulation)

       · Linux  internal  AX.25  network  attached  devices  (ax25-device  CALLSIGN-1)  are  only
         available  when  running on a Linux system.  On a non-Linux system it connects to a null
         interface, never getting anything and can always sink everything.

       The serial port name tells what kind of port is in  question,  and  while  port  baud-rate
       (9600)  and  character  settings (8n1) must always be set, they are ignored for the remote
       connection.

       Following speed modes are available:
            1200, 1800, 2400, 4800, 9600, 19200, 38400, 57600,
            115200, 230400, 460800, 500000, 576000
       Likely available speeds are in bold, other supported values are listed in italics.

       Following encapsulation modes are available:

       TNC2      is capable only to monitor the packets reported by TNC2 type debug  output,  and
                 Rx-iGate, but they are not acceptable as source for a <digipeater>.

       DPRS      is  special mode for gateway from D-STAR D-PRS to APRS.  This must always have a
                 callsign definition for the gateway.

       KISS      Basic KISS encapsulation.  No checksums.  Will  autodetect  (sometimes)  packets
                 with SMACK or FLEXNET characteristics.

       SMACK     Stuttgart  Modified  Amateurradio-CRC-KISS,  which  runs CRC-16 checksum on KISS
                 datastream much in the same way as HDLC has CCITT-CRC checksum on it.

       FLEXNET   FLEXNET which runs a CRC checksum of its own polynomial on KISS datastream  much
                 in the same way as HDLC has CCITT-CRC checksum on it.

       BPQCRC    XOR  "checksum"  on  dataframes.   Also  known  as  "XKISS", and "XORSUM".  This
                 detects single bit failure, but weakly any multibit failures.  Extra 0x00  bytes
                 have no effect on checksum, etc.

       On  <kiss-subif  tncid> sub-options the parameter is tncid, which sets up KISS multiplexer
       parameter so that subsequent options applies only on designated KISS sub-port.

       The callsign option sets port specific callsign when relaying to APRS-IS.

       The telem-to-is true option can be used to disable (by explicitly setting it  to  'false')
       radio interface telemetry transmission to APRS-IS.  By default it is on.  This is separate
       from <telemetry> sections, which send telemetry to RF interfaces.

       <interface>
          serial-device /dev/ttyUSB1 19200 8n1 KISS
          tx-ok         false          # receive only (default)
          callsign      OH2XYZ-R2      # KISS subif 0
          initstring    "...."         # initstring option
          timeout       900            # 900 seconds of no Rx
       </interface>

       <interface>
          serial-device /dev/ttyUSB1 19200 8n1 SMACK
          tx-ok         false          # receive only (default)
          callsign      OH2XYZ-R2      # KISS subif 0
          initstring    "...."         # initstring option
          timeout       900            # 900 seconds of no Rx
       </interface>

       <interface>
          serial-device /dev/ttyUSB2 19200 8n1 KISS
          initstring    "...."
          timeout       900            # 900 seconds of no Rx
          <kiss-subif 0>
             callsign OH2XYZ-2
             tx-ok    true             # This is our transmitter
          </kiss-subif>
          <kiss-subif 1>
             callsign OH2XYZ-R3        # This is receiver
             tx-ok    false            # receive only (default)
          </kiss-subif>
       </interface>

       <interface>
          tcp-device   172.168.1.1 4001 KISS
          tx-ok         false          # receive only (default)
          callsign      OH2XYZ-R4      # KISS subif 0
          initstring    "...."         # initstring option
          timeout       900            # 900 seconds of no Rx
       </interface>

       <interface>
          ax25-device OH2XYZ-6         # Works only on Linux systems
          tx-ok       true             # This is also transmitter
       </interface>

       <interface> # RX-IGATE ONLY, NOT USABLE AS DIGIPEATER SOURCE
          serial-device /dev/ttyUSB1 19200 8n1 TNC2
          callsign      OH2XYZ-R6      # TNC2 has no sub-ports
          initstring    "...."         # initstring option
          timeout       900            # 900 seconds of no Rx
       </interface>

BEACON DEFINITIONS

       The beacons are defined using <beacon> configuration sections.

       Because classical beacon definitions are highly error-prone, this program has a new way to
       define them:

       · The new way to define beacons:
         beacon symbol "R&" lat "0000.00N" lon "00000.00E"  \
                comment "aprx - iGate"

       · Semi-clasical definition of raw APRS packet:
         beacon raw "!0000.00NR00000.00E&aprx - iGate"

       · Load beacon text from a file, path data is configurable:
         beacon file /path/to/file

       · Run a program to produce beacon data in raw format:
         beacon exec /path/to/file timeout 10

       The fields and parameters:

       interface   An optional "interface" parameter tells that this beacon shall be sent only to
                   interface whose callsign is named.  Default is to send to all interfaces  that
                   have "tx-ok true" setting.

       type        An  optional  one  character string parameter, with one of following contents:
                   "!", "=", "/", "@", ";" and ")".

       srccall     An optional "srccall" parameter  tells  callsign  which  is  claimed  as  this
                   particular  beacon  source.   It  must be valid AX.25 callsign in text format.
                   When this "srccall" parameter is not given, value  of  "mycall"  configuration
                   entry is used.

       dstcall     An optional "dstcall" parameter has built-in software version dependent value,
                   but it can be used to define another value.

       via         An optional "via" parameter defaults to nothing, but can  be  used  to  define
                   additional "VIA" path tokens, for example: "WIDE1-1".

       item        An  optional  "item"  parameter  is  for defining a name for an item type APRS
                   packet.

       object      An optional "object" parameter is for defining a name for an object type  APRS
                   packet.

       symbol      A  mandatory "symbol" parameter is two character code, which for Rx-only iGate
                   is pair: "R&"

       lat         This mandatory parameter defines latitude coordinate (that  is:  north/south.)
                   It  is  expected  to be of format: "ddmm.mmN" where "dd" defines two digits of
                   degrees of latitude, and "mm.mm" defines two digits + decimal dot + two digits
                   of minutes of latitude.  Then comes literal "N" or "S" indicating hemisphere.

       lon         This  mandatory  parameter  defines longitude coordinate (that is: east/west.)
                   It is expected to be of format: "dddmm.mmE" where "ddd" defines  three  digits
                   of  degrees  of  longitude, and "mm.mm" defines two digits + decimal dot + two
                   digits of minutes of longitude.  Then comes  literal  "E"  or  "W"  indicating
                   hemisphere.

       comment     This optional parameter defines commentary text tail on the beacon packet.  If
                   you need characters outside US-ASCII  character  set,  use  of  UTF-8  encoded
                   UNICODE character set is recommended.

       raw         This  alternate  format  defines whole APRS packet content in raw text format.
                   Currently this type of packets are not validated for syntax at all!

       file        This alternative way defines path to a file with  single  text  line  defining
                   content of raw message data.

       exec        This alternative mode runs designated program, and waits for at most a timeout
                   number of seconds (default 10) for the program to produce the result.

       timeout     This is optional parameter  for  exec  allowing  altered  timeout  (number  of
                   seconds) for waiting the program to respond.  Default is 10 seconds.

       The  type/symbol/lat/lon/comment-format  supports  only  a  few types of APRS packets.  It
       splits input into small slices that are possible to validate in detail.   (See  "DEBUGGING
       SYSTEM" above.)

RF-TELEMETRY

       The  aprx system will always send telemetry for all of its interfaces to APRSIS, but there
       is an option to define telemetry to be sent to radio channel by using  following  sections
       for each transmitter that is wanted to send out the telemetry.

       The parameters of <telemetry> configuration section are:

       transmitter A mandatory callsign referring to an interface.

       via         An optional via-path parameter.  Only 1 callsign!

       source      One  or  more  of  interface callsigns for which the telemetry transmission is
                   made.

DIGIPEATER

       The aprx is possible to configure as a AX.25 digipeater with APRS twists.   This  is  done
       with <digipeater> configuration section and its subsections.

       There  can  be  at most one <digipeater> definition per each transmit capable interface in
       the system.  On a system with multiple transmitters, this  means  there  can  be  multiple
       digipeaters, each with different behaviour rules.

       Minimalistic setup for a digipeater will be as follows:

       <digipeater>
           transmitter     $mycall
           <source>
               source      $mycall
           </source>
       </digipeater>

       In  minimalistic  approach  the  system  does  digipeating of packets heard on the $mycall
       interface back to same interface.  Single requirement is that the  <interface>  block  has
       tx-ok true setting on it.

       In more complicated approaches it is possible to define multiple sources for packets:

       ·  Multiple device ports.

       ·  APRSIS pseudoport, which creates the Tx-iGate functionality.

   <digipeater> options
       Main-level <digipeater> options are:

       ·  transmitter defines which interface the digipeater will output to.

       ·  <trace> and <wide> sub-options are explained below.

       ·  <source> sub-option is explained below.

   <trace> and <wide> sub-options
       The  <trace>  sub-option  has  priority  over  the  <wide>  sub-option, otherwise they are
       configured the same way.

       The <trace> sub-option defines which AX.25 address contained  keywords  are  treated  with
       APRS  "New-N  paradigm"  rules  in  a  way  where  each  processing  node always marks its
       transmitter callsign on the transmitted AX.25 packet address header.

       The <wide> sub-option defines which AX.25 address contained keywords are treated with APRS
       "New-N  paradigm"  rules  in  a  way  where  processing node does not mark its transmitter
       callsign on the transmitted AX.25 packet address header.

       Available parameters are:

       keys     A string of comma-separated set of string tokens:
                   keys "TRACE,WIDE"
                Alternative form for this entry is:
                   keys "TRACE"
                   keys "WIDE"

       maxdone  Defines maximum number of  redistribution  hops  that  these  keywords  can  have
                completed  when  reaching  here.   If accounting finds more done, the system will
                just drop the packet instead of digipeating it onwards.

       maxreq   Defines maximum number of redistribution hops that these keywords can define.  If
                accounting  finds more requested, the system will just drop the packet instead of
                digipeating it onwards.

   <source> sub-options
       Primary definer option is source which gives callsign of an  <interface>  from  which  the
       AX.25 packets are received for this <source> block.

       Available relay-type modes on <source> definitions are:

       digipeater    Normal AX.25 digipeater behaviour with APRS New-N paradigm support.  This is
                     default mode.

       directonly    Digipeat  only  directly  heard  packets.   Useful  for  systems  that   are
                     designated as "fill-in".  See also "viscous-delay".

       third-party   Special mode for Tx-iGate.

       The  ratelimit  defines  two  parameters:  average  and limit number of packets sent in 60
       seconds.  Its definitions can  be  both  in  <digipeater>  and  in  digipeater's  <source>
       sections,  and  therefore  you  can limit each individual source to a max accepted rate as
       well as define separate rate limits for the transmitter.

       The viscous-delay defines a number of seconds from 0  (default)  maximum  of  9  that  the
       source  will  put  the message on duplicate detector delay processing.  All occurrances of
       same packet per duplicate detector  during  that  time  will  be  accounted  on  duplicate
       detection,  and  if at the end of the delay period there are more than one hit, the packet
       is discarded.  Use delay of 0 seconds for normal digipeater, 5 seconds for a fill-in, or a
       Tx-iGate.

       A  javAPRSSrvr  filter-adjunct style rules are possible with the filter options.  When you
       want multiple filters, use multiple options with associated parameters:
           filter t/m            # APRS messaging type packets
           filter a/la/lo/la/lo  # APRS positional packets within this area

       Also negative filters are possible (prefixed with minus character), which upon match cause
       rejection  of  the  packet.  Filters are evaluated in definition order, and first matching
       one will terminate the evaluation.  When no filters  are  defined,  everything  is  passed
       thru.   When  any  filter  is defined, only those matching non-negative filters are passed
       thru, and no default "pass everything else" behaviour exists.

       Supported "adjunct filters" are following:

       A/latN/lonW/latS/lonE
               Area filter, defined as area enclosing within latS/latN and  lonW/lonE.   Latitude
               and longitude are entered as degrees and decimals.

       B/call1/call2...
               Budlist filter.  Supports *-wildcards.

       D/digi1/digi2...
               Not supported at APRX internal filters

       E/call1/call2/...
               Not supported at APRX internal filters

       F/call/dist_km
               Great-circle distance in kilometers from friend's coordinates.  No wildcarding.
               (TODO: check that it really works!)

       M/dist  The  range  around  my  location  filter  requires  that you have defined also the
               "myloc" configuration entry.  It defines acceptance of positions and messages with
               senders within dist kilometers of the "myloc" position.

       O/object1/obj2...
               Object name filter.  Supports *-wildcards.

       P/aa/bb/cc...
               Prefix filter.

       Q/con/ana
               The Q-construct filter is not supported.

       R/lat/lon/dist
               Range filter.  Latitude and longitude are in degrees and decimals.  Distance is in
               kilometers.  No wildcards.

       S/pri/alt/over
               Symbol filter

       T/..../call/km
               Type filter.  Couple possible usages:

                 -t/c                Everything except CWOP

                  t/*/OH2RDY/50      Everything within 50 km of OH2RDY's last known position

               Type code characters are:

               *  An "all" wild-card.

               C  A CWOP.

               I  An ITEM.

               M  A MESSAGE.

               N  A NWS message.

               O  An OBJECT.

               Q  A QUERY.

               S  A STATUS response.

               T  A TELEMETRY packet or parameter message.

               U  A USERDEF message.

               W  A WX data packet

       U/unproto1/unproto2...
               Filters by value in destination address field, supports wildcard.

       The <trace> and <wide> sub-options exist also within each <source>.  Where such occur, the
       <source> specific <trace> sub-option trumps the definition on <digipeater> level, and same
       with <wide> sub-options.  This allows things like overriding flooding control keywords  on
       source basis, should such be necessary.

       A  set  of regex-filter rules can be used to reject packets that are not of approved kind.
       Available syntax is:

       regex-filter source RE
              source address field

       regex-filter destination RE
              destination address field

       regex-filter via RE
              any via path field

       regex-filter data RE
              payload content

       The regex-filter exists as ad-hoc method when all else fails.

NOTES: ERLANG

       The Erlang is telecom measurement of channel occupancy, and in this application  sense  it
       does tell how much traffic there is on the radio channel.

       Most  radio  transmitters are not aware of all transmitters on channel, and thus there can
       happen a collision causing loss of both messages.  The higher the  channel  activity,  the
       more  likely  that  collision  is.   For further details, refer to statistical mathematics
       books, or perhaps on Wikipedia.

       In order to measure channel activity, the aprx program suite has these built-in statistics
       counter and summary estimators.

       The  Erlag  value that the estimators present are likely somewhat underestimating the true
       channel occupancy simply because it calculates estimate of channel bit transmit rate,  and
       thus  a  per-minute  character  capacity.  It does not know true frequency of bit-stuffing
       events of the HDLC framing, nor each transmitter  pre-  and  port  frame  PTT  times.  The
       transmitters need to stabilize their transmit oscillators in many cases, which may take up
       to around 500 ms!  The counters are not aware of this preamble-, nor postamble-times.

       The HDLC bit stuffing ratio is guessed to be 1:1.025 (1 extra bit every 5 bytes)

NOTES: PROGRAM NAME

       Initially this program had name aprsg-ng, which was too close to another (a less  low-tech
       C++ approach) program had.

BUGS/WARTS

       The  Erlang-monitor mechanisms are of rudimentary quality, and can seriously underestimate
       the channel occupancy by ignoring pre- and postample transmissions, which can be  as  high
       as  50  centiseconds  for preample, and 20 centiseconds for postample!  When entire packet
       takes 50 centiseconds, such preample alone doubles channel occupancy.  A 6pack protocol on
       serial  link  (instead  of  KISS)  could inform receiver better on carrier presense times,
       however even  that  underestimates  RF  power  presense  (RSSI)  signal.   (6pack  is  not
       supported.)

       On  serial  lines supports really only 8n1 mode, not at all like: 7e1.  On the other hand,
       there really is no sensible usage for anything but 8n1...

SEE ALSO

       Couple web sites:
       http://www.aprs2.net/,
       http://www.aprs-is.net/,
       http://wiki.ham.fi/Aprx.en,
       http://ham.zmailer.org/oh2mqk/aprx/aprx-manual.pdf

       aprx-stat(8)

AUTHOR

       This little piece was written by Matti Aarnio, OH2MQK during a dark  and  rainy  fall  and
       winter  of  2007-2008  after  a  number  of  discussions  grumbling about current breed of
       available software for APRS iGate use in Linux (or  of  any  UNIX)  platforms.   Fall  and
       winter 2009-2010 saw appearance of digipeater functionality.

       Principal  contributors  and  test  users  include:  Pentti Gronlund, OH3BK, Reijo Hakala,
       OH1GWK.  Debian packaging by Kimmo Jukarinen, OH3GNU.  Testing of SMACK variant of KISS by
       Patrick  Hertenstein, DL1GHN.  The beacon exec functionality prototype by Kamil Palkowiski
       SQ8KFH.

                                aprx-2.08.svn593 - 2015 August 18                         aprx(8)