Online Amateur Radio Community Wiki

This page is read only. You can view the source, but not change it. Ask your administrator if you think this is wrong.
======Section 9 - Miscellaneous Topics======
===== AD-HOC =====
<code>AD-HOC(9)               XROUTER REFERENCE MANUAL             26/9/2023

</code> **NAME** <code>
        AD-HOC -- Ad-Hoc Networking.

</code> **DESCRIPTION** <code>
        "Ad-hoc" networking (AHN) is a variant of AXUDP linking. It
        differs from "normal" AXUDP in that the UDP/IP parameters of
        the link partners are not specified in advance, and instead
        of "one PORT per link", all AHN links share the same PORT.

        As the partners' UDP/IP details are not known in advance, AHN
        is "passive", i.e. like an AXTCP server, it must wait for
        incoming connections. Thus AHN can only be used at ONE end of
        a link.

        Upon receipt of an incoming AXUDP packet, XRouter "remembers"
        its UDP/IP parameters, and uses them to return the replies.

        At present, the UDP/IP parameters are remembered for only ten
        minutes, but as long as the AX25 T3 (link check) time is less
        than that, the link check packets prevent the parameters
        from expiry.

        The "ODN" command currently lists the stored parameters.

        AHN can be used at the same time as "normal" AXUDP, and they
        can both share the same INTERFACE. But there must only be one
        PORT devoted to AHN. If you try to specify more than one AHN
        port, XRouter will refuse to start.

</code> **CONFIGURATION** <code>
        An AHN PORT requires an AXUDP INTERFACE in XROUTER.CFG, for
        example:

              INTERFACE=9
                   TYPE=AXUDP
                    MTU=256
              ENDINTERFACE

             (Choose the interface number to suit yourself).

        Only TYPE=AXUDP and MTU= are required, all other parameters
        are ignored (at present).

        The minimum configuration for an AHN PORT is as follows:

              PORT=9
                  ID=Ad-Hoc Networking
                  INTERFACENUM=9
                  IPLINK=0.0.0.0
                  UDPLOCAL=10094
                  LEARN=1
              ENDPORT

        IPLINK has no default value. It must be a proper dotted-quad
        IP address i.e."0.0.0.0", not "0". This "special" IP address
        is what tells it to be an Ad Hoc Networking port.

        UDPLOCAL is the UDP "port" number upon which XRouter listens
        for incoming AHN packets. This MUST be different from any
        UDP ports used by "normal" AXUDP. Don't forget to "port
        forward" incoming UDP to this address.

        Note that UDPREMOTE must not be used.

        If there's an ETHERNET port available, XRouter will use its
        own IP stack for AHN, otherwise it will use the Linux stack.

        If you want to "force" the use of the Linux stack, for
        example if the link partner is on the same machine, add the
        following line to the PORT configuration:

            IPADDRESS=127.0.0.1

        Finally, LEARN tells XRouter to remember the IP address and
        udp port of the peer. 

</code> **CAVEATS** <code>
        AHN allows unplanned and unregulated linking between nodes,
        and is therefore deprecated. Unknown nodes which come and go
        at random can distort the network and cause excessive network
        management traffic. The facility was provided only because
        there was a demand for it. It's just another tool in the
        networking tool box.

        It is assumed that the link partner receives AXUDP on the
        same UDP port as it sends from. If this is not the case, AHN
        will not work, and normal AXUDP must be used.

</code> **SEE ALSO:** \\
[[packet:xrouter:docs:MAN9#AXTCP|        AXTCP(9)       -- AX25 over TCP.]] \\
[[packet:xrouter:docs:MAN9#AXUDP|        AXUDP(9)       -- AX25 over UDP.]] \\
[[packet:xrouter:docs:MAN7#LEARN|        LEARN(7)       -- Learn Unsolicited AX*P Peer Details.]] \\
[[packet:xrouter:docs:MAN8#XROUTER.CFG|        XROUTER.CFG(8) -- Main Configuration File]] \\

[[packet:xrouter:docs:|< Back to Index]]

----
===== APPLS =====
<code>APPLS(9)                XROUTER REFERENCE MANUAL            19/10/2023
</code> **NAME** <code>
        APPLS -- Application Support.

</code> **DESCRIPTION** <code>
        In this context, "applications" refers to programs which use
        XRouter to provide their connectivity with the outside world. 

        Unlike its 16 bit forerunner, XRouter does not provide the
        BPQ Host API, but it does provide the following means for
        supporting applications: 

            - AGW TCPHOST Interface 
            - WA8DED Hostmode Emulation 
            - TNC2 Emulation 
            - KISS / SLIP / PPP
            - Remote Host Protocol (RHP) 
            - Proxies
            - TCP applications (e.g. QtTermTcp)


        Defining Applications
        ~~~~~~~~~~~~~~~~~~~~~

        Some applications, such as those using the TNC2 emulator, do
        not accept incoming connections, and this section doesn't
        apply to them.  Nor does it apply to applications accessed
        via KISS / SLIP / PPP or proxies.  For the remainder,
        read on...

        In order for applications to be able to accept incoming
        connections, they must be specified in XROUTER.CFG, using
        APPL configuration blocks.

        Each definition block must begin with APPL=<number> and must
        end with ENDAPPL.  There must be a separate block for each
        application.  Applications which use more than one stream
        need only a single definition.  The APPL block should contain
        one or more of the following keywords:

        APPLNAME  The nickname or shortcut by which the application
                  is accessed from XRouter's command line. e.g.
                  "PMS".  If a user types this name at the command
                  prompt, they will be connected to the application.

        APPLCALL  The AX25 layer 2 callsign which the application
                  will use. If specified, the application will accept
                  AX25 L2 connects to this callsign, subject to the
                  setting of APPLMASK (see below).

        APPLALIAS The AX25 layer 2 "alias" used by the application.
                  If specified, the application will accept AX25 L2
                  connects to this callsign, subject to the setting
                  of APPLMASK (see below). 

        APPLQUAL  Netrom quality to broadcast (0-255).  If a non-zero
                  value is specified here, the APPLCALL will be
                  included in Net/Rom nodes broadcasts and the
                  application will be connectible at AX25 layer 4.
                  The higher the quality, the further the node entry
                  will propogate. 

        APPLFLAGS defaults to 0 if omitted. The flags are as follows:

                Bit Value  Action
                ------------------
                 0    1    Application has SYSOP privileges.

                 1    2    Allow "guest" users to access the appl.

                 2    4    XRouter sends "Connected to (applcall)"
                           to the user upon connection to an
                           application.  This is not required if the
                           application  sends its own "Connected to"
                           message.

                 3    8    XRouter sends "Connected to (usercall) to
                           the application when a user connects. 

        APPLTYPE is only required for TCP applications at present.
                 The format is APPLTYPE=TCP,[ip_addr:]tcp_port
                 (ip_addr is only required if the application is on
                 a different computer)

        Most fields within an application definition block are
        optional - you may have for instance choose to have an
        APPLNAME but no APPLCALL, meaning the application could only
        be reached by typing the applname at the command prompt.

        Or you could have an APPLCALL but no APPLNAME, in which case
        the application would be directly connectable, but wouldn't
        be reachable from a command line shortcut. 
 
        The application number must be between 1 and 8.  Some BPQHOST
        applications have fixed application numbers, e.g. BBS's and
        PMS's must usually be the first application and Host programs
        such as PAC4 are usually the second.  However, since BPQHOST
        API isn't currently implemented, the choice of application
        number is arbitrary at present.

        Example for a Bulletin Board System application using WA8DED
        hostmode.  It is accessed by typing "BBS" at the command
        prompt or by connecting via AX25 or NetRom to the callsign
        GB7PZT or the alias PZTBBS:

                APPL=3
                        APPLNAME=BBS
                        APPLCALL=GB7PZT
                        APPLALIAS=PZTBBS
                        APPLQUAL=100
                        APPLFLAGS=4
                ENDAPPL

        In the following example, the application has no callsigns or
        quality, so it can only be reached by issuing the command
        "HOST" at the command prompt:

                APPL=2
                        APPLNAME=HOST
                ENDAPPL

        Example for incoming connections to a TCP application such as
        QTTERMTCP. It can be acessed by an AX25L2 connection to G9ZZZ
        or by typing "SYSOP" at the command prompt. QtTermTCP is set
        up to listen on TCP port 8015:

                APPL=1
                        APPLNAME=SYSOP
                        APPLTYPE=TCP,8015
                        APPLCALL=G9ZZZ
                ENDAPPL


        AX25 Visibility
        ~~~~~~~~~~~~~~~

        If you want an application to be directly connectible on a
        particular port, the application must have an APPLCALL, an
        APPLALIAS or both, and the corresponding bit in that port's
        APPLMASK must be set.

        APPLMASK specifies which applications will be directly
        connectible on a given port.  The default is 255, which
        allows all applications.  The value is made up by adding
        together the desired selection from the following numbers:

                      1       - Enable Application 1
                      2       - Enable Application 2
                      4       - Enable Application 3
                      8       - Enable Application 4
                      16      - Enable Application 5
                      32      - Enable Application 6
                      64      - Enable Application 7
                      128     - Enable Application 8

        For example, if a port's definition contains "APPLMASK=9", it
        will only allow direct connections to applications 1 and 4 on
        that port, providing those applications have either an
        APPLCALL or an APPLALIAS.


        Downlinking From Applications
        ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

        Certain settings of a port's CFLAGS may prevent all
        downlinking on that port.  For example, in a mixed CB/HAM
        node you may need to use CFLAGS=1 to prevent CB users from
        making L2 downlinks on the HAM port.  But that would also
        prevent HAM applications from downlinking on that port.

        This can be solved by setting bit 2 (decimal value 4) of
        CFLAGS, which allows applications to downlink
        unconditionally.

        Setting this flag allows applications to make L2 downlinks on
        ports which are closed to users, e.g. CFLAGS=1 prevents
        everyone excepts sysops from downlinking, whereas CFLAGS=5
        prevents everyon except sysops and applications from
        downlinking. See CFLAGS for more details.

</code> **SEE ALSO:** \\
[[packet:xrouter:docs:MAN6#AGWHOST|        AGWHOST(6)     -- AGW Application Support.
]] \\
[[packet:xrouter:docs:MAN7#CFLAGS|        CFLAGS(7)      -- Connection Control Flags.
]] \\
[[packet:xrouter:docs:MAN9#DEDHOST|        DEDHOST(9)     -- WA8DED Hostmode Emulator.
]] \\
[[packet:xrouter:docs:MAN9#RHP|        RHP(9)         -- Remote Host Protocol.
]] \\
[[packet:xrouter:docs:MAN9#TNC2|        TNC2(9)        -- TNC2 Emulator.
]] \\
[[packet:xrouter:docs:MAN8#XROUTER.CFG|        XROUTER.CFG(8) -- Main Configuration File.
]] \\

[[packet:xrouter:docs:|< Back to Index]]

----
===== APRS =====
<code>APRS(9)                 XROUTER REFERENCE MANUAL            21/10/2023
</code> **NAME** <code>
        APRS -- Automatic Packet Reporting System.

</code> **DESCRIPTION** <code>
        APRS is (currently) an acronym for "Automatic Packet
        Reporting System", although the name tends to change from
        time to time! (it was originally called "Automatic *Position*
        Reporting System, and there has been talk of re-branding it
        to Automatic PRESENCE Reporting System).

        It is a protocol that uses AX25 UI frames and digipeaters to
        report a wide variety of parameters such as position, speed,
        weather, bearing, status, objects, frequencies and so on.

        XRouter includes the following sub-systems that support or
        make use of APRS:

                - APRS Generic Digipeating
                - APRS Igate
                - APRS Server
                - APRS Messaging Shell
                - APRS Weather reports
                - APRS DX recording
                - APRS Queries
                - Positions, distances & directions in MH lists

        Generic digipeating is a complex type of digipeating which
        responds to special digipeater addresses, and modifies a
        packet's digipeater addresses in transit. It also prevents
        duplicates and looping.

        The Igate is a client daemon that allows APRS data to flow to
        and from between the Internet APRS system and RF ports,
        messaging shell etc.

        The APRS server allows APRS applications such as UI-view to
        use XRouter to access all the APRS data handled by XRouter.

        The APRS messaging shell allows users to send and receive
        APRS messages and bulletins.

        Weather reports are received via RF and/or Igate, and are
        made available for users to read using the WX command.

        The DX feature stores a list of the furthest stations heard
        via RF.

        APRS Queries allow RF users to query which nodes are on
        channel, what DX they heard, what messages are waiting etc.

        MHeard lists are able to display the positions, bearings and
        distances of stations that broadcast APRS data.


        Specifying XRouter's Position
        ~~~~~~~~~~~~~~~~~~~~~~~~~~

        In order for most of these systems to work, XRouter needs to
        know its position on the globe. There are currently three
        ways to achieve this...

        The easiest method is to use the "LOCATOR=" directive in
        XROUTER.CFG, which enables you to specify an approximate
        location at the centre of a 1Km "Maidenhead" locator square,
        e.g. "LOCATOR=IO82VJ".

        If you don't know your LOCATOR square, an alternative method
        is to use lATITUDE and LONGITUDE directives in XROUTER.CFG.
        These are specified in decimal degrees, which can easily be
        found from Google Maps. East and North are positive numbers,
        while South and West are specified as negative numbers. You
        should not append N S E or W.

        Another method, which allows more precise (or less precise
        if you prefer) positioning, is to include an APRS-style
        position in IDTEXT, starting within the first 40 characters.

        The format is "!ddmm.mmN/dddmm.mmE#" where dd represents
        degrees of latitude/longitude and mm.mm represents minutes
        to two decimal places. "N" and "E" may be replaced by "S"
        and "W" as appropriate. For example:

              IDTEXT
              !5224.00N/00215.00W# Kidderminster Router (KDRMIN)
              ***

        You are urged to use at least one of these methods to define
        XRouter's position. It really does make Packet more
        interesting!


        APRS Generic Digipeating
        ~~~~~~~~~~~~~~~~~~~~~~~~

        XRouter supports APRS generic digipeating for RELAY, WIDE,
        TRACE, TRACEn-N and WIDEn-N aliases.

        Generic digipeating is configured on a port by port basis,
        using the flags marked "*" in "DIGIFLAG" as follows:

              1    Digipeat UI frames (note 1)
              2    Digipeat non-UI frames (note 1)
             *4    Enable RELAY generic digipeating.
             *8    Enable TRACE generic digipeating.
             *16   Enable WIDE (Well sited stations only!)
             *32   Allow APRS 3rd party digi via L4.
             *64   Allow digipeating to Internet (IGate).
             *128  Allow digipeating from Internet (IGate).
             *256  Enable UITRACE digipeating
             *512  Enable UIFLOOD digipeating

             Add the appropriate numbers together to enable the
             desired combination of services.

        Note 1: Irrespective of the generic digipeater settings, you
        may choose to allow regular digipeating (i.e. using XRouter's
        normal callsign or alias) on APRS ports, allow regular
        UI-only digipeating, or disable regular digipeating
        altogether, by manipulating bits 0 and 1 of DIGIFLAG.


        SSID Substitution Digipeating
        ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

        UITRACE and UIFLOOD represent two special addresses that are
        suffixed with pseudo-SSID's, e.g. "TRACE4-4" and "WIDE2-2".

        These addresses can digipeat several times. The first digit
        specifies the maximum number of hops, and the second is the
        hop counter, which is decremented each time the frame is
        digipeated.

        These two addresses behave slightly differently however. When
        a frame is digipeated on the alias specified by UITRACE, each
        digipeater inserts its own callsign in the digipeater list,
        and decrements the "SSID". Frames digipeated on the UIFLOOD
        address have their SSIDs decremented, but the digi doesn't
        insert its own callsign. 

        For the sake of consistency with UI-View, UITRACE defaults to
        "TRACE", giving TRACEn-n digipeating, and UIFLOOD defaults to
        WIDE, giving WIDEn-n digipeating.


        New-N Paradigm
        ~~~~~~~~~~~~~~

        According to the APRS "New-N Paradigm", RELAY, TRACE and WIDE
        are deprecated, UITRACE should be set to "WIDE", and UIFLOOD
        should be set to a "state" code (e.g. "GBR" for the UK).

        One of the main reasons for the New-N Paradigm was the fact
        that some of the older digipeaters would digipeat the same
        packets over and over. This does not happen with XRouter.

        Not everyone agrees with the "New-N Paradigm, so the choice
        of which features to enable is left you you.


        Mixing Modes
        ~~~~~~~~~~~~

        In quiet areas, you may wish to mix APRS and normal
        connected-mode operations on the same port, and that is the
        default if you enable any of the above flags in DIGIFLAG.

        However, in most areas, APRS tends to be on a separate
        frequency reserved for "unconnected nets", and you may wish
        to prevent people from connecting to the node or downlinking
        from it on your APRS-only ports.

        The CFLAGS keyword can be used in the PORT section of the
        XROUTER.CFG file to control uplinking and downlinking as
        follows:

               0     Prevent uplinking and downlinking.
               1     allow uplinking only.
               2     allow downlinking only.
               3     allow both up and downlinking.


        ID Beacons
        ~~~~~~~~~~

        Whilst all sysops are urged to include an APRS position in
        their normal IDTEXT, a dedicated APRS port may require a more
        detailed and cryptic  ID beacon, therefore you may define a
        different IDTEXT for each port if necessary.

        A "regular" port would include a position followed by some
        human-readable text, whereas the APRS-only ports would
        include additional data such as power / height / gain /
        direction,  wind speed, bowel movements etc., in encoded
        format.

        The IDTEXT may be sent via digipeaters by including the
        IDPATH keyword in the relevant port configuration section of
        XROUTER.CFG.


        Dupe Suppression
        ~~~~~~~~~~~~~~~~

        XRouter checks for its own callsign or alias in previously
        used digipeaters to prevent digi looping.  It will not
        digipeat frames it originated, and will not digipeat the
        same frame within 9 seconds.


        DX Facility
        ~~~~~~~~~~~

        The "DX [port]" command shows the best received APRS DX. It
        only works if XRouter's position has been defined as
        described earlier.

        The DXFLAGS keyword in the .CFG file controls whether or not
        the DX list contains callsigns heard via digipeaters.

        The DX list may be queried by RF stations, by means of APRS
        queries.


        APRS / UI-View queries
        ~~~~~~~~~~~~~~~~~~~~~~

        XRouter responds to the following general queries:

            ?APRS?   All stations query. 

            ~\xFD~   UI-View general query.

            ?IGATE?  Igate query.

        The response to the first two is the ID beacon for the port,
        which should contain the APRS position and station type.  The
        response to the ?IGATE? query shows the message and local
        user counts.

        The following "directed" queries (directed at portcall) are
        supported:

            ?APRSD   Directly heard stations list.
                     Responds with a list of stations heard directly
                     on the receiving port (i.e. not via digipeaters
                     or via 3rd party networks)

            ?APRSM   Un-delivered messages query.
                     If there are any un-delivered or expired
                     messages addressed to the sender of the query,
                     they are re-activated and transmitted on the
                     port which received the query.

            ?APRSP   Station Position.
                     If the sysop has defined XRouter's position, it
                     is sent in response to this query.

            ?APRSS   Station status.
                     The response consists of the software type and
                     version plus a list of the enabled generic
                     digipeater calls.

            ?PING?
            ?APRST   Trace Route.
                     Both of these return the route by which the
                     query was received.

            ~\xFE~n  UI-View "ping".
                     The response to this query is a UI-View ack for
                     the ping id.

            ~\FC~n   UI-View "DX" query.
                     Responds with a UI-View ack, followed by details
                     of the best DX heard directly by XRouter
                     (digipeated packets are NOT included!)

        See www.aprs.org for more info about APRS.

</code> **SEE ALSO:** \\
[[packet:xrouter:docs:MAN1#AMSG|        AMSG(1)        -- APRS Messaging Mode.
]] \\
[[packet:xrouter:docs:MAN9#APRS-SRV|        APRS-SRV(9)    -- APRS Server.
]] \\
[[packet:xrouter:docs:MAN9#APRS-SVC|        APRS-SVC(9)    -- NetRomX APRS Service.
]] \\
[[packet:xrouter:docs:MAN1#DX|        DX(1)          -- Display Distant APRS stations.
]] \\
[[packet:xrouter:docs:MAN9#IGATE|        IGATE(9)       -- APRS Igate.
]] \\
[[packet:xrouter:docs:MAN1#MHEARD|        MHEARD(1)      -- Display Recently Heard Stations.
]] \\
[[packet:xrouter:docs:MAN9#MHEARD|        MHEARD(9)      -- About the MHeard Facility.
]] \\
[[packet:xrouter:docs:MAN1#WX|        WX(1)          -- Display APRS Weather Information.
]] \\
[[packet:xrouter:docs:MAN8#XROUTER.CFG|        XROUTER.CFG(8) -- Main Configuration File.
]] \\

[[packet:xrouter:docs:|< Back to Index]]

----
===== APRS-SRV =====
<code>APRS-SRV(9)             XROUTER REFERENCE MANUAL            21/10/2023
</code> **NAME** <code>
        APRS-SRV -- APRS Server.

</code> **DESCRIPTION** <code>

        XRouter includes a rudimentary APRS server, which enables
        suitable APRS clients, such as UI-View, to connect to it on
        the LAN and exchange APRS traffic.  The number of concurrent
        clients is not limited.

        The server is available via NetRomX service 14, and TCP/IP.


        TCP Port Number
        ~~~~~~~~~~~~~~~

        The server listens for incoming connections on TCP port 1448.
 
        There is a tradition of choosing port numbers for APRS
        servers which represent the frequencies used by APRS, hence
        port 1448 was chosen because XRouter originates in the UK,
        and many European countries use 144.800 MHz.

        Overview Of Server
        ~~~~~~~~~~~~~~~~~~

        The following APRS packets are sent to clients:

           - APRS traffic received by any of XRouter's radio ports.

           - Traffic sent by other clients.

           - Traffic sent by users of XRouter's APRS messaging shell.

           - Filtered traffic from Internet APRS servers (if
             XRouter's IGATE is connected to an Internet APRS server)


        APRS packets from clients are distributed as follows:

           - To other clients, excluding the sender.

           - To XRouter's APRS messaging shell.

           - To radio ports (only if client is fully registered)

           - To Internet APRS servers via IGATE (if IGATE enabled).


        Registration and Login
        ~~~~~~~~~~~~~~~~~~~~~~

        Registration of clients is necessary to prevent unauthorised
        use of radio frequencies by unlicensed people.

        This may seem overly restrictive if your system is only used
        on a private LAN, but if you are connected to the Internet,
        it is essential.

        For example, if an unlicensed user connects to your server
        via the Internet, he must be prevented from sending traffic
        to your local RF ports.  He must also be prevented from
        sending traffic via your IGATE (if it is enabled) into the
        Internet system, and thence to other people's RF ports.

        Therefore, clients are required to complete a log-in process
        before they are allowed to send any traffic.  Log-in is not
        required for receive-only operations.

        The server accepts two different types of login.  When a
        user registers an APRS client program such as UI-View, he
        receives a "validation number" which XRouter uses in
        combination with the callsign to verify the user. Verified
        users may send traffic to local RF ports, or if IGATE is
        active, via other IGATES.

        If the user has NOT registered his copy of UI-View, the
        default validation number of "-1" allows him to send traffic
        to other clients and to the Internet, but that traffic will
        not be gated locally to RF, and is marked in such a way that
        it will not be gated to RF by other IGATES. This allows
        unregistered clients to communicate with each other via the
        Internet, but not via RF.  The client may only send APRS
        packets whose source callsign matches the login callsign.

        The alternative login system allows clients to verify
        themselves by supplying their callsign and a password which
        has been agreed with the sysop.  The password replaces the
        validation number in a login string.

        The login string is the only "command" accepted by the APRS
        server, and must take the form:

             "user <callsign> pass <password>"

        where <password> could be either a validation number or a
        text string, for example, "user g8pzt pass beanzmeanzheinz",
        or "user g7zzz pass 32751". Login is not acknowledged.


        The Client Connection
        ~~~~~~~~~~~~~~~~~~~~~

        There is no time-out on client connections, therefore there
        is no need for the client to send "keep-alive" signals.

        If the client connection is too slow to cope with the
        incoming data rate, packets to the client may be discarded.


        Local <> Internet Server Gating
        ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

        If IGATE is not running, no packets are gated to or from the
        Internet.

        Packets received from the Internet are not gated to clients
        unless they satisfy the IFILTER (Internet Filter) filtering
        rules in IGATE.CFG.  Likewise, packets received from clients
        are not gated to the Internet unless they satisfy the
        PFILTER (Packet Filter) rules.

        The following traffic is NOT gated from RF to Internet

           - Packets in "third party" format.

           - Packets which do not include the network identifier
             "TCPIP" in the digi path.

           - Packets which include the dummy callsigns NOGATE or
             RFONLY in the digi path.


        Using UI-View as a Client
        ~~~~~~~~~~~~~~~~~~~~~~~~~

        Select Setup/APRS Server Setup.

        In the box marked "Select A Server", enter the hostname and
        TCP port number of XRouter's APRS server, e.g.
        "myserver:1448" or "192.168.0.2:1448".  If the client is on
        the same computer as  XRouter, use "localhost:1448" or
        "127.0.0.1:1448". (If you use a private hostname, you may
        need to add a suitable entry into the HOSTS file in the
        WINDOWS directory, or Linux equivalent.)

        Check the boxes marked "Open the gateway" and "Gate local
        messages".

        If you have a registered version of UI-View, check the box
        marked "APRServe log on required", and enter your validation
        number.

        If your copy of UI-View is unregistered, you will be able to
        log on to XRouter's APRS server with the default validation
        number of -1, but your packets will not be gated to RF.

        To obtain full privileges using an unregistered copy, you
        must have a password, which must be registered with your
        callsign in XRouter's USERPASS.SYS file.  The callsign must
        not include the SSID, e.g. if UI-View's callsign is
        "G8PZT-11", the entry in USERPASS.SYS should simply be
        "G8PZT".  Un-check the "APRServe log on required" box, and
        in the box marked "Text to send upon connection" enter
        UI-View's callsign (with SSID) and your password in the
        following form:

              user g8pzt-11 pass virago


</code> **SEE ALSO:** \\
[[packet:xrouter:docs:MAN9#APRS|        APRS(9)         -- APRS in XRouter.
]] \\
[[packet:xrouter:docs:MAN9#APRS-SVC|        APRS-SVC(9)     -- NetRomX APRS Service.
]] \\
[[packet:xrouter:docs:MAN7#APRSPORT|        APRSPORT(7)     -- TCP Port for APRS Server.
]] \\
[[packet:xrouter:docs:MAN9#IGATE|        IGATE(9)        -- APRS-Internet Gateway.
]] \\
[[packet:xrouter:docs:MAN8#IGATE.CFG|        IGATE.CFG(8)    -- Igate Configuration File.
]] \\
[[packet:xrouter:docs:MAN6#TCP-PORTS|        TCP-PORTS(6)    -- TCP Service Ports.
]] \\
[[packet:xrouter:docs:MAN8#USERPASS.SYS|        USERPASS.SYS(8) -- User Passwords File.
]] \\
[[packet:xrouter:docs:MAN8#XROUTER.CFG|        XROUTER.CFG(8)  -- Main Configuration File.
]] \\

[[packet:xrouter:docs:|< Back to Index]]

----
===== APRS-SVC =====
<code>APRS-SVC(9)            XROUTER REFERENCE MANUAL              22/9/2023

</code> **NAME** <code>
        APRS-SVC -- NetRomX APRS Service.

</code> **DESCRIPTION** <code>
        NetRomX standard service 14 is an "APRS server". This relays
        APRS packets in the following way:

        The server sends the following APRS packets to clients:

           - Traffic received by any of XRouter's radio ports.

           - Traffic sent by other clients of the server.

           - Traffic sent by users of XRouter's APRS msg shell.

           - Filtered traffic from Internet APRS servers (if
             XROUTER's IGATE is connected to such a server)


        APRS packets from clients to server are distributed as
        follows:

           - To other clients, excluding the sender.

           - To XRouter's APRS messaging shell.

           - To radio ports

           - To Internet APRS servers via IGATE (if IGATE is running).

        Traffic is in plain ASCII text, with lines delimited by
        Carriage Return (CR) (ASCII 13). For example:
 
        MB7UYL>APXR01:=5224.00N/00215.00Wn Kidderminster, Worc's
         {Xrouter 501y}

        VE2PKT-4>ID:!4625.96N/07237.66WB 147.435Mhz 1.2Kb, VE2PKT-4,
         XRPI Router

        VK2DOT-1>ID:!3323.21S/15121.42E# Niagara Park Node -
          (VK2DOT-1) 44.136.16.1

        No login is required, and no commands are accepted. Simply
        disconnect when you are finished.

</code> **SEE ALSO:** \\
[[packet:xrouter:docs:MAN9#APRS|        APRS(9)     -- APRS in XRouter.]] \\
[[packet:xrouter:docs:MAN9#APRS-SRV|        APRS-SRV(9) -- APRS Server.]] \\
[[packet:xrouter:docs:MAN9#IGATE|        IGATE(9)    -- APRS-Internet Gateway.]] \\
[[packet:xrouter:docs:MAN9#SERVICES|        SERVICES(9) -- NetRomX Standard Services.]] \\


[[packet:xrouter:docs:|< Back to Index]]

----
===== ARP =====
<code>ARP(9)                  XROUTER REFERENCE MANUAL            21/10/2023
</code> **NAME** <code>
        ARP -- Address Resolution Protocol

</code> **DESCRIPTION** <code>
        The Address Resolution Protocol handles the association
        between IP addresses and "hardware" (Ethernet or AX25)
        addresses.

        In order for IP datagrams to be handled by AX25 or Ethernet
        links, they must first be "wrapped" in AX25 or Ethernet
        packets.

        The destination addresses of these packets is determined by
        the process of "Address Resolution".

        For example, imagine that you want to send an IP datagram to
        one of your neighbour nodes via RF.  TNC's don't understand
        IP, so you can't simply transmit a raw IP datagram onto the
        airwaves.  Your node must first "wrap" the datagram in an
        AX25 frame addressed to the neighbour node.  Upon receipt by
        the neighbour, the frame is "unwrapped", and the IP datagram
        contained therein is handled by the IP router.

        Exactly the same process is required to send IP over
        Ethernet, except that Ethernet frames are used instead.

        The destination address is usually obtained from an "ARP
        Table", that stores each neighbour's IP addresses along with
        their AX25 or Ethernet address.  This table can be built
        manually using ARP commands, or dynamically.  A typical ARP
        table would contain entries similar to this:

           IP Address      Type    Hardware addr
           ------------------------------------------
           44.131.91.2     AX25    G8PZT
           44.131.90.6     AX25    G8JVM-5
           192.168.0.23    Ether   00:12:34:66:21:DA

        If the destination address is not in the ARP table, XRouter
        broadcasts an "ARP request" packet, asking if anyone knows
        the hardware address associated with the destination IP
        address.  The destination node replies with an "ARP reply",
        giving the AX25  address that the datagram should be
        addressed to.  XRouter adds this data to the ARP table, then
        uses it to wrap and send the datagram.

        The "ARP entries" in the table usally have a finite lifetime
        (usually 15 minutes), because neighbours sometimes change
        their hardware addresses.  This lifetime may be altered by
        the sysop.

        When an entry gets too old, it is purged from the table,
        forcing XRouter to send another ARP request, thus picking up
        the new hardware address. The sysop may override this by
        "locking-in" ARP entries.

        A router other than the destination may reply to an ARP
        request if it is the gateway to a "hidden" network containing
        the destination. This is called "proxy ARP", is implemented
        in XRouter and is detailed in RFC1027.

        The ARP protocol is detailed in RFC826.
 
</code> **SEE ALSO:** \\
[[packet:xrouter:docs:MAN1#ARP|        ARP(1) -- ARP Commands. ]] \\

[[packet:xrouter:docs:|< Back to Index]]

----
===== AUDIO =====
<code>AUDIO(9)                XROUTER REFERENCE MANUAL               2/9/2023
</code> **NAME** <code>
        AUDIO -- Audio Output.

</code> **DESCRIPTION** <code>
        Raspberry Pi's and modern laptops do not have the traditional
       "PC speaker", so they cannot play the usual console bells and
        alerts. However, a sound device can be used instead.

        To enable sounds (assuming a suitable sound device is
        present), put the following directive anywhere in XROUTER.CFG

        # Audio device for sound output:
        # Default OSS device is /dev/dsp (/dev/audio on Rasp pi)
        #
        AUDIODEVICE=/dev/dsp
        #

        This uses OSS, (a) because OSS has been found to work much
        better than ALSA, and (b) because ALSA requires the host
        machine to have the "libasound" library installed. The
        XRouter philosophy is to avoid dependencies where possible.

        Having said that, XRouter can be supplied in "with-ALSA"
        versions if required.

        In order to use sound, on some platforms you may need to
        first run the command:

              sudo modprobe snd-pcm-oss

        The command only needs to be run once. Thereafter XRouter
        can be started and stopped without needing to use it again.

        On some platforms the modprobe command is not needed at all,
        but Linux has been gradually phasing out OSS, making it ever
        more awkward to use.

        You could add "snd-pcm-oss" into the /etc/modules file, which
        causes it to load the module at bootup.

        If snd-pcm-oss is not found on the system, and cannot be
        installed from a repository, one method which has been found
        to be successful is to run XRouter from within an OSS
        "wrapper" program such as "aoss" like this:

               "aoss /home/pi/xrouter/xrpi"

</code> **CAVEATS** <code>
        The downside of OSS is that it won't share the audio device,
        so if you have XRouter's audio enabled but another app is
        already using the sound device, XRouter will fail at boot.

</code> **SEE ALSO:** \\
[[packet:xrouter:docs:MAN7#AUDIODEVICE|        AUDIODEVICE(7)    -- Specify Audio Device
]] \\
[[packet:xrouter:docs:MAN1#BELL|        BELL(1)           -- Console sounds control
]] \\
[[packet:xrouter:docs:MAN8#XROUTER.CFG|        XROUTER.CFG(8)    -- Main Configuration File.
]] \\

[[packet:xrouter:docs:|< Back to Index]]

----
===== AUTOQUAL =====
<code>AUTOQUAL(9)             XROUTER REFERENCE MANUAL            19/10/2023
</code> **NAME** <code>
        AUTOQUAL -- Automatic Route Quality.

</code> **DESCRIPTION** <code>
        Automatic Route Quality Measurement" (Autoqual) is an optional
        tool to help sysops set consistent and meaningful NetRom route
        qualities.

        Background
        ~~~~~~~~~~

        NetRom makes routing decisions based on a fairly arbitrary
        metric, i.e. the "route quality", which is assigned by sysops,
        and disseminated in nodes broadcasts.

        In the better-managed parts of the NetRom network, route
        qualities tend to be assigned according to the baud rate of
        the link, with adjustments for retry rates, duplex / simplex
        and shared channels.

        However, there is no standard methodology for assigning
        quality, so not only will each sysop's notion of quality
        differ from that of other sysops, but also he will probably
        incorrectly assign the relative qualities of his own links.
        This leads to inconsistency and distorted routing.

        In other parts of the network, route qualities are simply
        assigned to 192 regardless of how good or bad the link is.
        This also leads to inconsistency and less-than-optimal
        routing decisions.

        The actual "goodness" of a link may continually change with
        atmospheric conditions, data throughput, other channel
        activity, QRM etc.  At certain times of day for example, it
        may be better to use an alternative link.

        A more accurate notion of "goodness" is simply the "Round
        Trip Time" (RTT) for the link, i.e. the time taken to send a
        packet and get a reply.  After all, this is what *really*
        matters to users. A link which responds quickly (i.e. with a
        low RTT) is perceived by users to be better than a link which
        responds slowly.  The RTT will track changes in retry rate,
        channel loading etc.

        The RTT can be easily and consistently measured by software
        on a continuous basis, thus the "goodness" of the link is
        accurately known at all times, and all routers of the same
        type will give comparable values independently of the sysop's
        notions of quality.


        Implementation
        ~~~~~~~~~~~~~~

        XRouter continually measures the RTT of neighbour links and
        uses the smoothed value to calculate a notional "route
        quality" every 5 minutes.  The maximum, minimum and standard
        deviation  of this quality are calculated and recorded for
        later display, and the value is further smoothed.  
  
        The smoothed calculated quality is displayed by the "R Q"
        command, and can either be used as a guide to allow the sysop
        to fix the RQ at a sensible value, or if the route has been
        configured for it, XRouter can use it dynamically, by setting
        the route's quality to the calculated value.

        This RTT to quality conversion is tailored to the British
        notion of quality, which gives somewhat lower but more
        meaningful qualities than used elsewhere.  For example, a
        typical 1200 baud half-duplex link with low retry rate would
        produce a calculated quality around 120. A good 9600 baud half
        duplex link would equate to around 190, with 210 for a really
        good full duplex 9k6 link.

        RTT measurement primarily uses L3RTT frames, but in their
        absence it also uses measurements of traffic throughput and
        retry rate.


        Enabling Automatic Route Quality
        ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

        Route quality calculation is automatic and continuous.
        However the calculated value is not actually used without the
        sysop's consent.

        In order to allow the route quality to be automatically
        adjusted, the sysop must specify a RQ between 256 and 511
        when adding a route using the "ROUTE ADD" command. 

        Alternatively, setting the PORT quality between 256 and 511
        will cause all *new* routes (not locked in ones) learned on
        that port to use automatic quality. 
  
        A quality between 256 and 511 will instruct XRouter to use
        "automatic" quality, with an initial value of (qual-256).      

</code> **SEE ALSO:** \\
[[packet:xrouter:docs:MAN1#ROUTES|        ROUTES(1)  -- Add, Drop and List NetRom Routes.
]] \\
[[packet:xrouter:docs:MAN7#QUALITY|        QUALITY(7) -- Default NetRom Quality.
]] \\

[[packet:xrouter:docs:|< Back to Index]]

----
===== AXIP =====
<code>AXIP(9)                 XROUTER REFERENCE MANUAL            21/10/2023
</code> **NAME** <code>
        AXIP -- AX25-over-IP Tunnelling.

</code> **DESCRIPTION** <code>
        AXIP is AX25 "encapsulated" within IP datagrams.  This
        enables AX25 systems to communicate with each other via
        TCP/IP networks (e.g. the Internet).  The frame structure is
        as follows :

                .-----------.------------------------.-----.
                | IP header |        AX25 frame      | CRC |
                '-----------'------------------------'-----'
                  (20 bytes) (Typically 15-340 bytes)  2 bytes


        The AX25 links created using AXIP can in turn support NetRom
        and amateur TCP/IP, just like real radio links.


        Setting Up AXIP Links
        ~~~~~~~~~~~~~~~~~~~~~~

        Assuming you have a prospective AXIP partner, you would set
        up an AXIP link as follows:

        1)  Configure and test IP routing between you and your
            partner. If you don't have reliable IP routing there's no
            point in proceeding!

            If you are linking via the Internet, it makes sense to
            use the Internet IP addresses for this purpose, rather
            than the amateur (44.x.x.x) ones, because the routing is
            more reliable and the throughput is faster.

        2)  If your partner has a dynamic IP address, they must have
            an account with a "dynamic DNS" provider, and you must
            use the hostname thus provided for all operations.  If
            you use the IP address instead, the link will stop
            working when the address changes.

        3)  If you wish to use your prospective partner's hostname
            (e.g. "g8pzt.ath.cx") instead of their IP address, your
            system needs access to a Domain Name Server (DNS).  This
            would usually be provided by Linux nowadays, so you may
            remove all "DNS=" lines from XROUTER.CFG.

        4)  If using the partner's hostname, verify that
            "PING <hostname>" resolves the address correctly.

        5)  Add an AXIP interface to XROUTER.CFG as follows:

                INTERFACE=7
                    TYPE=AXIP
                    MTU=256
                ENDINTERFACE

            (Choose the interface number to suit yourself).

            This interface can support an unlimited number of AXIP
            PORTs.  You may define multiple interfaces if your ports
            need different MTU's.

            Only TYPE=AXIP and MTU= are required, all other
            parameters are ignored (at present).

        6)  For each AXIP partner, add a PORT similar to this:

                PORT=8
                    ID=AXIP link with WA3IP
                    INTERFACENUM=7   <-- Points to INTERFACE above
                    IPLINK=55.73.88.69
                    FRACK=2000
                    RESPTIME=200
                ENDPORT

            You must specify at least ID, INTERFACENUM, and IPLINK.  

            IPLINK is the remote host's IP address or hostname. It is
            more efficient to use IP addresses, if you are able to do
            so, because it removes the need to resolve the hostnames,
            but see (2) above.   The assigned "protocol number" for
            AXIP is 93 (decimal).
            
            MAC parameters such as TXDELAY, TXTAIL, FULLDUP, PERSIST, 
            SLOTTIME, SOFTDCD etc. are meaningless for AXIP, but
            FRACK, RESPTIME, PACLEN, MAXFRAME, QUALITY etc. operate
            as normal.  
          
            On fast internet links you may wish to use a much lower
            FRACK, say 2000ms, than on radio.  It is not recommended
            that you reduce it much below 1000ms, as it needs to be
            *at least* twice the worst round-trip time plus the other
            end's RESPTIME.
        
            RESPTIME is probably the one which will have most effect
            on the responsiveness of the AX25 link, because it
            controls the time delay between receiving a packet and
            sending an ACK.  It should be just a little more than the
            time it takes to receive a maximum length packet.  For
            example, at a data rate of 56Kbits/sec, a 256 byte packet
            lasts less than 50msec, so RESPTIME=50 would be adequate.
            However the timing jitter due to operating under Windows
            means that RESPTIME should be more like 200ms.

        7)  If XRouter is indirectly connected to the Internet via an
            intermediate router, that router will probably be using
            some form of NAT (Network Address Translation) to share
            one "public" IP address between several systems on your
            LAN.  The "front end" router will probably route outgoing
            AXIP without problem, but it will not know where to send
            incoming AXIP unless explicitly configured.

            Configuring such a router for AXIP usually involves
            specifying a protocol number (93 for AXIP), and the LAN
            IP address of a machine to which it should be routed,
            i.e. XRouter's LAN IP address.

            You are advised that not all domestic routers can be
            configured to route incoming AXIP as it is not a
            commercially recognised protocol.  Some routers only
            allow TCP and UDP port redirection, with no provision for
            any other protocol.  If you or your link partner have
            such a router, you may need to consider AXUDP instead -
            see later.

        8)  Your link partner must set up a reciprocal arrangement,
            i.e. their IPREMOTE must be set to your public IP address
            or hostname.

        If everything has been set up correctly, you should be able
        to connect with your new neighbour node immediately, at least
        at AX25 layer 2.  You can test this by entering the command
        "C n ALIAS-1", where n is the PORT number of your link, and
        ALIAS is the node alias of your link partner. If this doesn't
        work, you or your partner have made a mistake somewhere in
        the configuration.

        Even if everything is configured correctly, it may take a
        while for NetRom to configure itself for the new link, as the
        nodes need to exchange NODES broadcasts first.  Once they
        have done so, there should be no delays in future.


        Notes
        ~~~~~

        You may of course use AXIP to communicate between nodes on
        the LAN, as long as they are not on the same machine.

        If you have more than one node on your LAN using AXIP, your
        Internet router is only able to direct incoming AXIP to *one*
        of them.  This means you can only have one AXIP node per
        public IP address.

        DO NOT set up an AXIP link to a link partner if you already
        have an AXUDP link.  This is a common mistake, and is likely
        to cause problems!

        Using one port per neighbour may seem wasteful, but it is a
        reliable method, and it allows you to monitor exactly what is
        going on.

 
        IP Routing Over AXIP
        ~~~~~~~~~~~~~~~~~~~~

        As mentioned earlier, you may route amateur IP (44.x.x.x) over
        your new AXIP link, and are encouraged to do so. Whilst the
        amprnet purists will argue that this is not as efficient as
        IP-over-IP (since it uses a few more bytes), it is a LOT
        easier to set up, and doesn't require that your domestic
        router and operating system can route IP-over-IP (many
        routers are not able to route incoming IP-over-IP to a
        specific PC, and Windows' IP stack totally blocks IP-over-IP).

        To route amateur IP over an AXIP link, simply add an IP route
        entry directing the required subnet to your neighbour's IP
        address on the AXIP port using datagram mode. For example, if
        the AXIP port is port 8, and the link partner (44.136.20.2)
        is able to accept all amprnet traffic for Australia, the
        entry would look like this:

           IP ROUTE ADD 44.136.0.0/16  44.136.20.2  8  d

        The source IP address for this mode of routing is the
        IPADDRESS of the AXIP port. Therefore, if XRouter's main
        IPADDRESS (in XROUTER.CFG) is not a 44-net address, you must
        override it with a 44-net address on the AXIP port.  If the
        main IPADDRESS is a 44-net address, which is the recommended
        configuration, do not specify IPADDRESS in the PORT
        configuration block.

</code> **SEE ALSO:** \\
[[packet:xrouter:docs:MAN9#AXUDP|        AXUDP(9)        -- AX25-over-UDP Encapsulation
]] \\
[[packet:xrouter:docs:MAN1#IP|        IP(1)           -- IP Routing / Configuration Commands.
]] \\
[[packet:xrouter:docs:MAN9#IPENCAP|        IPENCAP(9)      -- IP-in-IP Encapsulation.
]] \\
[[packet:xrouter:docs:MAN1#IPLINK|        IPLINK(1)       -- Display / Set a Port's IPLINK.
]] \\
[[packet:xrouter:docs:MAN7#IPLINK|        IPLINK(7)       -- Peer Address of a Link.
]] \\
[[packet:xrouter:docs:MAN9#IP-PRIMER|        IP-PRIMER(9)    -- IP Addressing / Routing Primer.
]] \\
[[packet:xrouter:docs:MAN8#IPROUTE.SYS|        IPROUTE.SYS(8)  -- IP Routing / Configuration File.
]] \\
[[packet:xrouter:docs:MAN8#XROUTER.CFG|        XROUTER.CFG(8)  -- Main Configuration File
]] \\

[[packet:xrouter:docs:|< Back to Index]]

----
===== AXSCTRL =====
<code>AXSCTRL(9)              XROUTER REFERENCE MANUAL            19/10/2023
</code> **NAME** <code>
        AXSCTRL -- TCP/IP Access Control.

</code> **SYNOPSIS** <code>
        This file deals with "access control", and is mainly of
        concern if your system is directly connected to a non-amateur
        TCP/IP network such as the Internet.

</code> **DESCRIPTION** <code>
        Some of the users who access your system via the Internet may
        be genuine Radio Amateurs, who may legitimately downlink on
        radio frequencies, while other users may not. And different
        countries may have different rules governing the
        inter-connection of radio and non-radio networks.

        Therefore some form of configurable access control is
        required, and this is provided by the entries in ACCESS.SYS,
        which specify the login requirements according to the
        caller's IP address. For example you may specify that hosts
        on your private LAN require no password.

        If ACCESS.SYS is not present, the default action is for logins
        to require a valid callsign only.

        The entries in ACCESS.SYS allow various levels of access
        control, e.g. username only, valid amateur radio callsign
        only, username plus password, and valid callsign plus
        password. They may also be configured for "guest access".
        This is intended to let people look around, but not to do
        anything that would cause a transmission to be made.

        Guests are prevented from using the SEND, CHAT and CONNECT
        commands, and from sending APRS messages using the APRS
        messaging shell.  For the TELNET command they are restricted
        by the rules in the file TELGUEST.ACL. If that file is not
        present, guests are denied access to the TELNET command.

        Guests are not necessarily unlicenced people. They may simply
        be hams who don't yet have a password for your system.

        If an entry in ACCESS.SYS specifies that a login password is
        required, the password should be located in file USERPASS.SYS.

        Failure to meet the access requirements results in immediate
        disconnection of the caller.

        Sysop access using the "@" command, RLOGIN (tcp port 513) and
        FTP do not use USERPASS.SYS, and are all controlled instead
        by entries in the sysop password file, PASSWORD.SYS.

        The "@" command, which is normally performed on publicly
        visible radio links, uses the password to send a grid of
        numbers, from which the caller must select one line and send
        the matching characters from the password.

        FTP uses the password grid method, but can be configured to
        use use plain password (secure wired links only) if SYSOP=1
        has been included in the appropriate PORT configuration in
        XROUTER.CFG.

        RLOGIN must only be used on secure wired networks because the
        caller must send the password itself.  

        Access to the APRS server is normally controlled by the
        "Validation number" which the user obtains from the author of
        his APRS client program upon registration.  However, if the
        user has not registered his client, he may be granted access
        to the server by including his callsign and a password in
        USERPASS.SYS.

        The Telnet Proxy and AGWHOST servers also use passwords in
        USERPASS.SYS.

        For further information you are referred to the sections
        detailing the ACCESS.SYS, PASSWORD.SYS and USERPASS.SYS
        files.

</code> **SEE ALSO:** \\
[[packet:xrouter:docs:MAN8#ACCESS.SYS|        ACCESS.SYS(8)   -- Telnet Access Control File.
]] \\
[[packet:xrouter:docs:MAN9#APRS-SRV|        APRS-SRV(9)     -- APRS Server.
]] \\
[[packet:xrouter:docs:MAN9#IDS|        IDS(9)          -- Intrusion Detection System.
]] \\
[[packet:xrouter:docs:MAN8#PASSWORD.SYS|        PASSWORD.SYS(8) -- Sysop Password File.
]] \\
[[packet:xrouter:docs:MAN8#USERPASS.SYS|        USERPASS.SYS(8) -- User Passwords File.
]] \\
[[packet:xrouter:docs:MAN8#XROUTER.CFG|        XROUTER.CFG(8)  -- Main Configuration File.
]] \\

[[packet:xrouter:docs:|< Back to Index]]

----
===== AXTCP =====
<code>AXTCP(9)                XROUTER REFERENCE MANUAL             29/9/2023

</code> **NAME** <code>
        AXTCP -- AX25-over-TCP Tunnelling.

</code> **DESCRIPTION** <code>
        AXTCP is AX25 "encapsulated" within a TCP stream.  This
        enables AX25 systems to communicate with each other via TCP/IP
        networks (e.g. the Internet) in a similar way to AXIP and
        AXUDP.  The frame structure is as follows:

            .-----.--------.---------.--------------------.-----.
            | Len | IP hdr | TCP hdr |      AX25 frame    | CRC |
            '-----'--------'---------'--------------------'-----'
        Bytes: 2      20       20       Typically 15-340     2

            (Len = (framelength-2), CRC = Cyclic Redundancy Check)

        AXTCP is particularly useful when it isn't possible to route
        AXIP or AXUDP, as detailed below:

        The Problem
        ~~~~~~~~~~~ 
        Many people in the UK use mobile broadband "dongles" to
        provide their Internet connection, either because it's a lower
        cost option than fixed-line broadband, or because the latter
        is not available in their area, or because they're "roving".

        As an example of the latter, a "mobile" node may be
        established in a vehicle and used to provide a local packet
        "hot-spot" for special events, emergency datacomms etc. It may
        be using mobile broadband, WiFi or other available Internet
        connections, and it is highly unlikely that such a connection
        could be configured to route AXIP or AXUDP. 

        The characteristics of mobile Internet which prevent the use
        of AXIP or AXUDP are that (a) the subscriber's IP address is
        volatile (so you can't set IPLINK), and (b) the subscriber is
        on a private network behind a NAT firewall, which doesn't pass
        incoming AXIP or AXUDP traffic!

        The solution
        ~~~~~~~~~~~~
        AXTCP offers a solution to these problems.  It differs from
        AXIP and AXUDP in three respects:

        - Firstly, it uses a bidirectional stream protocol (TCP/IP)
          which guarantees that the packets can flow in both
          directions, even through several stages of NAT and
          firewalling.

        - Secondly, it uses a client-server approach where the fixed
          server has no need to know the mobile client's IP address
          and port number.  The connection is initiated by the client,
          and the server simply responds via that connection.

        - And thirdly, the TCP protocol ensures that no AX25 packets
          are lost. 

        The AX25 links created using AXTCP can in turn support NetRom
        and amateur TCP/IP, just like real radio links.

        To use AXTCP, the "static" node is configured as an AXTCP
        server, and the "mobile" node as an AXTCP client.


        Configuring XRouter for AXTCP
        ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
        AXTCP is enabled by declaring an INTERFACE with TYPE=AXTCP. A
        single PORT is then attached to that interface.

        AXTCP interfaces can act as server, client, or both at once,
        depending on which keywords are included.

        An AXTCP server can support several simultaneous client
        connections, and a client can connect to several servers
        simultaneously.

        Note: When configuring a server, you must ensure that incoming
        TCP/IP connections are directed to the server's TCP port, i.e.
        there must be suitable NAT entries or "port forwarding" set
        up in the Internet "front end" router.
 

        Example AXTCP Server Interface
        ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
        The following configures an AXTCP server, listening for
        clients on TCP port 9393:

                INTERFACE=5           <-- change to suit yourself
                        TYPE=AXTCP
                        MTU=256
                        INTNUM=9393   <- Server port
                ENDINTERFACE

        The INTNUM parameter activates the server and specifies the
        TCP port that it listens on.  If this is zero, or not
        specified, the server is disabled. 


        Example AXTCP Client Interface
        ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
        This specifies a client which connects with the KIDDER node,
        whose address is g8pzt.ath.cx, port 9393:
 
                INTERFACE=5
                        TYPE=AXTCP
                        MTU=256
                        CONFIG=KIDDER g8pzt.ath.cx 9393
                ENDINTERFACE

        The CONFIG directive is used to specify a server, thereby
        activating client mode.  The format is as follows:

             CONFIG=<servalias> <hostname | ipaddr> <tcp_port>

        You may specify additional servers, by including a CONFIG for
        each one.  There is no limit to the number of CONFIG
        directives that can be used with a single interface. 


        Combined AXTCP Client/Server Interface
        ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
        A combined interface is specified by including both INTNUM and
        CONFIG directives.  For example, this combines a server
        listening on TCP port 9393 with 3 client connections: 
        
                INTERFACE=5
                        TYPE=AXTCP
                        INTNUM=9393
                        MTU=256
                        CONFIG=DORSET 216.23.45.91 10093
                        CONFIG=WALES gw3xr.dyndns.org 9394
                        CONFIG=Brum bm23.ath.cx 7507
                ENDINTERFACE

        This is just an example, and it could only be used at a
        "static" node, in which case the client connections could
        be replaced by AXIP or AXUDP anyway.

        Such a configuration *couldn't* be used for "mobile" node,
        because there's no way of directing incoming TCP port 9393 to
        a mobile server!  


        AXTCP PORT Settings
        ~~~~~~~~~~~~~~~~~~~
        A PORT attached to an AXTCP interface needs no special
        configuration, and should simply be configured with
        parameters (FRACK, RESPTIME, RFBAUDS) approriate to a high
        speed connection, for example:

                PORT=8
                    ID=AXTCP Operations
                    INTERFACENUM=5
                    FRACK=2000
                    RESPTIME=200
                    RFBAUDS=56000
                ENDPORT

        MAC parameters such as TXDELAY, TXTAIL, SLOTTIME, PERSIST,
        FULLDUP, SOFTDCD etc. are meaningless for AXUDP, but FRACK,
        RESPTIME, PACLEN, MAXFRAME, QUALITY etc. operate as normal.  
          
        On fast internet links you may wish to use a much lower FRACK,
        say 2000ms, than on radio.  It is not recommended that you
        reduce it much below 1000ms, as it needs to be *at least*
        twice the worst round-trip time plus the other end's RESPTIME.
        
        RESPTIME is probably the one which will have most effect on
        the responsiveness of the AX25 link, because it controls the
        time delay between receiving a packet and sending an ACK.  It
        should be just a little more than the time it takes to receive
        a maximum length packet.  For example, at a data rate of
        56Kbits/sec, a 256 byte packet lasts less than 50msec, so
        RESPTIME=50 would be adequate.  However the timing jitter due
        to operating under Windows means that RESPTIME should be more
        like 200ms.

        By default, all AXTCP connections use the same PORT, but if
        you prefer to use one port per neighbour, see the following
        section.  You must NOT attach more than one PORT to an AXTCP
        interface. 


        Multiple Interfaces / Ports
        ~~~~~~~~~~~~~~~~~~~~~~~~~~~
        A single AXTCP server can accommodate many clients, so there
        is no practical need to use more than one AXTCP interface and
        port.

        This is analogous to having several nodes on the same radio
        frequency, except that the nodes don't see each other's
        transmissions, and there is no "hidden station" effect.

        You may however prefer to assign each AXTCP partner to a
        seperate port, analogous to having a dedicated radio
        frequency for each neighbour.  In this case you may configure
        several interfaces, each with a single PORT attached.

        The only proviso is that if INTNUM is used, no two AXTCP
        interfaces may use the same INTNUM.


        Transaction Logging
        ~~~~~~~~~~~~~~~~~~~
        If the AXTCP option of LOGFLAGS is non-zero, XRouter logs
        AXTCP connections and disconnections, otherwise nothing is
        logged.

</code> **NOTES** <code>
        When a client connects to a server, it should immediately be
        possible to force an AX25 level 2 connection from either
        client or server, by entering the command "C n ALIAS-1",
        where n is the AXTCP port number, and ALIAS is the node alias
        of the peer.

        However, it may take a few minutes for the client and server
        to commence NetRom operations, because each end must first
        receive a nodes broadcast from the other.  The link-up time
        will be shorter if a prior link has been made recently.  It
        is hoped to speed up the linking time in a later version.

</code> **SEE ALSO:** \\
[[packet:xrouter:docs:MAN6#AXTCP-IFACE|        AXTCP-IFACE(6)  -- AXTCP Interface.
]] \\
[[packet:xrouter:docs:MAN9#AXIP|        AXIP(9)         -- AX25-over-IP Encapsulation
]] \\
[[packet:xrouter:docs:MAN9#AXUDP|        AXUDP(9)        -- AX25-over-UDP Encapsulation
]] \\
[[packet:xrouter:docs:MAN8#XROUTER.CFG|        XROUTER.CFG(8)  -- Main Configuration File
]] \\

[[packet:xrouter:docs:|< Back to Index]]

----
===== AXUDP =====
<code>AXUDP(9)                XROUTER REFERENCE MANUAL            21/10/2023
</code> **NAME** <code>
        AXUDP -- AX25-over-UDP Tunnelling.

</code> **DESCRIPTION** <code>
        AXUDP is AX25 "encapsulated" within UDP datagrams.  This
        enables AX25 systems to communicate with each other via
        TCP/IP networks (e.g. the Internet).  The frame structure is
        as follows:

          .-----------.------------.------------------------.-----.
          | IP header | UDP header |        AX25 frame      | CRC |
          '-----------'------------'------------------------'-----'
               (20 bytes)  (8 bytes)   (Typically 15-340 bytes) 

        It is slightly less efficient than AXIP, because there is an
        extra 8 byte UDP header between the IP header and AX25
        portion of the frame, but the difference is not significant.  

        One of the problems with AXIP is that many domestic routers
        cannot be configured to route AXIP to a specific PC. And even
        if they can, it can only be routed to one PC. This means you
        can only have one AXIP node per public IP address.

        The major advantage of AXUDP over AXIP is that it can usually
        be handled by domestic Internet routers without problem. And
        since UDP is a "ported" protocol (AXIP is "portless") you may
        have more than one AXUDP node on the same public IP address,
        by assigning them different UDP ports. The domestic router is
        then able to route incoming packets according to UDP port.

        The AX25 links created using AXUDP can in turn support NetRom
        and amateur TCP/IP, just like real radio links.

</code> **OPTIONS** <code>
        There are two main ways to set up formal AXUDP links, namely
        "One-Link-Per-Port" (recommended) or "Many-Links-Per-Port"
        (the BPQ way). Configuration of these is discussed later.

        Although "One-Link-Per-Port" uses more PORTs, it is the more
        flexible option. It is analagous to a full duplex radio link
        on a private frequency. It allows all the link parameters to
        be configured independently of any other link. It also allows
        the traffic to be monitored and captured without clutter from
        other traffic. It is more efficient in terms of processing,
        and supports connections to any of the peer's callsigns,
        SSIDs or aliases without any extra configuration.

        The "Many-Links-Per-Port" option is analogous to a radio link
        on a shared frequency. All ax25 connections have to share the
        same PORT parameters, and it is difficult to monitor one link
        without clutter from the others. It is computationally less
        efficient, and only supports connections to pre-defined SSIDs
        and aliases.

        Both of the above methods can co-exist.

</code> **CONFIGURATION** <code>
        Assuming you have a prospective AXUDP partner, both of the
        above mentioned methods require steps 1 through 5 below:

        1)  Configure and test IP routing between you and your
            partner. If you don't have reliable IP routing there's no
            point in proceeding!

            If you are linking via the Internet, it makes sense to
            use the Internet IP addresses for this purpose, rather
            than the amateur (44.x.x.x) ones, because the routing is
            more reliable and the throughput is faster.

        2)  If your partner has a dynamic IP address, they must have
            an account with a "dynamic DNS" provider, and you must
            use the hostname thus provided for all operations.  If
            you use the IP address instead, the link will stop
            working when the address changes.

        3)  If you wish to use your prospective partner's hostname
            (e.g. "g8pzt.ath.cx") instead of their IP address, your
            system needs access to a Domain Name Server (DNS).  This
            would usually be provided by Windows or Linux nowadays,
            so you may remove all "DNS=" lines from XROUTER.CFG.

        4)  If using the partner's hostname, verify that
            "PING <hostname>" resolves the address correctly.

        5)  Add an AXUDP interface to XROUTER.CFG as follows:

                INTERFACE=9
                    TYPE=AXUDP
                    MTU=256
                ENDINTERFACE

            (Choose the interface number to suit yourself).

            This interface can support an unlimited number of AXUDP
            PORTs.  You may define multiple interfaces if your ports
            need different MTU's.

            Only TYPE=AXUDP and MTU= are required, all other
            parameters are ignored (at present).

        Step 6 has two mutually exclusive alternatives. 6a is for
        "One-Link-Per-Port" and 6b is for "Multiple-Links-Per-Port".

        6a) One-Link-Per-Port:

            For each AXUDP partner, add an AXUDP port similar to this:

                PORT=8
                    ID=AXUDP link with VK1UDP
                    INTERFACENUM=9
                    IPLINK=27.69.88.73
                    UDPLOCAL=93
                    UDPREMOTE=93
                    FRACK=2000
                    RESPTIME=200
                ENDPORT

            You must specify at least ID, INTERFACENUM, and IPLINK.  

            IPLINK is the link partner's IP address or hostname.  It
            is more efficient to use IP addresses, if you are able to
            do so, because it removes the need to resolve the
            hostnames, but see (2) above.

            UDPLOCAL and UDPREMOTE are the UDP "service port" numbers
            for each end of the link, and if omitted they default to
            93 (don't confuse these with *protocol number* 93, which
            is AXIP). The numbers are independent, e.g. you may use
            93 for UDPLOCAL and 10093 for UDPREMOTE). 

            MAC parameters such as TXDELAY, TXTAIL, FULLDUP, PERSIST, 
            SLOTTIME, SOFTDCD etc. are meaningless for AXUDP, but
            Layer 2 parameters such as FRACK, RESPTIME, PACLEN,
            MAXFRAME, QUALITY etc. operate as normal.  
          
            On fast Internet links you may wish to use a much lower
            FRACK, say 2000ms, than on radio.  It is not recommended
            that you reduce it much below 1000ms, as it needs to be
            *at least* twice the worst round-trip time plus the other
            end's RESPTIME.
        
            RESPTIME is probably the one which will have most effect
            on the responsiveness of the AX25 link, because it
            controls the time delay between receiving a packet and
            sending an ACK.  It should be just a little more than the
            time it takes to receive a maximum length packet.  For
            example, at a data rate of 56Kbits/sec, a 256 byte packet
            lasts less than 50msec, so RESPTIME=50 would be adequate.
            However the timing jitter due to operating under Windows
            means that RESPTIME should be more like 200ms.

        6b) Multiple-Links-Per-Port

            This mode requires only ONE port, configured similar to
            the following:

               PORT=8
                    ID=AXUDP links
                    INTERFACENUM=9             
                    IPLINK=0.0.0.0
                    UDPLOCAL=10093
                    PEER=VK2DOT:DOTXR vk2dot.dyndns.org 9394
                    PEER=G8PZT-7 127.0.0.1 2345
                    PEER=G9DUM-3:DUMMY g9dum.ath.cx 10078
                    FRACK=2000
                    RESPTIME=200
                ENDPORT

            IPLINK must be present and must be exactly "0.0.0.0",
            otherwise it won't work.

            UDPLOCAL is the UDP service number on which XRouter
            listens for incoming AXUDP packets. This MUST be different
            from the service numbers used on any other PORTs.

            Note that UDPREMOTE must NOT be used in this case. The
            PEER statements are used instead.

        7)  If XRouter is indirectly connected to the Internet via an
            intermediate router, that router will probably be using
            some form of NAT (Network Address Translation) to share
            one "public" IP address between several systems on your
            LAN.  The "front end" router will probably route outgoing
            AXUDP without problem, but it will not know where to send
            incoming AXUDP unless explicitly configured.

            Configuring such a router for AXUDP usually involves
            specifying a UDP port number (your UDPLOCAL as specified
            above), and the LAN IP address of a machine to which it
            should be routed, i.e. Xrouter's LAN IP address. This is
            sometimes called "port forwarding".  There are websites
            (e.g. portforward.com) dedicated to showing you how to do
            this for most makes of router. 

            Some routers don't have the facility to open specific UDP
            ports, but at the very least should allow you to direct
            all UDP traffic to a specified IP address.

        8)  Your link partner must set up a reciprocal arrangement,
            i.e. their UDPREMOTE must match your UDPLOCAL and vice
            versa.

        If everything has been set up correctly, you should be able
        to connect with your new neighbour node immediately, at least
        at AX25 layer 2.  You can test this by entering the command
        "C n ALIAS-1", where n is the PORT number of your link, and
        ALIAS is the node alias of your link partner. If this doesn't
        work, you or your partner have made a mistake somewhere in
        the configuration.

        Even if everything is configured correctly, it may take a
        while for NetRom to configure itself for the new link, as the
        nodes need to exchange NODES brodcasts first.  Once they have
        done so, there should be no delays in future.


</code> **NOTES** <code>
        You may of course use AXUDP to communicate between nodes on
        the LAN, or even on the same machine.

        If you have more than one node on your LAN using AXUDP, your
        UDPLOCAL must not be the same as the UDPLOCAL (or equivalent
        thereof) of any other node on your LAN.  There are two
        reasons for this; Firstly, for a given UDP port, NAT routers
        cannot direct direct incoming traffic to more than one LAN IP
        address at a time.  Secondly, only one application on a PC
        may "own" a given UDP port number.

        Unlike other software, you *DO NOT* need a different UDPLOCAL
        for each AXUDP port.  It is quite common for link partners to
        specify that they will transmit AXUDP to you on a UDP port
        that is different to your other UDPLOCAL settings.  There is
        absolutely *NO* valid reason for this! It makes life more
        complicated for you, and you have to set up extra "port
        forwarding" entries in your NAT router.  For these reasons
        you are strongly advised to use the same UDPLOCAL for all
        AXUDP partners on a given node.  As a rule, you may NOT tell
        a link partner what his UDPLOCAL should be, no more than he
        should dictate what your UDPLOCAL should be. Instead, he
        should specify which UDP port he is listening on (which
        becomes your UDPREMOTE), and in return you tell him which UDP
        port you are listening on (which becomes his UDPREMOTE).

        DO NOT set up an AXUDP link to a link partner with whom you
        already have an AXIP link.  This is a common mistake, and is
        likely to cause problems!


</code> **IP ROUTING** <code>
        As mentioned earlier, you may route amateur IP (44.x.x.x)
        over your new AXUDP link, and are encouraged to do so. Whilst
        the amprnet purists will argue that this is not as efficient
        as IP-over-IP (since it uses a few more bytes), it is a LOT
        easier to set up, and doesn't require that your domestic
        router and operating system can route IP-over-IP (many
        routers are not able to route incoming IP-over-IP to a
        specific PC, and Windows' IP stack blocks IP-over-IP).

        To route amateur IP over an AXUDP link, simply add an IP
        route entry directing the required subnet to your neighbour's
        IP address on the AXUDP port using datagram mode. For
        example, if the AXUDP port is port 8, and the link partner
        (44.136.20.2) is able to accept all amprnet traffic for
        Australia, the entry would look like this:

           IP ROUTE ADD 44.136.0.0/16  44.136.20.2  8  d

        The source IP address for this mode of routing is the
        IPADDRESS of the AXUDP port. Therefore, if XRouter's main
        IPADDRESS (in XROUTER.CFG) is not a 44-net address, you must
        override it with a 44-net address on the AXUDP port.  If the
        main IPADDRESS is a 44-net address, which is the recommended
        configuration, do not specify IPADDRESS in the PORT
        configuration block.

</code> **SEE ALSO:** \\
[[packet:xrouter:docs:MAN9#AD-HOC|        AD-HOC(9)       -- Ad-Hoc Networking.
]] \\
[[packet:xrouter:docs:MAN9#AXIP|        AXIP(9)         -- AX25-over-IP Encapsulation
]] \\
[[packet:xrouter:docs:MAN1#IP|        IP(1)           -- IP Routing / Configuration Commands.
]] \\
[[packet:xrouter:docs:MAN9#IPENCAP|        IPENCAP(9)      -- IP-in-IP Encapsulation.
]] \\
[[packet:xrouter:docs:MAN1#IPLINK|        IPLINK(1)       -- Display / Set a Port's IPLINK.
]] \\
[[packet:xrouter:docs:MAN7#IPLINK|        IPLINK(7)       -- Peer Address of a Link.
]] \\
[[packet:xrouter:docs:MAN9#IP-PRIMER|        IP-PRIMER(9)    -- IP Addressing / Routing Primer.
]] \\
[[packet:xrouter:docs:MAN8#IPROUTE.SYS|        IPROUTE.SYS(8)  -- IP Routing / Configuration File.
]] \\
[[packet:xrouter:docs:MAN7#LEARN|        LEARN(7)        -- Learn Unsolicited AX*P Peer Details.
]] \\
[[packet:xrouter:docs:MAN1#UDPLOCAL|        UDPLOCAL(1)     -- Display / Set a Port's UDPLOCAL.
]] \\
[[packet:xrouter:docs:MAN1#UDPREMOTE|        UDPREMOTE(1)    -- Display / Set a Port's UDPREMOTE.
]] \\
[[packet:xrouter:docs:MAN8#XROUTER.CFG|        XROUTER.CFG(8)  -- Main Configuration File
]] \\

[[packet:xrouter:docs:|< Back to Index]]

----
===== BCAST =====
<code>BCAST(9)              XROUTER REFERENCE MANUAL              21/10/2023
</code> **NAME** <code>
        BCAST -- UI Broadcasting.

</code> **DESCRIPTION** <code>
        XRouter has the ability to "re-broadcast" a received UI frame
        onto several ports at once.  This can be thought of as a
        "one-to-many" PIPE, but there are subtle differences:

        Whereas pipes conduct all frames of the selected type(s),
        virtually regardless of source and destination addresses
        (unless they are selective pipes), the broadcast function
        acts only upon UI frames, and only if the source and
        destination addresses match those specified by the sysop.

        Another difference is that frames may be broadcast to
        different groups of ports depending on the destination
        address.  For example, FBB unproto headers from a BBS may be
        rebroadcast on certain user-access ports only, while mail
        beacons may be distributed to a different, possibly
        overlapping, set of ports.

        You may alternatively use this feature as a "filtered pipe"
        between two ports, allowing only UI frames with acceptable
        source and destination callsigns to pass through.

        Note that this feature does not require a "connection" to
        XRouter, it is purely an unconnected mode.  It was developed
        to allow BBS's to distribute mail beacons and "unproto" mail
        headers.  You may use it (or not) how you wish.

        You should be aware that broadcast traffic takes precedence
        over all other frames, so an excessively high level of
        broadcast activity may cause other outbound traffic on the
        destination port to be delayed. However, it is unlikely that
        anyone will notice this effect unless the channel is
        seriously overloading.

        Broadcasting is controlled by two keywords in each PORT
        section of the XROUTER.CFG file.  The first keyword is BCAST,
        which is used to specify the destination addresses to be
        broadcasted.

        For example, BCAST=MAIL,FBB will re-broadcast received
        non-digipeater UI frames addressed either to FBB or MAIL.
        The frames addressed to FBB will be broadcast on all ports
        which have FBB in their BCAST list, and those addressed to
        MAIL are broadcast on all ports which have MAIL in the BCAST
        list.

        If no matching ports are found, the frame is broadcast only
        on the port upon which it is received.  If you don't need the
        broadcast function, simply omit (or comment out) the BCAST
        directive.

        The second keyword is BCFROM, which is used to specify a list
        of callsigns from whom frames will be accepted for broadcast.

        You may use this to restrict the broadcast facility to
        certain senders only. BCFROM applies only to frames
        *directly* received on the port for which it is specified. 
        e.g. BCFROM=GB7PZT,GB7MAX stipulates that only frames from
        GB7MAX and GB7PZT will be accepted for broadcast.  If the
        keyword is omitted, the broadcast facility is unrestricted.
        
        For both keywords, the list of callsigns must be separated by
        commas, and must include no spaces.

</code> **CAVEATS** <code>
        Be careful not to configure BCAST and PIPE together in a way
        which causes infinite loops. This is a common cause of
        crashes.

</code> **SEE ALSO:** \\
[[packet:xrouter:docs:MAN7#BCAST|        BCAST(7)       -- Destinations for UI Broadcasting.
]] \\
[[packet:xrouter:docs:MAN7#BCFROM|        BCFROM(7)      -- Approved UI Broadcasters.
]] \\
[[packet:xrouter:docs:MAN9#PIPES|        PIPES(9)       -- Frame Pipes.
]] \\
[[packet:xrouter:docs:MAN8#XROUTER.CFG|        XROUTER.CFG(8) -- Main Configuration File.
]] \\

[[packet:xrouter:docs:|< Back to Index]]

----
===== CHARGEN =====
<code>CHARGEN(9)             XROUTER REFERENCE MANUAL               7/9/2023
</code> **NAME** <code>
        CHARGEN -- Character Generator Service

</code> **SYNOPSIS** <code>
        This file describes XRouter's Character Generator service,
        which is intended for testing purposes.

</code> **DESCRIPTION** <code>
        The CHARGEN service generates a stream of characters for
        testing purposes. It is very bandwidth hungry and should be
        used with caution. It uses the same "well known" service
        number (19) as the TCP/IP version.

        Upon opening a connection to NetromX service 19, the server
        starts sending lines of characters to the caller, and
        continues until the caller send "/x" followed by newline,
        or closes the connection. The server accepts no other
        commands.

        Conforming to the de-facto standard, each line of 72
        characters is offset by one. This creates a pattern which
        makes it easy to spot dropped characters. Here's an idea
        of what it looks like:

        c g8pzt 19
        G8PZT-1:MOBILE} Trying G8PZT::19...
        G8PZT-1:MOBILE} Connected to G8PZT::19

        "#$%&'()*+,-./0123456789:;<=>?@ABCDEFGHIJKLMNOPQRSTUVWXYZ
        #$%&'()*+,-./0123456789:;<=>?@ABCDEFGHIJKLMNOPQRSTUVWXYZ[
        $%&'()*+,-./0123456789:;<=>?@ABCDEFGHIJKLMNOPQRSTUVWXYZ[\ 
        %&'()*+,-./0123456789:;<=>?@ABCDEFGHIJKLMNOPQRSTUVWXYZ[\]
        &'()*+,-./0123456789:;<=>?@ABCDEFGHIJKLMNOPQRSTUVWXYZ[\]^
        '()*+,-./0123456789:;<=>?@ABCDEFGHIJKLMNOPQRSTUVWXYZ[\]^_
        ()*+,-./0123456789:;<=>?@ABCDEFGHIJKLMNOPQRSTUVWXYZ[\]^_`
        )*+,-./0123456789:;<=>?@ABCDEFGHIJKLMNOPQRSTUVWXYZ[\]^_`a

        and so on...

</code> **SEE ALSO:** \\
[[packet:xrouter:docs:MAN9#SERVICES|        SERVICES(9)  -- NetRomX Services.
]] \\

[[packet:xrouter:docs:|< Back to Index]]

----
===== CHAT-SRV =====
<code>CHAT-SRV(9)             XROUTER REFERENCE MANUAL            21/10/2023
</code> **NAME** <code>
        CHAT-SRV -- CHAT Server.

</code> **DESCRIPTION** <code>
        XRouter's integral chat server allows groups of users to hold
        live multi-way conversations without having to manage several
        TNC streams at once.

        It is available to all callers, and is accessed by using the
        CHAT command at the main prompt, or by connecting to NetRomX
        service 2, or by connecting directly to the server's callsign
        or alias.  TCP/IP users can additionally access it by
        TELNETting to port 3600 (this port can be reassigned or
        disabled using the CHATPORT directive in XROUTER.CFG).

        Sysops have a "always-on" chat window for chatting amongst
        themselves on channel 1234, and there is a "chat monitor"
        window for keeping an eye on chat activity.

        The server is tri-standard, i.e. it can exist on, and
        interact with, 3 completely different types of chat network
        simultaneously, namely XRchat, "Tampa Ping Pong Converse",
        and W0RLI RoundTable chat, as used by BPQ.

        XRouter's chat server is a fully functional RoundTable node,
        however data is NEVER transferred between networks. e.g. what
        is said on the RoundTable network is never propogated around
        the XRchat network and vice versa.


        Channels
        ~~~~~~~~

        The "XRchat" system has 32767 channels or " chat rooms", each
        of which can support an unlimited number of users, so it is
        possible for groups to have their own "private" room, or to
        reserve certain rooms for specific topics.

        Channels 1 to 255 (except 101 - see below) are "local" to
        each chat server, and the remaining channels 256-32767 are
        "global", i.e. they are linked with all other XRouter chat
        servers, providing there is at least one link set up with
        another server.

        Room 101 is a gateway to the W0RLI "RoundTable" / BPQChat
        network, providing there is at least one link with a
        RoundTable or BPQChat peer. Within room 101, users may create
        and occupy private chat spaces called "topics". The default
        topic at login is "general".

        In addition to the "positive" channel numbers, there are
        another 32768 channels numbered 0 to -32767.  These
        correspond to channels 0 to 32767 on the "Tampa Ping Pong"
        system.

        XRouter allows only limited interconnection between these two
        systems, because the channel layouts and topologies are
        completely incompatible.  XRchat was specifically designed
        for use on an anarchic, slow radio network, whereas Ping-Pong
        requires a more planned network topology to avoid loops, and
        is largely carried on Internet links.  The sheer volume of
        chat in the Ping-Pong system would overwhelm marginal radio
        links.

        Data received from Ping-pong is not propogated via the
        XRouter chat interlinks and vice versa.  In effect, XRouter
        can be a stub Ping-Pong host, but not part of the Ping-Pong
        backbone.  

        Channel 1000 is the default channel to which users are
        assigned at log-on, but they may set their preferred login
        channel using the "/CHANNEL DEFAULT" command.

        Users may "join" as many channels as they wish, so they may
        take part in several separate conversations at once. Users
        may listen on any number of positive and negative channels
        simultaneously, but may only *send* on one channel at a time.

        Once logged onto a channel, anything sent by the user is
        copied to all other users of that channel, except for lines
        beginning with a forward slash (/), which are interpreted as
        chat server commands.  The  distributed text is prefixed by
        the channel number and the sender's callsign and name, to
        allow the recipients to identify who sent it.


        Commands
        ~~~~~~~~

        All chat server commands begin with a forward slash (/), and
        most of them may be abbreviated to the initial letter.  The
        /? command shows the available commands and syntax, while
        /HELP gives more details. 

        The /NAME command is used to enter the user's first name, and
        serves as a "login".  Users are not permitted to join any
        channels until they have supplied a name.  TCP/IP users must
        additionally supply a callsign with the /USER command.

        /CHANNEL, /JOIN and /LEAVE are used to select the desired
        channel, /WHO shows the active channels and who is using them,
        and /QUIT terminates the chat session.  The full command set
        is shown in more detail in the command reference section.

        Users who log on to more than one chat server at once are
        treated as separate entities, and must supply their name and
        callsign on each server. Note that the RoundTable network
        does not allow a user to be logged on at more than one server,
        but there are often valid reasons for doing so, therefore the
        XRchat protocol allows multiple logins by design.


        Configuration
        ~~~~~~~~~~~~~

        The chat server is fully automatic and requires minimal
        setting up. It is configured using entries in XROUTER.CFG as
        follows:

        CHATCALL defines the chat callsign for AX25 and NetRom
        operations. A SSID of -8 is strongly recommended for all
        XRchat systems.

        CHATALIAS specifies the alias for AX25 and NetRom operations.
        It is recommended that this should begin with something
        geographically relevant, and end with "CHT" e.g. BHMCHT for
        Birmingham, LDSCHT for Leeds etc., so it can be easily
        identified in node tables.

        CHATQUAL specifies the NetRom "quality" assigned to the chat
        server and alias for L3/4 operations. If set to 0, the server
        will not be visible on the network.
        A setting of 255 makes the chat server as visible as the
        node, which just fills up the nodes tables. A value somewhere
        in between, to give medium visibility, is suggested.

        CHATLOG specifies the amount of detail that is logged. A value
        of 0 suppresses logging. Add together the values corresponding
        to the desired options from this table:

                1      Local user connect / disconnect event
                2      Remote user connect / disconnect event
                4      Peer server connect / disconnect event
                8      Local channels 1-255 join / leave events
                16     Public channel join / leave events
                32     Log channel notifications
                64     Log the text of conversations
                128    Use a single logfile, instead of daily ones


        CHATPORT adjusts or disables the TCP port which the chat
        server normally listens on. The default is 3600, but you may
        need to adjust this if you have another system or application
        using that port.    

        CHATLINKS specifies the callsigns of other servers to link to.

        - Only NetRom links are allowed with RoundTable/BPQChat peers.

        - Only TCP/IP links are allowed to Tampa Ping-Pong peers.

        - Links with XRChat peers may use either NetRom or TCP/IP,
          but NetRom is the norm.

        If NetRom linking is used, you must specify the peer's
        CALLSIGN not the alias. The peer's callsign and alias must
        exist in your nodes table, i.e. you can't link with peers
        beyond the NetRom "horizon".
   
        Unilateral linking is not allowed, and will not work.  You
        *must* co-ordinate it with your peers, such that you are in
        their CHATLINKS list and they are in yours.

        You should avoid linking to peer servers via slow links.  If
        the link isn't up to the job, frames will be dumped, and the
        users will therefore get a poor service.

        Peer links may be added and removed at any time using the
        /LInks command.


        Links With XRouter Peers
        ~~~~~~~~~~~~~~~~~~~~~~~~

        NetRom links with XRouter chat peers are specified in
        XROUTER.CFG as follows (you can put several peers in one
        CHATLINKS directive, or use one directive per link, or any
        combination thereof):

                CHATLINKS=<netrom_call>,<netrom_call>,...
           e.g. CHATLINKS=GB7GH-7,GB7BM-8,N0LBA-8

        or at the chat command prompt:

                /LI ADD <netrom_call>
           e.g. /LI ADD GB7BX-9

        For TCP/IP links with XRouter chat peers, the IP address and
        TCP "port" number must be specified, along with the CHATALIAS
        of the peer server, and you can only specify one peer per
        line.

                CHATLINKS=<ip_address>:<tcp_port> <peer_alias>
        e.g.    CHATLINKS=67.69.96.23:3600 KDRCHT

        or at the chat command prompt:

                /LI ADD <ipaddress>:<tcp_port> <peer_alias>
                /LI ADD 67.69.96.23:3600 KDRCHT
     

        Links with RoundTable/BPQ Peers
        ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

        Links with RoundTable/BPQ chat servers are defined similarly
        to the XRchat NetRom case, except that the peer callsigns
        must be prefixed with a '+', for example

                CHATLINKS=+XE1FH-11,+N1FGR
        or      /LI ADD +XE1FH-11

        The '+' is very important - it tells XRouter to use
        RoundTable protocol instead of XRchat protocol!


        Links with Tampa Ping-Pong Peers
        ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

        Links with Tampa Ping-Pong converse servers are specified in
        XROUTER.CFG as follows. Note the <peername> is prefixed with
        a '*' to distinguish it        from an XRchat TCP entry:

                CHATLINKS=<ip_address>:<tcp_port> *<peername>
        e.g.    CHATLINKS=80.195.22.67:3601 *brmcht

        Alternatively, use the /LINK ADD command

                /LI ADD <ipaddress>:<tcp_port> *<peername> 
        e.g.    /LI ADD 80.195.22.67:3601 *brmcht

      
</code> **FILES** <code>
        The chat server stores user accounts in the CHAT subdirectory,
        and reads its HELP files from CHAT/HELP/ subdirectory.      

        If transaction logging has been enabled by a non-zero CHATLOG
        directive in XROUTER.CFG, chat server activity is recorded in
        the LOG subdirectory.  If the "use single logfile" option is
        enabled, everything is logged to file CHATSERV.LOG, otherwise
        it is logged to dialy logfiles with names in the form
        yymmddCH.LOG, where yymmdd are the year, month and day.

</code> **AVAILABILITY** <code>
        The chat server is available to all users. It is also
        available via the HTTP and MQTT interfaces.

</code> **SEE ALSO:** \\
[[packet:xrouter:docs:MAN1#CHAT|        CHAT(1)        -- CHAT command.
]] \\
[[packet:xrouter:docs:MAN1#CHATCMDS|        CHATCMDS(1)    -- Chat server commands.
]] \\
[[packet:xrouter:docs:MAN7#CHATALIAS|        CHATALIAS(7)   -- Chat Server Alias.
]] \\
[[packet:xrouter:docs:MAN7#CHATCALL|        CHATCALL(7)    -- Chat Server Callsign.
]] \\
[[packet:xrouter:docs:MAN9#CHAT-SVC|        CHAT-SVC(9)    -- NetRomX Chat Service.
]] \\
[[packet:xrouter:docs:MAN7#CHATPORT|        CHATPORT(7)    -- TCP Port for Chat Server.
]] \\
[[packet:xrouter:docs:MAN9#MQTT-CHAT|        MQTT-CHAT(9)   -- MQTT Interface to Chat Server.
]] \\
[[packet:xrouter:docs:MAN8#XROUTER.CFG|        XROUTER.CFG(8) -- Main Configuration File.
]] \\

[[packet:xrouter:docs:|< Back to Index]]

----
===== CHAT-SVC =====
<code>CHAT-SVC(9)            XROUTER REFERENCE MANUAL              22/9/2023

</code> **NAME** <code>
        CHAT-SVC -- NetRomX CHAT (Converse) Service.

</code> **DESCRIPTION** <code>
        NetRomX "standard service" no. 8 connects to XRouter's
        integral chat server. This server allows groups of users to
        hold real-time (and non-real-time) text conversations.

        The service is used by the "CHAT <nodecall>" command, but is
        open to all, and no login is required.

        The server has a comprehensive set of commands, which all
        begin with a forward slash (/), for example /HELP. These are
        fully documented in the CHATCMDS manual pages, and in the
        chat server's own HELP system.

</code> **SEE ALSO:** \\
[[packet:xrouter:docs:MAN1#CHAT|        CHAT(1)     -- CHAT command.]] \\
[[packet:xrouter:docs:MAN1#CHATCMDS|        CHATCMDS(1) -- Chat server commands.]] \\
[[packet:xrouter:docs:MAN9#CHAT-SRV|        CHAT-SRV(9) -- Chat Server.]] \\
[[packet:xrouter:docs:MAN9#SERVICES|        SERVICES(9) -- NetRomX Services]] \\

[[packet:xrouter:docs:|< Back to Index]]

----
===== DAYT-SVC =====
<code>DAYT-SVC(9)             XROUTER REFERENCE MANUAL               7/9/2023
</code> **NAME** <code>
        DAYTIME -- DAYTIME Service.

</code> **DESCRIPTION** <code>
        The DAYTIME service returns the node's current local date and
        time, for test or general interest purposes. It is accessed
        via NetromX standard service 13.

        Upon connection to service 13, the server sends the local
        time as a single line of text. The response is currently like
        this, but may change in future to include timezone and DST:

              Thu May 20 16:37:24 2021

        When the caller has received the text, the server terminates
        the connection.

</code> **SEE ALSO:** \\
[[packet:xrouter:docs:MAN9#SERVICES|        SERVICES(9)  -- NetRomX Standard Services.
]] \\

[[packet:xrouter:docs:|< Back to Index]]

----
===== DEDHOST =====
<code>DEDHOST(9)              XROUTER REFERENCE MANUAL            21/10/2023
</code> **NAME** <code>
        DEDHOST -- WA8DED Hostmode Emulation.

</code> **DESCRIPTION** <code>
        XRouter can emulate a WA8DED TNC, in both "normal" mode and
        "host" mode. This can be used for both manual operations and
        application support, just like a real TNC.  Many applications
        are capable of using WA8DED host mode. See the MAN page for
        WA8DED for details of normal emulation mode.

                .---------.                  .-----.
        User -->| XRouter |------RS232-------| BBS |
                '---------'                  '-----'

        The application may be located on the same machine as
        XRouter, connected to it either via a pair of "virtual" COM
        ports, or via a pair of "real" COM ports interconnected with
        a null-modem cable.

        Alternatively, the application may be located on a seperate
        machine, using an RS232 null-modem cable to interconnect the
        machines. 


        Configuring XRouter To Support Applications
        ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

        1) Decide how to interconnect the application and XRouter.

           You can use either a pair of real COM ports and a
           null-modem cable, or a tty/pty pair 

        2) Add an INTERFACE.

           In XROUTER.CFG specify an interface similar to this, where
           "x" represents the interface number...
 
               INTERFACE=x
                    TYPE=ASYNC
                    COM=/dev/ttyUSB0
                    PROTOCOL=DEDHOST
                    APPLNUM=3
                    CHANNELS=4
                    SPEED=9600
                    FLOW=0
                    MTU=256
               ENDINTERFACE

           COM is the name of the serial device used to link to the
           application (on DOS / Windows this would be a COM number). 

           CHANNELS specifies the max no. of host channels the
           interface will provide (between 1 and 32). The total
           number of host channels available to be shared between all
           applications is 64. If XRouter cannot allocate the
           requested number of channels it will fail to start. (In
           versions up to 200e the number of channels was specified
           by INTNUM. This is now deprecated.) 

           MTU must be 256 

           APPLNUM (1-16???) specifies which application is using
           this interface. Corresponds to "n" in APPL=n (see below). 

           SPEED is the serial baud rate . Don't use too low a speed,
           otherwise badly-written applications may lose sync due to
           the time it takes for a poll to reach XRouter and the
           reply to reach the application. Speeds of 9600 and above
           should be OK. 

           FLOW must always be set to 0 or 4. Setting FLOW to any
           value other than 0 or 4 may cause the application or
           XRouter to hang. FLOW=4 is a special case which forces
           the WA8DED emulator to default to host mode (see later). 

           - Don't use CHANNEL, IOADDR, or INTNUM keywords. 

           - Don't try to attach any PORTs to this interface, as they
             are not required. 


        3) Define an Application:

           In XROUTER.CFG add an APPL=n block, to specify the
           application's callsign, alias, Netrom quality and
           visibility. The "n" parameter must match the APPLNUM
           specified in the INTERFACE block. For example: 

               APPL=3
                    APPLNAME=BBS
                    APPLCALL=GB7PZT
                    APPLALIAS=PZTBBS
                    APPLQUAL=100
                    APPLFLAGS=4
               ENDAPPL

           The application definition (APPL) block should contain one
           or more of the following keywords: 

           APPLNAME is the nickname or shortcut by which the
                    application is accessed from the XRouter's
                    command line. In the example above, if a user
                    types "BBS" at the command prompt, they will be
                    connected to the application. 

           APPLCALL is the AX25 layer 2 callsign which the
                    application will use.  If specified, the
                    application will accept AX25 L2 connects to this
                    callsign, subject to the setting of APPLMASK
                    (see below). 

           APPLALIAS is the AX25 layer 2 "alias" for use by the
                    application. If specified, the application will
                    accept AX25 L2 connects to this callsign, subject
                    to the setting of APPLMASK (see below). 

           APPLQUAL (0-255) is the Net/Rom quality to broadcast. If a
                    non-zero value is specified here, the APPLCALL
                    will be included in Net/Rom nodes broadcasts and
                    the application will be connectible at AX25 layer
                    4. The higher the quality, the further the node
                    entry will propogate. 

           APPLFLAGS defaults to 0 if omitted. A value of 4 instructs
                    XRouter to send "Connected to (applcall)" to the
                    user upon connection to an application. This may
                    be omitted if the application sends its own
                    "Connected to" message. 

           All fields within an application definition block are
           optional - you may have for instance choose to have an
           APPLNAME but no APPLCALL, meaning the application could
           only be reached by typing the applname at the command
           prompt. Or you could have an APPLCALL but no APPLNAME, in
           which case the application would be directly connectible,
           but wouldn't be reachable from a command line shortcut. 


        4) Set Application Visibility.

           In XROUTER.CFG set the APPLMASK on each PORT that you wish
           the application to appear on. The application will only
           monitor traffic and send UNPROTOs on the ports which have
           the application enabled via the APPLMASK.

           The APPLMASK parameter specifies which applications are
           directly connectible on a port. The default is 255, which
           allows all applications.  The value is made up by adding
           together the required options from the following numbers: 

                  1 - Enable Application 1  
                  2 - Enable Application 2  
                  4 - Enable Application 3  
                  8 - Enable Application 4  
                 16 - Enable Application 5  
                 32 - Enable Application 6  
                 64 - Enable Application 7  
                128 - Enable Application 8  

                Example: APPLMASK=5 (enable applications 1 and 3) 

           If you want an application to be directly connectible on a
           port, it must have either an APPLCALL or an APPLALIAS (or
           both), and the corresponding bit in that port's applmask
           must be set. 


        5) Configure The Application

           Finally, configure the application to use WA8DED hostmode
           on the other of the chosen COM port pair, with the same
           baud rate as specified in the INTERFACE block. 
 

        Default Mode
        ~~~~~~~~~~~~

        The default mode (host mode / terminal mode) is controlled by
        the FLOW parameter in the INTERFACE definition block. With
        FLOW=0, XRouter's WA8DED emulation starts in non-host
        ("terminal") mode because most applications expect it that
        way, therefore it allows them to sync up quickly. 

        However, some applications may expect the TNC to be in host
        mode, and may fail to sync if FLOW=0. In this case, setting
        FLOW=4 forces the WA8DED "TNC" to start in host mode. 

        This control is not a panacea. For example, If XRouter is
        stopped and restarted while an application is running in
        hostmode, everything should quickly sync up again if FLOW=4.
        But this setting may prevent the application from syncing up
        from cold. 

 
        Starting / Stopping Applications
        ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

        Where possible, XRouter should be started before the
        application, and stopped after it, because some applications
        malfunction if they don't see the expected responses when
        they start up and shut down. 

        If an application doesn't close down "cleanly", it may take a
        while to resync when it restarts. This is normal. 

 
        Hidden Applications
        ~~~~~~~~~~~~~~~~~~~

        If you have an application that only makes outgoing
        connections, you can omit the APPL block altogether. The
        application will still work, but it won't accept incoming
        connects. 

 
        Known Issues
        ~~~~~~~~~~~~

        a) FBB 16-bit versions 700g and 700i use 100% CPU when
           configured for WA8DED hostmode. The BBS seems to work OK
           despite this.  Although this is not an XRouter issue, we
           are looking at ways to fix the problem.

        b) WinFBB v701-35 often reports "Error initialising WA8DED
           Driver" and fails to communicate with XRouter after that.
           It usually boots cleanly if stopped and restarted.  The
           best setting for FLOW is 0.

        c) With WinFBB v701-35, the sysop is able to open a gateway
           connection to XRouter's command processor and make
           outgoing connections.  However, whilst incoming
           connections are accepted, WinFBB only sends the SID
           [FBB-701-ABFHMR$] and nothing else. It doesn't respond to
           any command.

        d) If XRouter is stopped and restarted within a short time,
           WinFBB v701-35 will resync cleanly. However, if too long
           an interval elapses before XRouter restarts, WinFBB goes
           into meltdown and will never resync.

        e) Although WinFBB 701-35 appears to run in DED mode, it
           doesn't run properly, and is therefore unusable as a BBS
           in this mode.

        f) If Com0Com is used without the "enable buffer overrun"
           option checked, closing the application may sometimes
           cause XRouter to hang until the application is restarted. 
 

        Breaking out of host mode
        ~~~~~~~~~~~~~~~~~~~~~~~~~

        If the emulator is inadvertently switched into, or left in,
        host mode it can be easily be returned to terminal mode using
        Hyperterm as follows: 

        - Send ctrl-a's slowly (1 or 2 per sec) until "INVALID
          COMMAND" appears (it may take up to 256 ctrl-a's to make
          this happen, but usually it will take a lot less). Stop
          sending ctrl-a's as soon as the response appears. If you
          inadvertently send one or two too many, *slowly* send up to
          4 more ctrl-a's and the message should appear again.

        - Send JHOST0 (there will be no response)

        - Send <esc> and it should display the "* " to indicate that
          it is in command mode. 
  

        Troubleshooting
        ~~~~~~~~~~~~~~~

        1) XRouter reports "All Host Ports in use" upon first attempt
           to connect to DEDHOST application:

           - The APPLNUM in the INTERFACE definition block does not
             match the application number specified in the APPL
             definition block. 

        2) Application frequently loses sync:

           - Serial port baud rate too low?
             If the baud rate is too low, the data may take too long
             to propogate back and forth between XRouter and the
             application, causing the application to think it has
             lost sync.  Good applications would adjust their polling
             rate according to the baud rate.  Unfortunately some
             don't!

           - Serial port baud rate too high?
             If the baud rate is too high the serial line may drop
             characters, causing loss of sync. Another, more likely,
             issue is that with high baud rates the "timeout" between
             the application sending a poll and expecting a reply may
             be too short for a multitasking operating system, even
             though it is OK for a firmware TNC.

           - FLOW not set to 0 or 4

           - The PC is too busy.
             Unlike a real TNC, XRouter does not have sole use of the
             CPU. Other processes may "steal" CPU time, causing a
             delay in responding to the application's polls. In most
             cases this shouldn't happen, but some applications poll
             too fast. The only solution is to avoid running
             CPU-hungry applications on the same PC.

           - Excessive tracing on XRouter's console.
             Writing characters to the console is very CPU-intensive,
             so having MON ON can cause delays in the poll-response
             cycle if the amount of trace traffic is heavy. Turning
             MON OFF or tracing fewer ports should alleviate the
             problem.

        3) XRouter hangs when application is stopped:

           - XRouter's RS232 output buffer is full and something is
             preventing it from emptying. - If using Com0Com virtual
             COM port emulator, check the "Enable buffer overrun"
             boxes - Use FLOW=0.
 
        4) Application won't sync if XRouter is stopped and restarted

           - XRouter's DEDHOST emulation starts in non-host mode
             because most applications expect it that way. This
             allows them to sync up quickly when they are started
             AFTER XRouter.  However, if XRouter is restarted while
             the application is running, the application won't know
             that XRouter is back in non-host mode, and will fail to
             sync. 

        5) Can't connect to application on port N / Can't monitor
           port N

           - The port's APPLMASK is not set correctly (see above for
             description of APPLMASK)

           - There is a bug in early versions - Although up to 16
             applications are allowed, if APPLNUM is more than 8, the
             application cannot be connected to.

        6) Application is monitoring port N uncesessarily.

           - The default APPLMASK setting for each port allows access
             to, and monitoring by, all applications. If you wish to
             suppress connections and monitoring on a particular
             port, you must set APPLMASK accordingly. To suppress all
             applications, set the port's APPLMASK to 0. 


        Random Factoids...
        ~~~~~~~~~~~~~~~~~ 

        - Uplinks and downlinks to DEDHOST applications show as link
          type "DED" on XRouter's "Users" display. 

</code> **SEE ALSO:** \\
[[packet:xrouter:docs:MAN9#WA8DED|        WA8DED(9)      -- WA8DED TNC Emulation.
]] \\
[[packet:xrouter:docs:MAN8#XROUTER.CFG|        XROUTER.CFG(8) -- Main Configuration File.
]] \\

[[packet:xrouter:docs:|< Back to Index]]

----
===== DHCP =====
<code>DHCP(9)                 XROUTER REFERENCE MANUAL            21/10/2023
</code> **NAME** <code>
        DHCP -- Dynamic Host Configuration Protocol.

</code> **DESCRIPTION** <code>
        The acronym DHCP stands for Dynamic Host Configuration
        Protocol.  This is a client-server based protocol which
        allows clients on a TCP/IP network to obtain their
        configuration parameters from a server.

        The protocol supports the transfer of a wide range of
        configuration parameters such as the client's IP address,
        netmask, DNS and gateway addresses, plus TCP/IP parameters
        such as MSS, but is most commonly used to allocate dynamic
        IP addresses to clients.

        IP addresses are "leased" to clients for a period of time,
        after which the client must renew the lease.  Servers
        generally attempt to re-assign the same IP address to the
        same client.


        DHCP in XRouter
        ~~~~~~~~~~~~~~~

        XRouter includes a DHCP client, and a DHCP server may be
        included in future, if the need arises.  The full range of
        configuration options is not supported, since in most XRouter
        application scenarios they are not required.  The options
        currently supported are client's IP address and lease time,
        DNS and gateway IP addresses.

        The DHCP client is available only on Ethernet interfaces
        which are using the EXTERNAL driver.  Lease negotiation and
        renewal are completely automatic, and the sysop need not be
        concerned with the process.


        Do you need DHCP?
        ~~~~~~~~~~~~~~~~~

        If you wish to connect XRouter to an ISP via a cable modem,
        e.g. to use it as an Internet Connection Sharing router, you
        will probably need DHCP if your ISP uses dynamic IP
        addressing.  However, if your ISP assigns you a static IP
        address you won't need DHCP.

        You will not need DHCP if your connection to the ISP is via
        dial-up PPP, because dynamic IP addresses are assigned as
        part of the PPP negotiation process.

        *** The above scenarios date back to the time when domestic
        routers had not yet become commonplace, when Windows
        "Internet Connection Sharing" was in its unreliable infancy,
        and XRouter was running on DOS machines.  Nowadays, with
        modern ADSL and cable routers, and proper TCP/IP built into
        Windows, it is unlikely that XRouter would be required to
        provide the Internet Connection Sharing service.

        The only reason you might wish to use DHCP these days is to
        obtain a dynamic LAN IP address from your domestic router,
        but this is not recommended practice. It is far better to use
        static IP addresses when feasible, especially when you are
        "port-forwarding" TCP and UDP ports to specific machines.

        You do not need DHCP for normal amateur radio operations.


        Enabling DHCP
        ~~~~~~~~~~~~~

        In XROUTER.CFG, put "DHCP=1" in the appropriate port
        definition block.  There is no need to specify a port
        IPADDRESS because one will be assigned by the DHCP server. 

        If however, a port IPADDRESS is specified (or it is not
        specified but a global IP address is specified), that address
        will be used for non-DHCP traffic until DHCP succeeds in
        leasing a (possibly different) address.  If the global
        IPADDRESS is 0.0.0.0 or not specified, it will be assigned
        by the first client which obtains a lease.

        To disable DHCP, put "DHCP=0" in the PORT definition block,
        or simply omit the keyword altogether.

        The DHCP command displays DHCP status information, and is
        detailed in DHCP(1).

</code> **SEE ALSO:** \\
[[packet:xrouter:docs:MAN1#DHCP|        DHCP(1)        -- DHCP Commands.
]] \\
[[packet:xrouter:docs:MAN7#DHCP|        DHCP(7)        -- Obtain Port IP Using DHCP.
]] \\
[[packet:xrouter:docs:MAN8#XROUTER.CFG|        XROUTER.CFG(8) -- Main Configuration File.
]] \\

[[packet:xrouter:docs:|< Back to Index]]

----
===== DISC-SRV =====
<code>DISC-SRV(9)             XROUTER REFERENCE MANUAL            21/10/2023
</code> **NAME** <code>
        DISC-SRV -- DISCARD Server.

</code> **DESCRIPTION** <code>
        The DISCARD server is a "sink" session, whereby XRouter
        ignores (discards) everything sent to it.  This is a useful
        tool for testing connections, throughput etc.

        The server is accessed either by connecting to TCP port 9,
        or by connecting to NetRomX serice number 9, or by issuing
        the DISCARD command at XRouter's command prompt. 

        The service terminates upon receipt of "/x" followed by
        newline, or when the caller disconnects.

        The server is always available on NetRomX service 9, and
        from the command line.  It is available by default on TCP,
        but that can be changed using the DISCARDPORT=n directive in
        XROUTER.CFG.  Setting the port to zero disables direct TCP
        access to the server.

</code> **SEE ALSO:** \\
[[packet:xrouter:docs:MAN1#DISCARD|        DISCARD(1)     -- DISCARD Command.
]] \\
[[packet:xrouter:docs:MAN9#DISC-SVC|        DISC-SVC(9)    -- NetRomX Discard Service.
]] \\
[[packet:xrouter:docs:MAN9#SERVERS|        SERVERS(9)     -- Servers In XRouter
]] \\
[[packet:xrouter:docs:MAN6#TCP-PORTS|        TCP-PORTS(6)   -- TCP Service Ports.
]] \\
[[packet:xrouter:docs:MAN8#XROUTER.CFG|        XROUTER.CFG(8) -- Main Configuration File.
]] \\

[[packet:xrouter:docs:|< Back to Index]]

----
===== DISC-SVC =====
<code>DISC-SVC(9)             XROUTER REFERENCE MANUAL             22/9/2023
</code> **NAME** <code>
        DISC-SVC -- NetRomX DISCARD Service.

</code> **DESCRIPTION** <code>
        NetRomX service 9 is a DISCARD server.  This is a "sink"
        session, whereby XRouter ignores (discards) everything sent
        to it.  This is a useful tool for testing connections,
        throughput etc.

        The service terminates upon receipt of "/x" followed by
        carriage return (ascii 13) , or when the caller disconnects.
        No other commands are accepted.

        The DISCARD server can also be accessed from XRouter's
        command prompt, or by connection to TCP port 9, unless the
        sysop disables it).

</code> **SEE ALSO:** \\
[[packet:xrouter:docs:MAN1#DISCARD|        DISCARD(1)   -- Start a Discard Session.]] \\
[[packet:xrouter:docs:MAN9#DISC-SRV|        DISC-SRV(9)  -- About the Discard Server]] \\
[[packet:xrouter:docs:MAN9#SERVICES|        SERVICES(9)  -- Servers In XRouter]] \\
[[packet:xrouter:docs:MAN6#TCP-PORTS|        TCP-PORTS(6) -- TCP Service Ports.]] \\


[[packet:xrouter:docs:|< Back to Index]]

----
===== DNS-SRV =====
<code>DNS-SRV(9)              XROUTER REFERENCE MANUAL            17/10/2023
</code> **NAME** <code>
        DNS-SRV -- Domain Name Server.

</code> **DESCRIPTION** <code>
        XRouter includes a basic DNS (Domain Name System) server,
        which can answer DNS queries from other systems via the
        standard UDP port 53.

        This is a legacy from DOS XRouter, and is unlikely to be of
        much practical use on the LAN port, since Windows / Linux can
        perform the same function.

        However, it may be of use via the radio and SLIP / PPP ports.

        The server only answers one query per message. Only standard
        queries for type A are currently answered.  Recursion is
        supported.  Other query types may be supported in a later
        version, if anyone requests that functionality.

        The server can act as a DNS proxy, allowing XRouter to
        function as an Internet Connection Sharing router for a
        network of clients.  The clients on the local "intranet" send
        their DNS queries to XRouter, which either resolves them using
        its own DNS lookup (DOMAIN.SYS), or queries an external DNS on
        their behalf if necessary.

        The "intranet" mentioned above could be hosts linked via SLIP,
        PPP or even an IP-over-ham-radio LAN.

</code> **SEE ALSO:** \\
[[packet:xrouter:docs:MAN8#DOMAIN.SYS|        DOMAIN.SYS(8) -- Domain Resolution File.
]] \\

[[packet:xrouter:docs:|< Back to Index]]

----
===== DUN =====
<code>DUN(9)                  XROUTER REFERENCE MANUAL            17/10/2023
</code> **NAME** <code>
        DUN -- Dial-Up Networking.

</code> **DESCRIPTION** <code>
        Dial-Up Networking (DUN) is a subsystem which allows XRouter
        to connect to other TCP/IP systems via a dial-up Public
        Switched Telephone Network (PSTN) link.

        This could be used for example to connect with an Internet
        Service Provider (ISP), enabling XRouter to link to other
        systems via the Internet.  Or (if you have unmetered telephone
        calls) it could be used for linking one XRouter directly with
        another via the PSTN on demand.

        DUN basically consists of:

             a) A script reader capable of configuring PPP,
                controlling a modem and logging into a remote system.

             b) A system to invoke these scripts when required.

    
        Configuring DUN
        ~~~~~~~~~~~~~~~

        Please see the manual section entitled "PSTN modem support"
        for details of how to configure XRouter to use a modem.

        Assuming you have a port configured for modem use, DUN
        requires at least one dialler script, to control the dial and
        login sequence.

        Dialler scripts are ordinary text files containing script
        commands as detailed below, one per line.  Lines must not
        exceed 256 characters in length.  The script file can be named
        as you wish, for example you might like to name your AOL dial
        script "AOL.SCR".  You will need to use this name later to
        identify the script, so it makes sense to call it something
        meaningful, rather than "SCRIPT1.TXT".  Script files must
        reside in the same directory as XRouter.EXE.

        Next you must configure DUN to invoke your script whenever a
        connection is required.  This is done by using the DUN ADD
        command to record the peer's IP address and the name of the
        script used to make the connection to that peer.  If you don't
        know the IP address you may use a "dummy" address, e.g.
        "1.1.1.1", because it is simply a handle used to invoke the
        appropriate script.  You should use one DUN ADD command for
        each script.

        Finally, you must add one or more entries to the IP routing
        table whereby the "gateway" IP address is that of the peer
        (or the dummy address as mentioned above).

        For example, suppose your ISP is aol.com, and you want to
        route all UK-bound IP traffic via them.  There is a modem
        connected to port 3, and you have created a suitable
        connection script named AOL.SCR.

        a) You don't know the IP address of AOL's router, so you
           choose a dummy address of "10.10.10.10".

        b) You then issue the command "DUN ADD 10.10.10.10 AOL.SCR",
           or include it in IPROUTE.SYS or BOOTCMDS.SYS.

        c) Finally, you add a routing entry as follows:

              "IP ROUTE ADD 44.131.0.0/16  10.10.10.10  3  d"

           which means "route all 44.131.x.x (UK) traffic via (dummy)
           gateway 10.10.10.10 on port 3 (the modem port) using
           datagram mode.

        Whenever XRouter receives a frame with a destination address
        in the 44.131 series, it will now invoke the dial script
        AOL.SCR.


        DUN Script Commands Overview
        ~~~~~~~~~~~~~~~~~~~~~~~~~~~~

              CONTROL    Raise / lower RS232 DTR signal.
              MODE       Protocol to use upon successful login.
              PPP        PPP configuration commands.
              SEND       Send text.
              SLEEP      Temporary pause.
              WAIT       Wait for text in received data.


        DUN Script Commands In Detail
        ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

        CONTROL - Raise / Lower RS232 DTR signal.

                Syntax: C[ontrol] <up | down>

                The CONTROL command is used to raise or lower the
                RS232 DTR (Data Terminal Ready) line.  Most modems
                require the DTR signal to be "up", and will disconnect
                or reset when it goes down.  Those modems which do not
                do this by default can usually be configured to do so
                by including "&D2" in the initialisation string.


        MODE    - Set protocol to use upon successful login.

                Syntax:  M[ode] <kiss | ppp | slip>
                Example: MODE PPP

                MODE specifies the protocol to use after your system
                has logged into the remote host, i.e. when the script
                ends without error.  It must precede the dialling and
                login sequence, and any protocol dependent commands,
                such as the PPP commands.


        PPP     - PPP configuration commands.

                Syntax:  P[pp] <idle | ipcp | lcp | log | pap> [arg]
                Example: PPP IDLE 300

                PPP commands are used to configure the PPP subsystem
                for the connection being established.  Note that
                within DUN scripts the <port> argument is omitted
                because XRouter knows which port the script is using.


        SEND    - Send a line of text.

                Syntax:  S[end] <text>
                Example: SEND ATDT01674302153

                The SEND command sends one line of text to the modem
                or the remote host, for example modem initialisation
                and dial commands, or login commands.  The <text>
                argument may contain spaces, and the system will
                append a carriage return/line feed.


        SLEEP   - Temporary pause.

                Syntax: SL[eep] <millisecs>
                Example: SLEEP 5000

                The SLEEP command causes the script to pause for the
                specified interval.  For example, you would need a
                short delay after issuing a modem reset command
                before any more commands would be accepted by the
                modem.  When the pause is complete, script execution
                continues on the next line.


        WAIT    - Wait for received text.

                Syntax: W[ait] <millisecs> <string> [exiterr]
                Example: WAIT 5000 Password: exiterr

                WAIT makes XRouter wait for specific responses from
                the modem or remote host.  <millisecs> specifies the
                maximum wait interval.  <string> specifies the string
                of characters (20 chars max, no spaces) to wait for.
                When the string is seen in the received data stream,
                the next script command is executed.

                If "exiterr" is present, the script will abort if the
                string is not seen before the interval expires.  If
                not present, the next script command will be executed
                upon timeout.


        Dial up networking may be administered "on the fly" using the
        DUN command , which is detailed in the sysop command reference
        section. The DUN ADD and DUN LOG commands may also be used in
        IPROUTE.SYS and / or BOOTCMDS.SYS to configure the system at
        boot time.


        Example DUN script
        ~~~~~~~~~~~~~~~~~~

        ; Xrouter DUN script for establishing PPP connection with ISP
        ;
        ; Upon connection, the ISP sends some greetings text, then
        ;   "Login:", and waits for login name.
        ;
        ; Upon receiving the login name it sends "Password:" and
        ;   waits for the caller to send the password.
        ;
        ; Upon receiving the password, the ISP sends
        ;   "Entering PPP mode".
        ;
        ;
        ; Drop DTR to reset any modem error condition
        control down
        ;
        ; Wait for 1 sec
        sleep 1000
        ;
        ; Raise DTR to allow normal operation
        control up
        ;
        ; Specify the mode to use after link is established
        mode ppp
        ;
        ; ISP requires PAP authentication: username=gb7pzt,
        ;   password=bsfjflavs
        ppp pap user gb7pzt bsfjflavs
        ;
        ; Get the modem's attention
        send AT
        ;
        ; Wait for up to 5 secs for an "OK" response.  Abort if none
        wait 5000 OK exiterr
        ;
        ; Modem is awake.  Dial the ISP
        send ATDT01905643000
        ;
        ; Wait for up to 1 minute for the "user:" login prompt
        wait 60000 user exiterr
        ;
        ; Prompt obtained. Send username
        send gb7pzt
        ;
        ; Don't bother waiting for "password:" prompt, just send
        ;   it after 1 sec.
        sleep 1000
        send bsfjflavs
        ;
        ; Wait for confirmation of entry to PPP mode
        wait 30000 PPP exiterr
        ;
        ; ISP is now in PPP mode.  XRouter will enter PPP mode when
        ;   script ends
        ;


</code> **FILES** <code>
        BOOTCMDS.SYS, IPROUTE.SYS and dialler scripts all reside in
        the same director as XRouter.EXE.

</code> **CAVEATS** <code>
        DUN development was halted abruptly before it had been
        properly finalised, debugged and documented.  You are
        therefore urged to use it with caution, and report any bugs.

</code> **SEE ALSO:** \\
[[packet:xrouter:docs:MAN8#BOOTCMDS.SYS|        BOOTCMDS.SYS(8) -- Boot Up Commands File
]] \\
[[packet:xrouter:docs:MAN1#DIAL|        DIAL(1)         -- Dialler Commands.
]] \\
[[packet:xrouter:docs:MAN1#DUN|        DUN(1)          -- Dial-Up Networking.
]] \\
[[packet:xrouter:docs:MAN8#IPROUTE.SYS|        IPROUTE.SYS(8)  -- IP Routing / Configuration File.
]] \\
[[packet:xrouter:docs:MAN1#PPP|        PPP(1)          -- Point to Point Protocol Commands.
]] \\
[[packet:xrouter:docs:MAN9#PSTN|        PSTN(9)         -- PSTN Modem Support.
]] \\

[[packet:xrouter:docs:|< Back to Index]]

----
===== DX-SVC =====
<code>DX-SVC(9)              XROUTER REFERENCE MANUAL              22/9/2023
</code> **NAME** <code>
        DX-SVC -- NetRomX DX Service.

</code> **DESCRIPTION** <code>
        The "DX" service uses NetRomX service number 27. It is
        normally used by the "DX <nodecall>" function.

        It is not intended for direct connection by humans, but such
        operation is possible, as described below:

        Upon connection to service 27, the user must send a valid
        DX command, such as "DX" to show the DX from all ports, or
        "DX 16" to restrict the DX list to port 16.  Only DX commands
        are accepted; any other command will cause disconnection.

        The connection is terminated by the server when the transfer
        is complete.

        It would be possible for automated network crawlers to use
        this feature for harvesting DX lists.

</code> **SEE ALSO:** \\
[[packet:xrouter:docs:MAN9#MH-SVC|        MH-SVC(9)   -- NetRomX MHeard Service.
]] \\
[[packet:xrouter:docs:MAN9#SERVICES|        SERVICES(9) -- NetRomX Standard Services.
]] \\

[[packet:xrouter:docs:|< Back to Index]]

----
===== DYNDNS =====
<code>DYNDNS(9)            XROUTER REFERENCE MANUAL                 6/9/2023
</code> **NAME** <code>
        DYNDNS -- Dynamic DNS Update Client.

</code> **DESCRIPTION** <code>
        More and more people these days have dynamic IP addresses,
        i.e. IP addresses which are assigned by their Internet Service
        Provider and which may be different each time they log on. 
        Broadband users are permanently connected to the internet, but
        even their IP addresses may be changed at any time by the ISP,
        unless they pay extra for a static address.

        For the normal internet user this is not a problem, because
        no-one else needs to know their IP address. However, if you
        want other people to be able to connect to your system, e.g.
        if you are running a web server, they need to know your
        current IP address. This is where the dynamic DNS providers
        come in.

        There are many organisations providing dynamic DNS services,
        one of whom is DYNDNS.ORG. It is easy, and free, to set up an
        account with dyndns.org, and after doing so you may choose one
        or more hostnames for your system, for example "g8pzt.ath.cx".

        All you then have to do is keep dyndns.org informed of your
        current IP address, either manually or using an automatic
        update client. Whenever someone asks their system to connect
        to "g8pzt.ath.cx", they are given its current IP address.

        Xrouter has an integral client for automatically maintaining
        dynamic DNS entries at dyndns.org, thus obviating the need to
        run an external client or perform manual updates.  If the
        client is enabled, and your IP address changes, the client
        will update one or more hostname entries on the dyndns.org
        DNS server.  If you do not use dynamic dns, you need read no
        further.

        The client is enabled by including the directive DYNDNS=1 in
        the relevant PORT configuration block in XROUTER.CFG, i.e. the
        port which is connected to the Internet. DYNDNS=0 disables the
        client, as does omitting the directive altogether.  Note: you
        must only use this directive on ONE port, and you may crash
        XRouter if you try to use it on more than one.

        The client requires a configuration file, DYNDNS.CFG, and it
        creates a data file DYNDNS.BIN. The configuration file is
        heavily commented, so it should be self-explanatory.

        If your Xrouter is *directly* connected to the Internet, i.e.
        via a PSTN modem or non-routing cable modem, the client simply
        monitors the port IP address (which is assigned by the ISP
        using IPCP or DHCP), and tells dyndns.org when it changes.
        This mode is selected by putting "NO" on the "Use external IP
        detection service" configuration line in DYNDNS.CFG.

        However, if your connection to the Internet is via a NAT
        router such as an ADSL modem/router or Windows ICS, the port
        IP address will be a "private" one which no-one else could
        access. In this case, the client can be configured to query an
        external IP address detection service at regular intervals,
        updating dyndns.org if a change is detected. This mode is
        selected by putting "YES" on the "Use external IP detection
        service" configuration line.

        Free accounts on dyndns.org are removed if they haven't been
        updated for 35 days.  Thus, if your IP address hasn't changed
        for 30 days, the client automatically sends an update to keep
        the account refreshed.

        You may have more than one hostname associated with your IP
        address, but that's not a problem.  In the "hostname(s) to be
        updated" line, simply list the hostname, separated by commas.
        Be careful not to include any spaces or mistakes in the line.

</code> **FILES** <code>
        DYNDNS.CFG(8) -- Configuration file

</code> **SEE ALSO:** \\
[[packet:xrouter:docs:MAN7#DYNDNS|        DYNDNS(7)      -- Enable / Disable Dynamic DNS Update Client.
]] \\
[[packet:xrouter:docs:MAN8#XROUTER.CFG|        XROUTER.CFG(8) -- Main Configuration File.
]] \\

[[packet:xrouter:docs:|< Back to Index]]

----
===== ECHO-SRV =====
<code>ECHO-SRV(9)             XROUTER REFERENCE MANUAL              6/9/2023
</code> **NAME** <code>
        ECHO-SRV -- ECHO Server.

</code> **DESCRIPTION** <code>
        The ECHO server simply echoes back to the user anything that
        he sends.  This is a useful tool for testing connections,
        throughput etc.

        The server is accessed by connecting to NetRomX service 7,
        or to TCP port 7, or by issuing the ECHO command at
        XRouter's command prompt. 

        An ECHO session can only be ended by sending "/x" or by
        disconnection.

        The server's TCP port may be changed by using the ECHOPORT
        directive in XROUTER.CFG.  Setting the port to zero prevents
        TCP connections to the server.

</code> **SEE ALSO:** \\
[[packet:xrouter:docs:MAN1#ECHO|        ECHO(1)        -- Start an Echo session.
]] \\
[[packet:xrouter:docs:MAN7#ECHOPORT|        ECHOPORT(7)    -- Specify TCP port for ECHO server
]] \\
[[packet:xrouter:docs:MAN9#SERVERS|        SERVERS(9)     -- Servers In XRouter
]] \\
[[packet:xrouter:docs:MAN6#TCP-PORTS|        TCP-PORTS(6)   -- TCP Service Ports.
]] \\
[[packet:xrouter:docs:MAN8#XROUTER.CFG|        XROUTER.CFG(8) -- Main Configuration File.
]] \\
[[packet:xrouter:docs:MAN#
|
]] \\

[[packet:xrouter:docs:|< Back to Index]]

----
===== ECHO-SVC =====
<code>ECHO-SVC(9)             XROUTER REFERENCE MANUAL             22/9/2023

</code> **NAME** <code>
        ECHO-SVC -- NetRomX ECHO Service.

</code> **DESCRIPTION** <code>
        NetRomX service 7 is an ECHO server. This simply echoes back
        to the user anything that he sends.  This is a useful tool
        for testing connections, throughput etc.

        The session can only be terminated by sending "/x" or by
        disconnection.

        The server may also be accessed by connecting to TCP port 7,
        or by issuing the ECHO command at XRouter's command prompt. 

</code> **SEE ALSO:** \\
[[packet:xrouter:docs:MAN1#ECHO|        ECHO(1)      -- Start an Echo session.]] \\
[[packet:xrouter:docs:MAN7#ECHOPORT|        ECHOPORT(7)  -- Specify TCP port for ECHO server]] \\
[[packet:xrouter:docs:MAN9#ECHO-SRV|        ECHO-SRV(9)  -- About the Echo Server]] \\
[[packet:xrouter:docs:MAN9#SERVERS|        SERVERS(9)   -- Servers In XRouter]] \\
[[packet:xrouter:docs:MAN6#TCP-PORTS|        TCP-PORTS(6) -- TCP Service Ports.]] \\

[[packet:xrouter:docs:|< Back to Index]]

----
===== FING-SRV =====
<code>FING-SRV(9)             XROUTER REFERENCE MANUAL             27/9/2023
</code> **NAME** <code>
        FING-SRV -- FINGER Server.

</code> **DESCRIPTION** <code>
        The FINGER Server allows users to "put a finger on" (i.e.
        find information about) other users.

        The server is accessed via the FINGER command at the main
        prompt, or by connection to TCP port 79.  The latter is
        intended for use by FINGER clients only.

        If the argument to the FINGER command is of the form
        <username>, where <username> is usually (but not necessarily)
        a callsign, the server looks in the FINGER subdirectory for a
        text file of that name.  If found it sends the contents to
        the user.

        If however the argument is of the form <user>@<host>, e.g.
        "g8pzt@gb7pzt" the server activates a finger client, which
        attempts to establish communication with the Finger server on
        the specified <host> to retrieve the desired data.

        This server is only partly developed at present, and future
        versions may return more information.  For the moment, if you
        wish to activate this feature, create a FINGER sub-directory
        within the XRouter working directory, then simply create a
        text file for each user, using the user's callsign or any
        other preferred "nickname" as the filename.  Use the name
        "sysop" for yourself.
  
        The files can contain anything you like, typically the user's
        name, location, station details, QSL information etc.  You
        may wish to ask your users to submit a short summary about
        themselves.  Please respect people's privacy by including
        only the details that they are happy to publish.

        As an example, the file finger/g8pzt might contain the text:

        Name: Paula
        Qth:  Kidderminster, Worc's IO82VJ
        Age:  (withheld ;-)
        Other: Sysop G8PZT:KIDDER router, Sysop GB7PZT BBS, Fourpak
               Secretary, Unemployed software author with special
               interest in comms software.  Author of: XServ AX25/IP
               BBS, XRouter, XRPi, XS32, Uk White Pages system, PEARL
               Off-line reader for Packet Radio, ELINK Echolink
               repeater system, Rig control software...

        The server is available by default, and requires no setting
        up, other than the IP routing and the finger files.

        The server's TCP port may be changed, or the server disabled,
        by using the FINGERPORT=n directive in XROUTER.CFG.  Setting
        the port to zero disables the server.

</code> **SEE ALSO:** \\
[[packet:xrouter:docs:MAN1#FINGER|        FINGER(1)      -- Finger Command.
]] \\
[[packet:xrouter:docs:MAN9#SERVERS|        SERVERS(9)     -- Servers In XRouter
]] \\
[[packet:xrouter:docs:MAN7#FINGERPORT|        FINGERPORT(7)  -- TCP Port for Finger Server.
]] \\
[[packet:xrouter:docs:MAN6#TCP-PORTS|        TCP-PORTS(6)   -- TCP Service Ports.
]] \\
[[packet:xrouter:docs:MAN8#XROUTER.CFG|        XROUTER.CFG(8) -- Main Configuration File.
]] \\

[[packet:xrouter:docs:|< Back to Index]]

----
===== FING-SVC =====
<code>FING-SVC(9)             XROUTER REFERENCE MANUAL             27/9/2023

</code> **NAME** <code>
        FING-SVC -- NetRomX FINGER Service.

</code> **DESCRIPTION** <code>
        NetRomX service 79 is a FINGER server. This server allows
        users to "put a finger on" (i.e. find information about)
        other users. 

        The server may also be accessed by connecting to TCP port 79,
        or by issuing the FINGER command at XRouter's command prompt. 

</code> **SEE ALSO:** \\
[[packet:xrouter:docs:MAN1#FINGER|        FINGER(1)     -- Start a Finger session.]] \\
[[packet:xrouter:docs:MAN7#FINGERPORT|        FINGERPORT(7) -- TCP port for Finger server]] \\
[[packet:xrouter:docs:MAN9#FING-SRV|        FING-SRV(9)   -- About the Finger Server]] \\
[[packet:xrouter:docs:MAN9#SERVERS|        SERVERS(9)    -- Servers In XRouter]] \\
[[packet:xrouter:docs:MAN6#TCP-PORTS|        TCP-PORTS(6)  -- TCP Service Ports.]] \\

[[packet:xrouter:docs:|< Back to Index]]

----
===== FTP-SRV =====
<code>FTP-SRV(9)              XROUTER REFERENCE MANUAL            27/9/2023

</code> **NAME** <code>
        FTP-SRV -- FTP Server.

</code> **DESCRIPTION** <code>
        XRouter's inbuilt FTP sever allows remote sysops to upload,
        download, list, rename and delete files, create and remove
        directories etc., which is useful when XRouter is located
        somewhere inaccessible, such as a garage or remote hilltop.

        For example, new configuration and program files may be
        uploaded, and the system can then be restarted to perform a
        remote upgrade.

        The FTP server is only available to sysops.  It is protected
        by a password grid, and is only accessible to those who have
        a password registered in the sysop password file,
        PASSWORD.SYS.

        Access to all files, drives and directories is unrestricted,
        because the FTP server is intended for remote system
        maintenance, not as a public file repository.  The HTTP and
        NFTP servers may be used for that purpose instead.

        The FTP server uses standard FTP commands, with the
        exception of the USER and PASS login sequence, which are
        tailored for use on a radio channel: 

        In addition to the normal password prompt, the server also
        presents the user with a matrix of 5 lines of 5 numbers.  The
        user may respond either with a string of characters, as with
        secure sysop login, or with the full password in plain text.

        The grid response would be used on a public RF channel, and
        the plain text password on a secure RF channel or wired link.

        The server was originally intended for manual operation via
        RF links, but automated FTP clients may be used on secure
        links, because the password matrix is ignored by all types of
        FTP client so far tested.  They simply respond with the plain
        text password.

        There are no automated FTP clients that respond to the
        password grid with a secure response, so you cannot (safely)
        use them via an unsecured RF link.  However, if you leave the
        client's password field empty, it will usually prompt you to
        enter a password upon connection, at which point you can
        respond to the grid challenge.

        You are advised not to transfer a password file or any other
        sensitive material via insecure RF links.

        The directory format is "Windows_NT" because that is the
        format which gives the best results with the widest range of
        FTP clients.

        There is comprehensive help available at the FTP command
        prompt, provided you have placed the FTP help files in the
        HELP/FTP directory.

        The transport mechanism for FTP is TCP/IP, therefore you must
        have the appropriate IP routing configured if you wish to use
        it via XRouter's IP stack.  No configuration (other than some
        form of TCP/IP network) is required for operation via the
        host system's IP stack.

        The TCP port used by the FTP server defaults to the standard,
        i.e. 21.  This may be changed for XRouter and/or the host
        system's TCP/IP stacks using the optional FTPPORT directive
        in XROUTER.CFG.

        Access to the server may be controlled according to the
        client's source IP address, by using appropriate entries in
        ACCESS.SYS.
 
        The FTP server commands are described in detail in the sysop
        command reference section.

</code> **SEE ALSO:** \\
[[packet:xrouter:docs:MAN8#ACCESS.SYS|        ACCESS.SYS(8)  -- TCP/IP Access Control File.
]] \\
[[packet:xrouter:docs:MAN9#AXSCTRL|        AXSCTRL(9)     -- TCP/IP Access Control.
]] \\
[[packet:xrouter:docs:MAN1#FTP-CMDS|        FTP-CMDS(1)    -- FTP Commands.
]] \\
[[packet:xrouter:docs:MAN7#FTPPORT|        FTPPORT(7)     -- TCP Port for FTP Server.
]] \\
[[packet:xrouter:docs:MAN6#TCP-PORTS|        TCP-PORTS(6)   -- TCP Service Ports.
]] \\
[[packet:xrouter:docs:MAN8#XROUTER.CFG|        XROUTER.CFG(8) -- Main Configuration File.
]] \\

[[packet:xrouter:docs:|< Back to Index]]

----
===== HELP =====
<code>HELP(9)                 XROUTER REFERENCE MANUAL            29/12/2023
</code> **NAME** <code>
        HELP -- Help system.

</code> **DESCRIPTION** <code>
        Basic syntax help for most commands is built into XRouter,
        and is available using the query (?) command, e.g. "? N"
        displays the syntax of the NODES command.

        More detailed help is implemented as separate files in the
        HELP directory, allowing you to customise it, and add extra
        help topics as desired.  Each topic occupies a separate file,
        with the filename the same as the topic name. 

        The "H *" command displays a sorted directory of all the
        files with the extension ".HLP" (i.e. "topics"). The
        extension is not displayed. "H <topic>" displays the contents
        of that topic's file. e.g. "H DX" shows help for the DX
        command. If the topic is mis-spelled, XRouter lists the
        topics with similar names.

        The help files don't occupy much space, but you may choose to
        omit some or all of them if you are running a system with
        limited storage.

        In addition to the HELP system, sysops will find more
        detailed information in the "sysop manual" using the MAN
        command.

</code> **FILES** <code>
        Help files are normal text files, with the extension changed
        to ".HLP". They may be created and edited using a simple text
        editor such as Notepad (windows) or Leafpad, nano etc (Linux).

        All help files are located within the HELP directory, which
        itself is in the directory containing XRouter.

        English help files should be placed in the HELP directory
        itself. Help files for other languages should be placed in
        sub-directories of the HELP directory. For example, French
        help files should be in HELP/FR/, Spanish help files in
        HELP/ES/, German help files in HELP/DE/, and Dutch help files
        in HELP/NL/.

        Filenames, including the extensions, MUST be in UPPER CASE.
        Lower case filenames and files without the .HLP extension are
        ignored.

        Try to keep the filenames concise, to save excessive typing.
        The longer the filename, the more likely that a user will
        mis-spell it.

        Within the .HLP files, lines beginning with a semicolon ';'
        are not displayed to users, so you can use them for comments,
        such as file modification details.

        Help files can be viewed from the console using <ALT+H>
        followed by <H>. This browser window is only around 76
        characters wide, so try to keep the lines shorter than this,
        to preserve formatting. In any case, lines longer than 72
        characters are bad practice, typopgraphically-speaking.

</code> **HISTORY** <code>
        The help system originated long ago on DOS XRouter, and in
        those days there was only limited association between filename
        extensions and programs. I.e. in most cases, the extension
        itself had no real meaning, other than to serve as a reminder
        to humans what the file contained. Which is exactly why the
        XRouter help files have the extension ".HLP", to distinguish
        them from ".MAN" (manual), ".SYS" (system), .CFG
        (configuration) and so on.  In those days, most programs
        could view and edit a text file, no matter what the extension.

        Unfortunately, Windows assumes that a file with the extension
        ".HLP" is a Windows help file, and that ".SYS" is a Windows
        system file. If you double click these files, Windows
        complains that the format is wrong.

        It would be more convenient for *Windows* if the files had
        the extension .TXT instead of .HLP, but how would we then know
        that they were help files? Therefore, XRouter continues to use
        the traditional file names.

</code> **SEE ALSO:** \\
[[packet:xrouter:docs:MAN1#HELP|        HELP(1) -- User Help Command.
]] \\
[[packet:xrouter:docs:MAN1#MAN|        MAN(1) -- Online Sysop's Manual.
]] \\

[[packet:xrouter:docs:|< Back to Index]]

----
===== HTTP-PROXY =====
<code>HTTP-PROXY(9)           XROUTER REFERENCE MANUAL            17/10/2023
</code> **NAME** <code>
        HTTP-PROXY -- HTTP Proxy / Tunnel.

</code> **DESCRIPTION** <code>
        HTTP Proxy
        ~~~~~~~~~~

        The HTTP proxy accepts requests on the normal HTTP port and
        forwards them to another server.

                                XRouter          (google.com)
             .------.          .-------.          .--------.
             | user |-- HTTP --| proxy |-- HTTP --| target |
             '------'    ^     '-------'     ^    '--------'
             (GET http://www.google.com/)  (GET /)


        If a client sends an HTTP request containing an "absolute"
        rather than relative URL, e.g. "GET http://www.google.com/",
        XRouter's HTTP server recognises that this is not a "local"
        request, and opens an HTTP connection to the target server, in
        this case www.google.com.  It then passes a modified request
        and any subsequent HTTP headers to the target server, and
        passes any responses back to the client.

        Apart from rewriting the request to remove the http:// and
        the target hostname, the proxy is fully transparent (a non-
        transparent proxy rewrites the request headers).

        If the target connection could not be established within a
        reasonable time (controlled by PROXYTIMEOUT in HTTP.SYS), an
        HTTP error message is returned to the client, and the client
        connection is closed.


        Downstream Proxy
        ~~~~~~~~~~~~~~~~

        XRouter's HTTP proxy may be configured to pass selected
        traffic to a "downstream" proxy.  This is enabled by using a
        directive with the following format in HTTP.SYS: 

            PROXY <ipaddr> <port> <subnet_mask>

            e.g. "proxy 44.131.91.245  80  255.0.0.0"

        <ipaddr> is the IP address of the downstream proxy.

        <port> is the TCP port number of the downstream proxy.

        <subnet_mask> when combined with the proxy address specifies
                      the range of addresses which are on the same
                      subnet as the downstream proxy. These addresses
                      bypass the downstream proxy, i.e. XRouter will
                      connect directly to them instead of via the
                      downstream proxy.

        This kludge allows 44-net systems to use a further proxy to
        gain a public (Internet) IP address when connecting non-44
        websites.  This is necessary because 44-net routing is
        unreliable at best, i.e. if a 44-net browser tries to
        connect directly to Google, the reply probably won't get
        routed back.

        For example, imagine a mobile station, consisting of a web
        browser and XRouter, with an IP/AX25 link to a nearby gateway,
        but no Internet connection. The IP address used over the
        radio link is 44.131.91.3.  The browser has been configured
        to use XRouter's HTTP proxy, which means the IP source address
        for all HTTP traffic from this station is 44.131.91.3.


         192.168.0.1<->192.168.0.2     62.31.206.176 <-> 173.194.41.99
          .------.    .-------.             .-------.       .--------.
          | user |----| proxy |-- RF Link --| proxy |- Inet-| Google |
          '------'    '-------'             '-------'       '--------'
                     44.131.91.3 <------> 44.131.91.245
            (mobile station)               (gateway)


        Via the nearby gateway, whose IP address is 44.131.91.245,
        the mobile station can happily browse 44-net (amprnet)
        websites. But when it tries to use Google, the replies
        aren't routed back.

        However, if the local gateway has been set up with the
        above PROXY command, the 44.x.x.x sites are connected directly
        by the mobile XRouter's proxy (routed via the gateway), whilst
        the non-44 sites are connected via the gateway's HTTP proxy.
        At this second proxy, they gain a 62.31.206.176 source
        address, which is reliably routable and doesn't rely on the
        co-operation of others in the amprnet.

        The obvious question is, why not use the gateway's proxy
        directly, using NAT to translate the browser's IP address to
        44.131.91.3?  The answer is that Windows' TCP/IP settings are
        tailored for fast wired links and are unsuitable for use via
        packet radio. The intermediate (mobile) proxy makes the TCP/IP
        radio-friendly.


        HTTP Tunnel
        ~~~~~~~~~~~

        The HTTP tunnel allows users located behind a corporate
        firewall, which blocks all non-HTTP traffic, to access regular
        telnet destinations. A Java client applet, such as XWEB.CLASS
        (supplied) would be typically be used to set up the connection
        through the tunnel.

             .--------.          .------.            .--------.
             | client |-- HTTP --| XRouter |-- Telnet --| target |
             '--------'          '------'            '--------'

        All traffic between the Java client and XRouter is carried on a
        regular HTTP port 80 connection, which is allowed to pass
        unhindered through the corporate firewall.

        An HTTP tunnel connection begins like a regular HTTP session,
        but instead of the GET method it uses CONNECT. For example:

                CONNECT g8pzt.ath.cx:23 HTTP/1.1

        Both host and port number must be present in the "URL" portion
        of the request.  The "host" portion may be either a hostname,
        or an IP address in dotted decimal form.

        If the request is denied because the destination is blocked by
        the security rules, the HTTP error message is "403 Forbidden",
        and the session terminates.

        If the request is allowed (see "security" below), the server
        attempts to connect to the specified host.  If successful, it
        then sends "200 Connection established" to the client,
        followed by a blank line.  The session then becomes fully
        transparent, and the HTTP server plays no further part in any
        transactions.  The streams are full 8-bit binary.


        Proxy / Tunnel Timeouts
        ~~~~~~~~~~~~~~~~~~~~~~~

        By default, 30 seconds is allowed for name resolution, and
        another 30 for the connection to establish.  This timeout may
        be altered using the PROXYTIMEOUT directive in HTTP.SYS (It
        may need to be more than 60 sec via radio channels).

        If the connection couldn't be established for any reason, the
        server sends a 5xx failure message, and the session terminates.


        Proxy / Tunnel Security
        ~~~~~~~~~~~~~~~~~~~~~~~

        If not configured correctly, the HTTP tunnel and proxy could
        pose a serious security risk, because they could allow users
        to access destinations behind your firewall.  In addition,
        they could be used to access an external destination via your
        IP address, thus hiding the identity of the caller.

        Therefore by default the proxy and tunnel are disabled.  In
        order to enable them you must configure some security...

        HTTP.ACL is the Egress Control file, i.e. it controls who the
        users of the proxy / tunnel are allowed to connect to.  If the
        file is not present, or there are no suitable entries in the
        file, the tunnel is blocked.

        It is suggested that egress control is configured such that
        "external" (i.e. Internet) users should only be allowed to
        connect to specific "internal" (i.e. intranet) destinations,
        such as the TELNET and CHAT servers, whilst intranet users may
        be allowed to connect to any destination.  See HTTP.ACL for
        details.

</code> **SEE ALSO:** \\
[[packet:xrouter:docs:MAN8#HTTP.ACL|        HTTP.ACL(8) -- HTTP Proxy / Tunnel Egress Control File.
]] \\
[[packet:xrouter:docs:MAN8#HTTP.SYS|        HTTP.SYS(8) -- HTTP Proxy / Rewrite Rules.
]] \\
[[packet:xrouter:docs:MAN9#HTTP-SRV|        HTTP-SRV(9) -- HTTP Server.
]] \\

[[packet:xrouter:docs:|< Back to Index]]

----
===== HTTP-SRV =====
<code>HTTP-SRV(9)             XROUTER REFERENCE MANUAL             27/9/2023

</code> **NAME** <code>
        HTTP-SRV -- HTTP Server.

</code> **DESCRIPTION** <code>
        XRouter's HTTP server delivers HTML files from disk to user,
        and also provides an HTML interface to XRouter for users and
        for system management.  The following functions are provided:

                - HTML file server
                - Server Side Includes
                - Browser interface to XRouter
                - URL Rewriting
                - Malicious request blocking
                - Java applet 
                - HTTP Proxy
                - HTTP Tunnelling

        (For details of the proxy / tunnel, please see the manual
        section for HTTP-PROXY.)

        Connectivity
        ~~~~~~~~~~~~
        By default, the HTTP server uses the standard HTTP port,
        which is TCP port 80, and the server is available via both
        XRouter and the host system's IP stacks. It is also always
        available as NetRomX service 80.

        The TCP port number, and availability on each stack, may be
        changed by using the HTTPPORT directive in XROUTER.CFG. 
        Setting the port number to zero disables the server on that
        stack.  See the HTTPPORT manual page for more information. 


        Server Root Directory
        ~~~~~~~~~~~~~~~~~~~~~
        The HTTP server's "root" directory is specified using the
        HTTPROOT directive in XROUTER.CFG, e.g. "HTTPROOT=C:\WEB".
        This allows the HTML files to be located somewhere more
        convenient, even on another drive if required.

        If you omit this directive, the default will be a directory
        called "HTTP" within the XRouter working directory. Users
        are not able to "climb out" of that directory, and if they
        attempt to do so they are IP-banned indefinitely.

        If the directory doesn't exist, the server will not work.

        For security reasons it is important that you don't use the
        XRouter working directory as the HTTP root!


        Default Page
        ~~~~~~~~~~~~
        When servicing a request which doesn't include a filename in
        the URL, (e.g. "http://g8pzt.ath.cx/") the server looks in
        the HTTP root directory for a file called INDEX.HTM.  If that
        file is not present, it looks for DEFAULT.HTM.  You may
        therefore use either file as a "landing page" or an index to
        your site.

        An example INDEX.HTM is supplied for your guidance.  It is by
        no means a perfect web page, just something thrown together
        to test a concept.  You are encouraged to change it to suit
        your own preferences.  You may need to alter the address in
        the "Connect" link to suit your own IP address / hostname.
        The connect function is normally performed by a Java applet.

        INDEX.HTM is meant as a default entry point for your XRouter
        web site.  Although XRouter's primary purpose is a router not
        a server, and the primary purpose of its HTTP server is to
        provide a web interface to the node, you may choose to create
        a complex web site, of which the command interface is but a
        small part.

        You may prefer to use INDEX.HTM as a splash or menu page for
        your site, putting the command interface on one or more linked
        sub-pages.  Or you may choose the opposite approach, putting
        all the commands on the main page along with links to other
        sites. The creativity is left to you...


        Executing XRouter Commands
        ~~~~~~~~~~~~~~~~~~~~~~~
        When the server receives a request whose URL begins with
        "/exec?cmd=", e.g. it passes the command to XRouter for
        execution, and serves a "template" page displaying the
        response to the command. The template serves as a wrapper for
        the text.

        If the command has arguments, they must be passed as "arg1",
        "arg2" etc. using the format "&arg1=x", where 'x' represents
        the argument.  There must be no spaces in the URL.

                Example: "exec?cmd=n&arg1=h"   - executes "N H"

        If you wish to override the inbuilt html template, edit the
        file EXEC.HTM, which was supplied with the installation
        package, and put it in the XRouter working directory.  This
        file does not reside within the HTTP directory tree because
        it is not intended to be served in the normal way.

        If EXEC.HTM exists, the server will serve it in place of the
        inbuilt template, replacing the <TEXT> tag with the result of
        the executed command.  EXEC.HTM does not currently support
        Server Side Includes (see below).


        Commands in Forms
        ~~~~~~~~~~~~~~~~~
        Another way of executing XRouter commands is within HTML
        forms.

        The form tag's ACTION field should be "exec".  Within radio
        button <INPUT> elements the NAME field should be "cmd" and the
        VALUE field should be the command plus any arguments, enclosed
        in quotes.  Further arguments can be specified with text input
        elements, as shown in the following example:

            <FORM ACTION="exec">
              <INPUT TYPE=radio NAME=cmd VALUE="n v">Via:<BR>
              <INPUT TYPE=radio NAME=cmd VALUE="n &gt;">&gt;Qual:<BR>
              <INPUT TYPE=radio NAME=cmd VALUE="n &lt;">&lt;Qual:<BR>
              <INPUT TYPE=radio NAME=cmd VALUE=n>Routes to:<BR>
              <INPUT TYPE=text SIZE=9 NAME=arg1>
              <INPUT TYPE=submit VALUE=Go>
            </FORM>


        Server Side Includes
        ~~~~~~~~~~~~~~~~~~~~
        Server Side Includes (SSI) provide another means to generate
        dynamic HTML.  Special tags in the HTML files cause the server
        to replace the tag with alternative data (such as the contents
        of another file) when the file is served.
 
        Server Side Includes are useful for including a common piece
        of code throughout a site, such as a page header, a page
        footer or a navigation menu.  If the common code is modified,
        all pages display the new code.  This is preferable to having
        to modify every page.

        SSI has a simple syntax:

            <!--#directive parameter=value parameter=value -->

        Directives are contained within HTML comments so that if SSI
        is not enabled, users will not see the SSI directives on the
        page, unless they look at its source.

        Note that the syntax does not allow spaces anywhere between
        the leading "<" and the directive.  The tag must begin with
        the exact sequence "<!--#" otherwise it won't be recognised.

        The SSI directives currently accepted are as follows:

            Directive  Parameter  Parameter value
            ~~~~~~~~~  ~~~~~~~~~  ~~~~~~~~~~~~~~~
            ECHO       VAR        DATE_LOCAL
            ECHO       VAR        LAST_MODIFIED
            EXEC       CMD        {any XRouter cmd string}
            FLASTMOD   FILE       {relative filename}
            FSIZE      FILE       {relative filename
            INCLUDE    FILE       {any file under current dir}
            INCLUDE    VIRTUAL    {any file within http tree}


        ECHO displays the contents of a specified HTTP environment
        variable. Variables include DATE_LOCAL which displays the
        local date and time, and LAST_MODIFIED which displays the
        modification date and time of the HTML file that is being
        served.

                Example: <!--#ECHO VAR=DATE_LOCAL -->

        EXEC executes a command. The CMD parameter specifies that the
        parameter value contains an XRouter command, and the parameter
        value specifies the command and any argument(s).  If the
        command has arguments, the string should be enclosed in
        quotes.  Not all commands are allowed, only those which are
        non-interactive and normally available to users.  The results
        of the execution are displayed to the user.  If the response
        contains tables, the whole directive should be enclosed in
        <PRE></PRE> tags to preserve the formatting.

                Example: <PRE><!--#EXEC CMD="r r" --></PRE>

        FLASTMOD and FSIZE display the date when the specified
        document was last modified, or the specified document's size.
        The FILE or VIRTUAL parameters specify the document to use.
        The FILE parameter defines the document as relative to the
        current document path; the VIRTUAL parameter defines the
        document as relative to the HTTP root.

                Example: <!--#FSIZE FILE=myfile.txt -->
        
        INCLUDE allows the content of one document to be included in
        another.  The file or virtual parameters specify the file
        (HTML page, text file, script, etc.) to be included. The FILE
        parameter defines the included file as relative to the current
        document path; the VIRTUAL parameter defines the included file
        as relative to the HTTP root.

                Example: <!--#INCLUDE VIRTUAL=/bbs/msglist.txt -->

        If the included file also contains Server Side Includes, they
        will not be actioned.

        Some servers will not execute SSI unless the HTML file has a
        .SHTML, .SHTM or .STM extension. XRouter does not require
        this.

        SSI cannot be used in EXEC.HTM at present.


        URL Rewriting
        ~~~~~~~~~~~~~
        URL rewriting modifies the URL's of incoming requests,
        according to a set of REWRITE rules in HTTP.SYS.  This can be
        used to organise widely-dispersed resources into a logical
        directory tree.

        The resources may be located on the same PC or even on
        different servers, but can be made to look as if they are all
        in the same tree on your server.  This is done by replacing
        parts of the requested URL with alternative strings of
        characters. 

        For example, if you only have one public IP address, but you
        have more than one HTTP server on your LAN which you wish to
        make visible to the outside world, you could use non-standard
        port numbers for the additional servers, but that is messy,
        (e.g. http://g8pzt.atx.cx:8081).  People cannot remember the
        port numbers, let alone be bothered to type them in!

        This is where XRouter can help, using URL rewriting plus the
        HTTP proxy to redirect requests to any number of alternate
        servers according to the first part of the URL.  E.g. a URL
        which begins with "/bbs" could be redirected to the web
        server on your BBS.

        If the rewritten URL begins with "http://{address}[:port]",
        where {address} can be either a hostname or IP address, it is
        treated as a proxy request, and redirected to the appropriate
        server.

        For more information see the manual section on HTTP.SYS.


        Malicious Request Blocking
        ~~~~~~~~~~~~~~~~~~~~~~~~~~
        XRouter's HTTP server doesn't suffer from the usual Windows
        vulnerabilites, so malicious HTTP requests designed to
        exploit them are simply a bandwidth-wasting nuisance
        rather than a real threat. You can frustrate the hackers
        by deploying the HTTPBAN.SYS file.

        This file contains "signatures" or "templates" of typical
        malicious request URL's.  For example a request for
        "default.ida" is part of a Code Red Worm attack, whilst
        requests for "cmd.exe" are an attempt to locate vulnerable
        Windows servers.

        You can find out which are the common hacks by examining your
        daily logfiles, looking for the "HR ... " (HttpRequest) lines.
        Common ones are "/default.ida" and "/scripts".

        The templates are compared in a sliding match with each
        requested URL.  If any part of the first 256 bytes of the URL
        matches a template, the sender's IP address is entered into a
        ban list and all further IP datagrams from that host are
        ignored until XRouter is restarted.  Up to 200 hosts can be
        banned simultaneously. 

        For more information, see the manual section on HTTPBAN.SYS.


        Java Applet
        ~~~~~~~~~~~
        The Java applet XWEB.CLASS can be used to connect to XRouter
        with a web browser.

        The distribution archive contains the applet file, plus 3
        rudimentary .HTM pages for you to examine or experiment with. 

        CONNECT.HTM is the menu page for 3 types of connection, and
        would typically be accessed via a "connect" link on the main
        page.  You may however wish to put the 3 connect options
        directly on the main page - it's up to you.

        CONN23.HTM uses the Java applet to perform a normal telnet
        connect to port 23.  The port number is configurable (see
        below), so you could clone the page for use with your chat
        server.

        CONN80.HTM uses the Java applet to perform a "tunnelled"
        connection, which can be used via corporate firewalls which
        block normal Telnet.

        If you wish to use the above files and the applet, they
        must be located within the HTTP tree.

        You can change the applet colours and font, the number of rows
        and columns displayed, and the connection mode (normal TELNET,
        or HTTP tunnel), using <PARAM> tags in the HTML file. For
        example: <PARAM NAME="font" VALUE="Courier">.

        The parameters which can be specified are as follows:

        Param name     Default    Description
        -----------------------------------------------------------
        rows           22         No. of rows in text window
        cols           80         No. of columns in text window
        bgcolour       Dark grey  Applet background colour.
        borderColour   Light grey Applet framework colour.
        textBackground Black      Background for text/cmd windows.
        textColour     White      Colour of sent / rcvd text.
        font           Times      Font style for sent / rcvd text
        port           9999       TCP port number for connections.
        mode           Normal     Connection mode (normal / proxy).

        The only mandatory parameter is "port". This should normally
        be 23 for a normal telnet connect or 80 for an http-tunnelled
        connect, but you may use other values if you have moved or
        translated your Telnet or HTTP ports.

        Colours should be specified as a 24 bit hexadecimal number in
        'C' style, e.g. 0xEECCFF, where the first 2 digits represent
        the RED value, the second two digits represent the GREEN value
        and the last two digits represent the BLUE value. Some
        browsers can only display 216 discrete colours, so you should
        preferably use the "browser-safe" values, which are all formed
        from combinations of 00, 33, 66, 99, CC and FF.

        The default font is quite small, and the characters are not of
        a constant width, which means tables sent by XRouter will not
        line up correctly.  You may use the "font" parameter to
        override the default.  The recommended font is "Courier",
        which is slightly larger and uses constant width characters.
        Note: if the chosen font is not found on the client's device,
        their default font will be used, so stick to the common ones.

        You may need to reduce the number of rows or columns displayed
        by the applet if you find it won't fit on a 640*480 screen. It
        fits nicely on 800*600, but you may wish to optimise it for
        another screen size, or even offer users the choice.

        If you change the font, rows or cols, you may need to tweak
        the WIDTH and HEIGHT attributes in the APPLET tag to prevent
        parts of the applet from being obscured.
 

</code> **FILES** <code>
        In XRouter root: EXEC.HTM, HTTP.SYS, HTTPBAN.SYS
        In HTTP tree: INDEX.HTM, CONNECT.HTM, CONN23.HTM, CONN80.HTM,
                      XWEB.CLASS

</code> **SEE ALSO:** \\
[[packet:xrouter:docs:MAN8#HTTP.ACL|        HTTP.ACL(8)    -- HTTP Proxy / Tunnel Egress Control File.
]] \\
[[packet:xrouter:docs:MAN8#HTTP.SYS|        HTTP.SYS(8)    -- HTTP Rewrite / Proxy Control File.
]] \\
[[packet:xrouter:docs:MAN9#HTTP-PROXY|        HTTP-PROXY(9)  -- HTTP Proxy / Tunnel
]] \\
[[packet:xrouter:docs:MAN8#HTTPBAN.SYS|        HTTPBAN.SYS(8) -- HTTP URL Blocking File.
]] \\
[[packet:xrouter:docs:MAN9#HTTP-SVC|        HTTP-SVC(9)    -- NetRomX HTTP Service
]] \\
[[packet:xrouter:docs:MAN7#HTTPPORT|        HTTPPORT(7)    -- TCP Port for HTTP Server.
]] \\
[[packet:xrouter:docs:MAN6#TCP-PORTS|        TCP-PORTS(6)   -- TCP Service Ports.
]] \\
[[packet:xrouter:docs:MAN8#XROUTER.CFG|        XROUTER.CFG(8) -- Main Configuration File.
]] \\

[[packet:xrouter:docs:|< Back to Index]]

----
===== HTTP-SVC =====
<code>HTTP-SVC(9)              XROUTER REFERENCE MANUAL             7/9/2023
</code> **NAME** <code>
        HTTP-SVC -- NetRomX HTTP Service

</code> **DESCRIPTION** <code>
        NetRomX Service 80 accesses XRLin's HTTP server, allowing
        HTTP over Netrom. 

        HTTP over NetRom? Shock horror! What a phenomenally stupid
        idea!!! Well maybe it is, maybe not? It's just another
        communication tool.

        This service is not new - it has been in XRouter since Jan
        2013. If you access an XRouter's web interface via TCP/IP,
        it's what allows you to click on certain nodes in the nodes
        list, and go to their default pages.

        Yes it might be slow, but if the HTML is kept clean and tight,
        it is workable, and unlike the Internet, the addresses are
        consistent. A node's "NetromWeb" address is simply its
        callsign.

        The service number is not affected by the setting of HTTPPORT,
        which only affects TCP/IP access to the server.

</code> **SEE ALSO:** \\
[[packet:xrouter:docs:MAN9#HTTP-SRV|        HTTP-SRV(9) -- HTTP Server]] \\
[[packet:xrouter:docs:MAN9#SMS-SVC|        SMS-SVC(9)  -- Short Messaging Service.]] \\
[[packet:xrouter:docs:MAN9#SERVICES|        SERVICES(9) -- NetRomX Standard Services.]] \\

[[packet:xrouter:docs:|< Back to Index]]

----
===== IDS =====
<code>IDS(9)                  XROUTER REFERENCE MANUAL            20/10/2023
</code> **NAME** <code>
        IDS -- Intrusion Detection System.

</code> **DESCRIPTION** <code>
        The purpose of XRouter's Intrusion Detection System (IDS) is
        to detect, repel and warn the sysop of, suspicious or
        malicious activities.

        It mainly operates on IP, where most of the threats arise,
        but also watches AX25 / Netrom. It does not need any setup
        and should not interfere with normal operation.

        The main indication of its presence is the "Security Monitor"
        window, which displays any detected threats. Other than that,
        there might be the occasional warning on the bottom right of
        the "overview" window.


        Security Monitor Window
        ~~~~~~~~~~~~~~~~~~~~~~~

        Positioned between the "Overview" window and the "Consoles",
        the "Security Monitor" is intended to remind / inform you of
        any suspicious actitvity.

        In most cases, this is just a waste of a window, showing all
        zeros and mostly empty space. That's a good thing - it shows
        you are (probably) safe.
 
        However if you have any IP services enabled, the window might
        come alive with activity. The top section shows an overview
        of the threat statistics, whilst the rest of the window shows
        the latest warning messages, in various colours according to
        the severity of the threat.

        There are 4 notification Levels as follows:

            1 - IMPORTANT!:  Intrusion / Escalation attempts (cerise)
            2 - WARNING:     Recon attempts (port scans etc (red)
            3 - ADVISORY:    Possible suspicious events (yellow)
            4 - INFORMATIVE: Unusual events (white)

        You can change which notifications are displayed using the
        following command:

            IDS V[erbosity] [level]

        [level] is 0 (no notifications) to 4 (all notifications).

        For example the command "IDS V 2" enables intrusion and recon
        notifications only.

        Pressing <F1> on the IDS window displays a pop-up box with
        the notification levels, a brief description of the stats,
        and a reminder of the IDS commands.

        The various statistics displayed in the upper pane are
        described in the section "IDS Statistics" below.


        IDS Logging
        ~~~~~~~~~~~

        The IDS notifications pane only has limited space, and you
        can't watch it all the time, which is where IDS logging comes
        in handy. 

        IDS events can be logged, either by enabling the IDS option
        in the LOG directive, or by using the command "IDS LOG ON".

        if IDS logging is enabled, some (but not all) IDS events are
        logged to the file LOG/YYMMDD_IDS.LOG, where YYMMDD are the
        2 digit year, month and day of the month.

        Log entries are usually of the form:

           <time> <source_IP> -> <dest_IP>[:port] <description>

        For example:

        15:11:12 192.168.0.135 -> 192.168.0.101:137 Unsolicited UDP
        20:16:02 192.168.0.135 -> 192.168.0.101:443 TCP SYN - refused
        21:04:57 44.197.188.109 -> 44.135.49.90:443 TCP SYN - refused

        The last entry reveals a threat from the section of 44-net
        that was sold off to commercial interests, and the need to
        update the IP access Control List entries to block this
        section of the 44/8 address space.


        IP Banning
        ~~~~~~~~~~

        One part of XRouter's defences is "IP banning".

        If XRouter detects malicious activity on its own TCP/IP
        stack, it will "ban" the originator's IP address. This means
        that any further packets from that IP address are ignored,
        for as long as the ban lasts.

        If malicious activity is detected on any Linux TCP or UDP
        port that is currently used by XRouter, that also causes
        a ban. In this case, TCP connections are terminated, and any
        further connections or UDP frames are ignored.

        There is no time limit on IP bans, and they are preserved
        across reboots. Up to 200 IP addresses can be banned at once.

        A larger table would become unwieldy, so when a new address
        is added, the oldest one is dropped. In practice this isn't
        usually a problem because the oldest aggressor has usually
        given up long ago, and is unlikely to come back.

        IP bans can be added manually using the IP BAN ADD command,
        the format of which is:

                IP B[an] A[dd] <ipaddr> [netmask]

        For example:

                ip ban add 44.197.188.109
                ip ban add 44.128.0.0  255.192.0.0

        They can also be removed using "IP U[nban] <ipaddr>".

        The ban list can be displayed using "IP B[an] L[ist]"

       
        Port Scanners
        ~~~~~~~~~~~~~

        Scans are not necessarily dangerous, although in some cases
        they may consume substantial resources. The main issue with
        scans is that are usually a prelude to an attack. Once your
        presence has been detected by a scan, the hackbots tend to
        inform each other and launch an attack. It may not happen
        immediately, but it will usually happen.

        If you have any TCP/IP services open to the Internet, for
        example Telnet or even AXUDP, scans are inevitable. The IDS
        warns you, so you can take evasive action, such as IP and 
        TCP / UDP ingress filtering, and allows you to test its
        efficacy. It also disrupts the scanning process, causing the
        hackbots to time out and move on. 

        A word of warning: If you scan your own system, you might
        suddenly find that you can no longer access XRouter from
        the machine that performed the scan because its IP has been
        banned. If you can access XRouter from its own console, or
        via a machine that hasn't been IP-banned, you can use the IP
        UNBAN command to remove the banned address.


        Honeypots
        ~~~~~~~~~

        In this context, a honeypot a sticky trap, set up on popular
        TCP or UDP ports, for catching internet low-life.

        Hackbots generally start their attacks by probing for open
        TCP ports, and to save time they often start with the most
        popular ones - telnet, SSH, HTTP, VNC and so on. If they find
        an open port, they tend to inform each other, then they all
        concentrate their attacks on that port.

        Unless you have a particular service port open, the chances
        are that anyone who tries to connect to it is up to no good.
        So the honeypot is a mitigation measure. It LOOKS like an
        attractive open port, but it's not! Anyone who connects to it
        gets their IP address logged and banned. After that they
        can't do any more attacking unless they change their IP
        address.

        It's not foolproof. Nation states have access to large
        numbers of IP addresses. But IP banning slows them down,
        and the IDS alerts you that there is a problem.


        Setting Up a Honeypot
        ~~~~~~~~~~~~~~~~~~~~~

        IP sub-commands BAN PORT ADD, BAN PORT DROP, BAN PORT LIST,
        and BAN PORT SAVE allow management of the "honeypot" ports.

        A honeypot is created using the following command:

              IP B[an] P[ort] A[dd] <TCP|UDP|ALL> <start> [end]

        <TCP|UDP|ALL> - protocol(s) to catch.
        <start>       - single port, or the start of a range.
        [end]         - last port in a range.

        For example: "ip ban port add tcp 443" sets up a honeypot
        which IP bans anyone who tries to cpnnect to TCP port 443.

        Similarly "ip ban port add tcp 5900 5999" creates a honeypot
        covering the TCP port range commonly probed for VNC.

        Honeypots and their stats can be displayed using:

              IP B[an] P[ort] L[ist]

        They can be saved (to IPBAN.SYS) using:

              IP B[an] P[ort] S[ave]

        And they can be removed using:

              IP B[an] P[ort] D[rop] <TCP|UDP|ALL> <start> <end>

        Note that both the start and end ports are mandatory in the
        DROP command. For single ports, both numbers are the same.


        IDS Statistics
        ~~~~~~~~~~~~~~

        If you have access to XRouter's display, the top section of
        the "Security Monitor" window gives you some statistics.

        If you have "sysop" access to XRouter you can also view more
        comprehensive stats using either the "S[tats] IDS" or the
        "IDS S[tats]" commands, both of which display the same data,
        something like this: 

            IDS Events:       25778   Cmd Overflow:     0
            FTP DIR Hacks:    0       IP Addr Heard:    100
            IP Addr Banned:   200     IP Banned Total:  183     
            IP Dgram Blocked: 2076    ICMP Frm Blocked: 32
            Honeypot Hits:    0       UDP Segs Ignored: 3251968
            UDP Segs Blocked: 22      TCP Segs Ignored: 9967
            TCP Segs Blocked: 2022    TCP Conn Blocked: 763     
            Bogus SYNs:       15776   Smurf Attacks:    0
            Fraggle Attacks:  0       IP Frag Attacks:  0
                      (Tiny=0  Huge=0  Overlapped=0)
            TCP Scans: SYN=1 FIN=0 ACK=57 NUL=0 MAI=82 XMS=0 OTH=9600
            Rejected Logins:  763 (Telnet=763, Rlogin=0, FTP=0,
               TelProxy=0)
            Malicious Logins: 182 (Telnet=182, Rlogin=0, FTP=0,
               TelProxy=0)
            HTTP No-Request:  0       HTTP Bad Request: 0
            HTTP Blocked:     0

        "IDS Events" is the total number of times the IDS has noticed
                something suspicious.

        "Cmd Overflow" is the number of times that someone has
                attempted a buffer overflow attack.

        "FTP DIR Hacks" is the number of attempts to escape from the
                FTP root directory.

        "IP Addr Heard" is the number of unique IP addresses heard.

        "IP Addr Banned" is the number of IP addresses in the "banned
                IP" table. As the table is saved across reboots, it
                is normal for it to be full.

        "IP Banned Total" is the number of new IP addresses banned
                since bootup. This figure may exceed the table size
                because new bans replace stale ones.

        "IP Dgram Blocked" is the number of IP datagrams blocked
                because the sender's IP address was in the banned IP
                table.

        "ICMP Frm Blocked" is the number of ICMP frames blocked
                because the sender's IP address was in the banned IP
                table.

        "Honeypot Hits" is the number of times someone attempted to
                access one of the "honeypot" ports. These are traps
                which lure port scanners into an IP ban.

        "UDP Segs Ignored" is the number of UDP segments ignored
                because there was no matching socket to receive them.

        "UDP Segs Blocked" is the number of UDP segments blocked
                because the sender's IP address was on the banned IP
                list.

        "TCP Segs Ignored" is the number of TP segments ignored
                because there was no matching listener socket.

        "TCP Conn Blocked" is the number of TCP connection attempts
                blocked because the sender was on the banned IP list.

        "Bogus SYNs" is the number of TCP connection attempts blocked
                because the SYN was malformed or maliciously crafted.

        "Smurf Attacks" are distributed denial of service attacks
                which use ICMP directed at broadcast addresses.

        "Fraggle Attacks" are variations of Smurf attacks, where the
                attacker sends lots of traffic to UDP ports 7 (Echo)
                and 19 (CHARGEN)

        "IP Frag Attacks" is the number of IP fragmentation attacks.
                These attacks attempt to overwhelm or crash the IP
                fragment reassembly mechanism.
                Tiny - First fragment is too short to contain valid
                       TCP+IP headers, so it could bypass port-number
                       filtering.
                Huge - Fragment exceeds maximum datagram size.
                Overlapped - Fragments which overlap but don't align.

        "TCP Scans" is the number of TCP port scans detected and
                blocked. Totals for each scan type are shown
                separately:

                SYN - Scanner sends SYN but never completes the 3 way
                      TCP handshake.
                FIN - TCP segments with only the FIN bit
                ACK - Only the ACK flag is set
                NUL - NULL scan (no flags are set)
                MAI - Maimon scan (FIN and ACK flags set)
                XMS - Xmas Tree scan (FIN, PSH and URG flags set)
                OTH - Other types of scan
 
        "Rejected Logins" are Telnet / FTP etc logins which were
                rejected because the source IP was banned or the
                login credentials were incorrect.

        "Malicious Logins" are TCP logins attempted using suspicious
                or common attack credentials.

        "HTTP No-Request" is the number of connections to XRouter's
                HTTP server which didn't contain an HTTP request.
                These are usually the result of port scanning.

        "HTTP Bad Request" is the number of malformed or maliciously
                crafted HTTP requests. These are usually attempts to
                exploit vulnerabilities in certain types of HTTP
                server or operating system.

        "HTTP Blocked" is the number of HTTP server connections
                refused because the sender's IP was in the blocked
                IP list.


        IDS-Related Commands
        ~~~~~~~~~~~~~~~~~~~~

        IDS L[og] [on | off]
        IDS S[tats]
        IDS V[erbosity] [0-4]
        IP B[an] A[dd] <ipaddr> [netmask]
        IP B[an] D[rop] <ipaddr>
        IP B[an] L[ist]
        IP B[an] P[ort] A[dd] <TCP|UDP|ALL> <start> [end]
        IP B[an] P[ort] D[rop] <TCP|UDP|ALL> <start> <end>
        IP B[an] P[ort] L[ist]
        IP B[an] P[ort] S[ave]
        IP B[an] S[ave]
        IP Q[uiet] [level]
        IP U[nban] <ipaddr>
        S[tats] IDS

</code> **CAVEATS** <code>
        The IDS is not set in stone. It evolves and morphs as the
        threatscape changes. Therefore some of the above may be out
        of date already.

        Nor does it claim to be a 100% foolproof system. XRouter's
        primary purpose is for Amateur Packet Radio, not Internet
        defence! The IDS must strike a balance between defending the
        system, informing (but not overwhelming) the sysop, and not
        getting in the way of normal operations.

</code> **SEE ALSO:** \\
[[packet:xrouter:docs:MAN1#IDS|        IDS(1)         -- Intrusion Detection System Commands.
]] \\
[[packet:xrouter:docs:MAN1#IP|        IP(1)          -- IP-related Commands.
]] \\
[[packet:xrouter:docs:MAN1#ACL|        ACL(1)         -- IP Access Control List Commands.
]] \\
[[packet:xrouter:docs:MAN7#LOG|        LOG(7)         -- Activity logging options
]] \\
[[packet:xrouter:docs:MAN8#ACCESS.SYS|        ACCESS.SYS(8)  -- Telnet Access Control File.
]] \\
[[packet:xrouter:docs:MAN8#IPBAN.SYS|        IPBAN.SYS(8)   -- Banned IP addresses File.
]] \\
[[packet:xrouter:docs:MAN8#XROUTER.CFG|        XROUTER.CFG(8) -- Main Configuration File.
]] \\
[[packet:xrouter:docs:MAN9#AXSCTRL|        AXSCTRL(9)     -- TCP/IP Access Control.
]] \\

[[packet:xrouter:docs:|< Back to Index]]

----
===== IGATE =====
<code>IGATE(9)                XROUTER REFERENCE MANUAL            16/10/2023
</code> **NAME** <code>
        IGATE -- APRS Internet Gateway.

</code> **DESCRIPTION** <code>
        XRouter has an inbuilt APRS Igate, which allows received APRS
        packets to be gated to an Internet APRS server, and packets
        from the server to be gated to RF.  You will need an APRS port
        and an internet connection to take advantage of this.

        Igate operation is controlled mainly by configuration settings
        in file IGATE.CFG.  If the file isn't present, the igate
        daemon can be started, but nothing will happen.  The file
        includes keywords which specify the Internet APRS server
        addresses, various timers controlling connections, the
        filtering rules for gating packets, and the logging options.

        In addition to the settings in IGATE.CFG there are a few in
        XROUTER.CFG, which control whether or not the Igate daemon
        starts at boot-up, and which ports may send to and receive
        from the Internet.


        Choosing and specifying Internet Servers
        ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

        The choice of server, and the TCP port to use on that server,
        depends on where in the world you are located, and what sort
        of data you're interested in.  There are several types of
        server, and the services they provide aren't always
        comparable.

        Some servers provide a "raw" data feed containing APRS
        activity from all over the world, which can amount to a
        considerable volume.  Some also provide "filtered" or "local"
        feeds, e.g. Ohio-only or messages-only.

        There's no point in connecting to a "raw" feed if there is a
        "local" feed available, as you will merely be wasting CPU
        time and internet bandwidth downloading data you are going to
        discard.  APRS message-only feeds tend to be on port 1314,
        whereas "raw" feeds tend to be on port 10151, or 2023 if
        it's a Ahub server.

        Using a browser to connect to http://server_address:14501
        sometimes  produces a status page containing useful server
        addresses. You could start your search at "first.aprs.net".

        In IGATE.CFG you may specify as many servers as you wish, each
        on a separate line with the following format:

               SERVER <ipaddress | hostname>:<port>

               e.g. SERVER 128.196.58.1:1314

        The port number must be separated from the IP address or
        hostname by a colon so that the combined address:port forms a
        contiguous string of characters with no spaces.

        The servers are tried in rotation, starting with the first on
        the list. If a connection attempt fails, or the link
        subsequently closes, the next server is tried.  When the end
        of the list is reached it starts all over again at the first
        one.  The behaviour is modified by various timer settings
        - see below.

        You may find out which server is currently in use by using the
        "TCP STATUS" command.


        Connection Timers
        ~~~~~~~~~~~~~~~~~

        There are various keywords which may be used in IGATE.CFG to
        control the timings associated with connections to the
        Internet servers, and they are as follows:

        WAIT <secs> -- Time to wait for connection establishment.

            Specifies the number of seconds to wait for connection
            after sending a connect request.  If not specified, the
            default is 60.  
            If you have a permanent Internet connection, you may wish
            to set a lower value, but if you're using dialup you may
            wish to make it longer, e.g. 90 secs to allow time for
            dialling and modem negotiation.  If no response is
            received from the server within the WAIT interval, the
            next server in the SERVER list will be tried.

        PAUSE <secs> -- Interval between successive tries.

            Specifies the number of seconds to wait between successive
            connection attempts to the same server.  Default is 60
            secs.

            If a server goes down or fails to respond, there's no
            point in aggressively trying to connect. For one thing,
            if you have connection logging enabled you will build a
            big logfile!  This timer is mainly of use when you have
            only one server in you SERVERS list, or when several
            servers go down.

        MAXTRIES <n> -- No. of failed connect attempts allowed.

            If a server consistently fails to respond to connect
            attempts, there's a good chance it has gone temporarily or
            permanently off line.  The MAXTRIES value specifies the
            maximum number of failed connect attempts allowed before a
            server is ignored, and the default is 10.  If the limit is
            reached, that particular server will not be retried until
            the SKIP interval (see below) expires.

        SKIP <secs> -- "Blacklist" interval.

            Specifies the amount of time for which a server will not
            be tried after MAXTRIES failed connect attempts.  This
            effectively removes a server from the list for the SKIP
            interval, after which it is placed back on the list.
            Default is 3600 secs (1 hour).


        Packet Filtering
        ~~~~~~~~~~~~~~~~

        The Igate contains powerful packet filters, which can be
        applied to traffic gated in both directions.  The filtering
        rules are specified in IGATE.CFG using IFILTER (internet to
        packet) and PFILTER (Packet to internet) statements, the
        general form of which are as follows:

               xFILTER <from_call> <to_call> <text>

        Each field may include the following wildcards:

               *     Matches zero or more characters.
               ?     Matches any single character.
               #     Matches a single digit.
               @     Matches a single alphabetic character.
               \     Escape - interpret next character literally.

            The '*' character may only be used at the end of a field.

        For example:  "IFILTER G#@@@*  *  :*" will accept from the
        internet feed only those packets sent by valid G0 to G9 + 3
        letter callsigns, addressed to anyone, which contain APRS
        messages.

        The '\' (escape) character causes the next character to be
        interpreted literally, instead of as a wildcard, e.g. "\*"
        will match '*' and "\\" will match '\'.

        A caret '^' at the start of any field will invert the sense of
        the whole test, causing matching packets to be REJECTED, e.g. 

               IFILTER ^M7ABC  *    *
               IFILTER *       ^APZ244*   !*

        The first statement will reject all packets from M7ABC, and
        the second will reject all static position reports sent to the
        destination APZ244 (e.g. if they can't be trusted).  Rejection
        statements MUST be placed at the beginning of the filter
        rules, before any catch-alls.

        The maximum length of each field (pattern) is currently 10
        characters.  There is no limit to the number of xFILTER
        statements you may specify.  If no rules are specified,
        nothing will be gated.

        All valid APRS and UI-View packets (except 3rd party packets,
        and those with NOGATE or RFONLY somewhere in the digi path)
        received by the router are offered to the PFILTER, providing
        the appropriate DIGIFLAGS are set (see below). Mic-E packets
        are decoded to text before being offered to the Internet
        servers because they may contain characters which won't pass
        through the servers.  This decoding takes place before
        filtering.

        You should be VERY careful when designing your filter rules,
        as you could quite easily overload the RF channel by
        attempting to gate too much data to it.  There is little point
        in gating non-local data.

        To reduce unnecessary traffic, APRS "messages" are only gated
        to RF if the recipient has been seen locally on RF within the
        last hour.


        Radius of Interest
        ~~~~~~~~~~~~~~~~~~

        In IGATE.CFG the statement "RADIUS <km>" sets a radius in
        Kilometres from XRouter's position.  Position reports from
        within this radius are gated to RF, providing they pass the
        IFILTER rules.  The default radius is 100Km.  Setting
        "RADIUS 0" allows unlimited gating of positions.


        Controlling gating direction / port(s)
        ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

        Regardless of any other settings, an XRouter port will not
        broadcast packets received from the Internet, or offer
        received packets to the internet, unless the appropriate bits
        are set in the port DIGIFLAG. You should add one or both of
        the following values to DIGIFLAG:

            Bit Value Option
            ------------------------------------------------
             6   64   Enable gating from Packet to Internet.
             7  128   Enable gating from Internet to Packet.

        Packets accepted (i.e. passing IFILTER) from the Internet are
        broadcast on ALL ports which have bit 7 of DIGIFLAG set, so be
        careful not to lazily set DIGIFLAG to 255!


        Activity logging
        ~~~~~~~~~~~~~~~~

        Igate activity can be recorded in the file ./LOG/IGATE.LOG by
        including a LOG keyword with non zero argument in IGATE.CFG.
        The argument is a number made up as follows:

            Bit Value Option
            ------------------------------------------------
             0    1   Record Igate daemon start and stop events.
             1    2   Record Inet server connections / disconnections.
             2    4   Record frames sent from Internet to Packet.
             3    8   Record frames sent from Packet to Internet.

        The "record frames" options can generate a lot of data, so
        they're intended mainly for testing purposes, e.g. making sure
        your filters are correctly set.  To avoid the logfile growing
        too big, you are advised to periodically rename or otherwise
        remove it, allowing a fresh one to start.


        Starting and stopping the Igate daemon
        ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

        The daemon may be started and stopped at any time with the
        commands "START IGATE" and "STOP IGATE".  If the daemon is
        already running, attempting to restart it will simply produce
        an error message, as will trying to stop it if already
        stopped.

        The IGATE.CFG file is re-read each time the daemon is started,
        so the configuration can be changed without stopping XRouter,
        by editing the file (using Notepad or the PZTDOS line editor),
        then re-starting the daemon.  Editing can take place while
        the daemon is running.

        The daemon may be started automatically when XRouter boots, by
        including IGATE=1 in the "global" section of XROUTER.CFG.

</code> **SEE ALSO:** \\
[[packet:xrouter:docs:MAN9#APRS|        APRS(9)        -- Automatic Packet Reporting System.
]] \\
[[packet:xrouter:docs:MAN1#DIGIFLAG|        DIGIFLAG(1)    -- Display / Set digipeat options.
]] \\
[[packet:xrouter:docs:MAN3#EDIT|        EDIT(3)        -- PZTDOS Line Editor.
]] \\
[[packet:xrouter:docs:MAN8#IGATE.CFG|        IGATE.CFG(8)   -- IGATE Configuration File.
]] \\
[[packet:xrouter:docs:MAN1#START|        START(1)       -- Start Daemon Processes.
]] \\
[[packet:xrouter:docs:MAN1#STOP|        STOP(1)        -- List / Stop Daemon Processes.
]] \\
[[packet:xrouter:docs:MAN1#TCP|        TCP(1)         -- TCP status / configuration commands.
]] \\
[[packet:xrouter:docs:MAN8#XROUTER.CFG|        XROUTER.CFG(8) -- Main Configuration File.
]] \\

[[packet:xrouter:docs:|< Back to Index]]

----
===== INFO =====
<code>INFO(9)                 XROUTER REFERENCE MANUAL            21/10/2023
</code> **NAME** <code>
        INFO -- Info System.

</code> **DESCRIPTION** <code>
        When the user issues the "I" command without any arguments,
        the text specified by INFOMSG (in XROUTER.CFG) is sent to
        him.

        However, this command may also form the entry point for a
        much more comprehensive information system which the sysop
        may configure how he wishes.  For example you may wish to
        include details of the local packet network and clubs, and
        maybe a set of tutorials on general packet topics...

        In order to do this, the INFO directory must exist (within
        the directory containing XRouter), and must contain the
        desired info in the form of text files with the extension
        ".INF".

        After using "I" by itself, the user will then be invited to
        enter "I *" to list the available info topics.  If the user
        enters that command, the filenames (without the .INF) are
        displayed in alphabetical order, and the user is invited to
        read the files using the "I <topic>" form of the command.

        If the user enters a filename which is not found,
        XRouter displays a list of similar filenames. 

        The filename should be relevant to the contents, but try to
        keep it fairly short.  You should aim to keep each file
        concise in order to save air time, preferably breaking
        complex subjects into a series of small files with "see also"
        references to link them.  It is very frustrating for users to
        begin reading a file only to discover it's not of interest,
        and then having to wait a long time for it to finish!  You
        may use ANSI or HTML in the files, but not pure binary. 

        Within the .INF files, lines beginning with a semicolon ';'
        are not displayed to users, so you can use them for comments,
        such as file modification and version details.

</code> **SEE ALSO:** \\
[[packet:xrouter:docs:MAN9#HELP|        HELP(9)     -- Help System
]] \\
[[packet:xrouter:docs:MAN9#INFO-SVC|        INFO-SVC(9) -- NetRomX Information Service
]] \\

[[packet:xrouter:docs:|< Back to Index]]

----
===== INFO-SVC =====
<code>INFO-SVC(9)             XROUTER REFERENCE MANUAL              7/9/2023
</code> **NAME** <code>
        INFO-SVC -- NetRomX Information Service

</code> **DESCRIPTION** <code>
        Isn't it frustrating to connect to a node, only to find that
        there is no INFO command, or the sysop hasn't bothered to set
        up any information?

        Where in the world is it? We aren't all familiar with country
        prefixes!

        What software is it running? That affects which commands we
        must use to find information. What sort of node is it? Just a
        router, or is it the node underlying a BBS or DX cluster?
        Where can I find more information about the system, the
        person or group responsible, the software etc?

        The NetRomX "Information Service" (service no. 1) is intended
        to answer some of your questions. It is accessed by
        connecting to service 1 on any XRouter running version 501v
        or later. For example, to connect to G8PZT's info service:

            C G8PZT 1

        The information is provided in a form which is readable by
        both humans and machines. It is of the "<keyword>: <value>"
        form, with each piece of information on a separate line.
        Every keyword is unique. Only a few have been implemented so
        far, although others are planned. Your suggestions would be
        welcome.

        The server closes the connection after sending the data.

        The INFO command accomodates this feature, so the user
        doesn't even have to remember the service number or add the
        "stay" flag. The syntax is:

            I[nfo] [nodecall | nodealias]

        Here's a typical session: 

            info kidder
            VK2DOT-1:DOTXR} Info:
            Trying G8PZT::1...

            VK2DOT-1:DOTXR} Connected to G8PZT::1 

            Node-Type: Host / Router
            Node-Callsign: G8PZT
            Node-Alias: KIDDER
            QTH: Kidderminster, Worc's
            Maidenhead: IO82VJ
            Position: 52.400002 / -2.250000
            Sysop-Callsign: (to be done)
            Software-Type: AX25+NetRom+IP Router/Node
            Software-Name: XrPi
            Software-Version: 501y (19/7/20)
            Software-Author: Paula G8PZT
            Software-Info: http://vk2dot.dyndns.org/xrpi
            Software-Uptime: 4d, 11h, 3m, 58s
            Local-Time: Fri, 21 May 2021 03:27:06 +0000
            Local-Sunrise: 05:05
            Local-Sunset: 21:08
            Netrom-Known: 250
            Netrom-Neighbours: 6
            AX25-Links: 6
            Amprnet-IP: 44.136.16.6
            Amprnet-Name: g8pzt.ampr.org
            Netrom-Services: 1,2,7,8,9,13,14,16,18,19,21,23,80,87

            VK2DOT-1:DOTXR} Welcome back 

</code> **SEE ALSO:** \\
[[packet:xrouter:docs:MAN1#INFO|        INFO(1)     -- Display information.]] \\
[[packet:xrouter:docs:MAN9#INFO|        INFO(9)     -- Info system.]] \\
[[packet:xrouter:docs:MAN9#SERVICES|        SERVICES(9) -- NetRomX Standard Services.]] \\

[[packet:xrouter:docs:|< Back to Index]]

----
===== INP3 =====
<code>INP3(9)                 XROUTER REFERENCE MANUAL            17/10/2023
</code> **NAME** <code>
        INP3 -- Inter-Node Protocol 3.

</code> **DESCRIPTION** <code>
        INP3 is version 3 of the so-called "Internode Protocol". This
        is a protocol for exchanging time-based routing information
        between neighbour nodes.  Despite the misleading name, it is
        not concerned with general inter-node traffic, only the
        routing information.

        INP3 is analogous to NetRom nodes broadcasts, except that the
        information is "unicast" to each neighbour via the normal
        AX25L2 inter-node links, instead of being broadcast via UI
        frames.

        NetRom nodes broadcasts and INP3 can happily co-exist on the
        same network, as they are are concerned with different
        metrics.  NetRom broadcasts propogate route QUALITY, whilst
        INP3 unicasts propogate TRIP TIME.  These are two completely
        different metrics, and there is NO valid way to convert one to
        the other, especially quality to time, since route quality is
        such a nebulous and subjective quantity.

        However, there is one caveat: Some types of node software,
        including Linux and (X)net (no relation to XRouter!) convert
        time to quality and vice versa.  This causes distorted routing
        when qualities are converted to bogus trip times.  Assigning
        slightly lower route qualities to these neighbours helps to
        prevent traffic being diverted through them. 

        The protocol is summarised below:


        Information Exchange 
        ~~~~~~~~~~~~~~~~~~~~

        All INP3 routing information traffic between two neighbour
        nodes is carried alongside regular inter-node traffic, by
        AX25L2 numbered information frames with PID 0xCF (NetRom).


        Link Quality Estimation
        ~~~~~~~~~~~~~~~~~~~~~~~

        The "quality" of an inter-node link is determined by its mean
        one-way frame transport time, usually measured by the exchange
        of L3RTT frames.  This value is called the Smoothed Neighbour
        Transport Time (SNTT).


        Trip Time
        ~~~~~~~~~

        This is the all-important metric.  For a given target node, it
        is simply the sum of all the intermediate nodes' SNTTs.  It is
        measured in 10ms units, with a maximum (horizon) value of
        60000, i.e. 600 seconds.  A trip time of 60000 is used to mark
        a route as unusable.

        The sysop may set a local limit which is less than 60000 using
        MAXTT.  Routes which exceed the local limit are propogated
        with the horizon value.

        In this context "route" means a path through the network,
        involving one or more intermediate nodes.  The optimum route
        to a target node is generally considered to be the one with
        the lowest trip time.


        Hop Count
        ~~~~~~~~~

        Each inter-node link is counted as one HOP.  This is a second
        metric which is propogated alongside trip time.  Routes with
        lower hop counts are preferred.  A hop count of 30 is
        considered to be the horizon, and marks the route as unusable.

        The sysop may set a local limit which is less than 30 using
        MAXHOPS.  Routes which exceed the local limit are propogated
        with the horizon value.


        Propogation of Routing Information
        ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

        A route via a neighbour is valid as long as it is regularly
        updated in unicasts from that neighbor, with a trip time less
        than the horizon.  If the route is not regularly updated, or
        the trip time reaches the horizon, that route is marked as
        unusable.  If the link with the neighbour is broken, all
        routes via that neighbour are marked as unusable. 

        Routes with trip time below the horizon are called positive
        information and represent available nodes.  Positive
        information is not time critical and, like NetRom nodes
        broadcasts, is sent at scheduled intervals only.

        Any update of positive information with a slower target time
        (or route loss) is called negative information.  This is
        always propogated immediately.

        Information about nodes which are routed via a neighbour is
        never returned to that neighbour.  Instead it is returned with
        horizon values.  This is called "poisoned reverse". 


        Packet Structure
        ~~~~~~~~~~~~~~~~

        Routing information is exchanged using "Routing Information
        Frames" (RIF), containing one or more Routing Information
        Packet" (RIP).  Each RIP contains information about one node,
        such as callsign,  trip time and hop count, plus optional
        fields such as alias and IP address.

        A RIF starts with a single identification byte of 0xFF. This
        value is guaranteed not to appear in normal L3 frame headers
        as the first byte.  The end of the RIF is marked by a zero
        byte, 0x00.  The following diagram shows a RIF containing
        one RIP:


        Byt: 1      7          1          2            n        1        
        .------.----------.--------.-------------.-----------.------.
        | 0xFF | <axcall> | <hops> | <trip time> | <options> | 0x00 |
        '------'----------'--------'-------------'-----------'------'
                <------ Routing Information Packet --------->
         <-------------- Routing Information Frame ---------------->

        <axcall>      Callsign in AX25 format
        <hops>        No. of hops to target (1-30)
        <trip time>   Trip time to target in 10ms units (1-60000)
        <options>     Variable length options field as below:


        Bytes:      1        1      n = <length>
              .----------.--------.--------------.
              | <length> | <type> |    <data>    |
              '----------'--------'--------------'

              <length>  Length of data field in bytes (0-255)
              <type>    Type of data field (0=alias, 1=IP addr)
              <data>    Data field.

</code> **SEE ALSO:** \\
[[packet:xrouter:docs:MAN9#L3RTT|        L3RTT(9)   -- Layer 3 Round Trip Time
]] \\
[[packet:xrouter:docs:MAN7#MAXHOPS|        MAXHOPS(7) -- Maximum Hop Count.
]] \\
[[packet:xrouter:docs:MAN7#MAXTT|        MAXTT(7)   -- Maximum Trip Time.
]] \\
[[packet:xrouter:docs:MAN1#QUALITY|        QUALITY(1) -- NetRom Route Quality.
]] \\
[[packet:xrouter:docs:MAN1#ROUTES|        ROUTES(1)  -- Add, Drop & List Neighbour Routes.
]] \\

[[packet:xrouter:docs:|< Back to Index]]

----
===== IP-CODES =====
<code>IP-CODES(9)             XROUTER REFERENCE MANUAL            17/10/2023
</code> **NAME** <code>
        IP-CODES -- IP Country Codes.

</code> **SYNOPSIS** <code>
        List of Amprnet region codes.

</code> **DESCRIPTION** <code>
        Within Amprnet, the second octet from the left usually
        represents a country or region. The following is a list of
        those regions.        

        IPADDR  REGION(s)
        -----------------------------------------------
        44.002  USA: California: Sacramento
        44.004  USA: California: Si Valley - SFO
        44.006  USA: California: Sta Barb/Ventura 
        44.008  USA: California: San Diego 
        44.010  USA: California: Orange Countyl
        44.012  USA: Eastern Washington,Idaho
        44.014  USA: Hawaii & Pacific Islands
        44.016  USA: California: Los Angeles/Valley
        44.017  USA: California: Antelope/Kern County
        44.018  USA: California: San Brdo & Riverside
        44.020  USA: Colorado: Northeast
        44.022  USA: Alaska 
        44.024  USA: Washington:Western/Puget 
        44.026  USA: Oregon 
        44.028  USA: Texas: North
        44.030  USA: New Mexico
        44.032  USA: Colorado: Southeast
        44.034  USA: Tennesee
        44.036  USA: Georgia
        44.038  USA: South Carolina
        44.040  USA: Utah
        44.042  USA: Mississippi
        44.044  USA: Massachusetts:western
        44.046  USA: Missouri
        44.048  USA: Indiana
        44.050  USA: Iowa
        44.052  USA: New Hampshire
        44.054  USA: Vermont
        44.056  USA: Eastern&Central Mass
        44.058  USA: West Virginia
        44.060  USA: Maryland
        44.062  USA: Virginia
        44.064  USA: New Jersey: northern
        44.065  USA: New Jersey: southern
        44.066  USA: Delaware
        44.068  USA: New York:
        44.069  USA: New York: WNY
        44.070  USA: Ohio - old
        44.071  USA: Ohio - new
        44.072  USA: Illinois
        44.073  USA: Illinois
        44.074  USA: North Carolina (east)
        44.075  USA: North Carolina (west)
        44.076  USA: Texas: south
        44.077  USA: Texas: west
        44.078  USA: Oklahoma
        44.080  USA: Pennsylvania: eastern
        44.082  USA: Montana
        44.084  USA: Colorado: Western
        44.086  USA: Wyoming
        44.088  USA: Connecticut
        44.090  USA: Nebraska
        44.092  USA: Wisconsin
        44.094  USA: Minnesota
        44.096  USA: District of Columbia
        44.098  USA: Florida
        44.100  USA: Alabama
        44.102  USA: Michigan
        44.104  USA: Rhode Island
        44.106  USA: Kentucky
        44.108  USA: Louisiana
        44.110  USA: Arkansas
        44.112  USA: Pennsylvania: western
        44.114  USA: N&S Dakota
        44.116  USA: Oregon:NW&PDX,Vancouver
        44.118  USA: Maine
        44.120  USA: special use in Nevada
        44.122  USA: Kansas Puckett
        44.123  USA: Virgin Islands
        44.124  USA: Arizona
        44.125  USA: Southern Nevada, Northern Nevada
        44.126  Puerto Rico
        44.128  Reserved for testing
        44.129  Japan
        44.130  Germany
        44.131  United Kingdom
        44.132  Indonesia
        44.133  Spain
        44.134  Italy
        44.135  Canada
        44.136  Australia
        44.137  Netherlands
        44.138  Israel
        44.139  Finland
        44.140  Sweden
        44.141  Norway
        44.142  Switzerland
        44.143  Austria
        44.144  Belgium 
        44.145  Denmark
        44.146  Philippines
        44.147  New Zealand
        44.148  Ecuador
        44.149  Hong Kong
        44.150  Slovenija
        44.151  France
        44.152  Venezuela
        44.153  Argentina
        44.154  Greece
        44.155  Ireland
        44.156  Hungary
        44.157  Chile
        44.158  Portugal
        44.159  Thailand, Laos, Vietnam, Kampuchea
        44.160  South Africa
        44.161  Luxembourg
        44.162  Cyprus
        44.163  Central America: Panama, Costa Rica, Nicaragua,
        44.163  Central America: Honduras, El Salvador
        44.163  Central America: Guatamala, Belize, Netherland Antilles
        44.164  Surinam, French Guiana, Guyana, Mozambique
        44.164  Atlantic Equitorial Islands, Martinique
        44.164  Trinidad&Tobago, Falkland Islands, Aruba
        44.165  Poland
        44.166  Korea
        44.167  India, Bangladesh, Nepal, Burma 
        44.168  China, Taiwan
        44.169  African Continent
        44.170  Croatia
        44.171  Colombia, Peru, Uruguay
        44.172  Sri Lanka, Malaysia
        44.173  Mexico
        44.174  Brazil
        44.175  Cuba, Dominican Republic, Haiti
        44.176  Turkey
        44.177  Czech Republic
        44.178  Russia
        44.179  Gibraltar, Malta/Gozo
        44.180  Yugoslavia(Serbia&Montenegro)
        44.181  Slowak Republic
        44.182  Romania
        44.183  Iceland
        44.184  Lebanon
        44.185  Bulgaria
        44.186  Singapore
        44.187  Lithuania, San Marino
        44.188  Armenia, Azerbaijan, Belarus, Estonia, Georgia,
        44.188  Kazakhstan, Kyrgyzstan, Latvia, Moldova, 
        44.188  Tajikstan, Turkmenistan, Ukraine, Uzbekistan 
        44.189  Bosnia & Herzegovinia
        44.190  Pacific Islands, Guam
        44.193  Outer Space
        44.194  Oceana
        44.195  Antarctica
        44.196  Arctic
</code>
[[packet:xrouter:docs:|< Back to Index]]

----
===== IPENCAP =====
<code>IPENCAP(9)              XROUTER REFERENCE MANUAL            17/10/2023
</code> **NAME** <code>
        IPENCAP -- IP-in-IP Encapsulation.

</code> **DESCRIPTION** <code>
        The orginal form of IP-within-IP encapsulation, used by
        KA9Q NOS to tunnel amateur IP (amprnet or 44-net) datagrams
        via the public Internet, was IPIP, which used protocol number
        94.  Somewhere in the mists of time, the protocol number was
        changed to 4 and the protocol was renamed IPENCAP (usally
        referred to as ENCAP, but sometimes still called IPIP).

        The structure of both types is the same, and is shown below.
        Only the IP "protocol" number is different.  It can be seen
        that the amprnet (inner) datagram is carried within the
        "payload" section of a public (outer) IP datagram:

                .------------------.--------------------------.
                | Public IP header |    Amprnet IP datagram   |
                '------------------'--------------------------'
                <-------------- Public IP datagram ----------->


        Unfortunately IPENCAP is deliberately blocked by Windows,
        starting with XP Service Pack 2, as a "security measure".
        Therefore, **unless you use the NdisXpkt driver**, it is not
        possible to use IPENCAP via an **Ethernet adaptor** with XR32.
        This is a Windows problem, not an XR32 problem!!  However, it
        is still possible to use IPEncap via SLIP and PPP links.

        (Note that the older form of the protocol, IPIP (protocol 94)
        *isn't* blocked by Windows, and may be therefore be used
        without NdisXpkt.)

        There are no sush restrictions on the DOS and Linux versions
        of XRouter.

        IPENCAP can be used to route amprnet datagrams across *any*
        TCP/IP network, not just the Internet.  For example it can be
        used to tunnel datagrams between nodes on a LAN.  In this case
        the "outer" IP header would contain LAN IP addresses, and the
        "inner" header might contain amprnet IP addresses.

        The IPENCAP protocol is used extensively between amprnet
        gateways.  The routing entries to achieve this are found in
        file ENCAP.TXT (usually only available by secure FTP). See
        the MAN page for ENCAP.TXT for more info.


        Configuring IPENCAP
        ~~~~~~~~~~~~~~~~~~~

        Note: For the purposes of this guide it is assumed that your
        connection to the Internet is via a domestic NAT/PAT router
        with firewall. 

        This may sound obvious, but in order to create any form of
        tunnel between amprnet hosts, each host needs both an amprnet
        (44.x.x.x.) and a public (e.g. 62.x.x.x) address. You MUST
        ensure that your amprnet IP address is specified as XRouter's
        "main" address, by including the line IPADDRESS=44.x.x.x near
        the top of the XROUTER.CFG file (replacing x.x.x with your IP
        address). 

        If you are using the EXTERNAL interface (which allows XRouter
        to use its own IP stack), you then "override" the main address
        on the port which connects to the LAN or Internet, by
        including a different IPADDRESS= statement in the PORT block.

        If you are not using the EXTERNAL interface, Windows or Linux
        provides the LAN/Internet IP address for you. 

        Secondly, you and your link partner(s) must set up and test
        IP routing between your public (i.e. non-44.x.x.x) IP
        addresses.  You cannot proceed until this step is complete! 

        IPENCAP encapsulation is specified by IP ROUTE entries with
        mode "e" (encap).  For example, the format to use in
        IPROUTE.SYS is as follows:

             IP ROUTE ADD  44.131.91.0/24  66.23.18.2  0  encap

        The first IP address is the amateur IP address, or range
        thereof, to be routed via this IPENCAP tunnel.  If you don't
        fully understand this format, see the MAN page for the IP
        command. 

        The second address is the public IP address or hostname of the
        link partner to whom the first address(es) will be routed.  It
        is more efficient to use an IP address if possible, rather
        than a hostname, but the hostname may be required if the
        partner's public IP address changes frequently. (DO NOT put
        the partner's 44-net address in here!) 

        The last but one field (which is normally an XRouter PORT
        number in normal route entries) is ignored and you set it to
        zero.

        Mode "encap" signifies IPENCAP encapsulation. 

        In ENCAP.TXT and XENCAP.TXT the format is as follows:

             route addprivate 44.0.0.0/8 encap 66.23.18.2

        In either case the mode "encap" can be abbreviated to "e"
        alone.

        Be aware that IPENCAP is subject to your access control rules,
        and depending on your existing rules you may need to add the
        following line to your rules in IPROUTE.SYS...

            ACL PERMIT  0.0.0.0/32  0.0.0.0/0


        Internet Routers
        ~~~~~~~~~~~~~~~~

        If you wish to route IPENCAP across the Internet, don't forget
        to specify a routing for IP *protocol* 4 (note *protocol* not
        TCP/UDP port) in any "front-end" routers:

        If XRouter is indirectly connected to the Internet via an
        intermediate router, that router will probably be using some
        form of NAT (Network Address Translation) to share one
        "public" IP address between several systems on your LAN.  The
        "front end" router will probably route outgoing IPENCAP
        without problem, but it will not know where to send incoming
        IPENCAP unless explicitly configured.

        Configuring such a router for IPENCAP usually involves
        specifying a protocol number (4 for IPENCAP), and the LAN IP
        address of a machine to which it should be routed, i.e.
        XRouter's LAN IP address.

        You are advised that not all domestic routers can be
        configured to route *incoming* IPENCAP as it is not a
        commercially recognised protocol.  Some routers only allow
        TCP and UDP port forwarding, with no provision for any other
        protocol.  If you or your link partner have such a router,
        you may need to consider IPUDP instead.

</code> **SEE ALSO:** \\
[[packet:xrouter:docs:MAN8#ENCAP.TXT|        ENCAP.TXT(8)   -- Amprnet Encapsulated Routing File.
]] \\
[[packet:xrouter:docs:MAN1#IP|        IP(1)          -- IP Routing / Configuration Commands.
]] \\
[[packet:xrouter:docs:MAN9#IPIP|        IPIP(9)        -- IPIP Protocol.
]] \\
[[packet:xrouter:docs:MAN8#IPROUTE.SYS|        IPROUTE.SYS(8) -- IP Routing / Configuration File.
]] \\
[[packet:xrouter:docs:MAN9#IPUDP|        IPUDP(9)       -- IP-within-UDP Encapsulation.
]] \\
[[packet:xrouter:docs:MAN8#XROUTER.CFG|        XROUTER.CFG(8) -- Main Configuration File.
]] \\

[[packet:xrouter:docs:|< Back to Index]]

----
===== IPIP =====
<code>IPIP(9)                 XROUTER REFERENCE MANUAL            17/10/2023
</code> **NAME** <code>
        IPIP -- IPIP Encapsulation.

</code> **DESCRIPTION** <code>
        IPIP is the "old" form of IP-within-IP encapsulation, used by
        KA9Q NOS to tunnel amateur IP (amprnet or 44-net) datagrams
        via the public Internet.  Somewhere in the mists of time, the
        protocol number was changed to 4 and the protocol was renamed
        IPEncap (usally referred to as ENCAP).

        The structure of both types is the same, and is shown below.
        Only the IP "protocol" number is different.  It can be seen
        that the amprnet (inner) datagram is carried within the
        "payload" section of a public (outer) IP datagram:

                .------------------.--------------------------.
                | Public IP header |    Amprnet IP datagram   |
                '------------------'--------------------------'
                <-------------- Public IP datagram ----------->


        Unfortunately IPEncap is deliberately blocked by Windows,
        starting with XP Service Pack 2, as a "security measure".
        Therefore, **unless you use the NdisXpkt driver**, it is not
        possible to use IPEncap with XR32.  This is a Windows
        problem, not an XR32 problem!! There are no such restrictions
        on the DOS and Linux versions of XRouter.

        IPIP provides an alternative to IPEncap that ISN'T blocked by
        Windows.  If you are using the NDIS driver, IPIP is provided
        automatically.  If you are not using NDIS, you need to put
        IPIP=1 in XROUTER.CFG in order to activate IPIP.

        IPIP can be used to route amprnet datagrams across *any*
        TCP/IP network, not just the Internet.  For example it can be
        used to tunnel datagrams between nodes on a LAN.  In this case
        the "outer" IP header would contain LAN IP addresses, and the
        inner IP header might contain amprnet addresses.


        Configuring IPIP
        ~~~~~~~~~~~~~~~~

        Note: For the purposes of this guide it is assumed that your
        connection to the Internet is via a domestic NAT/PAT router
        with firewall. 

        This may sound obvious, but in order to create any form of
        tunnel between amprnet hosts, each host needs both an amprnet
        (44.x.x.x.) and a public (e.g. 62.x.x.x) address. You MUST
        ensure that your amprnet IP address is specified as XRouter's
        "main" address, by including the line IPADDRESS=44.x.x.x near
        the top of the XROUTER.CFG file (replacing x.x.x with your IP
        address). 

        If you are using the EXTERNAL interface (which allows XRouter
        to use its own IP stack), you then "override" the main IP 
        address on the port which connects to the LAN or Internet, by
        including a different IPADDRESS= statement in the PORT block.

        If you are not using the EXTERNAL interface, Windows or Linux
        provides the LAN/Internet IP address for you. 

        Secondly, you and your link partner(s) must set up and test
        IP routing between your public (i.e. non-44.x.x.x) IP
        addresses.  You cannot proceed until this step is complete! 

        IPIP encapsulation is specified by IP ROUTE entries with mode
        "i". For example, the format to use in IPROUTE.SYS is as
        follows:

             IP ROUTE ADD  44.131.91.0/24  66.23.18.2  0  ipip

        The first IP address is the amateur IP address, or range
        thereof, to be routed via this IPIP tunnel.  If you don't
        fully understand this format, see the MAN page for the IP
        command. 

        The second address is the public IP address or hostname of the
        link partner to whom the first address(es) will be routed.  It
        is more efficient to use an IP address if possible, rather
        than a hostname, but the hostname may be required if the
        partner's public IP address changes frequently. (DO NOT put
        the partner's 44-net address in here!) 

        The last but one field (which is normally an XRouter PORT
        number in normal route entries) is ignored and you set it to
        zero.

        Mode "ipip" signifies IPIP encapsulation. 

        In XENCAP.TXT the format is as follows:

             route addprivate 44.0.0.0/8 ipip 66.23.18.2

        In either case the mode "ipip" can be abbreviated to "i"
        alone.  Mode "ipip" is allowed in XENCAP.TXT but not in
        ENCAP.TXT.

        Be aware that IPIP is subject to your access control rules,
        and depending on your existing rules you may need to add the
        following line to your rules in IPROUTE.SYS...

            ACL PERMIT  0.0.0.0/32  0.0.0.0/0


        Internet Routers
        ~~~~~~~~~~~~~~~~

        If you wish to route IPIP across the Internet, don't forget to
        specify a routing for IP *protocol* 94 (note *protocol* not
        TCP/UDP port) in any "front-end" routers:

        If XRouter is indirectly connected to the Internet via an
        intermediate router, that router will probably be using some
        form of NAT (Network Address Translation) to share one
        "public" IP address between several systems on your LAN.  The
        "front end" router will probably route outgoing IPIP without
        problem, but it will not know where to send incoming IPIP
        unless explicitly configured.

        Configuring such a router for IPIP usually involves specifying
        a protocol number (94 for IPIP), and the LAN IP address of a
        machine to which it should be routed, i.e. XRouter's LAN IP
        address.

        You are advised that not all domestic routers can be
        configured to route *incoming* IPIP as it is not a
        commercially recognised protocol.  Some routers only allow
        TCP and UDP port forwarding, with no provision for any other
        protocol.  If you or your link partner have such a router,
        you may need to consider IPUDP instead.

</code> **SEE ALSO:** \\
[[packet:xrouter:docs:MAN1#IP|        IP(1)          -- IP Routing / Configuration Commands.
]] \\
[[packet:xrouter:docs:MAN9#IPENCAP|        IPENCAP(9)     -- IPENCAP Protocol.
]] \\
[[packet:xrouter:docs:MAN8#IPROUTE.SYS|        IPROUTE.SYS(8) -- IP Routing / Configuration File.
]] \\
[[packet:xrouter:docs:MAN9#IPUDP|        IPUDP(9)       -- IP-within-UDP Encapsulation.
]] \\
[[packet:xrouter:docs:MAN8#XROUTER.CFG|        XROUTER.CFG(8) -- Main Configuration File.
]] \\

[[packet:xrouter:docs:|< Back to Index]]

----
===== IP-PRIMER =====
<code>IP-PRIMER(9)            XROUTER REFERENCE MANUAL            17/10/2023
</code> **NAME** <code>
        IP-PRIMER -- IP Addressing / Routing Primer.

</code> **IP ADDRESSES** <code>
        All IP addresses consist of a 32 bit binary number, which
        is composed of four 8-bit binary numbers.  For clarity they
        are usually expressed as four decimal numbers separated by
        dots, the so called "dotted quad" form, for example
        44.131.91.2.

        Each of the numbers which make up the quad can range from
        0 to 255, i.e. 256 numbers in total.  The numbers 0, 128
        and 255 are usually reserved for special purposes.

        The most significant (leftmost) number identifies the
        "network" within the whole Internet.  44 was originally
        allocated to Amateur Packet Radio, or "ampr.org". However,
        the upper quarter of this range has now been sold off, so
        44 is no longer exclusively amprnet.

        Within the so-called "amprnet", the second number from the
        left usually identifies the country, although in the USA it
        generally identifies a state. In some parts of the world it
        identifies a group of countries. In our example 131 is the
        code for the whole UK. Numbers 192 and above no longer
        belong to amprnet.

        The third number from the left identifies the "region"
        within the country or state, and in our example region 91
        is North Worcestershire.

        The rightmost number identifies up to 256 separate users
        within the region.  The addresses within a region are
        sometimes allocated on a first come first served" basis,
        or sometimes in groups to allow further subdivision of a
        region.

</code> **IP ROUTING** <code>
        Unlike NetRom routing, IP routing is often explicitly defined
        by the sysop, although just like NetRom it can be automated
        using RIP (Routing Information Protocol). The IP equivalent
        of a NetRom "nodes table" is the "IP routes table". This can
        be initialised using entries in IPROUTE.SYS.

        The basic idea is that, for any destination IP address,
        XRouter must send the IP packet (usually called a
        "datagram") either directly to the destination (if it's on
        the LAN or within radio range), or to a "gateway" which
        knows how to reach the destination.  In the most extreme
        case, you can simply send all non-local IP traffic to a
        gateway, who will handle it for you.

        Since there are billions of IP addresses, it would be
        impractical to define a route for every possible
        destination. This is where the hierarchical structure
        of IP addresses come to your aid.

        If you are in the USA, you don't need to know explicitly
        how to route to everyone in the UK. All you need to know
        is how to route to the UK, then the routers within the UK
        will do the work for you. If you don't know a route to
        the UK, simply route the traffic to a gateway who does.
        There is always someone willing to act a a gateway on your
        behalf.

        Routing decisions are made using a special combination of
        IP addresses and "bits", for example 44.0.0.0/8. This tells
        XRouter to compare the destination IP address of datagrams
        with the leftmost 8 bits of 44.0.0.0, ignoring the
        rightmost 24 bits. This will match any address beginning
        with 44, i.e. the whole of amprnet (as was). Since the
        rightmost 24 bits are ignored, 44.131.91.2/8 would have
        *exactly* the same effect.

        The higher the number of bits, the more precise the match,
        for example 44.131.0.0/16 would "catch" all datagrams
        addressed to the UK, 44.131.91.0/24 would catch all
        datagrams addressed to North Worcestershire, UK, and
        44.131.91.2/32 would match only one destination, namely
        44.131.91.2.  The "/32" is always the default if the
        number of bits is not specified.

        Having "caught" a destination, the remainder of a routing
        entry tells XRouter which gateway (if any) to send it to,
        which port to send it on, and what mode to use.

        IP routing is usually specified in IPROUTE.SYS using
        commands like this:

        IP ROUTE ADD <host>[/len] <gateway> <port> [mode [metric]]

        Example: IP ROUTE ADD 44.131.93.0/24  44.131.93.240  5  d

        This would route all region 93 traffic (44.131.93.0 -
        44.131.93.255) to the gateway 44.131.93.240 on port 5
        using datagram mode.

</code> **ROUTING MODES** <code>
        The routing [mode] indicates how the traffic is to to be
        handled, and is specified using a single letter as
        follows:
        
            d = Datagram (direct)
            e = Encap (ip-over-ip protocol 4)
            i = IPIP  (ip-over-ip protocol 94)
            n = Netrom (ip-over-netrom)
            r = Reject
            s = Silent discard
            u = IPUDP  (ip-over-UDP) 
            v = Virtual circuit (ip-over-ax25)
            k = Kernel

        "Datagram" is the usual mode, and is the default if "mode"
                   is omitted. It transmits datagrams "raw" inside
                   SLIP, PPP, Ethernet or AX25 UI frames, according
                   to the protocol used on the the destination port. 
                   There is no error correction at the link layer,
                   so datagram mode should only be used on wire
                   links, or RF links with low loss rates. 

        "Virtual Circuit" mode gives better performance on less
                          than perfect RF links. It transports the
                          IP datagrams inside AX25 <I> frames,
                          detecting and correcting errors at the
                          link layer.

        "Netrom" mode is less efficient, but can "tunnel" datagrams
                 across non-ip sections of the network by wrapping
                 them in Netrom layer 3 frames.

        "Encap" mode is used for IP/IP encapsulation, i.e. sending
                44-net datagrams across the Internet by "wrapping"
                them in datagrams with public Internet addresses.
                This uses IP protocol number 4. Unfortunately, in
                some cases Windows blocks this protocol (see below). 

        "IPIP" is the original IP-within-IP encapsulation mode,
               using IP protocol number 94, and has the advantage
               that it is not blocked by Windows.

        "IPUDP" mode is similar to Encap and IPIP, except that the
                datagrams are first wrapped in UDP before being
                transported in IP.  The advantage is that UDP is
                usually able to pass through routers which don't
                support IPIP or IPEncap, and can be selectively
                routed to different machines according to the UDP
                service port numbers.

        "Reject" entries are used to reject traffic destined for
                 systems which don't exist, or are which not
                 reachable via any port.  If simply routed on the
                 default port, such datagrams would waste resources
                 and would probably end up looping back to us.
                 Datagrams matching a "reject" entry are rejected
                 by returning an ICMP "destination unreachable"
                 report to the sender.  The "gateway" ip address
                  should be 0.0.0.0 and the port number is ignored.

        "Silent Discard" entries are similar to "Reject", except
                         that they simply dump the unwanted
                         datagrams without sending an ICMP error
                         report.  This saves bandwidth when the
                         problem is persistent, and is more
                         suitable than "Reject" for suppressing
                         malicious network probes.
 
        "Kernel" mode is a dummy mode. It tells XRouter to use the
                  host operating system's TCP/IP services to handle
                  this traffic. It is intended only as a last resort,
                  e.g. when operating without the EXTERNAL intarface.
                  The host O/S allows XRouter to originate and
                  terminate TCP, UDP, IPIP, ICMP and AXIP, but not to
                  *route* those protocols.  Therefore, using a mode
                  "k" entry you may Telnet and Ping from XRouter, but
                  you are not allowed to route 3rd party traffic, e.g.
                  from RF to Internet.


</code> **ENCAP BLOCKING** <code>
        Starting with Windows XP Service Pack 2, the IPEncap (encap)
        protocol 4 was blocked by Windows for so-called "security
        reasons".

        Therefore if you are using WinXPSP2 or a later O/S, encap
        mode can only be used via Ethernet if XR32 is able to
        bypass Windows and talk directly to the Ethernet card using
        the NDISXPKT driver. But this driver is currently only
        available for Windows 2000 and XP.

        This means that, until an NDIS driver is written for later
        versions of Windows, you are not able to use encap mode on
        those platforms.

        However this only applies to Ethernet. If you have a SLIP
        or PPP (i.e. serial cable) link with another system, you
        may use encap mode whatever operating system is in use.

        Linux does not block IPEncap, but you may need to give
        XRouter the required privileges to use it.

</code> **ADDRESS RESOLUTION PROTOCOL (ARP)** <code>
        ARP is responsible for mapping gateway IP addresses to
        "hardware" (i.e. AX25 or Ethernet) addresses.

        In order to send an IP datagram over an AX25 or Ethernet
        network, it must be "wrapped" in an AX25, Ethernet, or
        Netrom packet, and that packet will need a destination
        address appropriate to that network. For example, to route
        a datagram to 44.131.91.2 it must be wrapped in an AX25
        packet addressed to GB7PZT-5.

        The system *will* sometimes work without any ARP entries,
        due to the process of "ARP resolution", whereby a router
        can make a broadcast asking adjacent systems if they know
        the hardware address for a given IP address, but this
        process takes time and the adjacent routers may not know
        the answer.  Thus, for RF links at least, it is advisable
        to put ARP entries for each of your direct RF neighbours
        int IPROUTE.SYS. The general form of an ARP entry is:

            ARP <ADD | PUBLISH> <host> <hwtype> <hwaddr>

        <host>   is the neighbour's IP address in dotted quad form.

        <hwtype> is the hardware address type, i.e. "ax25"
                 "netrom" or "ether".

        <hwaddr> is the hardware address, i.e. AX25 callsign or
                 Ethernet address.

        Example ARP entries:

        This one causes datagrams bound for 44.131.90.6 to be
        wrapped in AX25 packets addressed to GB7IPT-9:

             arp add 44.131.90.6  ax25  GB7IPT-9

        Whereas the following will send datagrams bound for
        44.131.95.7 to the G7GHP-5 system via the GB7DIG digipeater.
        Up to 8 digipeaters may be used in a single comma-delimited
        string:

             arp add 44.131.95.7  ax25  G7GHP-5,GB7DIG

        This one will wrap datagrams destined for 44.131.24.1 in
        Netrom packets addressed to node GB7CX:

             arp add 44.131.24.1  netrom  GB7CX

        The following will wrap the datagrams in ethernet packets.

             arp add 44.131.91.9  ether  00:00:1B:2C:04:81

        ARP PUBLISH is used in cases where one system is "hidden"
        behind another, and allows other systems to discover the
        correct hardware address to use.

        For example, say 44.131.91.127 is only reachable via
        44.131.91.245.  Unless all the local systems were
        specifically configured to route to 91.127 via 91.245,
        they wouldn't know how to do it. Including the entry:
        "arp publish 44.131.91.127 ax25 g8pzt" on the 91.245
        (g8pzt) router causes it to respond to anyone who asks
        for the hardware address for 91.127, giving its own ax25
        address.

</code> **SEE ALSO:** \\
[[packet:xrouter:docs:MAN1#ARP|        ARP(1)         -- Address Resolution Protocol Commands.
]] \\
[[packet:xrouter:docs:MAN1#IP|        IP(1)          -- IP Routing / Configuration Commands
]] \\
[[packet:xrouter:docs:MAN8#IPROUTE.SYS|        IPROUTE.SYS(8) -- IP Router Control File.
]] \\

[[packet:xrouter:docs:|< Back to Index]]

----
===== IPUDP =====
<code>IPUDP(9)                XROUTER REFERENCE MANUAL            17/10/2023
</code> **NAME** <code>
        IPUDP -- IP-over-UDP Tunnelling.

</code> **DESCRIPTION** <code>
        The "Amateur Packet Radio IP Network" (amprnet) is a private
        network for transferring TCP/IP between amateur radio
        stations.  It was originally assigned the class A IP address
        block 44.x.x.x, but although it is notionally part of the
        wider Internet, the public Internet has limited knowledge of
        how to route it.

        To solve this problem, amprnet traffic is usually wrapped or
        "encapsulated" within publicly-routable IP datagrams.  At the
        destination gateway the frame is "unwrapped" to reveal the
        original amprnet datagram. 

        IPUDP is IP encapsulated in UDP/IP.  It allows amateur IP to
        be transported across other IP networks such as the Internet,
        to form "Virtual Private Networks" (VPN's).

        In contrast to IPIP and IPEncap, which transport the private
        (e.g. amateur) IP directly inside the payload portion of a
        public (e.g. Internet) IP datagram, IPUDP transports the
        private datagram in the payload portion of a UDP frame, which
        is itself transported as payload in a public IP datagram.
        This requires 8 bytes more overhead than IPIP, but it is far
        more flexible. 


            .------------------.----------------------------------.
            | Public IP header | UDP Header | Amprnet IP datagram |
            | 62.31.20.2       |   94->94   |   44.131.91.2       |
            | -> 82.31.65.8    |            |   ->44.68.1.5       |
            '------------------'------------'---------------------'
             <---------------- Public IP datagram --------------->

                           IPUDP Packet Structure

           (In the above diagram, the amprnet (44-net) datagram
              forms the payload of a publicly-routable UDP/IP
              datagram. The IP addresses are for illustrative
                             purposes only.) 


        IPIP and IPENCAP, hereafter collectively referred to as
        IP-in-IP, are "portless" protocols, and it is therefore
        difficult (in come cases impossible) to make them pass
        through some types of domestic NAT / PAT router which rely on
        translating TCP and UDP service port numbers in order to
        share a public IP address among several LAN hosts. 

        IPUDP overcomes this limitation because it transports the data
        using a well known protocol (UDP) which NAT / PAT routers can
        understand, thus it can get through where IP-in-IP cannot.
        For example, it is easy to configure even the most basic
        domestic router to route incoming UDP port 94 to a specific
        machine on the LAN, but it is not often possible to do the
        same with IP *protocol* 4. 

        The IPUDP protocol currently defaults to UDP port 94 for no
        better reason than because the number was easy to remember,
        being the same as the original protocol number for IPIP.  In
        addition, there were no other well-known protocols using this
        port number.  If difficulties are encountered with port 94,
        please inform the protocol originator (G8PZT). There's nothing
        to stop you using any other UDP port number.

        IPUDP is only used for tunnelling amateur IP through the
        public Internet, or for situations where conventional routing
        isn't possible (e.g. XR32 without NdisXpkt).  It would be
        pointless when routing via a radio link. 

        IPUDP tunnels are one-way.  To create two-way IPUDP routing,
        the other end of a link needs to set up a reverse tunnel.
        However, the reverse route needn't necessarily use a tunnel. 


        When To Use IPUDP
        ~~~~~~~~~~~~~~~~~

        If you are running a Linux version of XRouter, most of this
        following section may be ignored, and you can jump to the
        final two paragraphs...
 
        The Windows version of XRouter (XR32) was originally designed
        to be used with the NdisXpkt driver, which allowed it to have
        its own LAN IP address and IP stack.  In this mode it could
        route anything, just like its DOS predecessor (XR16). 

        However, there is no 64-bit version of the NdisXpkt driver,
        so XR32 was subsequently made "dual-mode", such that it could
        be made to run with or without the driver. 

        Without the NdisXpkt driver, XR32 was forced to use facilities
        provided by the Windows TCP/IP stack.  Those facilities were
        limited, and in some cases were deliberately crippled by
        Microsoft.  For example, later versions of Windows XP prevent
        the use of IPENCAP (protocol number 4). 

        Since no-one likes having to install and load drivers, the
        majority of sysops now tend to use XR32 without NdisXpkt.
        However this is a "basic" mode, with limited facilities,
        compared to the "full" (NdisXpkt) mode. It was only intended
        as a stop-gap measure, until a 64-bit driver could be written. 

        In basic mode, XR32 can originate and terminate all the common
        protocols (TCP, UDP, ICMP etc.), but cannot actually route raw
        IP via the *Ethernet* NIC without some form of encapsulation.
        (SLIP / PPP connections are not restricted in this way)

        As mentioned above, XR32 in "basic" mode cannot currently use
        the IPENCAP protocol, so your options for routing IP via an
        Ethernet NIC are limited to the following: 

        a) Route IP across existing AXUDP/AXIP links.

           This is the least efficient in terms of packet overhead,
           although that is of litle concern on a broadband
           connection!  It is easy to set up, but the downside is that
           you can only route traffic to your immediate AXUDP or AXIP
           neighbours, not the wider world. However, if everyone sets
           up their default routes to direct the traffic to and from
           an IPENCAP-capable gateway, this should be no barrier. 


        b) Use original IPIP protocol (protocol number 94).
 
           This is the most efficient, and allows you to make a single
           hop (as far as 44-net is concerned) tunnel to *any*
           gateway that can accept IPIP protocol 94.  In order to
           receive this protocol however, your Internet router must be
           capable of routing by PROTOCOL, which many routers aren't.
           This protocol doesn't involve AX25 at all. 


        c) Use IPUDP protocol.

           This option also allows you to hop directly to any other
           gateway, providing they can handle IPUDP, and it doesn't
           use AX25.  It is only marginally less efficient than IPIP,
           and as mentioned previously, it has the advantage that it
           is easy to route through NAT/PAT routers. 


        Although DOS and Linux versions of XRouter (and XR32 in
        "full" mode) allow IPEncap, you cannot use IPEncap if your
        Internet router can't handle it.  In this case, IPUDP may be
        the preferable option.

        Even if your domestic Internet router can handle the IP-in-IP
        protocols (4 and 94), it can only route such traffic to ONE
        host on the LAN. But it can route IPUDP to multiple hosts, if
        different UDP port numbers are used.


        Creating An IPUDP Tunnel
        ~~~~~~~~~~~~~~~~~~~~~~~~

        (Note: For the purposes of this guide it is assumed that your
        connection to the Internet is via a domestic NAT/PAT router
        with firewall.) 

        The following may sound obvious, but in order to create any
        form of tunnel between amprnet hosts, each host needs both an
        amprnet (44.x.x.x.) and a public (e.g. 62.x.x.x) address.  You
        MUST ensure that your amprnet IP address is specified as
        XRouter's "main" address, by including the line
        IPADDRESS=44.x.x.x near the top of the XROUTER.CFG file
        (replacing x.x.x with your IP address). 

        If you are using the EXTERNAL interface (which allows XRouter
        to use its own IP stack), you then "override" this IP address
        on the Ethernet port, by including an IPADDRESS= statement in
        the Ethernet PORT block.  The IP adress should be approriate
        for your LAN.  If you are not using the EXTERNAL interface,
        Windows or Linux provides the LAN IP address instead. 

        Secondly, you and your link partner(s) must set up and test IP
        routing between your public (i.e. non-44.x.x.x) IP addresses.
        You cannot proceed until this step is complete! 

        If you are using a domestic router between XRouter and the
        Internet, you must "open" UDP port 94 to direct incoming IPUDP
        traffic to XRouter's LAN address. This must be a "static"
        (permanent and unchanging) translation, not a transient or
        "port triggered" one. 

        Finally, for each tunnel destination you must add an IP route
        entry into IPROUTE.SYS, similar to the following: 

            IP ROUTE ADD  44.131.91.0/24    62.31.206.176  0   u


        The first IP address is the amateur IP address, or range
        thereof, to be routed via this IPUDP tunnel.  If you don't
        fully understand this format, see the manual sections
        detailing IPROUTE.SYS and the IP ROUTE ADD command. 

        The second address is the public IP address or hostname of the
        link partner to whom the first address(es) will be routed.  It
        is more efficient to use an IP address if possible, rather
        than a hostname, but the hostname may be required if the
        partner's public IP address changes frequently. (DO NOT put
        the partner's 44-net address in here!) 

        The last but one field (which is normally an XRouter PORT
        number in normal route entries) is used in IPUDP entries to
        modify the UDP service number.  "0" is the recommended
        setting, meaning "use default" (see below). 

        Mode "u" signifies IPUDP encapsulation. 


        Reassigning the IPUDP Port Number
        ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
        Since you can only have one application using a given UDP port
        number per IP stack, you are not able to run more than one
        copy of XRouter on the same machine unless you reassign or
        disable the IPUDP ports to avoid contention.  You may do this
        using the IPUDPPORT=n keyword anywhere in XROUTER.CFG, where
        n is a number between 0 and 65535. 

        It is recommended that you use port 94 (the default) as the
        primary port, 95 as the first alternative, 96 for the second,
        97 for the third, and so on, as these numbers are not assigned
        to any particular service.  You should avoid using the numbers
        associated with standard services such as DNS (53), DHCP (67
        and 68), AXUDP (93), WINS (135) and so on.  For a
        comprehensive list search for "assigned numbers" on the web.

        Please bear in mind that if you reassign your IPUDP port,
        others will not be able to route IPUDP to you unless you
        inform them of the new number. 


        Routing to Alternative UDP port
        ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

        Creating an IPUDP tunnel to a peer who has reassigned his
        IPUDP port is relatively simple, as the following example
        shows: 

            IP ROUTE ADD  44.131.91.0/24   62.31.206.176  95   u

        Note the "95" in the last but one field, which tells XRouter
        to address the packets to UDP port 95 instead of the default
        port 94.  That's all there is to it! 


        Disabling IPUDP
        ~~~~~~~~~~~~~~~ 

        If you are using XRouter for AX25/Netrom only, and don't wish
        to take part in the amprnet, then you probably won't have
        included an IPADDRESS= line in XROUTER.CFG.  In this case all
        IP facilities, including IPUDP, are disabled automatically.

        However, you may have an IP address but wish to disable IPUDP
        for other reasons. You can do this easily by including the
        directive "IPUDPPORT=0", anywhere in XROUTER.CFG.


        More Info
        ~~~~~~~~~

        This file is too big already. For FAQ and troubleshooting
        info, please see the MAN page entitled IPUDP-FAQ.

</code> **SEE ALSO:** \\
[[packet:xrouter:docs:MAN1#IP|        IP(1)          -- IP Routing / Configuration Commands.
]] \\
[[packet:xrouter:docs:MAN9#IPENCAP|        IPENCAP(9)     -- IPENCAP Protocol.
]] \\
[[packet:xrouter:docs:MAN9#IPIP|        IPIP(9)        -- IPIP Protocol.
]] \\
[[packet:xrouter:docs:MAN8#IPROUTE.SYS|        IPROUTE.SYS(8) -- IP Routing / Configuration File.
]] \\
[[packet:xrouter:docs:MAN9#IPUDP|        IPUDP(9)       -- IP-within-UDP Encapsulation.
]] \\
[[packet:xrouter:docs:MAN9#IPUDP-FAQ|        IPUDP-FAQ(9)   -- IPUDP Frequently Asked Questions.
]] \\
[[packet:xrouter:docs:MAN9#NDISXPKT|        NDISXPKT(9)    -- NDISXPKT Driver.
]] \\
[[packet:xrouter:docs:MAN8#XROUTER.CFG|        XROUTER.CFG(8) -- Main Configuration File.
]] \\

[[packet:xrouter:docs:|< Back to Index]]

----
===== IPUDP-FAQ =====
<code>IPUDP-FAQ(9)            XROUTER REFERENCE MANUAL            21/10/2023
</code> **NAME** <code>
        IPUDP-FAQ -- IPUDP FAQ / Troubleshooting.

</code> **DESCRIPTION** <code>
        This document contains Frequently Asked Questions and
        troubleshooting information related to the IPUDP protocol.
        It is a work in progress...


        IPUDP Frequently Asked Questions
        ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

        Q) Under what circumstances should I use IPUDP?

           A) You might consider using IPUDP in the following
              situations: 

           - When you cannot use IPEncap because are running XRouter
             on Windows without the NdisXpkt driver. 

           - When your Internet router cannot handle "portless"
             protocols such as IPIP, IPEncap, AXIP etc. 

           - When you have an existing system that requires your
             Internet router to route IPENCAP to it (you can only
             have one IPENCAP host per public IP address). 

           - When you have more than one system on the same public
             IP address and require independent routing to each. 

           - When you have more than one XRouter on the same machine,
             with different 44-net addresses. 

           - When you wish to route between 44-net systems on your
             LAN that can't use IPEncap. 

           - Just for the fun of it! :-) 


        Q) Can I Send IPUDP To Anyone? 

           A) No. It is believed that IPUDP is only implemented by
              XRouter at the time of writing.


        Q) If I use IPUDP, can I still use other forms of IP routing? 

           A) Yes. You can safely "mix and match" your IP routing
              modes to suit your own requirements.  What you mustn't
              do is have identical route table entries with different
              modes.  Nothing dangerous will happen, but XRouter will
              ignore the duplicates. 


        Q) Do I need an AXIP interface to use IPUDP?

           A) No. IPDUP is completely unrelated to AX25, AXIP, AXUDP
              etc. and does not need a special INTERFACE or PORT. 


        Q) Do I need ENCAP.TXT?

           A) No, not for IPUDP itself, but you may need it if you
              intend to use IPEncap alongside IPUDP.

              There is an XRouter-only version of ENCAP.TXT called
              XENCAP.TXT, which can accept routing modes other than
              "encap".  Place it into your XRouter working directory
              and type IP ROUTE LOAD to read it into your routing
              table.

              If you wish to add your system(s) to the list so that
              they can receive IPUDP traffic, please email
              g8pzt[at]blueyonder.co.uk, stating your callsign, the
              subnet address(s) that you handle, your public IP
              address, and your IPUDP port number if it isn't 94. 


        Troubleshooting
        ~~~~~~~~~~~~~~~

        IPUDP is a well-proven technology.  When things don't work,
        it is always due to a configuration error, not a fault in
        XRouter.

        Try PINGing the destination host to see if XRouter generates
        an error message. Some of the errors so far observed are
        listed below: 

        o Boot up error: "IPUDP Initialisation error 20048" 

          The IPUDP port is already in use by another process on the
          PC.  This error is usually caused by trying to run more
          than one XRouter on the same machine.  You must use the
          IPUDPPORT keyword in XROUTER.CFG to disable IPUDP on all
          but one XRouter, or to assign a different port number to
          each one. 


        o Error 9x02 (No memory)
 
          This should never happen, but if it does, Windows must be
          seriously overloaded!  This is a transient error, and
          should clear itself.  If not, close some apps.


        o Error 9206 (Permission denied)
 
          The IP Access Control List is preventing the packet from
          being sent because the combination of source and
          destination IP addresses is not within one of the ranges
          you have defined to be "legal".  Possible causes are: 

          - XRouter's "main" IP address not defined, or is not a
            44-net address.
 
          - Incorrect configuration of IP Access Control List.
            Try commenting out all the ACL entries in IPROUTE.SYS and
            reloading the file.  If this fixes the problem, there is
            a faulty of missing entry.  You may need to add the
            following entry: ACL PERMIT  0.0.0.0/32  0.0.0.0/0


        o Error 9411 

          The IPUDP subsystem was not initialised because the main IP
          address was not defined, or because IPUDPORT is set to 0 in
          XROUTER.CFG. 


        o No Response From Target

          Assuming you have set up the route entry correctly, there
          are many possible reasons for failure.  The following list
          is by no means exhaustive: 

          - Your system has no viable route to the target's public
            IP address.  Try PINGing or Telnetting to that address.
            Note that if IP QUIET or firewalling is active, you may
            not get a reply to your PINGs.

          - There is a higher priority but non-functional route in
            the IP routing table, preventing the IPUDP route from
            being used.

          - There's a problem with your or your partner's Internet
            connection.
 
          - The target system is currently off-line for maintenance.

          - The target's sysop has disabled IPUDP, or has reassigned
            the IPUDPPORT.
 
          - The target's Internet router is not set up to route IPUDP
            to his XRouter, or the response is via IPUDP and your
            Internet router is not set up to route it to your
            XRouter.
 
          - The target's IP addresses are set up incorrectly.
 
          - The target hasn't configured a route that leads back to
            you. Note that he doesn't need to configure a *direct*
            route back to you, he may send it via other routers or
            gateways.

          - An intermediate router is dropping the return packets.

          - The response is IPUDP and the target is replying to the
            wrong UDP port number.
 
          - The response is via IPEncap and your Internet router is
            not set up to route it, or your system is not using
            NdisXpkt (Windows only), and can therefore not accept
            IPEncap. 

</code> **SEE ALSO:** \\
[[packet:xrouter:docs:MAN1#IP|        IP(1)          -- IP Routing / Configuration Commands.
]] \\
[[packet:xrouter:docs:MAN9#IPENCAP|        IPENCAP(9)     -- IPENCAP Protocol.
]] \\
[[packet:xrouter:docs:MAN9#IPIP|        IPIP(9)        -- IPIP Protocol.
]] \\
[[packet:xrouter:docs:MAN8#IPROUTE.SYS|        IPROUTE.SYS(8) -- IP Routing / Configuration File.
]] \\
[[packet:xrouter:docs:MAN9#IPUDP|        IPUDP(9)       -- IP-within-UDP Encapsulation.
]] \\
[[packet:xrouter:docs:MAN9#NDISXPKT|        NDISXPKT(9)    -- NDISXPKT Driver (Windows Only).
]] \\
[[packet:xrouter:docs:MAN8#XROUTER.CFG|        XROUTER.CFG(8) -- Main Configuration File.
]] \\
[[packet:xrouter:docs:MAN#
|
]] \\

[[packet:xrouter:docs:|< Back to Index]]

----
===== KISS =====
<code>KISS(9)                 XROUTER REFERENCE MANUAL            17/10/2023
</code> **NAME** <code>
        KISS -- KISS Protocol.

</code> **DESCRIPTION** <code>
        KISS (Keep It Simple, Stupid) is a simple protocol which
        encapsulates AX25 frames for transmission over serial (e.g.
        RS232) lines.  The framing method is identical to SLIP.
        There is no flow control or error handling in the original
        protocol.

        The protocol specifies the following special characters:

                Name  Hex   Dec  Purpose
                ---------------------------
                FEND  0xC0  192  Frame End
                FESC  0xDB  219  Frame Escape
                TFEND 0xDC  220  Transposed FEND
                TFESC 0xDD  221  Transposed FESC

        The FEND characters mark the start and end of the frame
        containing the encapsulated datagram as follows:

                .------.------.-------.------.
                | FEND | Type | Data  | FEND |
                '------'------'-------'------'

        In order to ensure that the FEND character only occurs at the
        start and end of the frame, FENDs which occur within the
        unencapsulated data are "escaped" to the two byte sequence
        FESC TFEND. Likewise FESC is escaped to the sequence
        FESC TFESC.

        It is permissible (but not obligatorry) for two frames to
        share a FEND:

                .------.------.-------.------.------.-------.------.
                | FEND | Type | Data  | FEND | Type | Data  | FEND |
                '------'------'-------'------'------'-------'------'
              

        The first byte of each frame, after the FEND, is a "type"
        indicator.  This byte is broken into two 4-bit nibbles such
        that the low-order nibble indicates the command number (given
        in the table below) and the high-order nibble indicates the
        port number for that particular command.  In systems with
        only one HDLC port, it is by definition Port 0.  In
        multi-port TNCs, the upper 4 bits of the type indicator byte
        can specify one of up to sixteen ports.

        The following commands are defined:

        Command  Function    Comments
        -------------------------------------------------------------- 
           0     Data frame  The rest of the frame is data received
                             from / to be sent to the HDLC channel.   

           1     TXDELAY     The next byte is the transmitter keyup
                             delay in 10 ms units.  The default
                             start-up value is 50 (i.e. 500 ms). 

           2     PERSIST     The next byte is the persistence
                             parameter, p, scaled to the range 0-255
                             with the following formula: P=p*256-1
                             The default value is P=63 (i.e. p=0.25).  
 
           3     SLOTTIME    The next byte is the slot interval in 10
                             ms units. The default is 10 (i.e. 100ms). 

           4     TXTAIL      The next byte is the time to hold up the
                             TX after the FCS has been sent, in 10 ms
                             units.  This command is obsolete, and is
                             included here only for compatibility
                             with some existing implementations.  
 
           5     FULLDUP     The next byte is 0 for half-duplex,
                             nonzero for full-duplex. The default is 0
                             (i.e. half-duplex).  

           6     SetH/w      Specific for each TNC.  In the TNC-1,
                             this command sets the modem speed.  Other
                             implementations may use this function for
                             other hardware-specific functions.  
    
          255    Return      Exit KISS and return control to a higher
                             level program.  This is useful only when
                             KISS is incorporated into the TNC along
                             with other applications.  
        --------------------------------------------------------------

        Only command 0 is allowed in frames from TNC to host.
        Commands 1 to 6 are used to set TNC parameters, and are
        usually sent at 5 minute intervals.


        Limitations Of Plain KISS
        ~~~~~~~~~~~~~~~~~~~~~~~~~

        In the original protocol, there is no error detection to
        protect against noise and corruption on the RS232 lines.

        More seriously, the host has no way of knowing how much data
        is queued in the TNC awaiting transmission. A busy channel
        could prevent the TNC from transmitting, causing the host's
        FRACK timer to repeat frames, which simply add to the queue.
        When the channel clears, the original frame and all the
        repeats are spewed out in one huge transmission, causing the
        other end of the link to respond with a load of acks.  In bad
        cases, the AX25 module retries out, so when the channel
        clears, the original frame, plus repeats, plus a string of
        <DISC> frames are sent!


        KISS With Checksum
        ~~~~~~~~~~~~~~~~~~

        Checksum-KISS appends a single byte checksum to the "data"
        portion of the frame, to detect line errors.  Frames that
        fail the checksum test are silently discarded.  The upper
        layer eventually detects the loss and re-sends the frame.


        KISS With Acknowledgement (ACKMODE)
        ~~~~~~~~~~~~~~~~~~~~~~~~~

        When operating in this mode, the host attaches a 16-bit
        "serial number" to each frame (between the "type" and "data"
        fields), and the TNC sends an "acknowledgement" frame to the
        host when it has transmitted that frame on-air.  This enables
        the host to know how much data is queued, and to start its
        AX25 timers at the correct time.  This mode uses the command
        code of 12 for both data frames and the acknowledgements.


        Polled KISS
        ~~~~~~~~~~~

        In this mode, the TNC does not send any data to the host until
        it is asked to do so by a POLL command (command number 14).

        This allows several TNC's to be multiplexed together (usually
        with a diode matrix) onto one COM port, which removes the need
        for one COM port per TNC.  Up to 16 TNC's can be multiplexed
        onto one COM port.  Each TNC must have a different "address",
        i.e. in the upper nybble of the Type field.
        

        Serial Line Parameters
        ~~~~~~~~~~~~~~~~~~~~~~

        Serial lines used for KISS must run at 8 data bits. Flow
        control must be hardware or none, as XON/XOFF flow control
        would interfere with the protocol.

        If flow control is used, the cable must contain at least 5
        cores, namely TXD, RXD, RTS, CTS and GND.  If flow control is
        not used, only TXD, RXD and GND are required.

        When KISS is used to connect a PC to a TNC, a "straight
        through" cable is used, because a TNC is considered a DTE
        (Data Terminal Equipment). 

        When KISS is used to interconnect two applications, some form
        of NULL MODEM is required. In the case of "real"
        RS232 this could be an actual null modem device, or a cable
        that is wired such that the TXDs at each end go to the RXDs
        at the other end, and the RTSs at each end go to the CTSs at
        the other.  "Virtual" COM port pairs such as Com0Com include
        this functionality as standard.


        Configuring a KISS Link
        ~~~~~~~~~~~~~~~~~~~~~~~

        KISS can be used to link XRouter with KISS TNC's, or with
        other KISS systems via real or "virtual" COM ports. A typical
        configuration in XROUTER.CFG would be as follows:

                INTERFACE=1
                        TYPE=ASYNC       <-- Serial RS232
                        COM=1            <-- COM port number (*)	
                        PROTOCOL=KISS    <-- Use KISS
                        SPEED=38400      <-- Baud rate
                        FLOW=0           <-- No flow control
                        MTU=256          <-- See below
                        KISSOPTIONS=NONE <-- Plain KISS
                ENDINTERFACE

                (*) On Linux versions COM specifies a TTY device name.

        MTU specifies the largest size for the data portion of an AX25
        frame, and the largest IP datagram that can be handled.  This
        should be set to 256 for KISS TNC's because they usually have
        small packet buffers.  For KISS links not using TNC's, MTU may
        be set larger, up to 1500.

        KISSOPTIONS are as follows:

            NONE     - Plain KISS (most TNC's use this) (default)

            POLLED   - For TNCs which send only when polled.

            CHECKSUM - Packets protected by checksum.  You can
                       only use this option if your TNC supports it.

            ACKMODE  - For TNC's which inform XRouter when a frame has
                       been transmitted on air.

            SLAVE    - XRouter will act like a polled KISS TNC,
                       sending only when commanded to do so.

            Polled and slave are mutually exclusive.
            BPQKISS eproms require POLLED and CHECKSUM, and their use
            of ackmode is optional.


        The PORT is configured like this:

                PORT=3
                        ID=144.675MHz User Port
                        INTERFACENUM=1
                        CHANNEL=B
                ENDPORT


        CHANNEL is only required if the TNC is not using its default
        channel / port.


        KISS TNC's
        ~~~~~~~~~~

        Most TNC's can be switched into KISS mode using a command
        such as "KISS ON", but they have a tendency to randomly drop
        back to command mode.  Therefore it is more usual to replace
        the EPROM with a purpose made KISS EPROM. There are several
        versions, such as BPQKISS, JKISS, KISS and 220KISS.  These
        usually default to channel A, but can be "patched" for other
        channels.

        For example the BPQKISS EPROM may be patched for different
        KISS channels by changing the byte at address 20(hex) in the
        PROM as follows:

                Channel Byte-20h     Channel Byte-20h
                ----------------     ----------------
                   A      00h           I      80h
                   B      10h           J      90h
                   C      20h           K      A0h
                   D      30h           L      B0h
                   E      40h           M      C0h
                   F      50h           N      D0h
                   G      60h           O      E0h
                   H      70h           P      F0h

        Once in KISS mode, the only way to switch a conventional TNC
        back to normal mode is to send the sequence 192, 255, 192 on
        the serial line.  This can be done using a terminal program
        and the numeric keypad, or a simple program such as
        KISSOFF.EXE.


        Dial-Up KISS
        ~~~~~~~~~~~~

        A temporary KISS connection may be established over an XRouter
        dial-up link using the MODE command in the DUN script.  This
        is only likely to be of use where phone calls are free!

</code> **SEE ALSO:** \\
[[packet:xrouter:docs:MAN9#DUN|        DUN(9)         -- Dial-up Networking.
]] \\
[[packet:xrouter:docs:MAN9#SLIP|        SLIP(9)        -- Serial Line Internet Protocol.
]] \\
[[packet:xrouter:docs:MAN8#XROUTER.CFG|        XROUTER.CFG(8) -- Main Configuration File.
]] \\

[[packet:xrouter:docs:|< Back to Index]]

----
===== L2FRAG =====
<code>L2FRAG(9)               XROUTER REFERENCE MANUAL            17/10/2023
</code> **NAME** <code>
        L2FRAG -- AX25 Layer 2 Fragmentation.

</code> **DESCRIPTION** <code>
        Data originated by XRouter is always packaged into the correct
        sized frames for the underlying link.  For AX25, this size is
        specified by PACLEN, which defines the largest payload of an
        information-bearing frame.

        However XRouter has no control over the size of NetRom
        datagrams originated at other systems, which may be larger
        than the PACLEN of the AX25 L2 link onto which they are to be
        routed.

        To cope with this situation, XRouter includes a layer 2
        fragmentation scheme, which (if enabled) breaks the datagram
        into two or more PACLEN (or smaller) chunks.  This scheme is
        only used for connected-mode AX25 (LAPB).  It supersedes an
        earlier NetRom-specific fragmentation scheme which appears to
        be no longer used.

        A fragmented datagram is indicated by the presence of a
        2-byte PID (Protocol Identifier) field in place of the usual
        single-byte field.  The first byte has the decimal value 8,
        indicating that a second PID byte follows.  The second byte
        indicates how many segments (up to 127) remain to be sent.
        The first segment is indicated by the value 128, and the last
        segment by 0, i.e. no fragments left.

        Whether or not XRouter uses fragmentation is controlled by
        bit 4 of CFLAGS (decimal 16).  If this bit is set, XRouter
        fragments outgoing datagrams if necessary.  If the flag is
        not set, datagrams are sent unfragmented.  This flag should
        only be set if the peer is known to be capable (xNOS systems
        usually are).

        If a fragmented datagram is received from a peer, that peer
        is assumed to be capable of fragmentation, and XRouter will
        enable fragmentation (and re-assembly of received fragments)
        regardless of the setting of bit 4 of CFLAGS. 

        Compatible Systems
        ~~~~~~~~~~~~~~~~~~

        xNOS and all versions of XRouter are known to be compatible
        with this scheme. The status of others such as BPQ32, PE1CHL
        Net etc. are unknown at the time of writing (2013). Reports
        would be appreciated.

</code> **SEE ALSO:** \\
[[packet:xrouter:docs:MAN7#CFLAGS|        CFLAGS(7) -- Connection Control Flags
]] \\
[[packet:xrouter:docs:MAN9#L3FRAG|        L3FRAG(9) -- NetRom Layer 3 Fragmentation.
]] \\
[[packet:xrouter:docs:MAN1#PACLEN|        PACLEN(1) -- AX25 Max Packet Length.
]] \\

[[packet:xrouter:docs:|< Back to Index]]

----
===== L3FRAG =====
<code>L3FRAG(9)              XROUTER REFERENCE MANUAL             16/10/2023
</code> **NAME** <code>
        L3FRAG -- NetRom Layer 3 Fragmentation.

</code> **DESCRIPTION** <code>
        Long ago there was a proposed scheme for fragmenting NetRom L3
        datagrams that were larger than the PACLEN of the underlying
        AX25 L2 link.  This involved breaking large datagrams into
        PACLEN (or smaller) fragments, and manipulating bits in the L2
        Protocol Identifier (PID), to indicate whether the L2 frame
        contained the first, intermediate or last fragment of a NetRom
        datagram.

        The PID values were as follows:

                Hex   Dec   Meaning
                ---------------------------------------------
                CF    207   First & last (i.e. only) fragment
                8F    128   First fragment    
                4F     64   Last fragment
                0F     15   Intermediate fragment. 

        The scheme was implemented in XRouter, but was not understood
        by BPQ, which was a popular node software of the time.
        Therefore the code had to be disabled.  It is not known which,
        if any, modern software implements this scheme.

        The fragmentation scheme described above is believed to have
        been superseeded by a general-purpose L2 fragmentation scheme
        as described in the MAN page entitled L2FRAG.

</code> **SEE ALSO:** \\
[[packet:xrouter:docs:MAN9#L2FRAG|        L2FRAG(9) -- AX25 Layer 2 Fragmentation.
]] \\
[[packet:xrouter:docs:MAN1#PACLEN|        PACLEN(1) -- AX25 Max Packet Length.
]] \\

[[packet:xrouter:docs:|< Back to Index]]

----
===== L3RTT =====
<code>L3RTT(9)              XROUTER REFERENCE MANUAL                7/9/2023
</code> **NAME** <code>
        L3RTT -- Layer 3 Round Trip Time.

</code> **DESCRIPTION** <code>
        L3RTT is an acronym for "Layer 3 Round Trip Time". L3RTT is a
        protocol for measuring the round trip time (RTT) of links.

        Round trip time is used to estimate the performance of a link.
        The smoothed one-way trip time is used in making routing
        decisions, and during the automatic estimation of route
        QUALITY (Autoqual).

        Whilst the layer *2* RTT for a link can be estimated by timing
        how long it takes to get an acknowledgement to a given AX25L2
        frame, this doesn't tell the full story.  The RTT may be good,
        yet the link may be experiencing delays simply because there
        is too much traffic queued on the link.

        L3RTT uses a special type of NetRom layer 3 packet which is
        immediately reflected back by the neighbour if it understands
        the protocol.  This packet is queued with other link traffic,
        so it gives a more accurate estimate of the layer 3 RTT at
        that moment.  The interval between queueing the L3RTT packet
        and receiving the returned packet is the layer 3 RTT.

        XRouter sends L3RTT packets on already-open neighbour node
        links at 5 minute intervals.  L3RTT does not open closed
        links.


        L3RTT frame format:
        ~~~~~~~~~~~~~~~~~~

        Bytes: 7       7       1     1   1   1   1   1            1
           .-------.-------.-------.---.---.---.---.---.--------.----.
           | l3src | L3dst | l3ttl | 0 | 0 | 0 | 0 | 5 | <text> | CR |
           '-------'-------'-------'---'---'---'---'---'--------'----'     
           <----- L3 Header ------><- Dummy L4header -><- Payload -->

           <l3src> is the sender's NODECALL
           <l3dst> is L3RTT-0
           <L3ttl> is 2 (decremeted to 1 by recipient)

        The dummy header simulates L4 <INFO S0 R0>, and the <text>
        field is as follows (one space between each field):

          6    10    10    10    10      6     11    n      n     n
        <fid> <ts> <srtt> <rtt> <pid> <alias> <id> <vers> <maxt> <flg>


            <fid>   Frame ID "L3RTT:"
            <ts>    Time stamp (10ms units)
            <srtt>  Smoothed Round Trip Time
            <rtt>   Last round trip time.
            <pid>   Unique ID for this packet.
            <alias> Nodealias of sender.
            <id>    INP3 version identifier: "LEVEL3_V2.1"
            <vers>  Software name and version e.g. "XRouter201c"
            <maxt>  Max trip time (10ms units) e.g. "$M60000"
            <flg>   Flags field: "$N" indicates INP3 capable

</code> **NOTES** <code>
        The above formatting can no longer be relied upon, as some
        faulty 64-bit softwares are overflowing the 10-byte fields!

        Some people complain that the L3RTT packets are too long. But
        that's the point! They are supposed to simulate typical data
        bearing frames. Short packets would give over-optimistic
        measurements, and may succeed on poor links where longer
        data-bearing packets would be subject to retries. 

</code> **SEE ALSO:** \\
[[packet:xrouter:docs:MAN9#AUTOQUAL|        AUTOQUAL(9) -- Automatic Route Quality
]] \\
[[packet:xrouter:docs:MAN1#QUALITY|        QUALITY(1)  -- Netrom Route Quality
]] \\

[[packet:xrouter:docs:|< Back to Index]]

----
===== MENU =====
<code>MENU(9)                 XROUTER REFERENCE MANUAL            24/10/2023
</code> **NAME** <code>
        MENU -- Console Pop-up Menu.

</code> **DESCRIPTION** <code>
        Console sysops can access a GUI-style "pop-up" menu at any
        time by hitting ALT_M (i.e. pressing the ALT and M keys
        together) at any time.

        This one-line "main" menu pops up on top of the the second
        line of the display, which is usually the title bar for
        whichever XRouter "window" is currently being displayed. 

        At the time of writing the top-level options are "File, View
        and Help.  The first character of each menu item is
        highlighted in red, signifying that it is a "hot-key", i.e.
        the menu item can be directly accessed by pressing the
        highlighted key.  ALT_F, ALT_V and ALT_H directly access the
        (F)ile, (V)iew and (H)elp menus respectively.

        The left and right arrow keys navigate the top level menu,
        highlighting the selected item in white text on a blue
        background. As each main memu item is selected, a "drop-down"
        sub-menu appears beneath it.

        The sub-menus also have "hot-keys" and highlighted items.
        The highlight can be moved using the up and down arrow keys,
        and the menu item can be actioned using the RETURN key. Or
        the item can be directly actioned using the hot key.

        For example, there are 3 ways to save the nodes table using
        this menu system:

        Firstly, ALT_M displays the main menu, where you can use the
        left or right arrow keys to select the (F)ile menu, the up
        and down arrow keys to select (S)ave nodes, then hit RETURN
        to perform the action.

        The second method is to use ALT_F to display the (F)ile menu,
        then select (S)ave Nodes using the up and down arrows and
        RETURN key as before.

        The third method is simply to use ALT_F followed by S. 

        This menu system is a forgotten work in progress, still a
        very long way from completion.  Feedback and suggestions are
        always welcome.

</code> **OPTIONS** <code>
        ALT+M    Top level menu

        ALT+F    (F)ile menu
                     (R)eload IP routes
                     (S)ave nodes table
                     E(X)it program

        ALT+H    (H)elp menu
                     (A)bout XRouter
                     (H)elp Topics
                     (M)anual Topics
                     (I)nfo Topics
                     (C)onfig Info

        ALT+V    (V)iew menu
                     C(L)ear Window  
                     S(Y)sop Chat
                     (C)hat Monitor
                     (S)ession Monitor
                     (N)odes Monitor
                     (R)outes Monitor
                     (X)router Status
                     Sec(U)rity Monitor
                     Console (1)
                     Console (2)
                     Console (3)

        The (H)elp, (M)an and (I)nfo Topics options display lists of
        the available topics. The lists can be navigated using the
        arrow keys, and the topic can be viewed in a scrollable
        window by hitting RETURN on the highlighted topic.
   
</code> **NOTE** <code>
        On the Windows version (XR32), the menu is accessed simply by
        tapping the ALT key, but this is not possible on Linux
        because Linux terminals don't produce a keycode when the ALT
        key is pressed by itself.
</code>
[[packet:xrouter:docs:|< Back to Index]]

----
===== MHEARD =====
<code>MHEARD(9)               XROUTER REFERENCE MANUAL            18/10/2023
</code> **NAME** <code>
        MHEARD -- "Monitor Heard".

</code> **DESCRIPTION** <code>
        MHEARD is another legacy command name from early TNC days.

        The MHEARD facility lists recently heard stations, and may be
        enabled or disabled for any port.  It records callsigns in
        reverse order of reception, with the most recent at the top of
        the list, along with other useful information, such as the
        date/time, position, type, and the number of frames heard.

        This allows sysops and users alike to discover who else the
        node can hear, to aid the search for suitable digipeaters, and
        to diagnose problems. 

        Even on linking-only ports, where there is only usually one
        partner, it provides a useful indication when the frequency
        is being encroached upon, either by deliberate squatting,
        unauthorised attempts to link, or lift conditions.

        It is therefore recommended that you enable MHEARD on all
        ports, and indeed this is the default.  The ability to disable
        MHEARD (to save memory) was necessary in DOS XRouter, but
        memory is not an issue in Windows and Linux versions. 

        If you have set your LOCATOR, or have included an APRS-style
        position report in your ID beacon, XRouter will know its own
        position and will display position, distance and bearing for
        any stations which broadcast APRS positions.  This is a great
        aid to network mapping, and it would be nice if everyone were
        to add APRS positions to their ID beacons.

        If a station was heard via a digipeater, the digipeater call
        is also shown, and the letter "D" is shown in the "type"
        field.  If the heard station is a node, the letter "N" is
        displayed. If it is sending IP traffic, "I" is shown, and if
        it is sending ARP traffic, "A" is shown.

        Within XROUTER.CFG, the "MHEARD=n" directive is used in each
        PORT definition block to enable or disable the MHEARD facility
        and to set the size of the list.  For example "MHEARD=50",
        enables it and sets the table size to record a maximum of 50
        callsigns.  If the directive is omitted, the default size is
        15 callsigns.

        You can control which types of station are recorded in the MH
        list using the "MHFLAGS=n" directive in XROUTER.CFG, or by
        using the MHFLAGS command during run-time.  The default value
        for n is 255 (show everything), and the number is formed by
        adding numbers representing the desired options as follows:

           1   Record directly heard stations
           2   Record directly heard digipeaters
           4   Record digipeated stations
           8   Record direct/digipeated separately for each station
          16   Preserve MHeard list across reboot

        For example "MHFLAGS=3" would show directly heard stations and
        digipeaters, but not the stations heard via digipeaters.

        If the "Preserve MHeard lists across reboot" option is set,
        the PORTs MHEARD list is saved to disk at exit and re-loaded
        at startup. The list is also saved at regular intervals. 

        A port's mheard list may be cleared by using the
        "MHCLEAR <port-number>" command.  You may clear all MH lists
        by specifying port 0.

        The MHEARD list is available to sysops and users alike, using
        the MH command (see command reference section).

</code> **SEE ALSO:** \\
[[packet:xrouter:docs:MAN1#DX|        DX(1)          -- DX list.
]] \\
[[packet:xrouter:docs:MAN1#J|        J(1)           -- Recent Sessions.
]] \\
[[packet:xrouter:docs:MAN1#MHCLEAR|        MHCLEAR(1)     -- Clear MHeard list.
]] \\
[[packet:xrouter:docs:MAN1#MHEARD|        MHEARD(1)      -- Display recently heard stations.
]] \\
[[packet:xrouter:docs:MAN7#MHFLAGS|        MHFLAGS(7)     --  Set MHeard options.
]] \\
[[packet:xrouter:docs:MAN1#MHSIZE|        MHSIZE(1)      -- Adjust size of MHeard list.
]] \\
[[packet:xrouter:docs:MAN7#MHEARD|        MHEARD(7)      -- MHeard size/enable directive
]] \\
[[packet:xrouter:docs:MAN8#XROUTER.CFG|        XROUTER.CFG(8) -- Main Configuration File.
]] \\

[[packet:xrouter:docs:|< Back to Index]]

----
===== MH-SVC =====
<code>MH-SVC(9)              XROUTER REFERENCE MANUAL              22/9/2023
</code> **NAME** <code>
        MH-SVC -- NetRomX MHeard Service.

</code> **DESCRIPTION** <code>
        The MHEARD service uses NetRomX service number 26. It is
        normally used by the "MHEARD <nodecall>" function.

        It is not intended for direct connection by humans, but such
        operation is possible, as described below:

        Upon connection to service 26, the user must send a valid
        MHEARD command, such as "MH 0" to list the ports on which
        MHeard is available, or "MH 16" to obtain the MH list for
        port 16.  Only MHeard commands are accepted, any other
        command will cause disconnection.

        The connection is terminated by the server when the transfer
        is complete.

        It would be possible for automated network crawlers to use
        this feature for harvesting MHeard lists, using the data for
        example to build a map showing who can hear whom.

</code> **SEE ALSO:** \\
[[packet:xrouter:docs:MAN9#DX-SVC|        DX-SVC(9)   -- NetRomX DX List Service.
]] \\
[[packet:xrouter:docs:MAN9#SERVICES|        SERVICES(9) -- NetRomX Standard Services.
]] \\

[[packet:xrouter:docs:|< Back to Index]]

----
===== MOD128 =====
<code>MOD128(9)               XROUTER REFERENCE MANUAL            18/10/2023
</code> **NAME** <code>
        MODULO128 -- AX25 Modulo-128.

</code> **DESCRIPTION** <code>
        Modulo-128 is an extension to AX25, with sequence numbers
        from 0 to 127 instead of the usual 0 to 7.  This allows a
        much bigger MAXFRAME (up to 63) to be used, and is primarily
        of use on good links.

        On conventional (Modulo-8) AX25 links, much of the
        inter-node traffic consists of short frames containing level
        4 control information. These frames are interspersed with
        data-bearing frames, which themselves may be only partially
        full.  Thus a router may transmit 7 frames in one go, but
        the transmission may only be a few hundred bytes in total.

        This is inefficient, due to the delays associated with
        channel access, TXDELAY, TXTAIL, RESPTIME etc.  On fast,
        error-free links the data arrives in short bursts, separated
        by long gaps of inactivity.

        With Modulo-128, many more frames can be packed into a
        single transmission, so the channel overheads become less
        significant.  

        Because the largest allowed MAXFRAME value for Modulo-128
        is 63, there can never be any sequence number ambiguity, and
        this allows frame "re-sequencing", or "selective reject".

        With normal AX25, if the first frame of a multi-frame set is
        lost, the whole set of frames must be re-transmitted.

        If Modulo-128 is used however, the "good" frames are stored
        by the recipient, and only the lost frame is re-sent.
        Together with the stored frames, this completes the set, and
        the whole set can be acked.  This is a much more efficient
        strategy.

        XRouter is capable of both Modulo-128, and frame
        resequencing.

        Modulo-128 frames are displayed on the trace screen as
        "EAX25" (Extended AX25) instead of "AX25", and are initiated
        by a new frame type "SABME" (Set Asynchronous Balanced Mode
        Extended).  You will notice the sequence numbers being
        displayed as "<I R25 S32>"

        The method of activation isn't fully decided as yet.  If a
        caller requests Modulo-128 (by sending an SABME frame),
        XRouter will respond with <UA> and go into Modulo-128 mode.

        The strategy for outgoing links is more complex.  If the
        port MAXFRAME is greater than 7, *ALL* level 2 downlinks on
        that port will be tried using Modulo-128 (i.e. XRouter will
        send <SABME> instead of <SABM>.  This is not on user ports,
        since hardly any users are EAX25 compatible.

        If the called system is Modulo-128 capable, the correct
        response to <SABME> is <UA>, otherwise the correct response
        according to the AX25 protocol is either <DM> or <FRMR>,
        which will cause XRouter to fall back to normal Modulo-8
        AX25.

        Most systems do answer correctly, but there may however be
        some systems which do not properly implement AX25, for
        example by silently discarding <SABME> frames, and it will
        not be possible to link to these systems if MAXFRAME is
        greater than 7.  This may be addressed in a future version.

        It is more likely that Modulo-128 would be used on
        inter-node links with other XRouters, Linux and PE1CHL nodes,
        so to activate it, simply define a MAXFRAME > 7 for those
        routes which require it. If the port is dedicated to one
        link, you can set the port MAXFRAME > 7 instead.

</code> **SEE ALSO:** \\
[[packet:xrouter:docs:MAN1#ROUTES|        ROUTES(1)      -- NetRom Route commands.
]] \\
[[packet:xrouter:docs:MAN7#MAXFRAME|        MAXFRAME(7)    -- Maximum Unacked AX25 Frames Directive.
]] \\
[[packet:xrouter:docs:MAN8#XROUTER.CFG|        XROUTER.CFG(8) -- Main Configuration File.
]] \\

[[packet:xrouter:docs:|< Back to Index]]

----
===== MQTT-BLOG =====
<code>MQTT-BLOG(9)            XROUTER REFERENCE MANUAL             26/9/2023

</code> **NAME** <code>
        MQTT-BLOG -- MQTT Interface to Sysop's Blog.

</code> **DESCRIPTION** <code>
        The sysop's blog may be operated via XRouter's inbuilt MQTT
        broker, and/or via an external broker, by subscribing or
        publishing to certain topics.

        This facility is incomplete. The curently available
        functionality is documented in the next section.

</code> **OPTIONS** <code>
        a) Receive Notifications of Blog Events:
        ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

        Topic: xrouter/event/{nodecall}/blog

        The payload of an event notification is an un-named JSON
        object containing the following fields:

        Name          Type      Description
        -----------------------------------------------------------
        "id"          integer   Article/post number.
        "rcvd"        string    Date/time of message creation (*).
        "size"        integer   Length of the blog text in bytes.
        "from"        string    Callsign of the post's creator.
        "subject"     string    Topic of the post (32 chars max)
        "text"        string    Body of the post (plain ASCII)
        "event"       string    Type of event ("posted" or "deleted")

        (*) in format "1997-09-14T23:47:00Z"

        b) Retrieve a Blog Post:
        ~~~~~~~~~~~~~~~~~~~~~~~~

        Topic: xrouter/get/{nodecall}/blog/msg/{msgnum} 

        The response payload is an un-named JSON object containing
        the following fields:

        Name          Type      Description
        -----------------------------------------------------------
        "id"          integer   Article/post number.
        "rcvd"        string    Date/time of message creation (*).
        "size"        integer   Length of the blog text in bytes.
        "from"        string    Callsign of the post's creator.
        "subject"     string    Topic of the post (32 chars max)
        "text"        string    Body of the post (plain ASCII)

        (*) in format "Mon, 14 Sep 1997 23:47:00 GMT"


        c) Post a Blog Article / Reply:
        ~~~~~~~~~~~~~~~~~~~~~~~~~~~~

        Topic: xrouter/put/{nodecall}/blog

        The payload must be a JSON object containing the following
        fields:

        Name          Type      Description
        -----------------------------------------------------------
        "sender"      string    Callsign of sender
        "replyto"     integer   No. of msg being replied to (0=new)
        "subject"     string    Subject of the post (32 chars max)
        "text"        string    Body of the post (unlimited size)

        Response: None unless QOS > 0

</code> **LIMITATIONS** <code>
        The blog's MQTT interface does not yet notify "like" events,
        nor does it allow article listings, deletion, "liking", or
        the retrieval of replies. Those functions will be added in a
        future version

</code> **SEE ALSO:** \\
[[packet:xrouter:docs:MAN1#BLOG|        BLOG(1)      -- Access Sysop's Blog.]] \\
[[packet:xrouter:docs:MAN7#BLOGFLAGS|        BLOGFLAGS(7) -- Options For Sysop's Blog.]] \\
[[packet:xrouter:docs:MAN9#REST-BLOG|        REST-BLOG(9) -- REST Interface to Blog.]] \\
[[packet:xrouter:docs:MAN9#MQTT-CLI|        MQTT-CLI(9)  -- MQTT Client]] \\
[[packet:xrouter:docs:MAN9#MQTT-SRV|        MQTT-SRV(9)  -- MQTT Server / Broker.]] \\

[[packet:xrouter:docs:|< Back to Index]]

----
===== MQTT-CHAT =====
<code>MQTT-CHAT(9)            XROUTER REFERENCE MANUAL             26/9/2023

</code> **NAME** <code>
        MQTT-CHAT -- MQTT Interface to Chat Server.

</code> **DESCRIPTION** <code>
        The chat server may be operated via XRouter's inbuilt MQTT
        broker, and/or via an external broker, by subscribing or
        publishing to certain topics.

        This facility is incomplete. The curently available
        functionality is documented in the next section.

</code> **OPTIONS** <code>
        a) Receive Notifications of Chat Events:
        ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

        These events are published by XRouter whenever someone
        joins or leaves a channel, changes name, personal text or
        channel topic, or sends a nmessage.

        Subscribe Topic: xrouter/event/{nodecall}/chat/{event-type}

        Event-types are:

            join    User joins a channel
            leave   User leaves a channel
            name    User sets or changes name
            pers    User sets or changes personal text
            topic   User sets or changes channel topic
            msg     User sends a chat message

        The payload of an event notification is an un-named JSON
        object containing the following fields:

            Name      Type     Description
            -----------------------------------------------------
            "user"    string   Callsign of user
            "host"    string   Alias of chatserver the user is on
            "name"    string   User's name
            "time"    string   Time of event in form HH:MM
            "channel" number   Channel number (*1)
            "topic"   string   Topic name for channel (*2)
            "pers"    string   Personal text (*3)
            "reason"  string   Reason for leaving channel (*4)

            (*1) "channel" not present in "name" or "pers" events
            (*2) "topic" only present in "topic" events
            (*3) "pers" only present in "pers" events
            (*4) "reason" only present in "leave" events

        Internally the event time is stored as a 32bit unsigned
        integer, representing the number of seconds since 1/1/70. It
        could be sent as a number instead of a string, if that was
        easier for the consuming client?

        Channel numbers can range from -32767 to +32767. Negative
        channels are used for Tampa Ping Pong chat. Channel 101 is
        BPQ (W0RLI's RoundTable) chat. Channel numbers between 0 and
        999, except 101, are local only. Channels > 999 are
        distributed to all XRChat servers.


        b) List Chatserver Channels and Users:
        ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

        If the client publishes a "get" request, XRouter responds by
        publishing the requested data to a similar "status" topic.

        Request Topic:  xrouter/get/{nodecall}/channels

        Response Topic: xrouter/status/{nodecall}/channels

        The response payload is a JSON array, which may be empty. If
        present, each array element (channel) has at least the
        following fields:

            Name      Type     Description
            ----------------------------------------------------
            "number"  number   Channel number (-32767 to 32767)
            "topic"   string   Channel topic, e.g. "RoundTable"
            "users"   array    List of users on the channel

        The "users" array may be empty. If any users are present, a
        user array element contains the following fields:

            Name      Type     Description
            ----------------------------------------------------
            "user"    string   User ID (usually callsign)
            "host"    string   Alias of their chat server
            "name"    string   User's name
            "idle"    string   Elapsed time since activity
            "stat"    string   Short presence/status text
            "pers"    string   Personal text
            "qth"     string   Home town

        Some fields may be empty, e.g. personal text and QTH.

        Idle time is "0s" to "59s", then "1h" to "23h", then "1d"
        upwards.

        Short presence/status codes are:

            "Offline"   Not on chat
            "Avail"     Available to chat
            "Busy"      Possibly watching, but likely too busy to reply
            "BRB"       Be Right back - very short break
            "Away"      Away from computer for a while
            "Lunch"     Out to lunch
            "Phone"     On the phone, will be back
            "D.N.D"     Do Not Disturb. Don't involve me
            "Asleep"    Gone to bed, so not watching live
            "In&Out"    Reading and responding intermittently

        Example:

            pub xrouter/get/G8PZT-1/channels

            xrouter/status/G8PZT-1/channels
            [
            {
            "number": 101,
            "topic": "RoundTable",
            "users": [
                 ]
            },
            {
            "number": 1000,
            "topic": "Welcome",
            "users": [
            "user": "G8PZT-4",
            "host": "MOBCHT",
            "name": "Paula",
            "idle": "1m",
            "stat": "Avail,",
            "pers": "Programming again!"
            "qth": "kidderminster"
                  ]
            },
            {
            "number": 1234,
            "topic": "Sysop Chat",
            "users": [
                   ]
            }
            ]


        c) Post a Chat Message:
        ~~~~~~~~~~~~~~~~~~~~~~~

        Publish Topic: xrouter/put/{nodecall}/chat

        The payload must be a JSON object containing the following
        fields:

            Name        Type      Description
            ------------------------------------------------------
            "sender"    string    Callsign of sender
            "channel"   number    Destination channel
            "name"      string    Sender's name
            "text"      string    Body of the message

        Channel numbers can range from -32767 to +32767. Negative
        channels are used for Tampa Ping Pong chat. Channel 101 is
        BPQ (W0RLI's RoundTable) chat. Channel numbers between 0 and
        999, except 101, are local only. Channels > 999 are
        distributed to all XRChat servers.

        Response: None unless QOS > 0

</code> **LIMITATIONS** <code>
        The chat MQTT interface is only a proof-of-concept at this
        stage, and some details may change. More functionality will
        be added in a future version.

</code> **SEE ALSO:** \\
[[packet:xrouter:docs:MAN1#CHAT|        CHAT(1)      -- Connect to Chat Server.]] \\
[[packet:xrouter:docs:MAN9#CHAT-SRV|        CHAT-SRV(9)  -- About the chat server.]] \\
[[packet:xrouter:docs:MAN9#MQTT-CLI|        MQTT-CLI(9)  -- MQTT Client]] \\
[[packet:xrouter:docs:MAN9#MQTT-SRV|        MQTT-SRV(9)  -- MQTT Server / Broker.]] \\

[[packet:xrouter:docs:|< Back to Index]]

----
===== MQTT-PMS =====
<code>MQTT-PMS(9)             XROUTER REFERENCE MANUAL             26/9/2023

</code> **NAME** <code>
        MQTT-PMS -- MQTT Interface to Personal Message System.

</code> **DESCRIPTION** <code>
        The PMS may be operated via XRouter's inbuilt MQTT
        broker, and/or via an external broker, by subscribing or
        publishing to certain topics.

        This facility is incomplete. The curently available
        functionality is documented in the next section.

</code> **OPTIONS** <code>
        a) Receive Notifications of PMS Message Events:
        ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

        These events are published by XRouter whenever someone
        creates, reads, or kills a message, and when a message is
        delivered to the recipient's PMS.

        Subscription Topic: xrouter/event/{nodecall}/pmsg

        The payload of an event notification is an un-named JSON
        object containing the following fields:

            Name      Type      Description
            -----------------------------------------------------
            "number"   integer   Message number.
            "mid"      string    Message ID (MID or BID)
            "rcvd"     string    Date/time of message reception (*1).
            "size"     integer   Length of the message body in bytes.
            "type"     string    Type of message: (A, P, B, E, T etc)
            "status"   string    Message status: (R, F, U etc) (*2)
            "to"       string    Destination address (*3)
            "from"     string    Callsign of the message's creator.
            "subject"  string    Message subject (32 chars max)
            "event"    string    Event type (*4)

        (*1) in format "1997-09-14T23:47:00Z"
        (*2) type and status may in future be unambiguous words
        (*3) e.g. "g8pzt", "all@gbr", "g8pzt@gb7pzt.#24.gbr.eu"
        (*4) event types are as follows:

             "newmsg"    New message	
             "fwded"     Message has been forwarded
             "read"      Message has been read
             "killed"    Message has been killed

        Example:

            {
            "number": 117,
            "mid": "47DCE8A17PZT"
            "size": 67,
            "type": "P",
            "to": "G8PZT@DOTPMS",
            "from": "G9DUM",
            "subject": "test 1",
            "event": "newmsg"
            }


        b) Retrieve a Message:
        ~~~~~~~~~~~~~~~~~~~~~~

        Publish Topic: xrouter/get/{nodecall}/mail/msg/{msgnum} 

        The response payload is an un-named JSON object containing
        the following fields:

        
            Name      Type      Description
            -----------------------------------------------------
            "number"   integer   Message number.
            "mid"      string    Message ID (MID or BID)
            "rcvd"     string    Date/time of message reception (*1).
            "size"     integer   Length of the message body in bytes.
            "type"     string    Type of message: (A, P, B, E, T etc)
            "status"   string    Message status: (R, F, U etc) (*2)
            "to"       string    Destination address (*3)
            "from"     string    Callsign of the message's creator.
            "subject"  string    Message subject (32 chars max)
            "text"     string    Body of the message (*4)

        (*1) in format "1997-09-14T23:47:00Z"
        (*2) type and status may in future be unambiguous words
        (*3) e.g. "g8pzt", "all@gbr", "g8pzt@gb7pzt.#24.gbr.eu"
        (*4) Message body includes all RFC822 and routing headers

        c) Post a Message:
        ~~~~~~~~~~~~~~~~~~

        Publish Topic: xrouter/put/{nodecall}/mail

        The payload must be a JSON object containing the following
        fields:

            Name        Type      Description
            ------------------------------------------------------
            "from"      string    Callsign of sender
            "to"        string    Destination (see below)
            "type"      string    Only "P" or "B" at present
            "subject"   string    Subject of message (32 chars max)
            "text"      string    Body of the message

        For private messages the destination may be just a callsign,
        or <callsign>@<hierarchical-address>. For bulletins it may
        be simply <topic> or <topic>@<distribution>. For email it is
        <user>@<host>.

        Response: None unless QOS > 0

</code> **LIMITATIONS** <code>
        The PMS's MQTT interface is only a proof-of-concept at this
        stage, and some details may change. More functionality will
        be added in a future version.

</code> **SEE ALSO:** \\
[[packet:xrouter:docs:MAN1#PMS|        PMS(1)      -- Access Personal Message System.]] \\
[[packet:xrouter:docs:MAN9#PMS|        PMS(9)      -- About the Personal Pessage System.]] \\
[[packet:xrouter:docs:MAN9#REST-PMS|        REST-PMS(9) -- REST Interface to PMS.]] \\
[[packet:xrouter:docs:MAN9#MQTT-CLI|        MQTT-CLI(9) -- MQTT Client]] \\
[[packet:xrouter:docs:MAN9#MQTT-SRV|        MQTT-SRV(9) -- MQTT Server / Broker.]] \\

[[packet:xrouter:docs:|< Back to Index]]

----
===== MQTT-PUB =====
<code>MQTT-PUB(9)            XROUTER REFERENCE MANUAL              23/9/2023

</code> **NAME** <code>
        MQTT-PUB -- MQTT Publisher.

</code> **DESCRIPTION** <code>
        The MQTT "publisher" is an inbuilt MQTT client daemon which,
        if enabled, automatically connects to an *external* MQTT
        broker (server), and publishes data to it. The broker may be
        on the LAN or in the cloud.

        The broker's IP address or hostname is specified using
        MQTTSERVADDR in XROUTER.CFG, and its TCP port number by
        MQTTSERVPORT, which defaults to 1883. If the broker address
        is not specified (the default condition), or the broker port
        is set to 0, the publisher is disabled.
        If enabled, various information is sent to the broker in JSON
        format, including station configuration, layer 2, 4 and 7
        events such as connections and disconnections, radio control
        events such as PTT, frequency and mode changes, PMS message
        events, chat server events, raw packet data and so on. As
        proof of concept, a web-based chat server interface has been
        demonstrated.

        The term "publisher" is somewhat of a misnomer, as the data
        flow is bi-directional.

        Therefore any client of the external broker may not only
        passively receive "pushed" data from XRouter, but may also
        "push" data to XRouter, and "pull" data from it on request.

        By publishing to "getter" topics, a client may request status
        reports, such as lists of AX25 L2 links, routes, nodes, L4
        circuits, sessions, recent sessions, chat server status,
        MHeard and DX lists etc. 

        By publishing to "putter" topics, a client may also send data
        to the node, such as chat, PMS and control mesages, raw
        packet data etc. Ulitmately it should be possible to provide
        a full MQTT-based interface to packet radio.

        See MQTT-SRV(9) for the list of getter and putter topics.

</code> **SEE ALSO:** \\
[[packet:xrouter:docs:MAN9#MQTT-CLI|        MQTT-CLI(9)     -- MQTT Client]] \\
[[packet:xrouter:docs:MAN9#MQTT-SRV|        MQTT-SRV(9)     -- MQTT Server / Broker]] \\
[[packet:xrouter:docs:MAN9#MQTT-SVC|        MQTT-SVC(9)     -- NetRomX MQTT Service]] \\
[[packet:xrouter:docs:MAN7#MQTTSERVADDR|        MQTTSERVADDR(7) -- Hostname / IP of Externam MQTT Broker]] \\
[[packet:xrouter:docs:MAN7#MQTTSERVPORT|        MQTTSERVPORT(7) -- TCP Port for External MQTT Broker]] \\
[[packet:xrouter:docs:MAN8#XROUTER.CFG|        XROUTER.CFG(8)  -- Main Configuration File.]] \\

[[packet:xrouter:docs:|< Back to Index]]

----
===== MQTT-SRV =====
<code>MQTT-SRV(9)            XROUTER REFERENCE MANUAL              23/9/2023

</code> **NAME** <code>
        MQTT-SRV -- MQTT Server / Broker.

</code> **DESCRIPTION** <code>
        XRouter has an inbuilt MQTT broker (server), which allows
        MQTT clients to exchange information with XRouter, with each
        other, and with an external broker.

        The broker may be enabled on XRouter and/or Linux IP stacks
        using the MQTTPORT directive in XROUTER.CFG. The usual TCP
        port number for MQTT is 1883.

        Although primarily intended for use via the LAN, the broker
        is also available via NetRomX service 1883 for anyone who
        wants to experiment with MQTT over radio.

        Clients may "publish" data to "topics", and may "subscribe"
        to topics, in order to receive any data published to that
        topic.

        XRouter automatically publishes "events", both to the
        internal MQTT broker, and if configured to do so, to an
        external broker.

        The information, which is published in JSON format, includes
        station configuration, layer 2, 4 and 7 events such as
        connections and disconnections, radio control events such as
        PTT, frequency and mode changes, PMS message events, chat
        server events, raw packet data and so on. As proof of
        concept, a web-based chat server interface has been
        demonstrated.

        A client may also request status reports, such as lists of
        AX25 L2 links, routes, nodes, L4 circuits, sessions, recent
        sessions, chat server status, MHeard and DX lists etc.

        A client may also send information to the node, such as chat,
        PMS and control mesages. Ultimately it should be possible to
        provide a full MQTT-based interface to packet radio. That bit
        is left up to you!

</code> **OPTIONS** <code>
        Subscription Topics:
        ~~~~~~~~~~~~~~~~~~~~

        Subscribing to any of the following topics causes XRouter to
        publish data asynchronously, to the same topic:

        xrouter/event/{nodecall}/blog           Sysop's Blog Events
        xrouter/event/{nodecall}/chat/{evtype}  Chat Events
        xrouter/event/{nodecall}/circuit        NetRom L4 Cct Events
        xrouter/event/{nodecall}/link           AX25 Link Events
        xrouter/event/{nodecall}/pmsg           PMS Message Events
        xrouter/event/{nodecall}/radio/{number} Radio Events
        xrouter/event/{nodecall}/session        Session Layer Events
        xrouter/event/{nodecall}/wall           Message "wall" Events
        xrouter/event/{nodecall}/wx[/{call}]    Weather data events
        xrouter/ax25/{nodecall}/rcvd/{portnum}  Raw AX25 Frames Rx'd
        xrouter/ax25/{nodecall}/sent/{portnum}  Raw AX25 Frames Tx'd
        xrouter/ipv4/{nodecall}/rcvd            Raw IPV4 Frames Rcvd
        xrouter/ipv4/{nodecall}/sent            Raw IPV4 Frames Sent
        xrouter/kiss/{nodecall}/rcvd/{ifacenum} KISS Frames Received
        xrouter/kiss/{nodecall}/sent/{ifacenum} KISS Frames Tx'd
        xrouter/nr3b/{nodecall}/rcvd            Netrom Traffic Rx'd
        xrouter/nr3b/{nodecall}/sent            Netrom Traffic TX'd

        Getter Topics:
        ~~~~~~~~~~~~~~

        These are used to obtain information *from* XRouter on demand.
        Publishing to any of these topics elicits a reply from
        XRouter, with "get" replaced by "status" in the topic:
 
        xrouter/get/{nodecall}/blog/msg/{msgnum} Retrieve a blog post
        xrouter/get/{nodecall}/channels     Chat channel occupancy
        xrouter/get/{nodecall}/circuits     Netrom L4 circuits
        xrouter/get/{nodecall}/config       Node Configuration Info
        xrouter/get/{nodecall}/jlist        Recent Sessions
        xrouter/get/{nodecall}/links        AX25 circuits
        xrouter/get/{nodecall}/mheard       Port "MHeard" Lists
        xrouter/get/{nodecall}/nodes        NetRom Nodes Table
        xrouter/get/{nodecall}/node/{call}  Info For Specific Node
        xrouter/get/{nodecall}/recent       Recent chat messages
        xrouter/get/{nodecall}/routes       NetRom Neighbour Routes
        xrouter/get/{nodecall}/users        Current Sessions
        xrouter/get/{nodecall}/wall/msg/{msgnum} Retrieve a wall post


        Putter Topics:
        ~~~~~~~~~~~~~~

        These are used to send information *to* XRouter. They don't
        elicit any response, other than a PUBACK if QOS > 0.

        xrouter/put/{nodecall}/ax25/{portnum}   Send raw AX25  (*1)
        xrouter/put/{nodecall}/blog             Post a blog article
        xrouter/put/{nodecall}/chat             Send a CHAT message
        xrouter/put/{nodecall}/ipv4             Send raw IP datagram
        xrouter/put/{nodecall}/kiss/{ifacenum}  Send raw KISS Frame
        xrouter/put/{nodecall}/nr3b             Send raw NetRom (*2)
        xrouter/put/{nodecall}/wall             Post a wall message
        xrouter/put/{nodecall}/wx               Post local weather data

        (*1) Without HDLC framing or CRC
        (*2) Routable datagrams only, no L3RTT, INP3 or Nodes bcasts!

</code> **CAVEATS** <code>
        This system is by no means finished. There's a lot more that
        could be done, but it needs someone to actually USE it and
        provide feedback.

</code> **SEE ALSO:** \\
[[packet:xrouter:docs:MAN9#MQTT-BLOG|        MQTT-BLOG(9)   -- MQTT Interface to Sysop's Blog.]] \\
[[packet:xrouter:docs:MAN9#MQTT-CLI|        MQTT-CLI(9)    -- MQTT Client]] \\
[[packet:xrouter:docs:MAN9#MQTT-SVC|        MQTT-SVC(9)    -- NetRomX MQTT Service.]] \\
[[packet:xrouter:docs:MAN9#MQTT-PUB|        MQTT-PUB(9)    -- MQTT Publisher.]] \\
[[packet:xrouter:docs:MAN9#MQTT-WALL|        MQTT-WALL(9)   -- MQTT Interface to Message Wall.]] \\
[[packet:xrouter:docs:MAN7#MQTTPORT|        MQTTPORT(7)    -- TCP Port for MQTT Broker.]] \\
[[packet:xrouter:docs:MAN8#XROUTER.CFG|        XROUTER.CFG(8) -- Main Configuration File.]] \\

[[packet:xrouter:docs:|< Back to Index]]

----
===== MQTT-SVC =====
<code>MQTT-SVC(9)            XROUTER REFERENCE MANUAL              22/9/2023

</code> **NAME** <code>
        MQTT-SVC -- NetRomX MQTT Broker Service.

</code> **DESCRIPTION** <code>
        NetRomX service 1883 connects to XRouter's inbuilt MQTT
        broker, allowing MQTT over NetRom for anyone who wants to
        experiment.

        This may be a bad idea, but we don't know until we give it
        a go!

        It may be that we have to restrict the types of data that
        can be sent and received, to avoid death-loops.

</code> **SEE ALSO:** \\
[[packet:xrouter:docs:MAN9#MQTT-PUB|        MQTT-PUB(9) -- MQTT Publisher.]] \\
[[packet:xrouter:docs:MAN9#MQTT-SRV|        MQTT-SRV(9) -- MQTT Server / Broker]] \\
[[packet:xrouter:docs:MAN9#SERVICES|        SERVICES(9) -- NetRomX Standard Services]] \\

[[packet:xrouter:docs:|< Back to Index]]

----
===== MQTT-WALL =====
<code>MQTT-WALL(9)            XROUTER REFERENCE MANUAL             26/9/2023

</code> **NAME** <code>
        MQTT-WALL -- MQTT Interface to Message Wall.

</code> **DESCRIPTION** <code>
        The message "wall" may be operated via XRouter's inbuilt MQTT
        broker, and/or via an external broker, by subscribing or
        publishing to certain topics.

        This facility is incomplete. The curently available
        functionality is documented in the next section.

</code> **OPTIONS** <code>
        a) Receive Notifications of Wall Events:
        ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

        Topic: xrouter/event/{nodecall}/wall

        The payload of an event notification is an un-named JSON
        object containing the following fields:

        Name          Type      Description
        -----------------------------------------------------------
        "id"          integer   Article/post number.
        "rcvd"        string    Date/time of message creation (*).
        "size"        integer   Length of the text portion in bytes.
        "from"        string    Callsign of the post's creator.
        "text"        string    Body of the post (plain ASCII)
        "event"       string    Type of event ("posted" or "deleted")

        (*) in format "Mon, 14 Sep 1997 23:47:00 GMT"

        b) Retrieve a Wall Post:
        ~~~~~~~~~~~~~~~~~~~~~~~~

        Topic: xrouter/get/{nodecall}/wall/msg/{msgnum} 

        The response payload is an un-named JSON object containing
        the following fields:

        Name          Type      Description
        -----------------------------------------------------------
        "id"          integer   Article/post number.
        "rcvd"        string    Date/time of message creation (*).
        "size"        integer   Length of the text in bytes.
        "from"        string    Callsign of the post's creator.
        "text"        string    Body of the post (plain ASCII)

        (*) in format "Mon, 14 Sep 1997 23:47:00 GMT"


        c) Post a Wall Message / Reply:
        ~~~~~~~~~~~~~~~~~~~~~~~~~~~~

        Topic: xrouter/put/{nodecall}/wall

        The payload must be a JSON object containing the following
        fields:

        Name          Type      Description
        -----------------------------------------------------------
        "sender"      string    Callsign of sender
        "text"        string    Body of the post (unlimited size)

        Response: None unless QOS > 0

</code> **LIMITATIONS** <code>
        The wall's MQTT interface does not yet notify "like" events,
        nor does it allow article listings, deletion, "liking", or
        the retrieval of replies. Those functions will be added in a
        future version

</code> **SEE ALSO:** \\
[[packet:xrouter:docs:MAN1#WALL|        WALL(1)      -- Access Message Wall / Guestbook.]] \\
[[packet:xrouter:docs:MAN7#WALLFLAGS|        WALLFLAGS(7) -- Options For Message Wall.]] \\
[[packet:xrouter:docs:MAN9#REST-WALL|        REST-WALL(9) -- REST Interface to Wall.]] \\
[[packet:xrouter:docs:MAN9#MQTT-SRV|        MQTT-SRV(9)  -- MQTT Server / Broker.]] \\

[[packet:xrouter:docs:|< Back to Index]]

----
===== MQTT-WX =====
<code>MQTT-WX(9)              XROUTER REFERENCE MANUAL             26/9/2023

</code> **NAME** <code>
        MQTT-WX -- MQTT Interface to Weather System.

</code> **DESCRIPTION** <code>
        If XRouter has a source of weather information, e.g. APRS
        broadcasts, local sensors or an online source, weather updates
        can be received from XRouter's inbuilt MQTT broker by
        subscribing to the "weather events" topic, i.e.

            xrouter/event/{nodecall}/wx

        Weather data stored on XRouter can also be retrieved at any
        time using MQTT "get" requests.

        A "get" request is an MQTT "publish" packet with a topic of
        the general form:

            xrouter/get/{nodecall}/{resource}

        Such requests are actioned directly by XRouter and are NOT
        published to other clients.

        The response from XRouter is published to a topic of the
        general form:

            xrouter/status/{nodecall}/{resource}

        The response payload is either a JSON object or a JSON array,
        depending on the requested resource.

        The response is sent only to the client making the request.

        There are curently two possible {resource} types, namely the
        "station ID" of a weather station, or "allwx".  Station ID's
        are usually callsigns, but may take other forms such as
        "LOCAL", "SHED", "SHACK" and so on.

        LOCAL is the primary resource for locally sourced weather
        information.  Unlike the other resources it maintains max/min
        values and times, trends and so on.

        Weather information can also be uploaded to XRouter from a
        local source (e.g. RTL_433), via the MQTT server.

</code> **OPTIONS** <code>
        a) Receive Notifications of Weather Reports:
        ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

        Subscribe Topic:  xrouter/event/{nodecall}/wx

        The payload of a weather event is an un-named JSON object
        containing some or all of the following fields:

        Name             Type     Description
        -----------------------------------------------------------
        "id"             string   Station id, e.g. "G8PZT" or "LOCAL"
        "lat_deg"        number   Latitude of WX station in degrees
        "lon_deg"        number   Longitude of wx station in degrees
        "dist_km"        number   Distance from our node in kilometres
        "dir_deg"        number   Direction from our node in degrees
        "dt"             integer  Observation time, secs since 1/1/70
        "observed"       string   Date and time of observation (*1) 
        "pressure_mb"    number   Air pressure in millibars
        "temperature_C"  number   Air temperature in degrees C
        "humidity"       number   Relative Humidity in percent
        "dewpoint_C"     number   Dew point in degrees Centigrade
        "heat_index_C"   number   Heat index in deg Centigrade
        "wind_chill_C"   number   Wind Chill in degrees Centigrade
        "wind_mph"       number   Wind speed in miles per hour
        "wind_dir_deg"   number   Wind direction in degrees
        "gust_mph"       number   Wind gust speed in miles per hour
        "raintoday_mm"   number   Total rain since midnight in mm
        "rain1h_mm"      number   Current rainfall rate mm/hour
        "rain24h_mm"     number   Total rain in past 24 hours in mm
        "sunrise"        string   Sunrise time at the station hh:mm
        "sunset"         string   Sunset time at the station hh:mm
        "daylight_hours" number   Hours between sunrise and set

        (*1) As "dt" but human-readable e.g. 2024-03-14T15:19:59Z


        b) Requesting Weather Data From a Specific Station:
        ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

        Publish Topic:  xrouter/get/{nodecall}/wx/{station_id}

        Reply topic:    xrouter/status/{nodecall}/wx/{station_id}

        The reply payload is an anonymous JSON object, containing
        the fields detailed in section (a) above.


        c) Requesting All Available Weather Data:
        ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

        Publish Topic:  xrouter/get/{nodecall}/allwx

        Reply topic:    xrouter/status/{nodecall}/allwx

        The reply payload is an anonymous JSON array, containing zero
        or more JSON objects.  Each object, representing one weather
        station, contains the fields detailed in section (a) above.


        d) Uploading Weather Data To XRouter:
        ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

        Publish Topic:  xrouter/put/{nodecall}/wx

        Payload:    JSON object containing weather data.

        The exact format of the payload is configurable by the sysop,
        to match the fields used by the originating MQTT source.  The
        default values as as follows:

        Name             Type     Description
        --------------------------------------------------------
        "model"          string   Sensor make/model
        "id"             string   Sensor identifier
        "time"           string   Observation time (mandatory) (*1)
        "pressure"       number   Air pressure in millibars
        "temperature_c"  string   Air temperature in degrees C (*2)
        "humidity"       integer  Relative humidity in percent
        "wind_avg_m_s"   string   Wind speed in metres per sec (*3)
        "wind_max_m_s"   string   Gust speed in metres per sec (*3)
        "wind_deg"       string   Wind direction in degrees (*4)
        "rain_mm"        string   Total rainfall in mm (*5)
        "light_lux"      string   Solar Irradiance in lux (*6)
        "uv"             integer  UV level
        "uvi"            integer  UV Index
        "battery_ok"     integer  Sensor battery indication

        (*1) Observation time is mandatory.  Acceptable formats are
             Unix epoch (i.e. secs since 1/1/1970), a date/time like
             "yyyy-mm-dd hh:mm:ss", or "yyyy-mm-ddThh:mm:ssZ". e.g.
             "2024-03-14T15:19:59Z".

        (*2) Temperature defaults to centigrade, unless the value
             string is suffixed by the letter "F" (case independent).
             If the value contains a decimal point, it is assumed to
             be in degrees.  If there is no decimal point, it
             signifies tenths of a degree.  In this mode, negative
             temperatures using either 12-bit or 16-bit "two's
             complement" are accepted.
             e.g. "10.1" and "101" both mean 10.1 degrees Centigrade.
             "50.5F or "505 F" or "50.5 f" all mean 50.5 degrees
             Fahrenheit. "65540" means -1.5 degrees Centigrade if the
             sensor is using 16-bit two's complement.
   
        (*3) Wind speeds default to miles per hour if no units are
             present in either the field name or the value string.
             If the field name contains "m_s" or the value string
             contains "m/s", the units are metres per second.
             If the field name contains "km_h" or the value string
             contains "km/h" the units are kilometres per hour.

        (*4) Wind direction may be specified in whole degrees (0-359),
             or as cardinal points, e.g. "N", "W", "SSE" etc.

        (*5) If the field name contains "mm" or the value contains a
             decimal point, the rainfall units are assumed to be
             millimetres, otherwise they are assumed to be cumulative
             "bucket tips".  The default bucket size of 0.3mm, can be
             changed using the WXBUCKET directive in XROUTER.CFG.

        (*6) Light level defaults to watts per square metre, but can
             be specified in Lux by appending "lux", e.g. "4568 lux".

        The uploaded data is assumed to be from a local sensor, and
        is therefore stored under the station ID "LOCAL".  Future
        versions may allow for extra sensors, as per the REST API.

</code> **EXAMPLES** <code>
        xrouter/event/G8PZT/wx       - Get weather notifications
        xrouter/get/G8PZT/wx/G6GUH-7 - Retrieve WX data from G6GUH-7
        xrouter/get/G8PZT/allwx      - Retrieve all weather data

</code> **SEE ALSO:** \\
[[packet:xrouter:docs:MAN1#WX|        WX(1)        -- Display Weather Information.]] \\
[[packet:xrouter:docs:MAN9#WX|        WX(9)        -- Weather Information System.]] \\
[[packet:xrouter:docs:MAN9#REST-WX|        REST-WX(9)   -- REST Interface to Weather System.]] \\
[[packet:xrouter:docs:MAN9#MQTT-SRV|        MQTT-SRV(9)  -- MQTT Server / Broker.]] \\

[[packet:xrouter:docs:|< Back to Index]]

----
===== NAT =====
<code>NAT(9)                  XROUTER REFERENCE MANUAL            17/10/2023
</code> **NAME** <code>
        NAT -- Network Address Translation.

</code> **DESCRIPTION** <code>

        Section 1 - About Network Address Translation
        ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

        In order for a computer (sometimes called a "host") to
        communicate with other computers using TCP/IP it must have an
        IP address.  This is a 32 bit number unique to that machine,
        and it is composed of four 8 bit fields which hosts use to
        make routing decisions.

        Theoretically, there could be 2**32 unique addresses (just
        over 4000 million), but in practice the figure is a lot lower
        because some of the addresses are not used.  This is due to
        the way addresses are separated into classes and assigned to
        networks.

        For example, the "class A" address series 44.x.x.x is assigned
        to the amateur radio network and contains 2**24 (16.7 million)
        addresses. Within this series, the series 44.131.x.x is
        assigned to the UK, and contains 2**16 (65536) addresses.

        Taking this further, the series 44.131.91.x is assigned to
        north Worcestershire and contains 2*8 (256) addresses, yet
        there are only a couple of IP stations in north
        Worcestershire.  So the remaining IP addresses are "wasted".
        A similar wastage occurs in every county in the UK and every
        country in the world.

        Although there are only a couple of registered IP stations in
        the 44.131.91.x series, each station may be running more than
        one computer. Some of these machines are nothing to do with
        amateur radio and therefore are not entitled to a 44.x.x.x
        series IP address.  In addition, registering IP addresses is a
        lengthy procedure which is impractical for dealing with a home
        network in which computers are rearranged frequently.

        In order to cater for these private and experimental networks,
        a number of address ranges were set aside for "unregistered"
        use.  One such series is 192.168.0.x which can cater for up to
        256 hosts.  Any one of these addresses may be used in millions
        of private networks at once, thus alleviating the shortage of
        IP addresses.

        A problem arises if an "unregistered" host on a private
        network needs to communicate with a host on the "registered"
        network.  Packets from the unregistered (local) host can be
        routed to the registered (global) host, but since the local
        host is unregistered, and the same address is used many places
        at once, the network has no way of knowing where to send the
        replies.

        This is where Network Address Translation (NAT) comes to the
        rescue. NAT operates on each datagram, substituting one IP
        address with another.

        For instance a local address such as 192.168.0.2 can be
        translated to a globally recognised one, such as 44.131.91.2,
        allowing a host on a LAN to access, and be visible to, the
        global network.

        Consider this example:

              Registered IP           Unregistered IP
              44.131.91.2             192.168.0.2
              44.131.91.3             192.168.0.16

        Packets arriving from the global network addressed to
        44.131.91.2 are re-addressed to 192.168.0.2 and routed to the
        appropriate machine on the local network, while those
        addressed to 44.131.91.3 are re-addressed to 192.168.0.16 and
        routed to that machine.

        In the reverse direction, packets originating from host
        192.168.0.2 on the LAN, destined for the global network, have
        their source address changed to the globally recognised
        44.131.91.2, and 192.168.0.16 is translated to 44.131.91.3.

        This one to one mapping of one address to another is called
        STATIC NAT, (also known as RFC1631 NAT) and is implemented in
        Xrouter.


        Port Address Translation
        ~~~~~~~~~~~~~~~~~~~~~~~~
        With Static NAT, if you have more than one local host which
        needs to be visible on the global network, you must own more
        than one registered IP address.  A refinement of NAT, called
        Port Address Translation (PAT) allows one registered IP
        address to be shared by many unregistered hosts, by
        manipulating the "service port" numbers in TCP and UDP packet
        headers.

        For example, consider the following mappings:

              Global address  Port            Local address   Port
              --------------  ----            -------------   ----
              44.131.91.2     777             192.168.0.1     1024
              44.131.91.2     778             192.168.0.2     1024
              44.131.91.2     779             192.168.0.5     1631


        TCP segments originating from port 1024 on local host
        192.168.0.1, and destined for the global network, are
        re-addressed to look like they originated from port 777 on
        the globally-recognised host 44.131.91.3. Likewise, segments
        from port 1631 on local host 192.168.0.5 are made to look like
        they originated from port 779 on global host 44.131.91.2. The
        translations are reversed for incoming segments.

        PAT can be static or dynamic.  With static PAT, the sysop must
        set up the translation table as in the example above.  Dynamic
        PAT builds the table automatically, and the entries are
        removed when they're finished with.  This makes the two
        systems behave very differently, as discussed below.


        Static PAT
        ~~~~~~~~~~
        This form of PAT consistently translates a global address/port
        pair to an equivalent local address/port pair and vice versa.
        Since the mappings are permanent and predictable, the
        designated ports on the local hosts are visible to the global
        network.  This is ideal for making local servers (e.g. SMTP,
        HTTP, POP3) globally visible.

        Static PAT can be used to multiplex several hosts onto one IP
        address, or it can simply be used to manipulate port numbers,
        for example to create "virtual hosts" as shown below:

              Global address  Port            Local Address   Port
              44.131.91.2     80              192.168.0.1     8000
              44.131.91.3     80              192.168.0.1     8001
              44.131.91.4     80              192.168.0.1     8002

        The outside world sees 3 web servers (port 80 is the HTTP
        port), with the IP addresses 44.131.91.2, 91.3 and 91.4, yet
        in reality there are 3 separate web server processes (ports
        8001, 8002, 8003) running on one host.

        There is a problem with static PAT however.  TCP/IP server
        processes use predictable port numbers.  For instance, HTTP
        servers usually use port 80 (although they can often be
        re-configured for a different port), which means that incoming
        TCP segments addressed to port 80 will always go to the web
        server, and the server will reply using the same port as the
        source.

        TCP/IP *clients* on the other hand tend to use unpredictable
        port numbers.  For example, the first Telnet client session on
        a freshly booted Windows98 system will use port 1024, the next
        session will use port 1025 and so on.  With static PAT, set up
        to translate port 1024 to an outside world address/port pair,
        the first Telnet session will succeed, but the second and
        subsequent ones will fail.

        Therefore as a general rule, static PAT is useful for making
        local SERVERS globally visible, but not for accessing the
        global network using local CLIENTS.  It's a one way street.
        This effect can be exploited to prevent LAN users from
        accessing the global network.


        Dynamic PAT
        ~~~~~~~~~~~
        Dynamic PAT is commonly used to multiplex several hosts onto
        one IP address a process called "Overloading", and it tends to
        act as a one way street in the opposite direction to static
        PAT.

        Translation entries are created when a local host originates a 
        connection to the global network, and are removed when that
        connection is closed.  Thus dynamic PAT cannot generally be
        used to make local servers globally visible, but outgoing
        connections can be made without hindrance.

        This creates a simple "firewall", preventing your local hosts
        from attacks from the global network.

        Both static and overloaded PAT are implemented in XRouter.


        Limitations of NAT / PAT
        ~~~~~~~~~~~~~~~~~~~~~~~~
        Unfortunately, NAT and PAT are not completely transparent to
        the user, and there are certain situations which they cannot
        handle.

        IP, ICMP, TCP and UDP packet headers each contain a
        "checksum", and the IP addresses and service port numbers are
        included in the calculation. This means that any change to the
        address or port numbers requires all the checksums to be
        recalculated and re-inserted.

        In most cases it is sufficient to manipulate the packet
        headers alone, but some protocols convey IP address and TCP
        port numbers in the data portion of the packet, and these
        present more of a problem.

        ICMP error reports return part of the faulty datagram, and
        that part must be re-translated and the checksums recalculated
        if the process is to remain completely invisible to the user.

        Certain FTP transactions convey an IP address and port number,
        expressed in ASCII, in the data.  NAT must look for these and
        change them.  Besides being a non-trivial operation, the
        problem with this is that the translated addresses may occupy
        a different amount of space when expressed in ASCII, so NAT
        must build a new packet, and must adjust the TCP sequence
        numbers on every subsequent packet.

        There are other applications which similarly embed addressing
        information in the data portion of the packet, and strictly
        speaking, the TCP/IP layers must remain unaware of this
        information as it is of a higher layer.  In this respect NAT
        breaks normal layering rules.

        PAT achieves multiplexing by translating service port numbers,
        but some protocols do not use service port numbers at all, so
        these can not pass through PAT.  For example, ICMP, IPIP and
        AXIP can only pass through static NAT, whereas AXUDP and IPUDP
        can pass through PAT.

        The following protocols and traffic will pass through NAT:

           Protocol  Supported Traffic / Applications
           -------------------------------------------------
           RIP ?
           ICMP       Ping, Traceroute etc.
           AXIP       Ax25 tunnelling
           IPIP       IP tunnelling.
           UDP        AXUDP, IPUDP, DNS, TFTP
           TCP        Telnet, HTTP, SMTP, NNTP, POP, Finger, Rlogin
                      Plus any other traffic which does not use
                      TCP/IP addresses in the application data.


        Only the following protocols / traffic will pass through PAT:

           Protocol  Supported Traffic / Applications
           -------------------------------------------------
           UDP       AXUDP, IPUDP, DNS, TFTP
           TCP       Telnet, HTTP, SMTP, NNTP, POP, Finger, Rlogin
                     Plus any other traffic which does not use
                     TCP/IP addresses in the application data.



        Section 2 - Configuring NAT / PAT on Xrouter
        ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

        The "NAT" commands are used for configuring both NAT and PAT
        on the fly. They can also be embedded in the IPROUTE.SYS or
        BOOTCMDS.SYS files to configure the system at startup.

        The following commands are available:

           NAT ADD     Adds entries to the translation table.
           NAT DROP    Deletes entries from the translation table.
           NAT LIST    Displays the translation table.

        Syntax is as follows:

        NAT ADD STATIC <localIP>[:port] <globalIP>[:port] [tcp | udp]
        NAT ADD OVERLOAD <localIP> <globalIP> <subnet_mask>

        The first form adds static NAT and PAT entries, and the second
        form is used only for adding overloaded dynamic PAT entries.

        In each case <localaddr> represents the "private" or
        "unregistered" IP address of a host on the stub network, and
        <globaladdr> represents a globally recognised or "registered"
        address.

        In the STATIC case, if port numbers are specified, TCP and UDP
        traffic matching the specified IP addresses will be translated
        ONLY if it also matches the specified ports.  If ports are not
        specified, all traffic is translated.  If the optional
        protocol is specified, only traffic of that protocol will be
        translated by that entry.

        The OVERLOAD case does not accept port numbers, and it
        requires a subnet mask to be specified.  The mask is used in
        combination with the local address to form a range of
        addresses which will be accepted for translation.  For
        example, if the local address is 192.168.0.0 and the netmask
        is 255.255.255.240, addresses 192.168.0.0 to 192.168.0.15
        inclusive will be translated.

        NAT DROP <local>[:port] [tcp | udp]

        Simple entries, i.e. those in which the protocol shows "ALL"
        and the port numbers are zero, can be removed by the form:

                "NAT DROP <localaddr>" e.g. "NAT DROP 192.168.0.2".

        If the translation table entry includes port numbers, the
        form:

           "NAT DROP <local_address>[:port]" is required, e.g.
           "NAT DROP 192.168.0.2:23".

        If the translation entry is protocol-specific, the protocol
        must be specified when removing the entry, e.g.:

           "NAT DROP 192.168.0.2 TCP".

        NAT LIST

        This command currently requires no arguments.


        Order of Entries in NAT table
        ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
        The order of entries within the translation table is
        important, because XRouter will translate upon the first
        matching entry.  This gives you maximum flexibility to cater
        for your particular needs.  As a general rule, port-specific
        and protocol-specific entries should be declared before
        non-specific "catch-all" entries.  Overload entries can be
        declared anywhere, providing they don't inadvertently "hide"
        a static translation for the same address.

        Consider this example:

        NAT ADD STATIC    192.168.0.2:87  44.131.91.2:23  TCP
        NAT ADD STATIC    192.168.0.2     44.131.91.2
        NAT ADD OVERLOAD  192.168.0.0     44.131.91.3  255.255.255.240

        In the above example, TCP frames originating from port 87 on
        local host 192.168.0.2 will be translated by the first entry,
        to look like they originated from port 23 on global host
        44.131.91.2.

        UDP and all other TCP frames from that host will be translated
        by the second entry, which leaves the port numbers alone.
        This entry also translates "portless" protocols such as AXIP,
        ICMP, IPIP etc.

        The third entry translates any TCP or UDP frame originating
        from local hosts 192.168.0.0 to 192.168.0.15, excluding
        192.168.0.2, to look as if it originated at 44.131.91.3.

        If the second entry had been placed before the first, it would
        never have been executed, because the non-specific static
        entry would have intercepted *every" frame from 192.168.0.2. 
        If the overload entry had been placed first, it would have
        intercepted every TCP and UDP frame from local hosts 0 to 15,
        so the port specific static would never have been executed.


        Routing Table Requirements
        ~~~~~~~~~~~~~~~~~~~~~~~~~~
        In addition to the translation table entries, you must ensure
        that IP routing to the target system is correctly configured.

        Network Address Translation is applied *before* the packet is
        routed. This means that for "outbound" packets, i.e. those
        originating on the "private" subnet, routing to the "public"
        net should be defined.  For "inbound" packets, i.e. those
        originating on the public net, addressed to one of the global
        NAT addresses, the should be a routing entry which will route
        the translated address to the *private* subnet. This is best
        illustrated with an example:

        In IPROUTE.SYS....

        ROUTE ADD 44.0.0.0/8         44.131.90.6     11      d
        ROUTE ADD 192.168.0.1/32     *               14      d

        NAT ADD STATIC 192.168.0.1   44.131.91.3

        The first entry routes all outbound 44-net packets to peer
        44.131.90.6 on port 11.

        The second entry routes packets addressed to 192.168.0.1 onto
        port 14 which is the Ethernet LAN.

        The third entry translates destination address 44.131.91.3 on
        incoming packets into 192.168.0.1 before sending the packet on
        the LAN as dictated by the second entry.

        Internet Connection Sharing
        ~~~~~~~~~~~~~~~~~~~~~~~~~~~
        If one of XRouter's ports is connected to the Internet (e.g.
        by dialup or cable modem), you may use dynamic PAT to allow
        other computers on a LAN to share the connection.  Assuming
        the computers on your LAN use addresses in the range
        192.168.0.1 to 192.168.0.255 (this is the range normally used
        by Windows), the NAT entry should look like this:

        NAT ADD OVERLOAD 192.168.0.0   0.0.0.0   255.255.255.0

        Note the special 0.0.0.0 entry, which tells XRouter to
        translate the source address on outgoing frames to the address
        of the port on which they are sent.  This is required if your
        Internet connection uses a dynamic IP address, but if your
        address is static you may insert it in place of the 0.0.0.0.

        If you don't have a DNS server on your LAN, you will need to
        set up the LAN computers to use Xrouter as their DNS.  You
        will also need to tell XRouter the address of at least one
        external DNS, either by including a "DNS=<ipaddr>" statement
        in XROUTER.CFG, or by using a "DNS ADD <ipaddr>" command.
        XRouter will then act as proxy DNS for the computers on the
        LAN.

        Summary
        ~~~~~~~
        a) Use NAT ADD... in IPROUTE.SYS to define translations.
        b) Add IP routing for the *global* NAT addresses.
        c) Use NAT... commands to display / adjust NAT on the fly.
        d) Report problems to me.


        References:
        ~~~~~~~~~~~
        RFC791  - Internet Protocol
        RFC792  - Internet Control Message protocol
        RFC793  - Transmission Control Protocol
        RFC1631 - The IP Network Address Translator
        RFC1700 - Assigned Numbers
        RFC1918 - Address Allocation for Private Intranets

</code> **SEE ALSO:** \\
[[packet:xrouter:docs:MAN1#NAT|        NAT(1)         -- NAT Commands
]] \\
[[packet:xrouter:docs:MAN8#IPROUTE.SYS|        IPROUTE.SYS(8) -- IP Routing / Configuration File
]] \\

[[packet:xrouter:docs:|< Back to Index]]

----
===== NCMP =====
<code>NCMP(9)                 XROUTER REFERENCE MANUAL            25/10/2023
</code> **NAME** <code>
        NCMP -- NetRom Control Message Protocol.

</code> **SYNOPSIS** <code>
        NCMP has been implemented in XRouter since July 2001. It is
        an extension to the NET/ROM protocol, facilitating extra
        tools for network administration, such as network probing
        and unknown route reporting.  It was described in Packet
        White Paper PWP106, most of which is reproduced below.

</code> **INTRODUCTION** <code>
        The Netrom Control Message Protocol is part of ISO Layer 3,
        and sits just above the routing sub-layer. It is intended to
        be transparently routable by any NET/ROM node, whether or not
        that node implements the protocol.

        To that end it uses NET/ROM "protocol extension" packets,
        which should (in theory) be routed "as-is" by any node which
        doesn't understand them.

</code> **PACKET STRUCTURE** <code>
        NCMP datagrams consist of a normal Layer 3 NET/ROM header,
        followed by the NCMP header, which may in some cases be
        followed an optional NCMP payload.

        The NCMP header is of variable length, and its first 5 bytes
        occupy the space normally used by a NET/ROM layer 4 header,
        as depicted in the diagram below:

                |<------------- NCMP Header ----------->| 
         -----------------------------------------------------------
        | L3hdr | Fam | Prot | Type | Code | 00 | (opt) | (Payload) |
         -----------------------------------------------------------

        Field  Bytes  Description
        --------------------------------------------------------
        L3hdr    15   NET/ROM Layer 3 Header
        Fam       1   Protocol Family = NET/ROM = 0x0f 
        Prot      1   Protocol = NCMP = 0x00
        Type      1   Type of NCMP packet (see below)
        Code      1   Usage depends on "type".
        Opt      var  Additional fields present in some types only
        Payload  var  Optional payload present in some types only

        The upper 4 bits of the TYPE are reserved for future
        expansion, and are set to zero in this version. The lower 4
        bits encode the packet type as follows:

            Type  Purpose
            ----------------------------------- 
             0    Probe Request
             1    Probe Reply
             2    Echo Request
             3    Echo Reply
             4    Routing Information Unicast
             5    Destination Unreachable

</code> **PACKET TYPES** <code>
        The following diagrams omit the L3 header for clarity:

        Type 0: Probe Request

             -------------------------------------------------
            | 0F | 00 | Type=0 | TTL | 00 | Tick(h) | Tick(l) |  
             -------------------------------------------------

            "TTL" is a Time To Live, limiting the no. of hops the
            probe may propagate. This value is also copied into the
            L3 TTL field. 

            "Tick" is a 16 bit tick counter, sent high octet first.
             This is returned unmodified by the responder, and used
            to calculate the Round Trip Time (RTT). 

            A node which responds to a probe request must return the
            whole datagram (including any additional fields not
            specified above), after changing the NCMP type from 0 to
            1 and inserting the TTL from the L3 header into the NCMP
            TTL field. 


        Type 1: Probe Reply

             -------------------------------------------------
            | 0F | 00 | Type=1 | TTL | 00 | Tick(h) | Tick(l) |  
             -------------------------------------------------

            "TTL" is the TTL from the L3 header of the rcvd probe. 

            "Tick" is the 16 bit tick count from the probe datagram 


        Type 2: Echo Request

             ------------------------------------------------------
            | 0F | 00 | Type=2 | TTL | 00 | ID | Seq | Opt payload |  
            -------------------------------------------------------

            "TTL" is the initial Layer 3 TTL
 
            "ID" is a unique 16 bit identifier, sent high octet
            first, allowing the originator to match responses with
            the requests. 

            "Seq" is a 16 bit sequence number, sent high octet first.
             Usually carries a timestamp, allowing the RTT to be
             computed. 


        Type 3: Echo Reply

            -------------------------------------------------------
            | 0F | 00 | Type=3 | TTL | 00 | ID | Seq | Opt payload |  
            -------------------------------------------------------

            "TTL" is the TTL from the L3 header of the received
            request. 

            The ID, SEQ and Payload fields must be returned
            unmodified.


        Type 4: Routing Information Unicast

             -----------------------------------------------
            | 0F | 00 | Type=4 | xx | 00  |    INP3 Data    |
             -----------------------------------------------

            "xx" = unused field


        Type 5: Destination Unreachable

             -----------------------------------------------
            | 0F | 00 | Type=5 | Code | 00  | Returned Data |
             -----------------------------------------------

            "Returned Data" is the first 28 octets of the unrouted
            datagram.  

            "Code" is as follows:

            Code Meaning           Explanation
            ---------------------------------------------------------
             0   Host Unknown      The router does not know the
                                   destination node.
  
             1   Host Unreachable  The destination node is known, but
                                   there are no viable routes at this
                                   time, due to obsolescence or link
                                   failure. 
 
             2   Net Unreachable   The number of hops to the target
                                   system is more than the remaining
                                   Time To Live.
 
             3   Proto Unreachable The destination node does not know
                                   how to handle the requested
                                   protocol.
  
             4   Service Unreach   The requested service is not
                                   implemented at the destination
                                   node.
  
             5   TTL Exceeded      The datagram could not be routed
                                   any further because its Layer 3
                                   Time to Live reached zero.
  
             6   Frag Required     The datagram is too large for the
                                   outgoing link, and the link does
                                   not support fragmentation.
 
             7   Source Quench     The datagram could not be handled
                                   at this time due to insufficient
                                   resources. This situation is
                                   temporary. Upon receipt of this
                                   message, the sender should reduce
                                   the sending rate.  

</code> **PROBES** <code>
        Probe datagrams are intended for "peer discovery". In this
        context, PEER means another NCMP-capable node.  At this time,
        only XRouters are NCMP-capable, but wider adoption would be
        desirable.

        Probes are currently dispatched with an initial TTL of 6, to
        nodes with a quality of 20 or more and a one way trip time
        below 1 minute.  These figures are likely to be revised down
        in future.  If no reply is received, the probe interval
        increases.

        Upon receipt of a probe, no matter whom it is addresed to,
        an NCMP peer returns it to the sender. Thus only the nearest
        peers are discovered.

</code> **INFORMATION EXCHANGE** <code>
        The purpose of peer discovery is to facilitate the transfer
        of additional network-related information across a legacy
        network, most of which which doesn't, and probably never
        will, embrace INP3.

        Such information may include a node's position, town,
        software type and version, contact details, Amprnet IP
        address, available services and so on. These things make
        Packet Radio more interesting.

        Once a peer had been identified, XRouters are able to
        exchange INP3 data "tunneled" inside NCMP type 4 datagrams,
        even if the intervening nodes are not INP3-capable.

        A consequence of this exchange is to allow expansion of, and
        experimentation with, INP3-like options, without breaking the
        existing INP3 protocol.  When proven, such extensions could
        be incorporated into the "official" INP3 standard if there
        was agreement.

</code> **ECHO REQUESTS** <code>
        Echo requests are intended for testing the network, and are
        invoked using XRouter's NPING (Netrom Ping) and NTRACERT
        (Netrom Traceroute) commands.

</code> **SUPERVISORY** <code>
        "Destination unreachable" messages are intended to improve
        the user experience, by quickly reporting network problems,
        instead of leaving the user  waiting for a reply that will
        never come.

        For instance, if the user tries to connect to a node that is
        in the nodes table but no longer has a viable end-to-end
        path, one of the intervening nodes should quickly return a
        "destination unreachable" message, and the user would be
        informed.  Without this, the user could typically wait six
        minutes (L4T1 * L4RETRIES) for a "Connect failed" response.

        With the exception of echo and probe, NCMP datagrams are
        never sent in response to NCMP.

</code> **SEE ALSO:** \\
[[packet:xrouter:docs:MAN1#NPING|        NPING(1)    -- Send NetRom Echo Request(s).]] \\
[[packet:xrouter:docs:MAN1#NTRACERT|        NTRACERT(1) -- NetRom TraceRoute.]] \\
[[packet:xrouter:docs:MAN1#PEERS|        PEERS(1)    -- Show Nearest NCMP-capable nodes.]] \\
[[packet:xrouter:docs:MAN9#INP3|        INP3(9)     -- Inter-Node Protocol 3.]] \\

[[packet:xrouter:docs:|< Back to Index]]

----
===== NDISXPKT =====
<code>NDISXPKT(9)             XROUTER REFERENCE MANUAL            17/10/2023
</code> **NAME** <code>
        NDISXPKT -- NDIS Driver for XRouter (XR32 only).

</code> **DESCRIPTION** <code>
        NdisXpkt is an optional kernal-mode driver which allows XR32
        to share an Ethernet NIC with Windows, and to have its own
        completely independent IP address.

        The driver was written for XR32 in 2006 by Anthony Martin
        M1FDE, sadly now silent key.

        Unfortunately, it can only be used with Windows 2000 and
        Windows XP.


        Do I Need NdisXpkt?
        ~~~~~~~~~~~~~~~~~~~

        The NdisXpkt driver is only required if you wish to share an
        Ethernet NIC with Windows.  XR32 will work without it, but you
        will not have the full range of XR32's functionality.

        Without NdisXpkt XR32 is not able to:

            - Have its own Ethernet LAN IP address
            - Route "raw" IP via the Ethernet NIC.
            - Trace any raw IP activity via Ethernet NIC.
            - Use IPEncap encapsulation via Ethernet NIC.

        If you don't need any of the above, you don't need NdisXpkt.


        Explanation
        ~~~~~~~~~~~

        Without the NdisXpkt driver, XR32 is forced to use facilities
        provided by the Windows TCP/IP stack.  Those facilities are
        limited, and in some cases are deliberately crippled by
        Microsoft.  For example, later versions of Windows XP block
        the use of IPENCAP (protocol number 4). 

        Since no-one likes having to install and load drivers, the
        majority of sysops now tend to use XR32 without NdisXpkt.
        However this is a **basic** mode, with limited facilities,
        compared to the "full" (NdisXpkt) mode. It was only intended
        as a stop-gap measure, until a 64-bit driver could be written. 

        In basic mode, XR32 can originate and terminate all the common
        higher-level protocols (TCP, UDP, ICMP etc.), but cannot
        handle datagrams via the *Ethernet* NIC at the raw IP layer
        (IP via SLIP, PPP or IP-over-AX25 connections are not
        restricted however).  This means that XR32 cannot act as an
        IP router for datagrams to or from the LAN, unless those
        datagrams are encapsulated.  And it cannot trace IP headers
        to/from the LAN, although it is able to trace the "inner" IP
        headers of encapsulated datagrams.

        If you are using Win2000 or WinXp, and wish to install
        NdisXpkt, please read on...


        Installing NdisXpkt
        ~~~~~~~~~~~~~~~~~~~

        Before you can use NdisXpkt, it must be installed and started.

        NdisXpkt comes in two flavours, one for Windows 2000 and one
        for Windows XP.  Install only the one to match your operating
        system. The distribution package contains both, in separate
        directories named "Windows 2000" and "Windows XP".

        There are detailed installation instructions with screenshots
        in the INSTALL.HTM document of the NdisXpkt package.  They are
        summarised here:

        a) To install drivers, you need to log in using an account
           with Administrator priviledges.

        b) Extract the files from the .zip archive into a temporary
           directory on your hard drive.  You can remove this
           directory when you've finished installing.  Remember where
           you put them - you'll need them later.

        c) Open the control panel and double-click "Network
           Connections".

        d) You may only have one or two network connections in the
           lower part of the pane. Select one of the network
           connections.  It doesn't matter which you choose, a new
           driver will bind itself with all of them.  If you don't
           have any networks in the lower pane, you need to install
           one.  Either a network card, a USB network adapter, or a
           wireless LAN.  This driver can't be used without one.

        e) Hold the right mouse button and select "Properties" in the
           menu that appears.

        f) This window shows the different protocols that are bound
           to this network device.  We want to install something, so
           click the button marked "Install..."

        g) On the dialog that appears, select "Protocol" and click
           "Add".

        h) You don't want any of the standard choices, so click
           "Have Disk".  The "Install From Disk" dialog should appear. 

        i) Click "Browse" and navigate to the folder where you
           unzipped the files.  It will only show you .inf files.
           When you've found "ndispkt.inf", select it and click
           "Open", then "OK".

        j) Digital signing is not required for NDIS drivers, so click
           OK to install.

        k) The LAN connection properties box should now show
           "NdisXpkt" in the list.

        l) Click "Close" and you're done.

 
        Uninstalling NdisXpkt
        ~~~~~~~~~~~~~~~~~~~~~
 
        a) Make sure XR32 is not running, otherwise the system may
           not allow the driver to be stopped and uninstalled.

        b) Proceed as above until you reach the network connections
           properties box.

        c) Select the NdisXpkt protocol in the scrollable list.

        d) Click "Uninstall".  Windows reminds you that uninstalling
           removes it from all network ports.

        e) Click "Yes".  At this point the protocol should disappear
           from the list.

        f) Click "Close".
 

        Starting NdisXpkt
        ~~~~~~~~~~~~~~~~~

        To start the driver manually, open a command window and type:

                net start NdisXpkt

        At which point you should see the response:
 
            "The NdisXpkt service was started successfully".

        Note that the driver name is case sensitive and must be typed
        EXACTLY as above.  If you type it any other way, the driver
        will start but will not be available to XR32.

        NdisXpkt only needs to be started once per session.  You only
        need to start it again if you restart the operating system.
        It is hoped to automate the startup in future versions of
        XR32.

        In the meantime, you should be able to start NdisXpkt and
        XR32 using a batch file containing the following instructions:

            CD \MyProgs\XR32    <-- or wherever your XR32 is
            net start NdisXpkt
            XR32

        The batch file can be created using Notepad and saved as
        "STARTXR32.BAT" or something like that.  Test it to make sure
        it works.  It may need a short delay between "net start" and
        "XR32" to allow time for the NdisXpkt service to start.  A 4
        second delay can be achieved by insterting "Ping localhost"

        When you are sure that the batch file is working, drag it
        (or a shortcut to it) into Start Menu\Programs\Startup, and
        it should execute when Windows boots.


        Configuring an NdisXpkt INTERFACE
        ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

        XR32 interfaces to NdisXpkt driver via an EXTERNAL interface,
        which is declared in XR32.CFG as follows:

            INTERFACE=1
                TYPE=EXTERNAL        ; External device driver
                ID=Ethernet LAN
                PROTOCOL=ETHER
                MTU=1064
                ETHADDR=00:07:95:fa:d9:3b
            ENDINTERFACE

        Note that the ETHADDR is mandatory and must match the MAC
        address used by the chosen NIC.  To find your NIC's MAC
        address, open a command window and type

            IPCONFIG /ALL

        then look for "Physical address", e.g.

            Ethernet adapter Local Area Connection:
            Physical Address. . . : 00-07-95-FA-D9-3B

        Alternatively, type "ROUTE PRINT" and look for the name of
        the NIC in the list, e.g.

            Interface List
            0x1 ....................... MS TCP Loopback interface
            0x2 ...00 07 95 fa d9 3b .. SiS 900 PCI Fast Ethernet 

        As you can see, there are several different ways of depicting
        a MAC / physical / Ethernet address.  XR32 requires the use of
        colons ':' between the 6 pairs of characters.


        Configuring a PORT
        ~~~~~~~~~~~~~~~~~~

        The Ethernet port is declared like this:

           PORT=1
                ID=Ethernet
                INTERFACENUM=1
                IPADDRESS=192.168.0.2
                NETMASK=255.255.255.0
                etc...

        Make sure you choose a different IP address to the one
        Windows is using!

        Note: The use of interface type EXTERNAL for NdisXpkt is a
              temporary measure, liable to change in future.

</code> **SEE ALSO:** \\
[[packet:xrouter:docs:MAN6#IP-STACKS|        IP-STACKS(6) -- TCP/IP Stacks in XR32
]] \\
[[packet:xrouter:docs:MAN1#MPORT|        MPORT(1)    -- Set port to monitor
]] \\

[[packet:xrouter:docs:|< Back to Index]]

----
===== NFTP-SRV =====
<code>NFTP-SRV(9)             XROUTER REFERENCE MANUAL              7/9/2023
</code> **NAME** <code>
        NFTP-SRV -- Netrom File Transfer Protocol Server 

</code> **DESCRIPTION** <code>
        NFTP (Netrom File Transfer Protocol) is basically a form of
        FTP over NetRom. It uses fairly standard FTP server commands,
        but unlike FTP, in its simplest form it shares a single
        stream for both commands and data.

        NFTP uses NetRomX service 21, the same number as regular FTP.

        Strictly speaking, NFTP is a misnomer, because the protocol
        can be used over any reliable byte-ordered stream, be that
        AX25, NetRom or TCP.

        Although NFTP can be used by anyone, it is primarily intended
        for sysops to exchange files with each other. The protocol
        permits limited access to "public" files without login.

        The server can be accessed in one of 3 ways:

        If the source node is NetromX-capable, the user can connect
        directly to service 21 on the target node. For example,
        "C G8PZT 21". A typical response is shown: 

            c g8pzt 21
            DOTXR:VK2DOT-1} Trying G8PZT::21...
            DOTXR:VK2DOT-1} Connected to G8PZT::21 
            220 G8PZT NFTP ready - Restrictions apply

        Alternatively, the SYSOP of the source node may use the
        "NFTP <target>" command to invoke an NFTP client which
        connects to the target node. This client is not available to
        non-sysops, but there's no restriction on standalone clients.

        If the source node is *not* NetromX-capable, the user must
        connect to the target node then issue the NFTP command,
        supplying the target node's callsign as an argument.

        For example, if the user was connected to VK2DOT and wanted
        to connect to G8PZT's server, he  would issue "C G8PZT",
        wait for connection, then issue "NFTP G8PZT":

            c g8pzt
            DOTXR:VK2DOT-1} Connected to G8PZT
            nftp g8pzt
            G8PZT:KIDDER} Trying server
            220 G8PZT NFTP ready - Restrictions apply

        Once connected to the server, the HELP command reveals the
        available commands and their syntax:

            help
            211-Cmds: ABOR CWD HELP LIST MDTM NLST NOOP
            211-Cmds: PASS PWD QUIT REST RETR STOR TYPE USER
            211-(Additional commands available after login)
            211-
            211 Use HELP <cmd> for syntax etc.

            help stor
            211-STOR      Upload file to server
            211 Syntax: STOR <size> <filename>

        Login (using USER and PASS commands) is optional, and
        intended only for sysops.

        Unlogged users are restricted to a "public" directory, which
        by default is located at FTP/public. The true location is not
        shown to users. They cannot climb out of this directory, nor
        create any directories within it. It is purely a space for
        sysops and unlogged users to place publicly accessible files,
        such as useful documents, software etc. For example:

            list
            150 OK 286
            04-19-2021  02:41AM        <DIR>         .
            06-20-2020  04:07AM        <DIR>         ..
            04-19-2021  02:41AM                49375 repeaterlist.csv
            04-19-2021  02:36AM                93162 rfc8200.txt

                     4 file(s)         150,729 bytes
                     2 dir(s)          398,048 bytes free
            226 File sent ok


        The main protocol differences between FTP and NFTP are in the
        commands and responses associated with the transfer of data,
        i.e. commands like LIST, STOR and RETR.

        When a file or directory listing is requested using LIST or
        RETR, the server replies with the line "150 OK n", where n is
        the exact filesize in bytes.

        After receiving this line, the client must treat the next
        "n" received bytes as data, to be saved or displayed. After
        sending the data, the server sends the line
        "226 File sent ok", and is ready for the next command.

        The syntax to upload a file is "STOR <bytes> <filename>",
        for example, "STOR 96507 xrpi-manual.txt". If this is
        acceptable to the server, it responds "150 OK <bytes>".

        Upon receiving this line, the client must send exactly
        <bytes> bytes of data. The server will not return to command
        mode until it has received at least the specified number of
        bytes. Any excess bytes sent by the client are discarded by
        the server. 

        Thus you can read text files directly to your monitor, and
        create them directly from your keyboard if required.

</code> **NOTE** <code>
        Service 20 is reserved for possible future use as a separate
        "data" channel.

</code> **SEE ALSO:** \\
[[packet:xrouter:docs:MAN1#NFTP|        NFTP(1)     -- Start Netrom File Transfer Protocol Session.]] \\
[[packet:xrouter:docs:MAN9#NFTP-SVC|        NFTP-SVC(9) -- NetRomX NFTP Service.]] \\
[[packet:xrouter:docs:MAN9#SERVICES|        SERVICES(9) -- NetRomX Standard Services.]] \\

[[packet:xrouter:docs:|< Back to Index]]

----
===== NFTP-SVC =====
<code>NFTP-SVC(9)            XROUTER REFERENCE MANUAL              22/9/2023

</code> **NAME** <code>
        NFTP-SVC -- NetRomX File Transfer Service.

</code> **DESCRIPTION** <code>
        NetRomX service 21 connects to XRouter's NFTP server. This
        server allows files to be transferred across the NetRom
        network instead of TCP/IP. It uses similar commands to FTP,
        but shares a single stream for commands and data.

        The NFTP server is also available from XRouter's command
        prompt.

        For more information, see NFTP(9).

</code> **SEE ALSO:** \\
[[packet:xrouter:docs:MAN1#NFTP|        NFTP(1)     -- Start Netrom File Transfer Protocol Session.]] \\
[[packet:xrouter:docs:MAN9#NFTP-SRV|        NFTP-SRV(9) -- About the NFTP Server.]] \\
[[packet:xrouter:docs:MAN9#SERVICES|        SERVICES(9) -- NetRomX Standard Services.]] \\


[[packet:xrouter:docs:|< Back to Index]]

----
===== NTTY-SVC =====
<code>NTTY-SVC(9)              XROUTER REFERENCE MANUAL             7/9/2023
</code> **NAME** <code>
        NTTY-SVC -- NetRomX TTYLink Service

</code> **DESCRIPTION** <code>
        NetromX Service 87 is Netrom access to TTYLink - keyboard to
        keyboard chat with the sysop. It is equivalent to telnetting
        to TCP service 87, or using the YELL command on the target
        node.

        When a client connects to the server, the sysop of the server
        is paged, and has 90 seconds to respond. The page consists of
        a pop-up dialog on top of the sysop's current window, and an
        audible sound. Note the latter only works on older-style PC's
        which have a "PC Speaker", or have AUDIODEVICE defined.

        At any point during or after the 90 seconds, the client has
        the option to leave a short one-line message (160 chars max)
        or to abort the call. 

        If the sysop takes more than 90 seconds to respond, and the
        client has not disconnected, the sysop can still use the
        "talk" command to initiate a chat with the caller.

        Here's an example session where the sysop responds:

            c mobile 87 s

            VK2DOT-1:DOTXR} Trying G8PZT-1

            VK2DOT-1:DOTXR} Connected to G8PZT-1

            TTYLINK at MOBILE:G8PZT-1
            Calling sysop for 90 seconds..
            Type 'M' at any time to leave a short message,
             or 'Q' to quit...

            *** G8PZT-1 has come online to talk ***
            Hello, why are you calling me?
            Because I want to, silly!
            Fair enough, it's mad talking to oneself you know...
            I know, but no-one else is around.
            Ok, bye for now

            *** The other end terminated the chat

            VK2DOT-1:DOTXR} Welcome back

        And here's a session where the sysop didn't respond.
        Although not strictly TTYlink, it is a useful compromise,
        rather than allow an important call to be missed:

            c mobile 87 s

            VK2DOT-1:DOTXR} Trying G8PZT-1

            VK2DOT-1:DOTXR} Connected to G8PZT-1

            TTYLINK at MOBILE:G8PZT-1
            Calling sysop for 90 seconds..
            Type 'M' at any time to leave a short message,
             or 'Q' to quit...
            No response, please type a short (1 line) message now...
            (or enter a blank line to skip this step)

            Can you call me back to discuss xrpi release asap? 

            Message saved for sysop
            Goodbye
            VK2DOT-1:DOTXR} Welcome back

        The message is stored in the sysop's PMS, and a flashing
        asterisk on the top left corner of the status bar alerts the
        sysop to its presence. The sysop can then access their PMS
        to read the message like this:

            CMD(B/H/K/L/R/S/?)>
            l
            Msg# Stat  Rcvd  Time  To      From    Subject
            6 PR   22/05 03:25  SYSOP   G8PZT   TTYLink msg from
                                                 G8PZT@VK2DOT-1

            CMD(B/H/K/L/R/S/?)>
            r 6

            Msg#: 6
            Rcvd: 22/05 03:25
            From: G8PZT
            To:   SYSOP
            Subj: TTYLink msg from G8PZT@VK2DOT-1

            Can you call me back to discuss XRPi release asap?

            CMD(B/H/K/L/R/S/?)>

        It's all a bit untidy at present, but will hopefully be
        tidied up in future revisons.

</code> **SEE ALSO:** \\
[[packet:xrouter:docs:MAN1#TALK|        TALK(1)     -- Talk to a user or another sysop.]] \\
[[packet:xrouter:docs:MAN1#TTYLINK|        TTYLINK(1)  -- Keyboard chat with another TCP/IP system.]] \\
[[packet:xrouter:docs:MAN1#YELL|        YELL(1)     -- Page the sysop.]] \\
[[packet:xrouter:docs:MAN9#AUDIO|        AUDIO(9)    -- Audio Output.]] \\
[[packet:xrouter:docs:MAN9#SERVICES|        SERVICES(9) -- NetRomX Standard Services.]] \\

[[packet:xrouter:docs:|< Back to Index]]

----
===== PERMLINKS =====
<code>PERMLINKS(9)            XROUTER REFERENCE MANUAL            18/10/2023
</code> **NAME** <code>
        PERMLINKS -- Permanent NetRom Neighbour Links.

</code> **SYNOPSIS** <code>
        This file explains why XRouter tries to keep neighbour node
        links permanently open, why that is desirable, and why you
        shouldn't worry about it.

</code> **DESCRIPTION** <code>
        Old-fashioned nodes close their AX25 level 2 links with
        neighbour nodes after a period of inactivity, which can be
        less than ideal...

        Firstly, it takes a finite time to establish an AX25 L2
        interlink from "cold", which adds an unnecessary extra
        delay for NetRom link setup, and for L3 frames which arrive
        infrequently. If it takes 5 seconds to establish a link,
        and a frame has to pass through 10 nodes, that's an extra
        50 seconds of delay!

        Secondly there is the very common and highly disruptive
        problem known as the "ONE WAY LINK".  These can occur when
        an RF path fades, or when there is local interference, or
        when a transmitter, receiver, antenna, TNC or AX*P link
        malfunctions, leaving one node hearing the other but not
        vice versa.

        When a one-way link occurs, one peer can hear the other's
        nodes broadcasts, but there is no reverse path.  The node
        which received the broadcast mistakenly thinks it has a
        route to the node which made the broadcast, but since the
        two-way path required by an AX25 connection is not
        available, no connection can be made. No traffic can be
        transferred, so the neigbour node and all nodes advertised
        by him are unreachable.

        To make matters worse, the node which received the
        broadcast advertises all the nodes learned via that
        broadcast to its other neighbours. So in turn they think
        they have routes to distant nodes, when in fact they don't.
        The network is seriously disrupted by one broken link,
        causing a black hole where all packets are LOST. This
        situation can not recover until the one way link is fixed.

        The Better Way
        ~~~~~~~~~~~~~~

        In contrast, XRouter attempts to maintain permanent L2 links
        between neighbour nodes. You may find this disconcerting,
        but it has the following advantages:

        Firstly, it removes the link establishment time, so NetRom
        traffic can be routed without delay, no matter how
        infrequently it arrives.

        Secondly, it solves the "one way link" problem by promptly
        detecting when the link cannot accept traffic, and marking
        all nodes advertised by the peer as unusable, so that
        alternative routes can be used.

        Lastly, it enables continuous measurement of route quality
        and round trip time, used in making routing decisions. RF
        links, especially long ones, can be remarkably variable
        throughout the day and night, and these problems can be
        discovered through the process of continuous link audit.

        There is no need for concern. The only cost associated with
        keeping a link open is a tiny link check packet every 3
        minutes. Hardly a great waste of bandwidth! Remember that
        the old-fashioned way has a bandwidth cost too - at least
        two packets to open a link and two to close it, in addition
        to the link check packets. The benefits of permanent links
        far outweigh the disadvantages.

        How it Works
        ~~~~~~~~~~~~

        If port QUALITY and NODESINTERVAL are both non-zero, as soon
        as XRouter hears a nodes broadcast from a previously unknown
        neighbour, it will attempt to connect to it. If the connect
        is successful, the round trip time is measured, and the
        route is considered viable. The link is checked every 3
        minutes (adjustable via T3), and will close if non-viable.

        If the connect fails, the route is marked as unusable,
        therefore no nodes will be routed via it. The connection is
        retried at regular intervals.

        If the path is marginal, connection attempts may sometimes
        succeed and sometimes fail. It is not worth using a route
        like this, so you can prevent it from re-trying by locking
        in the neighbour with a zero quality.

        The ROUTES commands will show a ">" in the left-most column
        if the interlink is fully open, a "~" if it is opening or
        closing, or an "x" if the link can't be opened or has failed.
        This  provides a handy way of detecting link problems which
        might otherwise go un-noticed.

</code> **SEE ALSO:** \\
[[packet:xrouter:docs:MAN1#ROUTES|        ROUTES(1)      -- NetRom Routes Commands.
]] \\
[[packet:xrouter:docs:MAN7#NODESINT|        NODESINT(7)    -- Nodes Broadcast Interval.
]] \\
[[packet:xrouter:docs:MAN7#QUALITY|        QUALITY(7)     -- Default NetRom Quality.
]] \\
[[packet:xrouter:docs:MAN8#XROUTER.CFG|        XROUTER.CFG(8) -- Main Configuration File.
]] \\

[[packet:xrouter:docs:|< Back to Index]]

----
===== PIPES =====
<code>PIPES(9)                XROUTER REFERENCE MANUAL            18/10/2023
</code> **NAME** <code>
        PIPES -- Frame Pipes.

</code> **DESCRIPTION** <code>
        Frame pipes allow frames received (and optionally sent) on 
        one port to be copied to another port.

        A typical use might be to allow a PMS on one port to see
        the traffic on another port, e.g. UNPROTO headers from a
        local BBS.

        Note that this is *not* the same as digipeating. With
        digipeating, the user must specify a digipeater in the path,
        but with frame piping the packets are tunneled from one port
        to another with no intervention from the user.

        The facility is enabled by including the PIPE keyword within
        a port definition, e.g. PIPE=4 would pipe frames to port 4.
        If PIPE=0, or the keyword is omitted altogether, no piping
        takes place.

</code> **SELECTIVE PIPES** <code>
        By default, pipes are not selective, i.e. they pass traffic
        from any source callsign to any destination callsign (with
        the exception of Budlisted callsigns of course). On a busy
        channel, this could result in a lot of unnecessary traffic
        being piped.

        Pipes can be made selective however, by adding a comma
        delimited callsign list, e.g. "PIPE=4 GB7PZT,KDRBBS".  This
        reduces the loading on the destination port, by piping only
        those frames with the specified callsigns in the destination
        field.

        Pipes can also be made selective in terms of the types of
        traffic they pipe (AX25, NetRom etc). This is controlled
        by PIPEFLAG (see OPTIONS below)

</code> **BIDIRECTIONAL PIPES** <code>
        A pipe normally only allows traffic in one direction, so in
        order to have two way traffic you must either set up a
        reverse pipe on the partner port, for example:

           (on port 3)    PIPE=4  ; Pipe frames to port 4
           (on port 4)    PIPE=3  ; Pipe frames to port 3

        Or you may configure the pipe to be bi-directional, by
        setting the appropriate value in PIPEFLAG (see below)

        If a frame is piped on a bi-directional pipe, the source
        callsign is remembered so that responses will be piped back
        to the sender. XRouter remembers the last 20 callsigns that
        used a pipe.

        Bidirectional pipes are useful in cases where a BBS has a
        front end router.  Simply set up bi-directional selective
        pipes from each user port to the BBS port.  The BBS will
        then allow direct connection and will respond to resync
        requests.

        Bi-directional pipes are actually only quasi-bi-directional, 
        because they can only send *responses* in the reverse
        direction.  In the above BBS example, outgoing connections
        cannot be initiated to callsigns which haven't already used
        the pipe.

        For most purposes this isn't a problem, because it is the
        users that tend to initiate the connections, not the BBS.
        However, there may be cases where the BBS needs to poll the
        user's PMS, or to initiate forwarding to another BBS. If the
        callsign is remembered from a previous session, this will
        work, otherwise it will fail. 

        The only way to have truly unconditional two-way piping is
        to set up forward and reverse pipes as detailed above.

</code> **OPTIONS** <code>
        The types of frame to be piped can be controlled using the
        optional PIPEFLAG keyword, which is ignored unless piping
        is active.

        The value for PIPEFLAG is made up by adding together the
        desired options represented by the following numbers:

            1   - UI frames *not* addressed to nodecall/alias.
            2   - Non-UI frames *not* addressed to nodecall/alias.
            4   - UI frames addressed to nodecall/alias.
            8   - Non-UI frames addressed to nodecall/alias.
            16  - UI frames transmitted by the router.
            32  - Non-UI frames transmitted by the router.
            64  - Allow budlisted users to be piped.
            128 - Netrom  & nodes broadcast frames.
            256 - IP / ARP frames.
            512 - Bi-directional piping.

        e.g. PIPEFLAG=5 will pipe all received UI frames, but not
        those which originated from XRouter itself.

        If PIPEFLAG is not specified, the default value is 3, which
        pipes all regular AX25 Layer 2 traffic.  You are *STRONGLY*
        recommended to use the default value unless you specifically
        need to see additional traffic.

</code> **LIMITATIONS** <code>
        You may pipe several ports to a single destination port, but
        you can only have one *outgoing* pipe from any port.

</code> **CAVEATS** <code>
        Pipes are capable of generating an immense amount of traffic,
        so use them with care - your target port MUST be capable of
        dealing with the traffic load, and you should avoid setting
        up a combination of pipes which might cause an endless loop!

</code> **FILES** <code>
        The PIPE and PIPEFLAG directives are used in the PORT
        sections of XROUTER.CFG.

</code> **SEE ALSO:** \\
[[packet:xrouter:docs:MAN1#PIPE|        PIPE(1)        -- Display / Set Frame pipe.
]] \\
[[packet:xrouter:docs:MAN7#PIPEFLAG|        PIPEFLAG(7)    -- Frame Pipe Option Flags.
]] \\
[[packet:xrouter:docs:MAN9#BCAST|        BCAST(9)       -- Frame Broadcasting.
]] \\
[[packet:xrouter:docs:MAN8#XROUTER.CFG|        XROUTER.CFG(8) -- Main Configuration File
]] \\

[[packet:xrouter:docs:|< Back to Index]]

----
===== PMS =====
<code>PMS(9)                  XROUTER REFERENCE MANUAL              10/1/2024
</code> **NAME** <code>
        PMS -- Personal Message Server / Mailbox.

</code> **SYNOPSIS** <code>
        This file describes XRouter's inbuilt mailbox which can be
        used for both private messages and bulletins. The terms "PMS"
        and "mailbox" are used interchangeably.

</code> **DESCRIPTION** <code>
        XRouter's mailbox is a no-frills message storage and retrieval
        system which was originally intended for exchanging messages
        between users and the sysop, hence the legacy name PMS.

        The mailbox understands SIDs (System IDentifiers), MIDs
        (Message IDentifiers) and BIDs (Bulletin IDentifiers),
        hierarchical addressing, bulletins, MBL forwarding and reverse
        forwarding, so it can also be used to exchange private mail
        and bulletins with a full-service Bulletin Board System
        (BBS). In fact it is a mini-BBS in its own right, as users
        may leave bulletins for others to read.

        There is no limit to the number of messages or the size of a 
        message.  If a disk is available, messages are stored on the
        disk and will persist until killed, or expired by age. If no
        disk is available, messages are stored in RAM and will be lost
        if XRouter is restarted.

        If there is unread private mail addressed to the sysop, the
        latter is alerted by "PMS" flashing to the left of the node
        callsign on the top status bar.

</code> **BASIC CONFIGURATION** <code>
        The mailbox can be configured in one of several "modes"
        controlled by the PMSTYPE directive in XROUTER.CFG. The
        default is mode 1 i.e. standard PMS. To configure the mailbox
        as a full BBS instead, use PMSTYPE=4. See the section 7 page
        for PMSTYPE.

        The mailbox is always available from the node's command line,
        but if you want to enable "direct" AX25 connections, you must
        configure at least PMSCALL in XROUTER.CFG.

        If you want your mailbox to be visible on the NetRom networ
        as well, you must additionally add PMSALIAS and a non-zero
        PMSQUAL. For example: 

                PMSCALL=G8PZT-2
                PMSALIAS=PZTPMS
                PMSQUAL=50

        If you plan to exchange mail with other systems, you must set
        the PMSHADDR directive in XROUTER.CFG. Also note that the
        agreed specification for mail forwarding does not allow SSID's
        in mailbox callsigns, so even if PMSCALL includes an SSID, the
        mailbox "identity", as far as the mail forwading system is
        concented, is PMSCALL without SSID.

        Additional configuration options can be specified in PMS.CFG,
        which is explained in its own section 8 MAN page.

</code> **CONNECTING TO THE MAILBOX** <code>
        Whatever the setting of PMSTYPE, the mailbox can always be   
        accessed using the "PMS" command or by a connection to
        NetRomX service 2.

        If PMSTYPE=4, the mailbox is accessed via the "BBS" command
        instead. If the "PMS" command is used in this mode, only
        personal mail is shown by default.

        In addition, if PMSCALL is defined in XROUTER.SYS, users may
        perform an AX25 level 2 connect directly to the PMSCALL.
        (PMSCALL must not not be the same as NODECALL)

        If PMSALIAS and a suitable PMSQUAL are also defined, users may 
        also connect directly to the mailbox from another node, using
        "legacy" NetRom.

        At the time of writing there is no direct TCP/IP access to the
        the PMS, because a regular Telnet connection followed by the
        issuing of the "PMS" command is sufficient.
        
</code> **COMMANDS** <code>
        The mailbox has its own rudimentary command set, separate from
        the node commands. The following is a possibly incomplete list.
        (A full list can be obtained using the command "? **")

           <n> [n1 n2..]   Read message(s)
           ? [*]           Syntax and brief help
           A[bort]         Aborts paused message reading/listing
           B[ye]           Disconnect from the PMS.
           CB <cat> [dist] Copy any type of message to a bulletin
           CP <to> [at]    Copt any type of message to a private msg 
           EH <msgnum>     Edit header fields for <msgnum> (*3)
           EX[port] <n> <file> Export msg <n> to <file>  (*3)
           H[elp]          Display list of commands.
           HO[ld] <msg>    Hold a message (*3)
           FF              Force Forwarding run (*3)
           FP              Force Polling run (*3)
           H[elp] [topic]  Display help for PMS command or topic
           I[nfo] <call>   Display all WP info for <call>
           I@ <bbs>        List users with <bbs> as their 'home' BBS
           IC <call>       List users with pallsign <call> (*1)
           IH <haddr>      List users at hierarchical address <haddr>
           IM[port] <file> Import message(s) from MBL-format file (*3)
           IN <name>       List users called <name> (*1)
           IQ <qth>        List users at <qth> (*1)
           IZ <zip>        List users at <zip> / locator (*1)
           J [max]         Show most recent [max] callers (default 10)
           K[ill] <n ...>  Kill one or more messsages
           K> <call>       Kill messages TO <call> (*1)(*2)
           K< <call>       Kill messages FROM <call> (*1)(*2)
           K@ <dist>       Kill messages AT <distribution> (*3)
           KF [call]       Kill Forwarded msgs [TO call] (*1)(*3)
           KH [call]       Kill Held msgs [TO call]  (*1)(*3)
           KM              Kill Mine (messages you have read)
           KR [call]       Kill Read messages [TO call] (*1)(*3)
           L[ist]          List messages and bulletins.
           L[ist] <n>      List messages starting at number <n>
           L[ist] <f> <l>  List messages from numbers <f> to <l> 
           L> <to>         List messages TO callsign or category
           L< <from>       List messages FROM callsign
           L@ <at>         List messages AT a distribution
           L$ [to]         List messages waiting to be forwarded
           LA <n>          List oldest <n> messages (same as LO)
           LB [n]          List [max of n] Bulletins backwards
           LC [cat]        List bulletin categories (*1)
           LF [to]         List sucessfully Forwarded messages
           LH              List held messages (*3)
           LL <n>          List the Last (most recent) <n> messages 
           LM              List Mine (all messages addressed to you)
           LN              List New (unread) mail addressed to you
           LO <n>          List oldest <n> messages (same as LA)
           LP [n]          List [max of n] Private messages
           LR [to]         List private mail that has been read
           LS <text>       List messages whose subject contains <text>
           LT <text>       List messages containing <text> in body
           LU [to]         List Unread messages
           M[ine]          List messages sent by you
           MB <file> <cat> Make Bull from file to category <cat> (*3)
           MF <n> <file>   Make File from message <n> (*3)
           MFH <n> <file>  Make File from message, incl headers (*3)
           MP <file> <to>  Make Private message from a file (*3)
           N[ext]          Read next message in a "reading list"
           N[ame] [name]   Display or set your name in White Pages
           NC [on | off]   Display/set your ANSI colour preference
           NH [bbs]        Display or set your Home BBS
           NI              Summary of your user record
           NP [lines]      Set pagination [0=off]
           NQ [qth]        Display or set your QTH
           NZ [zip]        Display or set your Zip / Locator
           Q[uit]          Stop reading a list of messages
           R> <to>         Read messages TO callsign or category
           R< <from>       Read messages FROM callsign
           R@ <at>         Read messages AT a distribution
           R[ead] <n ...>  Read msg(s), hiding routing headers.
           RH <n ...>      Read message(s) showing routing headers
           RM              Read Mine (all messages addressed to you)
           RN              Read New (unread) mail addressed to you
           S[end]          Send a message to sysop.
           SB <topic>      Send bulletin to <topic>
           SF              Stop Forwarding run (*3)
           SP <call>       Send personal message to <call>
           SR              Send Reply to a message you just read
           U[nread] <msg>  Unread a message (mark it unread) (*2)
           UH <n n | all>  Un-hold one or more "held" messages (*3)
           VF              View Forwarding queue (*3)

           (*1) Wildcards are allowed.
           (*2) Non-sysops can only action their own messages.
           (*3) Sysop-only

</code> **MESSAGE STATUS** <code>
        Messages have a "status" indicator as follows:

           Status ' ' indicates unread "local" private mail.
           Status '$' indicates unforwarded non-local mail.
           Status 'F' indicates forwarded non-local mail.
           Status 'R' indicates local private mail that has been read.
           Status 'H' indicates that the message is "held".

</code> **DISCONNECTING** <code>
        To exit the mailbox, the user may send BYE or QUIT, or simply
        disconnect.

        Users who accessed the mailbox via the "PMS" or "BBS" commands
        are returned to  XRouter's "node" command prompt upon receipt
        of BYE or QUIT. Users who accessed via any other method are
        disconnected by these commands.

</code> **FILES** <code>
        Messages are stored as individual files in the PMS
        sub-directory of the XRouter working directory. 

        If PMSTYPE=4 (full BBS) the PMS directory may also contain
        other files which control BBS operations, such as PMS.CFG,
        BADWORD.SYS, DISTRIB.SYS, EXPORT.SYS, FWD.SYS, HOLD.SYS, and
        REJECT.SYS. Their purpose is as follows:

        BADWORD.SYS   List of "bad" words which cause message hold.
        DISTRIB.SYS   Controls distribution of mail to other BBS's
        EXPORT.SYS    Controls exporting of messages to files
        FWD.SYS       Controls "forwarding" & "polling" operations
        HOLD.SYS      Controls message "holding"
        PMS.CFG       Additional configuration info
        REJECT.SYS    Controls rejection of unwanted mail.

        Most of these plain text files contain their own
        documentation.
        
</code> **HOUSEKEEPING** <code>
        Optionally takes place at regular intervals (e.g. every 24
        hours - specified on PMS.CFG), when the PMS is idle.

        During this operation, out of date messages and message ID's
        are purged, and (if configured to do so) the  message base is
        re-numbered to remove gaps and keep the message numbers
        within a sensible range

</code> **MAIL IMPORT** <code>
        At intervals less than a minute, the PMS will check the PMS
        directory for the existence of a file called "mail.in". If the
        file exists, the mail it contains is imported and the file is
        deleted. Don't write directly to "mail.in" otherwise it might
        be imported before you finish writing it. Create the file with
        a different name, then rename it to "mail.in" when completed.

</code> **MAIL EXCHANGE** <code>
        This is a two-part process, the parts being DISTRIBUTION and
        FORWARDING. The former is controlled by DISTRIB.SYS, and the
        latter by FWD.SYS.

        Distribution is the process of queuing mail for onward
        transmission to neighbouring mail handlers, and is an
        instantaneous process, executed upon receipt of incoming mail.

        Forwarding is the process of connecting to neighbouring mail
        handlers, and sending the queued mail to them. It is a
        background process, which can optionally be initiated when
        mail is queued, or deferred until later.

</code> **NOTE** <code>
        If a command alias, or an application, with the name "PMS" is 
        defined, it takes priority over the internal PMS.

</code> **AVAILABILITY** <code>
        The PMS is available to all users. It is also available via
        the HTTP interface. Some functionality is available via REST
        and MQTT interfaces.

</code> **SEE ALSO:** \\
[[packet:xrouter:docs:MAN1#PMS|        PMS(1)      -- Start PMS Session.
]] \\
[[packet:xrouter:docs:MAN7#PMSALIAS|        PMSALIAS(7) -- PMS Alias
]] \\
[[packet:xrouter:docs:MAN7#PMSCALL|        PMSCALL(7)  -- PMS Callsign.
]] \\
[[packet:xrouter:docs:MAN7#PMSHADDR|        PMSHADDR(7) -- PMS Hierarchical Address.
]] \\
[[packet:xrouter:docs:MAN7#PMSQUAL|        PMSQUAL(7)  -- PMS Quality.
]] \\
[[packet:xrouter:docs:MAN7#PMSTYPE|        PMSTYPE(7)  -- PMS Mode.
]] \\
[[packet:xrouter:docs:MAN9#PMS-SVC|        PMS-SVC(9)  -- NetRomX PMS Service
]] \\
[[packet:xrouter:docs:MAN9#MQTT-PMS|        MQTT-PMS(9) -- MQTT Interface to PMS.
]] \\
[[packet:xrouter:docs:MAN9#REST-PMS|        REST-PMS(9) -- REST Interface to PMS.
]] \\

[[packet:xrouter:docs:|< Back to Index]]

----
===== PMS-SVC =====
<code>PMS-SVC(9)             XROUTER REFERENCE MANUAL              22/9/2023
</code> **NAME** <code>
        PMS-SVC -- NetRomX PMS Service.

</code> **DESCRIPTION** <code>
        NetRomX service 2 is a direct connection to the sysop's
        Personal Message/Mailbox System (PMS).

        It is used by the "PMS <nodecall>" command, but is also
        intended for human use.

        Broadcasting PMS's as NetRom nodes might have been acceptable
        long ago, but it clutters the nodes tables. The PMS service
        allows sysops to disable the PMS nodes broadcast, or to
        restrict the spread to the local area, while still retaining
        connectivity from afar. All the user has to do is connect to
        service 2 on the NODECALL.
 
</code> **SEE ALSO:** \\
[[packet:xrouter:docs:MAN1#PMS|        PMS(1)      -- Access Personal Message System(s)
]] \\
[[packet:xrouter:docs:MAN9#PMS|        PMS(9)      -- Personal Message System
]] \\
[[packet:xrouter:docs:MAN9#SERVICES|        SERVICES(9) -- NetRomX Standard Services.
]] \\

[[packet:xrouter:docs:|< Back to Index]]

----
===== POP3SRV =====
<code>POP3SRV(9)              XROUTER REFERENCE MANUAL            17/12/2023

</code> **NAME** <code>
        POP3SRV -- POP3 Server.

</code> **DESCRIPTION** <code>
        The POP3 server allows sysops to collect their PMS mail using
        a standard email client.

        Account passwords are stored in POPUSERS.SYS in the form:

                <account name> <password>

        The server is enabled by specifying POP3PORT in XROUTER.CFG,
        for example:

                POP3PORT=110 110

        You must declare a HOSTNAME, for example:

                HOSTNAME=mobile.g8pzt.ampr.org

</code> **OPTIONS** <code>
        

</code> **SEE ALSO:** \\
[[packet:xrouter:docs:MAN8#POPUSERS.SYS|        POPUSERS.SYS(8) -- Account passwords for POP3 Server.]] \\
[[packet:xrouter:docs:MAN8#XROUTER.CFG|        XROUTER.CFG(8)  -- Main Configuration File.]] \\

[[packet:xrouter:docs:|< Back to Index]]

----
===== PPP =====
<code>PPP(9)                  XROUTER REFERENCE MANUAL            17/10/2023
</code> **NAME** <code>
        PPP -- Point to Point Protocol.

</code> **DESCRIPTION** <code>
        Point to Point Protocol (PPP) is a protocol suite intended for
        use over simple links which transport packets between two
        peers, such as an RS232 link (or pair of virtual COM ports).

        Unlike SLIP, it includes facilities for link control (e.g.
        management of a dial up link), user authentication,
        negotiation of IP addresses, and the multiplexing of several
        protocols across a common link.

        PPP is designed to be self configuring.  Most of the options
        have standard default values, and peers negotiate anything
        which differs from the default.

        XRouter currently implements the most common PPP
        sub-protocols:

              - Link Control Protocol (LCP)
              - Password Authentication Protocol (PAP)
              - IP Control Protocol (IPCP)

        Most sysops will have no need to remember these protocol names
        and acronyms.  However, for those who wish to experiment, each
        protocol has its own set of commands.

        PPP has largely replaced SLIP for dial-up Internet access, and
        the interconnection of peers via RS232.

        If you want to know more about the internal workings of PPP,
        it is specified in RFC1661.


        Configuring XRouter for PPP
        ~~~~~~~~~~~~~~~~~~~~~~~~~~~

        There are three ways in which PPP may be used:

              - RS232 (and virtual COM port) links.
              - Dial-in.
              - Dial-out.

        The first case requires an INTERFACE to be configured to use
        PPP, but the other two cases temporarily establish a PPP link
        on a MODEM interface.  Each case is described in more detail
        below:


        Using PPP on Wire / Virtual COM Links
        ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

        In XROUTER.CFG, define an interface with TYPE=ASYNC and
        PROTOCOL=PPP.  For example:

           INTERFACE=1
              TYPE=ASYNC
              COM=1                   ; 1-4 or specify INTNUM/IOADDR
              SPEED=19200             ; Adjust as necessary
              PROTOCOL=PPP
              MTU=1600
           ENDINTERFACE


        Then "bind" a port to that interface thus:

           PORT=1
              ID=PPP link to Win98    ; Text to identify port
              INTERFACENUM=1          ; Bind to PPP interface
              IPADDRESS=192.168.0.4   ; Optional (see below)
           ENDPORT


        The use of IPADDRESS is optional.  If the keyword is omitted,
        XRouter's "global" IP address will be used on that port.  If
        the address is specified as 0.0.0.0, it signifies that a
        "dynamic" IP address should be obtained from the peer,
        otherwise the specified address will be used.

        The port is now ready for PPP using the standard PPP defaults,
        but if it requires any further configuration you may include
        the relevant PPP configuration commands in the file
        BOOTCMDS.SYS, which is read by XRouter at boot-up, after it
        has finished reading XROUTER.CFG.


        Using PPP on Dial-in links
        ~~~~~~~~~~~~~~~~~~~~~~~~~~

        The INTERFACE and PORT should be configured for PROTOCOL=MODEM
        as described in the manual section "PSTN Modem Support".

        When a logged-in caller issues the command XLINK PPP, XRouter
        automatically re-configures the port to support PPP.  It then
        looks for the file "PPPHOST.n", where n is the port number,
        and if found, the PPP configuration commands within the file
        are executed.  The file may optionally contain NAT
        configuration commands if required. The PPPHOST file is
        optional.  If not present, PPP will be initialised to the
        standard defaults.

        When the hardware link disconnects (e.g. user says goodbye or
        hangs up, link times out, or sysop kills it), the port is
        automatically re-configured back to its original MODEM
        protocol.


        Using PPP on Dial-out links
        ~~~~~~~~~~~~~~~~~~~~~~~~~~~

        The INTERFACE and PORT should be configured for PROTOCOL=MODEM
        as described in the manual section "PSTN Modem Support".  The
        local IP address follows the same rules as the wire-link case
        above, but may be overridden temporarily by IPCP commands.

        The dialler script (see DUN section) must contain the command
        "MODE PPP" plus any required PPP configuration commands.  Here
        is an extract from a typical connection script:

          ; Link will use PPP
          mode ppp
          ;
          ; Configure my authentication username and password
          ppp pap user gb7pzt bsfjflavs
          ;
          ; Set inactivity timeout to 2 minutes
          ppp idle 120
          ;
          ; Enable ppp state logging
          ppp log 1
          ;
          ; Set my (static) IP address for the duration of this call
          ppp ipcp local address 194.123.110.4
          ;
          ; Now dial the host
          send ATDT07979654234
          ;
          etc...

        The PPP configuration will persist until the call terminates,
        then the port will revert back to MODEM protocol to await the
        next incoming or outgoing call.


        PPP Configuration Commands
        ~~~~~~~~~~~~~~~~~~~~~~~~~~

        All PPP configuration commands start with "PPP", and are
        described in the sysop command reference section.   When used
        from the command line, or with a BOOTCMDS.SYS file, the first
        argument must be a port number.  However, PPP commands used
        within PPPHOST and dialler scripts *do not* include a port
        number, because XRouter knows which port is executing the
        script.

        e.g. at the command line: PPP 3 IDLE 300
             in a dialler script: PPP IDLE 300


        IP Routing with PPP
        ~~~~~~~~~~~~~~~~~~~

        When a PPP link opens, a route to the peer is automatically
        added to XRouter's IP routing table.  If the peer indicates
        that it knows the addresses of a primary and secondary DNS,
        those are added to XRouter's DNS list.


        PPP Logging
        ~~~~~~~~~~~

        PPP system activity can be recorded in file PPPLOG.TXT for
        diagnostic purposes.  The amount of detail is controlled by
        the number specified in the "PPP <port> LOG n" command as
        follows:

              0       No logging
              1       PPP start / stop / timeout events
              2       As 1, plus layer up / down events
              3       As 2, plus layer start / stop events
              4       as 3, plus option accept / reject events
              5       as 4, plus hexdump of configuration packets

        You are advised against using the higher levels other than on
        a temporary basis because they can create very large logfiles.

        If logging is in use, you should regularly remove the logfiles
        to prevent them growing too large.

</code> **SEE ALSO:** \\
[[packet:xrouter:docs:MAN8#BOOTCMDS.SYS|        BOOTCMDS.SYS(8) -- Bootup Configuration Commands File.
]] \\
[[packet:xrouter:docs:MAN1#DIAL|        DIAL(1)         -- Dial a PSTN connection.
]] \\
[[packet:xrouter:docs:MAN1#DUN|        DUN(1)          -- Dial Up Networking Configuration Commands.
]] \\
[[packet:xrouter:docs:MAN9#DUN|        DUN(9)          -- Dial-Up Networking.
]] \\
[[packet:xrouter:docs:MAN1#PPP|        PPP(1)          -- PPP Configuration Commands.
]] \\
[[packet:xrouter:docs:MAN8#PPPHOST.n|        PPPHOST.n(8)    -- PPP Configuration File(s)
]] \\
[[packet:xrouter:docs:MAN9#PSTN|        PSTN(9)         -- PSTN Modem Support.
]] \\
[[packet:xrouter:docs:MAN9#SCRIPT|        SCRIPT(9)       -- Dialer Scripts.
]] \\
[[packet:xrouter:docs:MAN1#XLINK|        XLINK(1)        -- Establish a Temporary SLIP / PPP Interlink.
]] \\
[[packet:xrouter:docs:MAN8#XROUTER.CFG|        XROUTER.CFG(8)  -- Main Configuration File.
]] \\

[[packet:xrouter:docs:|< Back to Index]]

----
===== PROXIES =====
<code>PROXIES(9)             XROUTER REFERENCE MANUAL              26/9/2023

</code> **NAME** <code>
        PROXIES -- Proxy Connections.

</code> **DESCRIPTION** <code>
        In this context, "proxies" are cross-protocol bridging
        mechanisms which allow systems using one protocol to be
        accessed using another protocol. They can also be used
        to give "hidden" systems a network presence.
 

        AX25 -> NETROM PROXY
        ====================

        This facility allows AX25 level 2 callers to connect
        "directly" to remote NetRom target callsigns, without
        needing to connect first to XRouter then issue a downlink
        connect request. In effect, it gives the NetRom target
        system a local AX25 presence.

          .------.          .-------.            .--------.
          | user |-- Ax25 --| proxy |-- NetRom --| target |
          '------'   link   '-------'    link    '--------'
           (g5ur)            (g8pzt)              (gb7bbs)

            
          .------.      Ax25 link        .-------.
          | G5UR |-- G5UR -> <- GB7BBS --| G8PZT |
          '------'                       '-------'
            (Proxy at G8PZT masquerades as GB7BBS)


        This facility is primarily for use in situations where
        a BBS or PMS is wire-linked to a "front-end" router,
        thus allowing the BBS callsign to be directly
        connectible on any port for which the proxy call is
        defined.  You may find other uses....

        A bi-directional selective frame pipe would provide a
        similar effect, but only for systems directly connected
        to XRouter, whereas PROXY allows the target system to be
        located several hops away.  Pipes can handle UI frames,
        whereas PROXY is for connected-mode operations only.

        Here's how it would be used on a typical set-up, which
        has two machines (or a virtual COM port linking two
        systems on the same machine). Only XRouter is connected to
        the radios, the BBS being KISS-linked to XRouter's port 7.

         -----------  (1)
        | Radio/TNC | ---.
         -----------     |
                         |    .---------.            .---------.
         -----------  (2)|    |  NODE   | (7) KISS   | GB7PZT  |
        | Radio/TNC |----|----|         |------------|         |
         -----------     |    |(XRouter)|  (rs232)   |  (BBS)  |
                         |    `---------'            `---------'
         -----------  (3)|
        | Radio/TNC |----|
         -----------     |
                         V
                        etc.

        Without PROXY, level 2 users would have to connect to
        XRouter, then issue the command "C GB7PZT",or "BBS" to
        connect to the BBS.

        With the line "PROXY=GB7PZT" in port 1's definition
        (in XROUTER.CFG), users on port 1's frequency simply
        connect to "GB7PZT" - XRouter intercepts the request and
        answers on behalf of the BBS.  It then connects via
        NetRom to GB7PZT.  In this case, the BBS is running on
        top of BPQ, so it has a NetRom address.

        If the target system (GB7PZT in this case) is not
        reachable via NetRom level 4, the connect request is
        refused.

        If you wish to use this facility, you must add a
        "PROXY=<call1>[,call2,...]" directive to each user PORT
        concerned.  Ports without the directive continue to
        function as normal.  You obviously wouldn't enable it
        on your forwarding ports for example.  You will notice
        that you can have several callsigns on the line, each
        separated by a comma, allowing you to act as a proxy
        for more than one system.

        Warning!  DO NOT enable PROXY on any frequency which
        is shared by the target system or you'll cause horrible
        problems (both the target and the proxy will respond to
        connects at the same time).


        AX25 / NETROM -> TCP PROXY
        ==========================

        This is an extension of the PROXY concept, allowing a
        remote TCP/IP-only system to have NetRom and AX25
        connectivity.

          .------.          .-------.            .--------.
          | user |-- Ax25 --| proxy |-- TCP/IP --| target |
          '------'   link   '-.-----'    link    '--------'
                              |
          .-------.           |
          | user2 |-- NetRom--'
          | @node |    link
          '-------'

        In the previous example, GB7PZT BBS used G8BPQ node
        "underneath" the BBS to provide NetRom connectivity
        across the KISS link.  With the extended proxy, BPQ can
        be removed altogether and the BBS can be run in pure
        TCP/IP mode.  This saves memory, whilst improving speed
        and reliability.  The BBS no longer has to support
        multiple protocols or interface types, that job being
        delegated to XRouter.

        Instead of having to connect first to XRouter then issue
        the awkward command "Telnet 44.131.91.2", users can
        simply connect "directly" to the BBS callsign (GB7PZT)
        on one of XRouter's radio ports. XRouter converts that
        connection into a TCP/IP connection with the BBS, and
        translates the data back and forth between AX25 and
        TCP/IP.

        Furthermore, the BBS callsign "GB7PZT" can be connected
        to directly from XRouter's command line, and also included
        in nodes broadcasts so it can be reached from a remote
        node.

        This type of proxy is created by putting an extended
        PROXY statement in the GLOBAL section of XROUTER.CFG,
        using the following format:

        PROXY=<call> <alias> <qual> <ipaddr> <tcpport> [passwrd]

        For example:

           PROXY=GB7PZT KDRBBS 150 192.168.0.4 8888 bloggs

        <call>    is the NetRom and AX25 callsign for the
                  proxied system.

        <alias>   is the NetRom / AX25 alias for the proxied
                  system.

        <qual>    is the NetRom "quality" (0 - 255) controlling
                  visibility on the NetRom network.

        <ipaddr>  is the proxied system's IP address.

        <tcpport> is the TCP service port number of the
                  proxied system.

        <passwrd> is an optional password sent to proxied
                  system upon connection. This is used to
                  verify that the TCP connection originates
                  from an approved proxy.

        AX25 and NetRom are pure binary channels, whereas standard
        telnet is not. The proxied system must provide a pure
        binary service port in order to make full use of this
        facility for compressed forwarding etc. G8PZT's "XServ"
        BBS software provides such a facility on TCP port 8888.

        If you are a software author interested in adapting your
        software to work with this proxy, the following information
        will be useful:

        Upon connection to the proxied system XRouter sends one line
        of text ending in <CR><LF>, containing one or more
        space-delimited fields. The first field is the callsign of
        the connectee in the form "G8PZT-7" (ax25) or
        "G6YAK-2@GB7BM" (NetRom).  The second field is a password
        which verifies the proxying system (note this is not the
        user's password).  Thereafter, the link switches to pure
        binary, and in accordance with AX25 practice both systems
        must send line ends as <CR> alone.

        There is no limit to the number of proxies you may
        configure.


        NETROM -> AX25 PROXY
        ====================

        This is similar to the NetRom -> TCP proxy described
        above, but is intended to allow an AX25-only system to
        have a NetRom presence.

          .------.            .-------.          .--------.
          | user |-- NetRom --| proxy |-- AX25 --| target |
          |@node |    link    '-------'   link   '--------'
          '------'               ^
             ^-(Target callsign appears in)
               (nodes tables on these nodes)


        This is enabled by putting an extended PROXY statement
        in the GLOBAL section of XROUTER.CFG, using the
        following format:

           PROXY=<call> <alias> <qual> <ax_call> <portnum>

        For example:

           PROXY=MB7UYL UYLBBS 150 G6KDR-3 7

        <call>    is the NetRom and AX25 callsign for the proxied
                  system.

        <alias>   is the NetRom / AX25 alias for the proxied
                  system.

        <qual>    is the NetRom "quality" (0 - 255) controlling
                  visibility on the NetRom network.

        <ax_call> is the proxied system's AX25 L2 callsign.

        <portnum> is the radio port the proxied system is
                  connected to.

        The above example creates a NetRom node whose callsign
        is "MB7UYL", alias "UYLBBS", with NetRom quality 150.
        Anyone who makes a connection to either of these
        addresses will instead be connected to the AX25 system
        "G6KDR-3", attached to XRouter's port 7.

</code> **OPTIONS** <code>
       Summary of the syntax for the 3 types of proxy....

       AX25 -> NetRom:
       ~~~~~~~~~~~~~~~
       PROXY=<call1>[,call2[,...]]

       AX25 / NetRom -> TCP:
       ~~~~~~~~~~~~~~~~~~~~
       PROXY=<call> <alias> <qual> <ipaddr> <tcp_port> [passwrd]

       NetRom -> AX25:
       ~~~~~~~~~~~~~~
       PROXY=<call> <alias> <qual> <ax_call> <portnum>
 
</code> **CAVEATS** <code>
        Be *very* careful when mixing proxies and pipes, or you
        will end up generating lots of FRMR's, and possibly
        crashing the system. These are powerful tools and must
        be used carefully.

        Proxies are intended for use with your own systems only.
        Do not act as a proxy for someone else's system without
        their permission.

        You must *NEVER* set up a proxy to give a NetRom
        presence to a node which already has one!!

        For proxies which include <portnum>, please ensure that
        the port actually exists (sysops often rearrange ports
        rendering the proxies inactive).

</code> **SEE ALSO:** \\
[[packet:xrouter:docs:MAN7#PROXY|        PROXY(7)       -- Proxy Connectivity.
]] \\
[[packet:xrouter:docs:MAN9#PIPES|        PIPES(9)       -- Frame Pipes.
]] \\
[[packet:xrouter:docs:MAN8#XROUTER.CFG|        XROUTER.CFG(8) -- Main Configuration File
]] \\

[[packet:xrouter:docs:|< Back to Index]]

----
===== PSTN =====
<code>PSTN(9)                 XROUTER REFERENCE MANUAL            18/10/2023
</code> **NAME** <code>
        PSTN -- PSTN Modem Support.

</code> **DESCRIPTION** <code>
        The following text describes a facility which was inherited
        from DOS XRouter, but which probably has no relevance
        nowadays?... 

        XRouter may be connected to one or more Public Switched
        Telephone Network (PTSN) modems, for dial-in and dial-out
        operations.

        Dial-in would, for example, allow users and/or sysops to
        connect to XRouter and operate it using a dumb terminal or a
        standard terminal package such as Telix or Hyperterm.

        Alternatively, after login, the link may be switched into
        SLIP or PPP mode for TCP/IP operations, behaving in exactly
        the same way as a dial-up Internet Service Provider.

        Dial-out allows XRouters to be linked with each other or with
        an Internet service provider, for the purposes of on-demand
        wired routing, or Internet Connection Sharing.

        A single modem may be used for both dial-in and dial-out
        operations on the same port, although not at the same time
        of course!


        Suitable Modem Types
        ~~~~~~~~~~~~~~~~~~~~

        Almost any modem is suitable, providing it can be initialised
        by a single string of characters and can be configured to
        disconnect when DTR is dropped.


        Hardware Configuration
        ~~~~~~~~~~~~~~~~~~~~~~

        External modems should be connected to a serial port using a
        cable with at least 8 connections, namely TXD, RXD, RTS, CTS,
        DTR, DSR, DCD and ground.  The RI (ring indicator) connection
        is not needed.

        Internal modems should be configured to use a spare COM
        number and IRQ.


        Software Configuration
        ~~~~~~~~~~~~~~~~~~~~~~

        Each modem requires an ASYNC interface definition in
        XROUTER.CFG, with COM (or IOADDR & IRQ if non-standard)
        configured for the appropriate serial port or modem card.
        You should use PROTOCOL=MODEM, FLOW=1 and MTU=576.

        To each "modem" interface should be attached a PORT with at
        least INTERFACENUM and ID specified.

        If the modem requires an initialisation string, add the
        directive INITSTR=<initstring>, e.g. to set the modem into
        auto answer mode use "INITSTR=ATS0=1".  If you don't include
        the INITSTR directive, the modem configuration is unaltered.

        If your modem does not, by default, hang up when the RS232
        DTR signal is dropped, you should configure it to do so by
        including "&D2" in the initialisation string, for example:
        "INITSTR=ATM0S0=1&D2".


        Example MODEM Interface and Port Configuration
        ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

        In XROUTER.CFG:

            INTERFACE=5
                TYPE=ASYNC
                COM=3     ; (or /dev/ttyxx for Linux)
                SPEED=57600
                PROTOCOL=MODEM
                FLOW=1
                MTU=576
            ENDINTERFACE

            PORT=2
                ID=PSTN Modem port
                INTERFACENUM=5
                INITSTR=ATS0=1
            ENDPORT


        If you will be allowing incoming calls, you must set up a
        callsign and password entry for each user in USERPASS.SYS.


        Dial-in Operation
        ~~~~~~~~~~~~~~~~~

        If you have configured the modem for auto-answer, PSTN
        callers must successfully complete a callsign and password
        challenge before they are allowed to use the XRouter command
        interface.

        The callsign must be a proper amateur radio callsign, not
        a "username".  If a valid callsign is not given, or if the
        callsign is not found in USERPASS.SYS, or if an incorrect
        password is supplied, the user is immediately disconnected.

        If this sounds unforgiving, it is meant to be!  It will cost
        hackers the price and time delay of a separate phone call
        for each attack.

        If the callsign and password challenge is successfully
        completed, the caller will be allowed full access to the
        command shell, exactly the same as a radio caller.

        XRouter will disconnect the caller after 15 minutes of
        inactivity.  You may initialise the modem to disconnect after
        a shorter interval if necessary.


        The XLINK command
        ~~~~~~~~~~~~~~~~~

        If the caller (e.g. using NOS) wishes to establish a TCP/IP
        link with XRouter, the XLINK command is used to switch the
        ASCII link into SLIP ("XLINK SLIP") or PPP ("XLINK PPP")
        mode.

        XRouter responds with "Entering SLIP mode" or "Entering PPP
        mode", and will thereafter no longer respond to ASCII
        commands.  SLIP or PPP mode may only be terminated by
        disconnection.

        In order to use SLIP or PPP modes, XRouter must have at least
        a global IPADDRESS, and you must set up IP routing to the
        caller's IP address on the modem port.

        You could either allow each caller to use their own IP
        address, and have one routing entry for each caller, or you
        may choose to require all callers on a particular port to use
        the same IP address (since only one may connect at any time)
        and set up a single routing entry.

        For example, you could tell each of your SLIP/PPP callers to
        set their IP address to 192.168.73.88, which is one of the
        "unregistered"  addresses anyone can use.  If your modem is
        on port 2, you would add the following entry to IPROUTE.SYS:

           route add 192.168.73.88/32 * 2 d

        Which means "route datagrams for 192.168.73.88 directly on
        port 2 using datagram mode".

        No ARP entry is necessary for the caller, because SLIP and
        PPP do not use "hardware addresses".


        XLINK PPP mode
        ~~~~~~~~~~~~~~

        XLINK SLIP mode requires no extra configuration, but PPP mode
        optionally uses an extra file to configure the PPP system for
        receive operations on the modem port.  For example, you may
        wish to use one IP address when making outgoing connects and
        a different one when receiving incoming connects.

        The optional file is named "PPPHOST.n" where n is the number
        of the modem port, e.g. "PPPHOST.2".  You may have a separate
        file with a different configuration for each modem port if
        required.  The file should be located in the same directory
        as XRouter itself and may contain any PPP configuration
        command.

        See the description of PPP commands for details of how to
        configure PPP.

        The PPP link inactivity timeout defaults to 5 mins, but can
        be overridden by including the PPP IDLE command in the
        PPPHOST.n file.

</code> **SEE ALSO:** \\
[[packet:xrouter:docs:MAN1#DIAL|        DIAL(1)        -- Dial a PSTN Connection
]] \\
[[packet:xrouter:docs:MAN1#DUN|        DUN(1)         -- Dial Up Networking Commands.
]] \\
[[packet:xrouter:docs:MAN1#PPP|        PPP(1)         -- PPP Configuration Commands.
]] \\
[[packet:xrouter:docs:MAN8#PPPHOST.n|        PPPHOST.n(8)   -- PPP Configuration File(s)
]] \\
[[packet:xrouter:docs:MAN1#XLINK|        XLINK(1)       -- The XLINK Command.
]] \\
[[packet:xrouter:docs:MAN8#XROUTER.CFG|        XROUTER.CFG(8) -- Main Configuration File.
]] \\

[[packet:xrouter:docs:|< Back to Index]]

----
===== REST-BLOG =====
<code>REST-BLOG(9)            XROUTER REFERENCE MANUAL             26/9/2023

</code> **NAME** <code>
        REST-BLOG -- REST Interface to Sysop's Blog.

</code> **DESCRIPTION** <code>
        The sysop's blog may be operated via a REST interface.

        For POST, the Content-Type: header MUST be "application/json".

        This facility is incomplete. The curently available
        functionality is documented in the next section.

</code> **OPTIONS** <code>
        a) Retrieve List of Blog Posts:
        ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

        Request-Type: GET
        Request-URL:  api/v1/blog/posts

        If successful, the response is an un-named JSON array of
        objects, each objct containing the following fields:

        Name          Type      Description
        -----------------------------------------------------------
        "id"          integer   Article/post number.
        "rcvd"        string    Date/time of message creation (*).
        "size"        integer   Length of the blog text in bytes.
        "from"        string    Callsign of the post's creator.
        "subject"     string    Topic of the post (32 chars max)

        (*) in format "Mon, 14 Sep 1997 23:47:00 GMT"

        b) Retrieve a Blog Post:
        ~~~~~~~~~~~~~~~~~~~~~~~~

        Request-Type: GET
        Request-URL:  /api/v1/blog/posts/{post-number}
        Example:      http://localhost:80/api/v1/blog/posts/21

        The response payload is an un-named JSON object containing
        the following fields:

        Name          Type      Description
        -----------------------------------------------------------
        "id"          integer   Article/post number.
        "rcvd"        string    Date/time of message creation (*).
        "size"        integer   Length of the blog text in bytes.
        "from"        string    Callsign of the post's creator.
        "subject"     string    Topic of the post (32 chars max)
        "text"        string    Body of the post (plain ASCII)

        (*) in format "Mon, 14 Sep 1997 23:47:00 GMT"


        c) Post a Blog Article / Reply:
        ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

        Request-Type: POST
        Request-URL:  /api/v1/blog/posts

        The payload must be a JSON object containing the following
        fields:

        Name          Type      Description
        -----------------------------------------------------------
        "sender"      string    Callsign of sender
        "replyto"     integer   No. of msg being replied to (0=new)
        "subject"     string    Subject of the post (32 chars max)
        "text"        string    Body of the post (unlimited size)

        Response: {"id": msg-number }

</code> **EXAMPLE** <code>
        curl -X POST http://localhost:80/api/v1/blog/posts \
        -H "Content-Type: application/json" -d '{\
        "sender": "G8PZT", "replyto": 0, \
        "subject": "test of post via REST", \
        "text": "Test of blog posts via REST interface"}' 

</code> **LIMITATIONS** <code>
        The blog's REST interface is only a proof-of-concept at this
        stage. It does not yet allow article deletion, "liking" of
        articles, or retrieval of replies. Those functions will be
        added in a future version

</code> **SEE ALSO:** \\
[[packet:xrouter:docs:MAN1#BLOG|        BLOG(1)      -- Access Sysop's Blog.]] \\
[[packet:xrouter:docs:MAN7#BLOGFLAGS|        BLOGFLAGS(7) -- Options For Sysop's Blog.]] \\
[[packet:xrouter:docs:MAN9#MQTT-BLOG|        MQTT-BLOG(9) -- MQTT Interface to Blog.]] \\
[[packet:xrouter:docs:MAN9#MQTT-SRV|        MQTT-SRV(9)  -- MQTT Server / Broker.]] \\

[[packet:xrouter:docs:|< Back to Index]]

----
===== REST-NETROM =====
<code>REST-NETROM(9)          XROUTER REFERENCE MANUAL             26/9/2023

</code> **NAME** <code>
        REST-NETROM -- REST API for NetRom Subsystem.

</code> **DESCRIPTION** <code>
        Net/Rom status and information can be retrieved using the
        REST API.

        Requests are made using HTTP, and the data is returned in
        JSON (JavaScript Object Notation) format.

        The base URL for such interactions is "/api/v1/netrom".

        Only HTTP "GET" requests are currently supported by the
        netrom API.

</code> **OPTIONS** <code>
        a) Retrieve List of Nodes:

            GET /api/v1/netrom/nodes


        b) Display Information for Specific Node:

            GET /api/v1/netrom/nodes/{id}	- 

            ({id} is the node callsign)


        c) Display List of Neighbour Routes:

            GET /api/v1/netrom/routes


        d) Display Information for Specific Route:

            GET /api/v1/netrom/routes/{id}


        e) Display List of Layer 4 Circuits:

            GET /api/v1/netrom/circuits
	

</code> **RETURNS** <code>
        If the request is successful, the HTTP response code is 200 OK
        and the response payload is in JSON format, as detailed below:

        a) Nodes List

           The response payload is a JSON array, which may be empty.
           Each array element is a JSON object which contains at least
           the following fields:

           Name     Type     Description
           ----------------------------------------------------
           "id"     string   Callsign of node
           "alias"  string   Alias of node

        b) Specific Node:

           The response payload is a JSON object which contains at
           least the above 2 fields, plus some or all of the
           following fields:

           Name       Type     Description
           ----------------------------------------------------
           "qual"     integer  NetRom "quality" metric
           "rtt"      number   Round Trip Time in seconds (*)
           "hops"     integer  Links between here & target (*)
           "sent"     integer  Frames from us, addressed to that node
           "rcvd"     integer  Frames to us, addressed from that node
           "queue"    integer  L3 frames queued for that node
           "position" string   Node's position in APRS format
           "locator"  string   Node's Maidenhead locator
           "qth"      string   Town, county etc
           "ipaddr"   string   44-net IP address & bits
           "tcp"      integer  44-net Telnet port
           "software" string   Software type
           "version"  string   Software version

            (more fields to be added)

            (*) Zero values of "hops" and "rtt" indicate that they
                have not yet been measured.

        c) Routes List:

           The response payload is a JSON array, which may be empty.
           Each array element is a JSON object which contains at least
           the following fields:

           Name     Type      Description
           ----------------------------------------------------
           "id"	    integer   Unique identifier for this route
           "port"   integer   Port number used by this route
           "call"   string    Callsign of neighbour node
           "qual"   integer   Assigned NetRom "quality" of route
           "sntt"   number    Smoothed Neighbour Trip Time in secs
           "lock"   bool      Route is sysop-locked (true / false)
           "state"  string    "closed", "opening", "open" or "failed"
           "nodes"  integer   No. of nodes routed via this neighbour

           The list may be modified using options in the query string.

           The "port" option can be used to show only the routes
           using a specified PORT, like this:

                /api/v1/netrom/routes?port=2

           Extra information may be displayed using the "detail"
           option, either as a decimal number like this:

               /api/v1/netrom/routes?detail=3

           or as a comma-delimited list of mnemonics, like this:

               /api/v1/netrom/routes?detail=inp,rty,arq

           The extra details, their mnemonics and numbers are listed
           below:

           Mnemonic "l2" - L2 Parameters (+1)

           Name        Type      Description
           ----------------------------------------------------
           "maxframe"  integer   L2 "window" size
           "frack"     integer   Frame Acknowledgement time
           "paclen"    integer   Maximum packet length (bytes)

           Mnemonic "inp" - INP3 Values (+2)

           Name        Type      Description
           ----------------------------------------------------
           "maxtt"     integer
           "thrmaxtt"  integer
           "maxhops"   integer
           "flags"     integer
           "thrsntt"   number
           "inpnodes"  integer,

           Mnemonic "rty" - Frame Counts and Retry Rates (+4)

           Name        Type      Description
           ----------------------------------------------------
           "sent"      integer
           "resent"    integer
           "rtyave"    number
           "rtynow"    number
           "rtymax"    number
           "rtymaxtm"  integer   Time when rty-max occurred

           Mnemonic "rat" - Throughputs, channel load etc (+8)

           Name        Type      Description
           ----------------------------------------------------
           "uptime"    number
           "txmean"    integer
           "txbest"    integer
           "txpeak"    integer
           "loadave"   integer

           Mnemonic "arq" Automatic Route Quality Calculations (+16)

           Name        Type      Description
           ----------------------------------------------------
           "qualave"   integer   Moving average quality
           "qualmin"   integer   Minimum quality
           "qualmax"   integer   Maxinum quality
           "qualdev"   integer   Standard deviation of quality

           Mnemonic "tim" - Times (+32)

           Name        Type      Description
           -------------------------------------------------------
           "bcrcvd"    integer   Time of last rcvd nodes broadcast
           "lasthrd"   integer   Time of last received frame


        d) Specific Route:

           The response is a single JSON object as detailed in (c)


        e) List of L4 Circuits:

           The response payload is a JSON array, which may be empty.   
           Each array element has at least the following fields:

           Name		Type	Description
           ----------------------------------------------------
           "remote"     string  Remote address: user@node:circuit
           "local"      string  Local L4 address + our_circuit no.
           "direction"  string  "incoming" / "outgoing"
           "service"    number  L4X "service number", e.g. 80=http
           "state"      string  Connection state (see below)
           "txq"        number  Bytes queued for transmission
           "rxq"        number  Bytes queued for reception
           "rtt"        number  Smoothed round trip time (ms)
           "tries"      number  Retry count for current event
           "timeout"    number  Layer 4 timeout interval in secs
           "conTmr"     number  Secs left until next timeout
           "chkTmr"     number  Secs left on chocke timer
           "ackTmr"     number  Secs left on delayed ack timer
           "remBusy"    bool    Remote end is busy


           Connection states:
           ~~~~~~~~~~~~~~~~~~
           0 - Disconnected
           1 - Awaiting Connect ACKnowledgement
           2 - Connected & ready to pass data
           3 - We requested disconnect, awaiting DACK
           4 - Waiting for session layer to dispose
           5 - Our end wants to close after data is sent


</code> **ERROR CODES** <code>
        If the request is not successful, one of the following HTTP
        error codes is returned:

            Code                    Meaning
            --------------------------------------------------
            400 Bad Request         Invalid resource specifier
            404 Not Found           Specified API not found
            415 Unsupported Media   POST data was not JSON
            500 No Resources        No memory, try again later


</code> **EXAMPLES** <code>

	GET /api/v1/netrom/nodes/g8pzt
	GET /api/v1/netrom/routes?port=3
	GET /api/v1/netrom/routes?port=4&options=255

        Example Response for /api/v1/netrom/routes:

          [
            {
              "id": 1,
              "port": 4,
              "call": "G8PZT",
              "qual": 10,
              "sntt": 0.03,
              "lock": false,
              "state": "open",
              "nodes": 66
            },
            {
              "id": 2,
              "port": 6,
              "call": "G8PZT-14",
              "qual": 10,
              "sntt": 0.60,
              "lock": false,
              "state": "open",
              "nodes": 2
            }
          ]

        Example Response for /api/v1/netrom/nodes

          [
            {
              "id": "SP2L-14",
              "alias": "2LJNOS"
            },
            {
              "id": "ZL2AQY-2",
              "alias": "AQYNOD"
            },
            {
              "id": "N2NOV-7",
              "alias": "ARECS"
            },
            {
              "id": "MB7NBA",
              "alias": "BAMPTN"
            }
          ]


        Example Response for /api/v1/netrom/node/g8pzt:

          {
            "id": "G8PZT",
            "alias": "KIDDER",
            "qual": 10,
            "rtt": "0.12",
            "hops": "1",
            "frames": 61,
            "queue": 0,
            "position": "5224.00N 00215.00W",
            "locator": "IO82VJ",
            "qth": "Kidderminster, Worcestershire, U",
            "ipaddr": "44.136.16.50/32",
            "tcp": 23,
            "software": "XRPi",
            "version": "503d"
          }

        Example Response for /api/v1/netrom/circuits:

          [
            {
              "remote": "G8PZT-8@G8PZT-8:0eaa",
              "local": "G8PZT-9:0001",
              "direction": "incoming",
              "state": 2,
              "txq": 0,
              "rxq": 0,
              "rtt": 91,
              "tries": 0,
              "timeout": 120,
              "conTmr": 121,
              "chkTmr": 0,
              "ackTmr": 0,
              "remBusy": false
            },
            {
              "remote": "VK2DOT-1@VK2DOT-1:0167",
              "local": "G8PZT-4:0002",
              "direction": "incoming",
              "state": 2,
              "txq": 0,
              "rxq": 0,
              "rtt": 0,
              "tries": 0,
              "timeout": 120,
              "conTmr": 120,
              "chkTmr": 0,
              "ackTmr": 0,
              "remBusy": false
            }
          ]


</code> **Routes with all options** <code>

[
{
"id": 1,
"port": 6,
"call": "G8ASO-7",
"qual": 180,
"sntt": 0.00,
"lock": true,
"state": "failed",
"nodes": 0,
"maxframe": 3,
"frack": 7000,
"paclen": 256,
"maxtt": 5000,
"thrmaxtt": 10000,
"maxhops": 30,
"flags": 1,
"thrsntt": 0.00,
"inpnodes": 1,
"sent": 0,
"resent": 0,
"rtyave": 0,
"rtynow": 0.00,
"rtymax": 0.00,
"uptime": 4.4,
"txmean": 0,
"txbest": 0,
"txpeak": 0,
"loadave": 0,
"qualave": 0,
"qualmin": 0,
"qualmax": 0,
"qualdev": 0
},
{
"id": 2,
"port": 4,
"call": "G8PZT",
"qual": 10,
"sntt": 0.03,
"lock": false,
"state": "open",
"nodes": 73,
"maxframe": 3,
"frack": 7000,
"paclen": 256,
"maxtt": 5000,
"thrmaxtt": 5000,
"maxhops": 30,
"flags": 14,
"thrsntt": 0.18,
"inpnodes": 1,
"sent": 91,
"resent": 0,
"rtyave": 0,
"rtynow": 0.00,
"rtymax": 0.00,
"uptime": 98.1,
"txmean": 328,
"txbest": 2034,
"txpeak": 2034,
"loadave": 21,
"qualave": 252,
"qualmin": 252,
"qualmax": 252,
"qualdev": 0,
"bcast-rcvd": 1710514580,
"last-heard": 1710515203
}
]

</code> **SEE ALSO:** \\
[[packet:xrouter:docs:MAN#|        ]] \\

[[packet:xrouter:docs:|< Back to Index]]

----
===== REST-PMS =====
<code>REST-PMS(9)             XROUTER REFERENCE MANUAL             23/3/2024

</code> **NAME** <code>
        REST-PMS -- REST Interface to Personal Message System.

</code> **DESCRIPTION** <code>
        The PMS may be operated via a REST interface, e.g.
        using a "curl" command.

        The request type is either GET (to request data from the
        PMS) or POST (to write data to the PMS). For POST, the
        "Content-Type:" header must be "application/json", and
        the payload must be in JSON format.

        This facility is incomplete. The currently available
        functionality is documented in the next section.

</code> **OPTIONS** <code>
        a) Retrieve List of Messages:
        ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

        Request-Type: GET
        Request-URL:  api/v1/mail/msgs
        URL Options:  offset   - from "start" of list, default 0
                      maxitems - default 500
                      to       - callsign or category
                      at       - Distribution, e,g GBR
                      from     - Sender's callsign
                      subject  - string to match in subject
                      fwd/rvs? - to be added?

        If successful, the response is an un-named JSON array of
        objects, each object containing the following fields:

        Name          Type      Description
        -----------------------------------------------------------
        "id"          integer   Message number.
        "mid"         string    Message ID (MID or BID)
        "rcvd"        integer   Date/time of message reception (*1).
        "size"        integer   Length of the message body in bytes.
        "type"        string    Type of message: (A, P, B, E, T etc)
        "status"      string    Message status: (R, F, U etc) (*2)
        "to"          string    Destination address (*3)
        "from"        string    Callsign of the message's creator.
        "subject"     string    Message subject (32 chars max)
        "links"       object    Contains link to read the message (*4)

        (*1) in Unix time, i.e seconds since 1st Jan 1970 UTC
        (*2) type and status may in future be unambiguous words
        (*3) e.g. "g8pzt", "all@gbr", "g8pzt@gb7pzt.#24.gbr.eu"
        (*4) e.g. {"view": "/api/v1/mail/msgs/803"}

        Note that messages are listed in REVERSE order, i.e. most
        recent first.

        b) Retrieve a Message:
        ~~~~~~~~~~~~~~~~~~~~~~

        Request-Type: GET
        Request-URL:  api/v1/mail/msgs/{msg-number}
        Example:      http://localhost:80/api/v1/mail/msgs/21

        The response payload is an un-named JSON object containing
        the following fields:

        Name          Type      Description
        -----------------------------------------------------------
        "id"          integer   Message number.
        "mid"         string    Message ID (MID or BID)
        "rcvd"        integer    Date/time of message reception (*1).
        "size"        integer   Length of the message body in bytes.
        "type"        string    Type of message: (A, P, B, E, T etc)
        "status"      string    Message status: (R, F, U etc) (*2)
        "to"          string    Destination address (*3)
        "from"        string    Callsign of the message's creator.
        "subject"     string    Message subject (32 chars max)
        "text"        string    Body of the message (*4)

        (*1) in Unix time, i.e seconds since 1st Jan 1970 UTC
        (*2) type and status may in future be unambiguous words
        (*3) e.g. "g8pzt", "all@gbr", "g8pzt@gb7pzt.#24.gbr.eu"
        (*4) Message body includes all RFC822 and routing headers


        c) Post a Message:
        ~~~~~~~~~~~~~~~~~~

        Request-Type: POST
        Request-URL:  /api/v1/mail/msgs

        The payload must be a JSON object containing the following
        fields:

        Name          Type      Description
        -----------------------------------------------------------
        "from"        string    Callsign of sender
        "to"          string    Destination (see below)
        "type"        string    Only "P" or "B" at present
        "subject"     string    Subject of message (32 chars max)
        "text"        string    Body of the message

        For private messages the destination may be just a callsign,
        or <callsign>@<hierarchical-address>. For bulletins it may
        be simply <topic> or <topic>@<distribution>. For email it is
        <user>@<host>.

        The response is a JSON object containing the number of the
        newly created post, for example: {"id": 22}

</code> **EXAMPLE** <code>
        curl -X POST http://localhost:80/api/v1/mail/msgs \
        -H "Content-Type: application/json" -d '{\
        "from": "G8PZT", "to": "all@gbr", \
        "type": "B",
        "subject": "XRouter 503 coming soon", \
        "text": "New XRouter expected to be completed by Xmas"}' 

</code> **LIMITATIONS** <code>
        The PMS's REST interface is only a proof-of-concept at this
        stage, and some details may change. More functionality will
        be added in a future version

</code> **SEE ALSO:** \\
[[packet:xrouter:docs:MAN1#PMS|        PMS(1)      -- Access Personal Message System.]] \\
[[packet:xrouter:docs:MAN9#MQTT-PMS|        MQTT-PMS(9) -- MQTT Interface to PMS.]] \\
[[packet:xrouter:docs:MAN9#PMS|        PMS(9)      -- About the Personal Mesaage System]] \\

[[packet:xrouter:docs:|< Back to Index]]

----
===== REST-WALL =====
<code>REST-WALL(9)            XROUTER REFERENCE MANUAL             26/9/2023

</code> **NAME** <code>
        REST-WALL -- REST Interface to Message Wall.

</code> **DESCRIPTION** <code>
        The message wall may be operated via a REST interface, e.g.
        using a "curl" command.

        The request type is either GET (to request data from the
        wall) or POST (to write data to the wall). For POST, the
        "Content-Type:" header MUST be "application/json", and
        the payload MUST be in JSON format.

        This facility is incomplete. The curently available
        functionality is documented in the next section.

</code> **OPTIONS** <code>
        a) Obtain List of Wall Posts:
        ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

        Request-Type: GET
        Request-URL:  /api/v1/wall/posts

        If successful, the response is an un-named JSON array of
        objects, each objct containing the following fields:

        Name          Type      Description
        -----------------------------------------------------------
        "id"          integer   Article/post number.
        "rcvd"        string    Date/time of message creation (*).
        "size"        integer   Length of the text portion in bytes.
        "from"        string    Callsign of the post's creator.
        "text"        string    Body of the post (plain ASCII)

        (*) in format "1997-09-14T23:47:00Z"

        b) Retrieve a Wall Post:
        ~~~~~~~~~~~~~~~~~~~~~~~~

        Request-Type: GET
        Request-URL:  api/v1/wall/posts/{post-number}
        Example:      http://localhost:80/api/v1/wall/posts/17

        The response payload is an un-named JSON object containing
        the following fields:

        Name          Type      Description
        -----------------------------------------------------------
        "id"          integer   Article/post number.
        "rcvd"        string    Date/time of message creation (*).
        "size"        integer   Length of the text in bytes.
        "from"        string    Callsign of the post's creator.
        "text"        string    Body of the post (plain ASCII)

        (*) in format "Mon, 14 Sep 1997 23:47:00 GMT"


        c) Post a Wall Message / Reply:
        ~~~~~~~~~~~~~~~~~~~~~~~~~~~~

        Request-Type: POST
        Request-URL:  /api/v1/wall/posts

        The payload must be a JSON object containing the following
        fields:

        Name          Type      Description
        -----------------------------------------------------------
        "sender"      string    Callsign of sender
        "text"        string    Body of the post (unlimited size)

        The response is a JSON object containing the number of the
        newly created post, for example: {"id": 22}

</code> **LIMITATIONS** <code>
        The wall's REST interface is only a proof-of-concept at this
        stage. It does not yet allow article deletion, "liking" of
        articles, or retrieval of replies. Those functions will be
        added in a future version

</code> **SEE ALSO:** \\
[[packet:xrouter:docs:MAN1#WALL|        WALL(1)      -- Access Message Wall / Guestbook.]] \\
[[packet:xrouter:docs:MAN7#WALLFLAGS|        WALLFLAGS(7) -- Options For Message Wall.]] \\
[[packet:xrouter:docs:MAN9#MQTT-WALL|        MQTT-WALL(9) -- MQTT Interface to Wall.]] \\
[[packet:xrouter:docs:MAN9#MQTT-SRV|        MQTT-SRV(9)  -- MQTT Server / Broker.]] \\

[[packet:xrouter:docs:|< Back to Index]]

----
===== REST-WX =====
<code>REST-WX(9)              XROUTER REFERENCE MANUAL             14/3/2024

</code> **NAME** <code>
        REST-WX -- REST Interface to Weather System.

</code> **DESCRIPTION** <code>
        Weather data stored on XRouter can be retrieved using the
        REST API.

        Requests are made using HTTP, and the data is returned in
        JSON (JavaScript Object Notation) format.

        The base URL for such interactions is "/api/v1/weather".

        Only HTTP "GET" requests are currently supported by the
        weather API.

</code> **OPTIONS** <code>
        a) Retrieve List of Weather Stations:

           Request-Type: GET
           Request-URL:  /api/v1/weather/stations

        b) Retrieve Weather Data From a Specific Station

           Request-Type: GET
           Request-URL:  /api/v1/weather/stations/{id}

           {id} is a station identifier, usually callsign, or LOCAL
           for observations entered into the node from a local sensor.


</code> **RETURN VALUES** <code>
        If successful, the HTTP response code is 200 and the payload
        contains the response in JSON format, as detailed below:

        For Stations List:

        The response is an anonymous JSON array of objects, each object
        containing the following fields:

        Name          Type      Description
        -----------------------------------------------------------
        "id"         string   Station id, e.g. "G8PZT" or "LOCAL"
        "lat_deg"    number   Latitude of wx station in degrees
        "lon_deg"    number   Longitude of wx station in degrees
        "dist_km"    number   Distance from our node in kilometers
        "dir_deg"    number   Direction from our node in degrees
        "dt":        integer  Observation time, in secs since 1/1/70

        For a Specific Station:

        The response is an anonymous JSON object, containing the above
        fields plus some of all of the following weaher data:

        Name             Type     Description
        -----------------------------------------------------------
        "observed"       string  Date and time of observation (*1)
        "pressure_mb"    number  Air pressure in millibars
        "temperature_C"  number  Air temperature in degrees C
        "humidity"       number  Relative Humidity in percent
        "dewpoint_C"     number  Dew point in degrees Centigrade
        "heat_index_C"   number  Heat index in deg Centigrade
        "wind_chill_C"   number  Wind Chill in degrees Centigrade
        "wind_mph"       number  Wind speed in miles per hour
        "wind_dir_deg"   number  Wind direction in degrees
        "gust_mph"       number  Wind gust speed in miles per hour
        "raintoday_mm"   number  Total rain since midnight in mm
        "rain1h_mm"      number  Current rainfall rate mm/hour
        "rain24h_mm"     number  Total rain in past 24 hours in mm
        "sunrise"        string  Sunrise time at the station hh:mm
        "sunset"         string  Sunset time at the station hh:mm
        "daylight_hours" number  Hours between sunrise and set

	(*1) As "dt" but human-readable e.g. 2024-03-14T15:19:59Z

        For Local Sensor Only:

        If there is a local weather sensor feeding XRouter, the
        response containing the above fields plus some or all of the
        following extra data, depending on the capabilities of the
        sensor:

        Name             Type      Description
        -----------------------------------------------------------
        "rain_max_mm_hr"   number  Maximum rain rate today mm/hour
        "press_max_mb"     number  Maximum air pressure today 
        "press_min_mb"     number  Minimum air pressure today
        "temp_max_C"       number  Maximum temperature today
        "temp_min_C"       number  Minimum temperature today
        "humid_max"        number  Maximum humidity today
        "humid_min"        number  Minimum humidity today
        "wind_ave_mph"     number  Moving average wind speed
        "wind_max_mph"     number  Maximum wind speed totay
        "gust_max_mph"     number  Maximum gust speed today
        "wind_dir_ave_deg" number  Moving average wind direction
        "wind_run_miles"   number  Total wind run today, in miles
        "light_w_sqm"      number  Current light level, watts/sq m
        "light_max_w_sqm"  number  Maximum temperature today
        "UV_index"         number  Current UV index
        "UV_index_max"     number  Maximum UV index today

              ("today" means since midnight GMT)

</code> **ERROR CODES** <code>
        400 Bad Request         Invalid resource specifier
        404 Not Found           Specified API not found
        415 Unsupported Media   POST data was not JSON
        500 No Resources        No memory, try again later

</code> **EXAMPLES** <code>
        a) Stations List:

          [
            {
              "id": "LOCAL",
              "lat_deg": 50.0935,
              "lon_deg": -5.0850,
              "dist_km": 0,
              "dir_deg": 0,
              "dt": 1710395654
            },
            {
              "id": "G8PZT",
              "lat_deg": 52.2400,
              "lon_deg": -2.1500,
              "dist_km": 0,
              "dir_deg": 0,
              "dt": 1710394799
            }
          ]

        b) Specific Station:

          {
            "id": "G8PZT",
            "lat_deg": 52.2400,
            "lon_deg": -2.1500,
            "dist_km": 0,
            "dir_deg": 0,
            "dt": 1710425999,
            "observed": "2024-03-14T15:19:59Z",
            "temperature_C": 13.3,
            "humidity": 51,
            "dewpoint_C": 3.5
            "wind_mph": 0.0,
            "wind_dir_deg": 202,
            "gust_mph": 1.0,
            "sunrise": "07:25",
            "sunset": "19:12",
            "daylight_hours": 11.78
          }

       c) Local Weather

          {
            "id": "LOCAL",
            "lat_deg": 50.0875,
            "lon_deg": -5.075,
            "dist_km": 0,
            "dir_deg": 0,
            "dt": 1710395899,
            "observed": "2024-03-14T06:58:19Z",
            "pressure_mb": 1006,
            "temperature_C": 10.9,
            "humidity": 94,
            "wind_mph": 16.6,
            "wind_dir_deg": 147,
            "gust_mph": 20.6,
            "rain_max_mm_hr": 0,
            "press_max_mb": 1010.1,
            "press_min_mb": 1005.9,
            "temp_max_C": 11,
            "temp_min_C": 10.6,
            "humid_max": 95,
            "humid_min": 94,
            "dewpoint_C": 9.7,
            "wind_ave_mph": 11.6,
            "wind_max_mph": 23.3,
            "gust_max_mph": 34.4,
            "wind_dir_ave_deg": 139,
            "wind_run_miles": 58.2,
            "light_w_sqm": 0,
            "light_max_w_sqm": 0,
            "UV_index": 0,
            "UV_index_max": 0,
            "sunrise": "07:35",
            "sunset": "19:25",
            "daylight_hours": 11.83
          }

</code> **SEE ALSO:** \\
[[packet:xrouter:docs:MAN1#WX|        WX(1)     -- Display Weather Information.]] \\
[[packet:xrouter:docs:MAN7#WXFILE|        WXFILE(7) -- Weather Import File.]] \\
[[packet:xrouter:docs:MAN9#WX|        WX(9)     -- Weather Information System.]] \\
[[packet:xrouter:docs:MAN9#WX-SVC|        WX-SVC(9) -- NetRomX Weather Service]] \\
[[packet:xrouter:docs:MAN#|        ]] \\

[[packet:xrouter:docs:|< Back to Index]]

----
===== RIP =====
<code>RIP(9)                  XROUTER REFERENCE MANUAL            18/10/2023
</code> **NAME** <code>
        RIP -- Routing Information Protocol.

</code> **DESCRIPTION** <code>
        Routing Information Protocol (RIP) allows IP routers to learn
        about each other's routing, similar to the way that NetRom
        exchanges nodes broadcasts.

        There are various versions of RIP, and XRouter currently
        implements RIP2 and RIP98. RIP2 is used for the IPEncap-based
        "44-net" network, and RIP98 was developed by G8BPQ specically
        for radio-based routers.  If there is a need for other
        flavours of RIP, they may be included in a later version.

        RIP98 works by sending its routing table to nominated peers
        at regular intervals, and accepting routing information from
        peers.  The routes learned by this means are added as
        temporary entries to the IP routing table.  These entries
        have a finite lifetime, and if not updated regularly they
        drop out of the routing table.

        Configuring XRouter to use RIP98
        ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

        The following configuration commands are available:

              RIP ACCEPT      Remove a peer from the refuse list.
              RIP ADD         Add a peer to the broadcast list. (*)
              RIP DROP        Remove a peer from the broadcast list.
              RIP LEARN       Allow / disallow route learning. (*)
              RIP REFUSE      Ignore broadcasts from a peer. (*)
              RIP STATUS      Show status of RIP.
              RIP TIMEOUT     Specify lifetime of learned routes. (*)

        Commands marked (*) may be used in BOOTCMDS.SYS or
        IPROUTE.SYS to configure the system automatically.

        By default, RIP98 route learning is OFF, so you need to
        include at least a "RIP LEARN ON" command, to enable your
        system to learn routes from others.  Your neighbours also
        need to add your IP address to their RIP broadcast lists.

        If you wish to inform your neighbours of your existence and
        your routing capabilities, you need some RIP ADD commands,
        one for each neighbour to whom you wish to send RIP updates.

        If you have LEARN enabled, and there is a neighbour who is
        sending unwanted RIP updates to you, you may ignore them
        using RIP REFUSE.

        The RIP commands are explained in more detail in section 1 of
        this manual.

</code> **SEE ALSO:** \\
[[packet:xrouter:docs:MAN1#RIP|        RIP(1) -- Routing Interface Protocol Commands.
]] \\

[[packet:xrouter:docs:|< Back to Index]]

----
===== RLOGIN =====
<code>RLOGIN(9)               XROUTER REFERENCE MANUAL            21/10/2023
</code> **NAME** <code>
        RLOGIN -- Remote Login.

</code> **DESCRIPTION** <code>
        RLOGIN is a "remote login" facility for sysops only.

        The secure password challenge/response mechanism, using
        the "@" command, is inconvenient for frequent use, and
        unnecessary in cases where the remote sysop can access
        the router via a "secure" link such as a wire link between
        two systems.  RLOGIN provides a connection with a plain
        text password system for these situations.

        RLOGIN uses a Telnet connection to TCP port 513. This
        port may be moved or disabled using the RLOGINPORT
        directive in XROUTER.CFG if required.

        Upon connection, the sysop is prompted to enter his
        callsign, and is then asked for his password.  If the
        two match with an entry in PASSWORD.SYS, the sysop is
        granted access with full sysop status.

</code> **FILES** <code>
        The following files affect the operation of RLOGIN. They
        must be located in the same directory as the XRouter program:

        PASSWORD.SYS is where the sysops' passwords are stored.
        XROUTER.CFG is where RLOGINPORT is specified.

</code> **CAVEATS** <code>
        Needless to say, this facility should *NEVER* be used
        over a radio link, otherwise someone will see the
        password.

        Connections to the RLOGIN service are not considered secure
        if they are via 44-net, because the packets may have
        travelled across RF, or via another Amateur's system. In
        that case, certain functions, such as the NFTP client are
        not allowed.

</code> **SEE ALSO:** \\
[[packet:xrouter:docs:MAN8#PASSWORD.SYS|        PASSWORD.SYS(8) -- Sysop Password File.
]] \\
[[packet:xrouter:docs:MAN7#RLOGINPORT|        RLOGINPORT(7)   -- TCP Port for RLOGIN.
]] \\
[[packet:xrouter:docs:MAN8#XROUTER.CFG|        XROUTER.CFG(8)  -- Main Configuration File.
]] \\

[[packet:xrouter:docs:|< Back to Index]]

----
===== SCRIPT =====
<code>SCRIPT(9)               XROUTER REFERENCE MANUAL            17/10/2023
</code> **NAME** <code>
        SCRIPT -- Dialer Scripts

</code> **DESCRIPTION** <code>
        Assuming you have a port configured for modem use, DUN
        requires at least one dialler script, to control the dial and
        login sequence.

        Dialler scripts are ordinary text files containing script
        commands as detailed below, one per line.  Lines must not
        exceed 256 characters in length.  The script file can be named
        as you wish, for example you might like to name your AOL dial
        script "AOL.SCR".  You will need to use this name later to
        identify the script, so it makes sense to call it something
        meaningful, rather than "SCRIPT1.TXT".  Script files must
        reside in the same directory as the XRouter executable.

        DUN Script Commands Overview
        ~~~~~~~~~~~~~~~~~~~~~~~~~~~~

              CONTROL    Raise / lower RS232 DTR signal.
              MODE       Protocol to use upon successful login.
              PPP        PPP configuration commands.
              SEND       Send text.
              SLEEP      Temporary pause.
              WAIT       Wait for text in received data.


        DUN Script Commands In Detail
        ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

        CONTROL - Raise / Lower RS232 DTR signal.

                Syntax: C[ontrol] <up | down>

                The CONTROL command is used to raise or lower the
                RS232 DTR (Data Terminal Ready) line.  Most modems
                require the DTR signal to be "up", and will disconnect
                or reset when it goes down.  Those modems which do not
                do this by default can usually be configured to do so
                by including "&D2" in the initialisation string.


        MODE  - Set protocol to use upon successful login.

                Syntax:  M[ode] <kiss | ppp | slip>
                Example: MODE PPP

                MODE specifies the protocol to use after your system
                has logged into the remote host, i.e. when the script
                ends without error.  It must precede the dialling and
                login sequence, and any protocol dependent commands,
                such as the PPP commands.


        PPP   - PPP configuration commands.

                Syntax:  P[pp] <idle | ipcp | lcp | log | pap> [arg]
                Example: PPP IDLE 300

                PPP commands are used to configure the PPP subsystem
                for the connection being established.  Note that
                within DUN scripts the <port> argument is omitted
                because XRouter knows which port the script is using.


        SEND  - Send a line of text.

                Syntax:  S[end] <text>
                Example: SEND ATDT01674302153

                The SEND command sends one line of text to the modem
                or the remote host, for example modem initialisation
                and dial commands, or login commands.  The <text>
                argument may contain spaces, and the system will
                append a carriage return/line feed.


        SLEEP - Temporary pause.

                Syntax: SL[eep] <millisecs>
                Example: SLEEP 5000

                The SLEEP command causes the script to pause for the
                specified interval.  For example, you would need a
                short delay after issuing a modem reset command
                before any more commands would be accepted by the
                modem.  When the pause is complete, script execution
                continues on the next line.


        WAIT  - Wait for received text.

                Syntax: W[ait] <millisecs> <string> [exiterr]
                Example: WAIT 5000 Password: exiterr

                WAIT causes XRouter to wait for specific responses
                from the modem or remote host.  <millisecs> specifies
                the maximum wait interval.  <string> specifies the
                string of characters (20 chars max, no spaces) to wait
                for.

                When the string is seen in the received data stream,
                the next script command is executed.

                If "exiterr" is present, the script will abort if the
                string is not seen before the interval expires.  If
                not present, the next script command will be executed
                upon timeout.


        Dial up networking may be administered "on the fly" using the
        DUN command , which is detailed in the sysop command reference
        section. The DUN ADD and DUN LOG commands may also be used in
        IPROUTE.SYS and / or BOOTCMDS.SYS to configure the system at
        boot time.


        Example DUN script
        ~~~~~~~~~~~~~~~~~~

        ; Xrouter DUN script for establishing PPP connection with ISP
        ;
        ; Upon connection, the ISP sends some greetings text, then
        ;   "Login:", and waits for login name.
        ;
        ; Upon receiving the login name it sends "Password:" and
        ;   waits for the caller to send the password.
        ;
        ; Upon receiving the password, the ISP sends
        ;   "Entering PPP mode".
        ;
        ;
        ; Drop DTR to reset any modem error condition
        control down
        ;
        ; Wait for 1 sec
        sleep 1000
        ;
        ; Raise DTR to allow normal operation
        control up
        ;
        ; Specify the mode to use after link is established
        mode ppp
        ;
        ; ISP requires PAP authentication: username=gb7pzt,
        ;   password=bsfjflavs
        ppp pap user gb7pzt bsfjflavs
        ;
        ; Get the modem's attention
        send AT
        ;
        ; Wait for up to 5 secs for an "OK" response.  Abort if none
        wait 5000 OK exiterr
        ;
        ; Modem is awake.  Dial the ISP
        send ATDT01905643000
        ;
        ; Wait for up to 1 minute for the "user:" login prompt
        wait 60000 user exiterr
        ;
        ; Prompt obtained. Send username
        send gb7pzt
        ;
        ; Don't bother waiting for "password:" prompt, just send
        ;   it after 1 sec.
        sleep 1000
        send bsfjflavs
        ;
        ; Wait for confirmation of entry to PPP mode
        wait 30000 PPP exiterr
        ;
        ; ISP is now in PPP mode.  XRouter will enter PPP mode when
        ;   script ends
        ;

</code> **SEE ALSO:** \\
[[packet:xrouter:docs:MAN1#DIAL|        DIAL(1) -- Dialer
]] \\
[[packet:xrouter:docs:MAN1#DUN|        DUN(1) -- Dial Up Networking commands
]] \\
[[packet:xrouter:docs:MAN9#DUN|        DUN(9) -- Dial Up Networking
]] \\

[[packet:xrouter:docs:|< Back to Index]]

----
===== SERVERS =====
<code>SERVERS(9)             XROUTER REFERENCE MANUAL             21/10/2023
</code> **NAME** <code>
        SERVERS -- Servers Available in XRouter.

</code> **DESCRIPTION** <code>
        In the XRouter context, servers are processes which accept
        connections or data from users (i.e. clients) and provide
        specific services (e.g. file transfer) to those clients.

        They are often associated with a specific TCP or UDP "service
        port" number, for example TCP port 21 for file transfer, UDP
        port 53 for DNS server and so on.

        XRouter contains a number of servers and makes them available
        by default, although they may be disabled by the sysop if
        desired.

        The policy of making services available by default is an
        attempt to provide useful services to the Amateur Radio
        Packet Network (amprnet) with minimal effort on the part of
        the sysop. If services were disabled by default, most sysops
        wouldn't enable them, either because they didn't understand
        them, or because they couldn't be bothered.

        Access to the benign servers is unrestricted, but most are
        protected by password and IP access control lists.

        The following servers are available in XRouter

        Name     Port   Proto   Function
        ---------------------------------------------------
        ECHO        7   TCP     Echoes data back
        DISCARD     9   TCP     Discards data
        FTP        21   TCP     File Transfer
        TELNET     23   TCP     User session
        DNS        53   UDP     Domain Name System
        FINGER     79   TCP     User information
        HTTP       80   TCP     Web server
        TTYLINK    87   TCP     Keyboard to Keyboard chat
        RLOGIN    513   TCP     Remote Login (sysop)
        SOCKS    1080   TCP     SOCKS Proxy
        APRS     1448   TCP     Serves APRS data
        MQTT     1883   TCP     Message Queue Telemetry Transport
        TELPROXY 2323   TCP     Raw TCP to AX25 bridge
        CHAT     3600   TCP     Conferencing
        AGWHOST  8000   TCP     AGW Packet Engine emulator
        RHP      9000   TCP     Remote application support
        HAMLIB      -   TCP     HamLib Emulator
        RIGSRV      -   TCP     Radio control server
        PMS         -     -     Personal Mail Server

        For details of how to move the above ports or disable the
        servers, please see the TCP-PORTS page.


        Brief Overview Of XRouter Servers
        =================================

        ECHO
        ~~~~
        Anything the user sends is echoed back to him.  This is a
        useful tool for test purposes. This server is also available
        from the command prompt, and as NetRomX service 7.


        DISCARD
        ~~~~~~~
        This simply dumps anything sent to it.  It is another useful
        tool for test purposes. This server is also available from the
        command prompt, and as NetRomX service 9.


        FTP
        ~~~
        Allows sysops to upload, download, move and rename files,
        create and remove directories etc. Not available to users.


        TELNET
        ~~~~~~
        Provides regular user access to the XRouter command prompt.
        Also available as NetRomX service 23.


        DNS
        ~~~
        Answers Domain Name System (DNS) queries, to provide a
        hostname to IP-address translation service. 


        FINGER
        ~~~~~~
        Allows users to retrieve information about other users or any
        other topics provided by the sysop. This server is also
        available from the command prompt, and as NetRomX service 79.


        HTTP
        ~~~~
        Serves HTML (web) pages, and provides a browser interface to
        XRouter. Can be made available on both XRouter and host
        system TCP stacks, plus NetRomX service 80.


        TTYLINK
        ~~~~~~~
        For direct keyboard to keyboard chat. Als avaiable on NetRomX
        service 79.


        RLOGIN
        ~~~~~~
        Secure remote login for sysops only, providing full syop-mode
        access.


        SOCKS Proxy
        ~~~~~~~~~~~
        Circuit level proxy allowing applications to access external
        services through a firewall as an alternative to NAT.


        APRS
        ~~~~
        Shares APRS data between clients such as UI-View, RF ports
        and the Internet APRS-IS systems. Can be made avaiable on
        both XRouter and host TCP stack, plus NetRomX service 14. 


        MQTT
        ~~~~
        Machine to machine information broker using a publish /
        subscribe paradigm. Allows sending and receiving of raw KISS,
        AX25, NetRom, XRChat etc, plus status / event information.
        Can be used to develop modern user interfaces.  Available on
        Linux TCP stack only. Also available, with restrictions, via
        NetRomx service 1883.


        TELPROXY
        ~~~~~~~~
        The Telnet Proxy server allows TCP/IP applications to make
        fully transparent raw binary connections (i.e. ones capable of
        handling compressed forwarding) to AX25 or NetRom
        destinations.


        CHAT
        ~~~~
        Allows groups of users to hold conferences, either locally or
        globally via a network of interconnected servers. Also on 
        NetRomX service 8.


        AGWHOST
        ~~~~~~~
        Emulates the AGW TCP host interface, enabling XRouter to
        support applications (e.g. UI-View) that were designed for
        use with the AGW Packet Engine.


        RHP
        ~~~
        Allows XRouter to support a wide range of applications which
        may be located on the same PC or remotely, using a
        socket-like paradigm.


        PMS
        ~~~
        A no-frills mailbox which can handle both private mail and
        bulletins. It is available from AX25 and the XRouter command
        prompt, but currently has no TCP port of its own. Available
        as NetRomX service 2.


        HAMLIB
        ~~~~~~
        Emulates the HamLib rig control interface, for use with
        applications that are designed to use Hamlib.  Available
        only on Linux TCP/IP stack.  Useful only when XRouter is
        controlling rigs.


        RIGSRV
        ~~~~~~
        Another radio control interface (private project).
        Available only on Linux TCP/IP stack.  Useful only when
        XRouter is controlling rigs.

</code> **SEE ALSO:** \\
[[packet:xrouter:docs:MAN9#CHAT-SRV|        CHAT-SRV(9)   -- Chat Server
]] \\
[[packet:xrouter:docs:MAN1#DISCARD|        DISCARD(1)    -- Start a Sink Session
]] \\
[[packet:xrouter:docs:MAN1#ECHO|        ECHO(1)       -- Start an Echo Session
]] \\
[[packet:xrouter:docs:MAN1#FINGER|        FINGER(1)     -- Display User Information
]] \\
[[packet:xrouter:docs:MAN6#TCP-PORTS|        TCP-PORTS(6)  -- TCP Server Ports
]] \\

[[packet:xrouter:docs:|< Back to Index]]

----
===== SERVICES =====
<code>SERVICES(9)            XROUTER REFERENCE MANUAL             22/10/2023
</code> **NAME** <code>
        SERVICES -- NetRomX Standard Services.

</code> **DESCRIPTION** <code>
        G8PZT extended NetRom at the turn of the century to create
        "NetRomX". This uses an alternative L4 connect request, with
        opcode 8, and the mnemonic "CREQX". This type of request
        includes a 16-bit "service number", and can therefore request
        connection to any of 65536 separate types of process on the
        target system.

        This is a major improvement over "standard" NetRom, which only
        allowed a node to host a maximum of 16 L4 services, one per
        SSID. This was not just a barrier to the development of novel
        services... In order to be connectable via L4, every such SSID
        had to be in everyone's nodes tables. And there was no
        agreement on which SSID should represent which service.

        With NetRomX there is no need to clutter the nodes tables with
        SSID's, because every service has a STANDARD number, as shown
        in the table below: 
 
        No.     Service   Description
        ------------------------------------------------------------
        0       CMD       Normal connection to Node's command line
        1       INFO      Standard Information server
        2       PMS       Personal Message System
        3       BBS       (reserved for Bulletin Board System)
        4       DX        (reserved for DX cluster/dx-spot feed)
        5       TPP       (reserved for "Tampa Ping-Pong" chat)
        7       ECHO      Echoes data back to sender
        8       CHAT      XRChat server 
        9       DISCARD   Data sink
        10      RMS       (reserved for winlink RMS}
        11      BPQCHAT   (reserved for BPQ chat server)
        13      DAYTIME   Local date/time (similar to RFC867)
        14      APRS      APRS Server
        15      CUSTINF   (reserved for custom information file server)
        16      WX        Local weather information
        17      TELEM     (reserved for Telemetry server)
        18      SMS       Short Message System server
        19      CHARGEN   Generates a test pattern
        20      NDATA     (reserved for NFTP extension)
        21      NFTP      Netrom File Transfer Protocol
        22      NSSH      (reserved for secure login - if legal?)
        23      TELNET    Normal L4 login (same as 0)
        25      SMTP      (reserved for Simple Mail Transfer Protocol)
        26      MHEARD    MHEARD server (shows MH lists)
        27      DXLIST    DX List server (shjows DX lists)
        79      FINGER    Finger server
        80      HTTP      NetromWeb (HTTP over Netrom) server
        87      NTTY      Netrom TTY - Keyboard to keyboard chat
        1883    MQTT      MQTT server

        If you know that the target system is XRouter (usually they
        have "XR" in the alias), you can be sure that if their PMS is
        enabled, it will be on service 2.

        Standard services facilitate simple commands such as
        "TIME <nodecall>", to discover the local time, time zone and
        daylight saving status at a distant node. Or "PMS <nodecall>"
        to connect directly to someone's PMS.

        It is envisaged that some of the services may be used by
        network crawlers (human and machine) to harvest data without
        needing to know the exact format of the commands on all the
        different types of software.

</code> **SEE ALSO:** \\
[[packet:xrouter:docs:MAN9#APRS-SVC|        APRS-SVC(9)  -- APRS Service.
]] \\
[[packet:xrouter:docs:MAN9#CHARGEN|        CHARGEN(9)   -- Character Generator Service.
]] \\
[[packet:xrouter:docs:MAN9#CHAT-SVC|        CHAT-SVC(9)  -- Chat Service.
]] \\
[[packet:xrouter:docs:MAN9#DAYT-SVC|        DAYT-SVC(9)  -- DAYTIME Service.
]] \\
[[packet:xrouter:docs:MAN9#DX-SVC|        DX-SVC(9)    -- DX Service
]] \\
[[packet:xrouter:docs:MAN9#DISC-SVC|        DISC-SVC(9)  -- Discard Service
]] \\
[[packet:xrouter:docs:MAN9#ECHO-SVC|        ECHO-SVC(9)  -- Echo Service.
]] \\
[[packet:xrouter:docs:MAN9#HTTP-SVC|        HTTP-SVC(9)  -- HTTP Service.
]] \\
[[packet:xrouter:docs:MAN9#INFO-SVC|        INFO-SVC(9)  -- Information Service.
]] \\
[[packet:xrouter:docs:MAN9#MH-SVC|        MH-SVC(9)    -- MHeard Service
]] \\
[[packet:xrouter:docs:MAN9#MQTT-SVC|        MQTT-SVC(9)  -- MQTT Service
]] \\
[[packet:xrouter:docs:MAN9#NFTP-SVC|        NFTP-SVC(9)  -- Netrom File Transfer Service.
]] \\
[[packet:xrouter:docs:MAN9#NTTY-SVC|        NTTY-SVC(9)  -- NetromTTY Service.
]] \\
[[packet:xrouter:docs:MAN9#PMS-SVC|        PMS-SVC(9)   -- Personal Message Service.
]] \\
[[packet:xrouter:docs:MAN9#SMS-SVC|        SMS-SVC(9)   -- Short Message Service
]] \\
[[packet:xrouter:docs:MAN6#TCP-PORTS|        TCP-PORTS(6) -- TCP Server Ports
]] \\
[[packet:xrouter:docs:MAN9#WX-SVC|        WX-SVC(9)    -- Weather Service.
]] \\

[[packet:xrouter:docs:|< Back to Index]]

----
===== SLIP =====
<code>SLIP(9)                 XROUTER REFERENCE MANUAL            19/10/2023
</code> **NAME** <code>
        SLIP -- Serial Line IP.

</code> **DESCRIPTION** <code>
        SLIP is a very simple protocol which encapsulates Internet
        Protocol (IP) datagrams for transmission over serial (e.g.
        RS232) lines. It is defined in RFC 1055.

        The SLIP protocol specifies the following special characters:

                Name  Hex   Dec  Purpose
                ---------------------------
                FEND  0xC0  192  Frame End
                FESC  0xDB  219  Frame Escape

        The FEND characters mark the start and end of the frame
        containing the encapsulated datagram as follows:

                .------.-------------.------.
                | FEND | IP Datagram | FEND |
                '------'-------------'------'

        In order to ensure that the FEND character only occurs at the
        start and end of the frame, FENDs which occur within the
        unencapsulated datagram are "escaped" to the two byte sequence
        FESC 220. Likewise FESC is escaped to the sequence FESC 221.

        It is permissible for two datagrams to share a FEND:

                .------.-------------.------.-------------.------.
                | FEND | IP Datagram | FEND | IP Datagram | FEND |
                '------'-------------'------'-------------'------'


        Serial Line Parameters
        ~~~~~~~~~~~~~~~~~~~~~~

        Serial lines used for SLIP must run at 8 data bits. Flow
        control must be hardware or none, as XON/XOFF flow control
        would interfere with the protocol.

        If flow control is used, the cable must contain at least 5
        cores, namely TXD, RXD, RTS, CTS and GND.  If flow control is
        not used, only TXD, RXD and GND are required.

        In all cases, a NULL MODEM is required. In the case of "real"
        RS232 this could be an actual null modem device, or a cable
        that is wired such that the TXDs at each end go to the RXDs
        at the other end, and the RTSs at each end go to the CTSs at
        the other.  "Virtual" COM port pairs such as Com0Com
        (Windows) or tty/pty pairs (Linux) include this functionality
        as standard.


        Configuring a SLIP Link
        ~~~~~~~~~~~~~~~~~~~~~~~

        SLIP can be used to link XRouter with other IP systems (e.g.
        NOS) via real or virtual COM ports. A typical configuration
        in XROUTER.CFG would be as follows:

                INTERFACE=13
                        TYPE=ASYNC     <-- Serial RS232
                        COM=13         <-- COM number / device	
                        PROTOCOL=SLIP  <-- Use SLIP
                        SPEED=38400    <-- Baud rate
                        FLOW=0         <-- No flow control
                        MTU=1500       <-- Allows largest IP
                ENDINTERFACE

                PORT=3
                        ID=SLIP Link to BBS
                        INTERFACENUM=13
                ENDPORT

        Unless overridden with a port IPADDRESS statement, the SLIP
        link will use XRouter's "core" IP address, i.e. the one
        specified by the global IPADDRESS. This is usually a 44-net
        address.

        Remember to set up an IP ROUTE entry for the neighbour system
        via this PORT number, e.g. if the neighbour's IP address is
        44.131.91.2, the following entry routes traffic to it via
        port 3 using datagram mode:

                IP ROUTE ADD 44.131.91.2  * 3  d

        Note that "virtual circuit" (v) and "netrom" (n) routing
        modes can not be used here.

        A SLIP link thus created does not involve the Windows or
        Linux IP stack in any way, therefore there is no restriction
        on the protocols that can be carried within the IP datagrams.

        For example you may create an AX25 link using AXIP, or tunnel
        traffic over the link using IPEncap. 

        SLIP was largely replaced by PPP long ago, but the beauty of
        it is its simplicity.  It is so easy to configure, and only
        requires a pair of COM ports and a 3 core cable.


        Temporary SLIP
        ~~~~~~~~~~~~~~

        A dial-in MODEM connection may be switched into SLIP mode for
        the remainder of the call using the "XLINK SLIP" command,
        thus emulating an old-fashioned dial-up ISP.

        This may possibly be of use for controlling remote sites that
        have telephone lines but no Internet connection.  Or even as
        a backup in case an Internet connection breaks down (cheap
        routers and switches fail!). See the manual entry for PSTN
        for more details.

</code> **SEE ALSO:** \\
[[packet:xrouter:docs:MAN1#IP|        IP(1)          -- IP Routing / Configuration Commands.
]] \\
[[packet:xrouter:docs:MAN8#IPROUTE.SYS|        IPROUTE.SYS(8) -- IP Configuration File.
]] \\
[[packet:xrouter:docs:MAN9#KISS|        KISS(9)        -- KISS Protocol.
]] \\
[[packet:xrouter:docs:MAN1#XLINK|        XLINK(1)       -- Establish a Temporary SLIP / PPP Interlink
]] \\
[[packet:xrouter:docs:MAN8#XROUTER.CFG|        XROUTER.CFG(8) -- Main Configuration File.
]] \\

[[packet:xrouter:docs:|< Back to Index]]

----
===== SMS-SVC =====
<code>SMS-SVC(9)              XROUTER REFERENCE MANUAL              7/9/2023
</code> **NAME** <code>
        SMS-SVC -- Short Messaging Service

</code> **DESCRIPTION** <code>
        This short messaging service is for XRouter sysops, and has
        nothing to do with telephone SMS. It uses NetRomX service
        number 18.

        The purpose of this service is to receive short, single-line
        messages (up to 160 characters), and to deliver them to the
        sysop.

        Although the protocol is plain text, it is intended for use
        by automatons, not humans.

        It is a one-way protocol. Nodes "push" messages to each
        other, by connecting to each other's SMS service. They
        cannot poll for mail.

        The protocol is not yet finalised. It works, but may need to
        be tweaked.

        Line endings conform to the "packet radio" standard, i.e.
        ASCII 13 (carriage return) only.

        Upon connection to the server, the client receives a greeting
        together with a "nonce" for authorisation purposes:

              G8PZT-1 SMS ready [34564287]

        The client must then respond with an authorisation string,
        calculated from the nonce:

              A 0xxxx<authstring>

        An invalid authorisation string, or any other response at
        this point results in disconnection. 0 is the version.

        Once authorised, there are only 3 possible commands, namely
        S, R and Q.

        The S command sends an SMS to the server:

              S <to> <from> <stamp> <text>

              <to> and <from> are callsigns
              <stamp> is the msg timestamp in secs since 1/1/70
              <text> is up to 160 characters of plain text.

        The R command sends a "read receipt" to the server,
        indicating that the recipient has read the message:

              R <to> <from> <stamp> <rstamp>

              <to> and <from> are callsigns
              <stamp> is the msg timestamp in secs since 1/1/70
              <rstamp> is the timestamp of when the message was read

        The client may send multiple S and R messages in one session.

        When the client is done, it sends Q (quit), and the server
        closes the connection.

        The sysop is alerted to the presence of an unread mesage by
        a flashing "S" on the top status bar. He can then type "SMS"
        to view the messages.

</code> **SEE ALSO:** \\
[[packet:xrouter:docs:MAN1#SMS|        SMS(1)      -- Short Messaging System for Sysops.]] \\
[[packet:xrouter:docs:MAN9#SERVICES|        SERVICES(9) -- NetRomX Standard Services.]] \\

[[packet:xrouter:docs:|< Back to Index]]

----
===== SOCKS =====
<code>SOCKS(9)                XROUTER REFERENCE MANUAL             27/9/2023

</code> **NAME** <code>
        SOCKS -- SOCKS Proxy Server.

</code> **DESCRIPTION** <code>
        The purpose of the SOCKS proxy server in XRouter is long
        forgotten.

        It was included in XRouter either to allow users on amprnet
        to view Internet web pages, or to allow a LAN browser to
        gain a 44.x.x.x source address, to view amprnet web sites.


        What is SOCKS?
        ~~~~~~~~~~~~~~
        SOCKet Secure (SOCKS) V4 is a protocol that acts as a circuit
        level proxy for applications, routing traffic between a client
        and server through a proxy server.  It was intended for
        accessing external services through a firewall, as an
        alternative to using NAT (Network Address Translaton).

        SOCKS5 is defined in RFC 1928, and is an extension of the
        SOCKS4 protocol.  It offers more choices of authentication,
        adds support for IPv6 and UDP that can be used for DNS
        lookups.

        XRouter implements both SOCKS V4 and V5. The implementation is
        functional but incomplete.


        How it Works
        ~~~~~~~~~~~~
        A SOCKS proxy acts as both client and server simultaneously.
        A user client makes a TCP connection to the the socks server,
        and communicates with it using the SOCKS protocol. The user
        instructs the SOCKS proxy to connect to the target server,
        from which point onwards the proxy becomes the client of the
        target server.

                                  .---------.
            .--------. 62.31.1.3  |  XRPi   | 44.131.91.1 .--------.
            | server |-----<------|  SOCKS  |-------<-----| client |
            '--------'            |  proxy  |             '--------'
            83.1.24.5             '---------'            44.131.91.2

        The above diagram depicts an amprnet client (44.131.91.2)
        connected to an Internet server (83.1.24.5) via a SOCKS proxy.
        On the amprnet side XRouter is using the amprnet address
        44.131.91.1, and on the Internet side it is using the Internet
        address 62.31.1.3.

        As far as the target server is concerned, it is talking with
        62.31.1.3, whilst the user client is connected to 44.131.91.1.
        Anything sent by the client is relayed to the server by the
        proxy and vice versa.


        Client Requirements
        ~~~~~~~~~~~~~~~~~~~
        Client programs for use with this proxy must have SOCKS client
        capability.  Programs such as Internet Explorer, Firefox, and
        many other have this capability.


        Access Control
        ~~~~~~~~~~~~~~
        The "rules" to control which destinations are allowed to be
        accessed via the SOCKS proxy are contained in the SOCKS.ACL
        file. 

        The rules allow you to specify which destination IP
        addresses and TCP ports may be accessed by specified
        source IP ranges.

        If the file is not present, or contains no valid rules, all
        destinations are blocked. Attempting to access a blocked
        destination causes the proxy to return an "access denied"
        code.


        Configuration
        ~~~~~~~~~~~~~
        The server is available by default, and requires no setting
        up, other than the IP routing and egress control.

        The server's TCP port may be changed, or the server disabled,
        by using the SOCKSPORT=n directive in XROUTER.CFG.  Setting
        the port to zero disables the server.

</code> **FILES** <code>
        SOCKS.ACL, XROUTER.CFG

</code> **SEE ALSO:** \\
[[packet:xrouter:docs:MAN8#ACCESS.SYS|        ACCESS.SYS(8)  -- TCP/IP Access Control List.
]] \\
[[packet:xrouter:docs:MAN9#NAT|        NAT(9)         -- Network Address Translation.
]] \\
[[packet:xrouter:docs:MAN8#SOCKS.ACL|        SOCKS.ACL(8)   -- SOCKS Egress Control List
]] \\
[[packet:xrouter:docs:MAN7#SOCKSPORT|        SOCKSPORT(7)   -- TCP Port for SOCKS Proxy.
]] \\
[[packet:xrouter:docs:MAN8#XROUTER.CFG|        XROUTER.CFG(8) -- Main Configuration File
]] \\

[[packet:xrouter:docs:|< Back to Index]]

----
===== STATS =====
<code>STATS(9)                XROUTER REFERENCE MANUAL              3/1/2024
</code> **NAME** <code>
        STATS -- Explanation of Output of STATS Command.

</code> **SYNOPSIS** <code>
        This document attempts to explain some of the responses
        produced by the "stats" command.

</code> **SUMMARY PAGE** <code>
        Entering S[tats] without arguments produces a single page
        containing the following fields (values removed to make the
        display fit the page):

            Time active (mins):
            Overruns:
            Memory blocks: Min/Cur/Max
            Nodes: Cur/Max/free/poss
            Total bytes sent/rcvd:
            Ccts/MaxCcts L2/L3/L4/TCP:

            HTTP Rqst/Srvd/Bytes/Prxyd

            IP Heard/Reasm/Rcvd/Routed:
            IP Bad Hdr/Chksum/Version:
            IP Sent/Frag/Unsent/Total:

            L4 Connects Tried/Made/Rcvd:
            L4 total frames Sent/Rcvd:

            L4 Info Snt/Rcvd/Resent/Reseq:
            L4 Choke Snt/Rxd RSET Snt/Rxd:
            L4 Timeouts/Failures: 
            L3 Frames Hrd/Rcvd/Sent/Rlyd:

        "Time active" is the elapsed time in minutes since XRouter
                was last restarted. Also shown are day, hours,
                minutes and seconds.

        "Overruns" is nothing to worry about. It is a measure of how
                fast the main code is being executed. Expect low
                overruns on a fast machine and higher overruns when
                there is a lot of console scrolling.

        "Memory blocks" shows the minimum, maximum and current number
                of allocated memory blocks.

        "Known nodes" is the number of nodes in the table. "Cur" is
                the current figure, "Max" is the maximum, "Free" is
                the number of free table slots currently available,
                and "Poss" is the number of nodes the table might
                contain if it was not limited in size. If this last
                figure is higher than "max", it indicates that the
                table is not big enough, which may cause loss of low
                quality and "stale" entries in favour of better ones.

        "Total bytes sent/rcvd" are the total bytes sent and received
                by all the ports.  They include all ax25 overhead.

        "Ccts/MaxCcts" shows the current and highest number of
                simultaneous circuits that have been active at any
                time.  Separate figures are shown for Ax25 levels 2,
                3 and 4, and TCP/IP.

        "HTTP Rqst/Srvd/Bytes/Prxyd" shows the total number of HTTP
                requests received and served, the number of bytes
                served, and the number of requests that were proxied,
                i.e. handled on behalf of another system.

        "IP Heard/Reasm/Rcvd/Routed" shows the total number of IP
                frames heard (i.e. addressed to us and to others),
                reassembled from fragments, received (i.e. addressed
                to us), and routed to others.

        "IP Bad Hdr/Chksum/Version" shows the number of IP frames
                ignored due to corrupt IP headers (e.g. too short to
                be a legal IP frame), checksum mismatch, and
                incompatible IP version.  

        "IP Sent" is the no. of IP datagrams originated by XRouter,
                i.e. not routed from somewhere else.  "Frag" is the
                number of datagrams which had to be fragmented to fit
                a link.  "Unsent" is the number of datagrams which
                couldn't be sent due to low  memory or no route, and
                "Total" is the total number of datagrams or fragments
                thereof which were transmitted.

        "L4 Connects Tried/Made/Rcvd" shows the total number of
                outgoing and incoming AX25 level 4 connections.
                "Tried" is the number of requests initiated, "Made"
                is the number which were successful, and "Rcvd" is
                the number of incoming connects.

        "L4 total frames Sent/Rcvd" shows the total number of NetRom
                level 4 frames of all types sent and received by
                XRouter.

        "L4 Info Snt/Rcvd/Resent/Reseq:" shows the totals for NetRom
                level 4 information-bearing frames.  "Snt" is the
                number of frames originated by us.  "Rcvd" is the
                number of frames addressed to us. "Resent" shows how
                many were re-transmitted because no ack was received.
                "Reseq" is the number of frames that re-sequenced,
                i.e. were received out of sequence but subsequently
                used when the missing frames arrived.

        "L4 Choke Snt/Rxd RSET Snt/Rxd:" counts the number of NetRom
                level 4 choke and RESET frames sent and received by
                XRouter.  A sent choke indicates that we are
                receiving L4 data faster than we can process it, and
                instructs the other end to back off for a while.  A
                received choke indicates that we are sending data too
                fast for the other end of the link to handle.  Note
                that these figures do not necessarily indicate that
                there is something wrong with XRouter's links, as
                they apply to the "virtual circuit" from one process
                to another, which may span many intervening nodes.
                L4 resets are sent when frames are received for
                non-existent circuits.

        "L4 Timeouts/Failures" shows the number of times the NetRom
                level 4 T1 timer timed out while waiting for an ack,
                causing re-transmission of a frame.  "Failures" shows
                the number of level 4 circuits which were aborted due
                to excessive retries.

                    ------------------------------

        Entering "S[tats] *" produces the above followed a set of
        PORT stats, then a set of INTERFACE stats.  

                    ------------------------------

        Note that the L4, TCP and IP stats may be displayed in
        isolation using "S L4", "S TCP", and "S IP".

</code> **IP-ERRORS** <code>
        In addition to the normal IP stats shown above, "S[tats] IP"
        shows a set of IP error counters as follows:
    
            IP NoRoute NoGatewy RouteLoop:
            IP Ignored Rejected Discarded:
            IP Denied TTLExpired NoSocket:
            IP TooBig HostEncap XrEncap: 
            IP HdrParam Recursion:

        "NoRoute" means that a datagram was dropped because there was
                no suitable route in the IP routing table, or the
                route pointed to a non-existent PORT.

        "NoGatewy" means that there is no suitable gateway for an
                encapsulated datagram. 

        "RouteLoop" means that the route for an encapsulated datagram 
                is back to the gateway it came from.

        "Ignored" means received datagrams ignored because they were
                on the same subnet as XRouter, but not addressed to
                it. Not an error, just info.

        "Rejected" means frames rejected because they matched an IP
                route entry of type "r" (reject). Unless IP QUIET is
                set, these elicit an ICMP resonse of HOST UNREACHABLE.

        "Discarded" means datagrams dropped because they matched an
                IP route entry of type "s" (silent discard). No ICMP
                response is sent.

        "Denied" means datagrams carrying TCP that were droppped
                because they failed XRouter's access control rules.

        "TTLExpired" means datagrams that couldn't be routed because
                their Time To Live counter had expired.

        "NoSocket" counts datagrams dropped because they were the
                wrong protocol for a route mode of "k" (kernel).

        "TooBig" means datagrams rejected because they were too large
                for the outgoing MTU and had the DF (don't fragment)
                option set. Unless IP QUIET is set, these elicit an
                ICMP response of "fragmentation needed".

        "HostEncap" counts encapsulated datagrams (IPIP, IPENCAP,
                IPUDP) that were suupposed to be routed via the
                operating system's IP stack, but failed to do so.

        "XrEncap" counts encapsulated datagrams (IPIP, IPENCAP,
                IPUDP) that were suupposed to be routed via XRouter's
                own IP stack, but failed to do so.

        "HdrParam" means datagrams dropped due to a problem in their
                IP header parameter lists.

        "Recursion" counts datagrams that were dropped because they
                traversed the IP stack too many times.

</code> **AXIP STATS** <code>
        These are displayed using "S[tats] AXIP".

                total frames heard
                frames ignored (too short)
                frames ignored (bad CRC)
                frames ignored (unsolicited)
                valid frames received 
                frames sent
                frames unsent (resolution failure)
                frames unsent (no route)
                frames unsent (routing loop)
                frames unsent (miscellaneous reasons)

        "Total frames heard" includes valid AXIP plus all other frames
                heard on the interface.

        "Too short" are received frames too short to be legal AXIP.

        "Bad CRC" are received frames long enough to be legitimate
                AXIP, but failed the CRC test.

        "Unsolicited" are valid AXIP from unrecognised senders.

        "Valid frames received" are the ones accepted into AX25.

        "Resolution Failure" occurs when IPLINK has been specified as
                a hostname, but that hostname can't be resolved to an
                IP address.

        "No Route" occurs when there is no IP route which can handle
                the encapsulated packet.

        "Routing loop" occurs when the IP routing is set up
                incorrectly, causing the encapsulated packet to be
                encapsulated again ad infinitum.

        "Miscellaneous Reasons" usually indicates a temporary IP
                routing problem, such as a loose plug.

</code> **AXUDP STATS** <code>
        These are displayed using "S[tats] AXUDP".

                total frames heard
                BPQ keepalives ignored
                other non-AXUDP ignored 
                unsolicited AXUDP ignored
                valid AXUDP received 
                frames sent
                frames unsent (resolution failure)
                frames unsent (no route)
                frames unsent (routing loop)
                frames unsent (miscellaneous reasons)

        "Total frames heard" includes valid AXUDP plus all other
                frames heard on the interface.

        "BPQ keepalives" are packets from BPQ systems that are
                intended to keep the AXUDP connection alive.

        "Other non-AXUDP" is anything else (other than BPQ
                keepalives, which is not valid AXUDP, e.g. port
                scans, malicious activity etc.
 
        "Unsolicited AXUDP" is valid AXUDP from sources with whom we
                don't have a formal arrangement.

        "Valid AXUDP received" are the ones accepted into AX25.

        "Resolution Failure" occurs when IPLINK has been specified as
                a hostname, but that hostname can't be resolved to an
                IP address.

        "No Route" occurs when there is no IP route which can handle
                the encapsulated packet.

        "Routing loop" occurs when the IP routing is set up
                incorrectly, causing the encapsulated packet to be
                encapsulated again ad infinitum.

        "Miscellaneous Reasons" usually indicates a temporary IP
                routing problem, such as a loose plug.

</code> **AXTCP STATS** <code>
        These are displayed using "S[tats] AXTCP".

                total frames heard
                frames ignored (too short)
                frames ignored (bad header) 
                frames ignored (bad CRC)
                frames received OK
                frames sent
                frames unsent (not connected)
                frames unsent (miscellaneous reasons)
                failed / blocked logins

        "Total frames heard" includes valid AXTCP plus all other
                frames heard on the interface.

        "Too short" are received frames too short to be legal AX25.

        "Bad header" counts frames where the length specified by the
                header didn't match the actual frame length. These
                could be malicious, so the connection is dropped for
                safety.

        "Bad CRC" are received frames long enough to be legitimate
                AXTCP, but failed the CRC test.

        "Frames received OK" are the ones accepted into AX25.

        "Frames sent" are the ones successfully sent.

        "Not connected" indicate frames that couldn't be sent because
                the TCP link was not connected.

        "Miscellaneous reasons" indicates frames that couldn't be sent
                due to a temproary problem such as insufficient memory
                or a blocked TCP queue.

        "Failed / blocked logins" are failed attempts to connect to
                the AXTCP server. Usually this results from port
                scanning or other malicious activity.

</code> **PORT STATS** <code>
        Displayed by "S[tats] L2" "S[tats] L3" and "S[tats] *".

        Note that on a system with more than 7 ports the display may
        wrap. This is not ideal, and may be addressed in future
        versions.

        The PORT stats start with Layer 3 counters, which may also be
        displayed in isolation using the "S[tats] L3" command:

                        Port:     2      4      6      8      9
            L3 Frames Heard       0    309      0      0      7 
            L3 Frames Rcvd        0    137      0      0      7
            L3 Frames Sent        0     59      0      0      0
            L3 Frames Relayed     0      0      0      0      0
                 
        "L3 Frames Heard" is the total number of ax25 level 3 frames
               heard, no matter who they are addressed to.

        "L3 Frames Rcvd" is the number of ax25 level 3 frames which
               were addressed to our XRouter.

        "L3 Frames Sent" is the number of ax25 level 3 frames which
               originated at our XRouter.

        "L3 Frames Relayed" is the number of ax25 level 3 frames
               which were routed through our system from elsewhere.


        After the level 3 stats come the ax25 level 2 counters, one
        per port. These can also be displayed in isolation using the
        "S[tats] L2" command:

                        Port:     2      4      6      8      9
            L2 Frames heard       0    628      0      0     78
            L2 Frames rcvd        0    520      0      0     74
            L2 Resequenced        0      0      0      0      0
            L2 Reassembled        0      0      0      0      0 
            L2 Info Received      0      0      0      0      0
            L2 T1 Timeouts        0    239      0      0      0
            L2 Digipeated         0      0      0      0      0
            L2 Info Sent          0    208      0      0      3 
            L2 Info re-sent       0      0      0      0      0
            L2 Fragmented         0      0      0      0      0
            L2 Frames Sent       12    491     18     13     87
            L2 REJ Received       0      0      0      0      0
            L2 Rx out of seq      0      0      0      0      0
            L2 Frames Corrupt     0      1      0      0      0
            L2 FRMRs Sent         0      0      0      0      0
            L2 FRMRs Rcvd         0      0      0      0      0
            Bytes Rcvd        37032  71809      0      0   1589
            Bytes Sent            0  21607    869   1460   1597
            Poll Timeouts         0      0      0      0      0
            Tx/Rx Active%        0/0    0/0    0/0    1/0    0/0
            Tx/Rx Peak%          0/0    0/0    0/0    1/0    0/0 
            Tx/Rx Mean%          0/0    0/0    0/0    0/0    0/0
.

        "L2 Frames heard" is the total number of ax25 level 2 frames
                heard, whether addressed to us or not.

        "L2 Frames rcvd" is the number of ax25 level 2 frames
                received which were addressed to XRouter.

        "L2 Resequenced" is the number of ax25 level 2 frames
                received out of sequence and subsequently used when
                the missing frames arrived.

        "L2 Reassembled" is the number of ax25 level 2 frames
                successfully reassembled from fragments.

        "L2 Info Received" is the number of ax25 level 2 information
                bearing frames received, i.e. addressed to XRouter.

        "L2 T1 Timeouts" counts the number of times that the ax25
                level 2 T1 (frack) timer timed out, causing
                transmission of a poll frame.

        "L2 Digipeated" is the number of ax25 level 2 frames
                digipeated by the port.  Note that if digiport isn't
                zero they may actually have been retransmitted by
                another port, but are recorded on the "receiving"
                port only.

        "L2 Info Sent" is the total number of ax25 level 2
                information frames sent by XRouter.

        "L2 Info re-sent" records how many ax25 level 2 information
                frames were re-sent due to frame loss.  A high figure
                here, in proportion to the "info sent" figure,
                indicates a problem with the RF link, the L2
                settings, or the other end's system (e.g. desense, or
                running out of buffers).

        "L2 Fragmented" is the number of ax25 level 2 information
                frames fragmented to fit the outgoing link.

        "L2 Frames Sent" is the total number of ax25 level 2 frames,
                of any type, sent by XRouter, i.e. it includes all
                info, supervisory, and digipeated frames.

        "L2 REJ Received" is the number of ax25 level 2 "reject"
                frames received, which indicate that the other end of
                the link didn't receive some of our frames.  There
                are many possible reasons for this, some of which are
                mentioned in the next paragraph.

        "L2 Rx out of seq" shows how many ax25 level 2 frames were
                received out of sequence, and indicates that some
                incoming frames are getting lost or corupted.  A few
                of the possible causes might be: signal too weak,
                fading, other signals on channel, natural or man made
                interference, desense or key clicks from adjacent
                transmitters, poor RX audio response, low received
                audio, over-deviation, RF frequency mismatch, badly
                aligned RX, TNC hardware problems, synthesised rig
                taking too long to stabilise on RX after TX, other
                end's synthesised rig taking too long to stabilise on
                TX, hum, noise, distortion or disturbances on
                modulated audio... the list is endless.

        "L2 Frames Corrupt" is the number of frames which were dumped
                because they were too short to be legal ax25 level 2
                frames, or were in some way invalid.  It is sometimes
                possible for a KISS TNC, especially if running "open
                squelch", to send garbage to the router,  or the frame
                may be trashed by bit errors on the serial link
                between TNC and XRouter, and in either case these
                frames are dumped if the error can be detected.

        "L2 FRMRs Sent/rcvd" shows how many ax25 level 2 "Frame
                Reject" frames were sent by the router, or received
                by it, indicating serious protocol errors or
                deliberate interference.

        "Bytes Sent" and "Bytes Rcvd" simply provide a port by port
                breakdown of the total bytes sent/rcvd figure.

        "Poll Timeouts" counts the number of times a pollled KISS TNC
                was polled with no response being received from it.
                A large figure might indicate a crashed, disconnected
                or unpowered TNC, or data loss on the serial link.

        "Tx/Rx Active%" are running averages of the percentage of
                time that the TX is tranmitting and RX is receiving.
                High figures would indicate a saturated RF channel.

        "Tx/Rx Peak%" are the peak values attained by the above.

        "Tx/Rx Mean%" are the long term averages of the TX and RX
                activity, i.e. since XRouter was booted.

</code> **INTERFACE STATS** <code>
        Following the PORT stats are the INTERFACE stats, which can
        also be displayed in isolation using S[tats] L1":

                   Interface:     2      4      9
            RX Bytes:         2048K  71809   1589
            RX Overruns:          0      0      0
            RX CRC/Parity:        0      0      0
            RX Framing err:       0      0      0
            RX Break/Abort:       0      0      0 
            RX Overflow:          0      0      0
            RX Misc. errors:      0      0      0
            RX Read errors:       0      0      0
            TX Bytes:          3463      0   2466
            TX Overflows:         0      0      0
            TX Underruns:         0      0      0
            TX Write errors:      0      0      0  

        "RX Overruns" counts the number of times a byte was received
                before the previous one was read by the CPU.  A high
                number indicates that the PC is too slow for the
                serial port or HDLC card data rate.  A 16550-based
                serial card may help if the port doesn't already use
                one.  Failing that, you will have to reduce the baud
                rate.

        "TX Underruns" is used only by HDLC cards, and counts the
                number of times the TX went empty while waiting for
                another frame byte to be loaded.  A significant
                figure indicates the computer is too slow for the
                baud rate.  Each underrun causes an aborted frame.

        "CRC/Framing Errors" counts either the number of bytes
                received without proper stop bits (ASYNC interfaces),
                or the number of received frames which are corrupt
                (HDLC cards).  For ASYNC interfaces, a significant
                count here can indicate a hardware problem, such as a
                faulty line driver, serious RS232 line noise or
                distortion, or significant baud rate mismatch.  For
                HDLC cards it indicates a level 1 problem, such as
                distortion in the TX/RX RF or audio paths, or simply
                a lot of packet collisions.

        "Break/Abort Errors" counts the number of times a line
                "space" condition longer than 1 word interval was
                received.  For serial ports this can indicate a
                faulty line driver, a faulty diode matrix on a
                multi-drop kiss system, or even (as happened to me)
                a malfunctioning TNC EPROM.  On HDLC cards it can
                result from insufficient audio drive from the RX, a
                mismatched baud rate, squelch tails, or genuine ABORT
                sequences transmitted by the other end of the link.

        "CRC Errors" shows the number of frames abandoned due to CRC
                (Cyclic Redundancy Check) or checksum error.  For
                KISS interfaces this is only maintained if the
                CHECKSUM kissoption is enabled.

        "Rx Overflow err" shows the number of times a frame was
                abandoned because it was too large to fit into the
                receive buffer.

        "Tx Overflow err" counts the number of times that the TX
                couldn't accept a character (serial devices) or a
                frame (block devices) because the TX buffer was full.
                If you persistently get a high value, it indicates
                that the device is too slow for the data throughput.

        "RX Misc. errors" counts all sorts of miscellaneous errors,
                and the meaning is different for each type of
                interface.  For example, on KISS interfaces it counts
                KISS framing errors. 

</code> **IDS STATS** <code>
        Finally "S[tats] IDS", which is sysop-only, elicits a summary
        of XRouter's IDS (Intrusion Detection System) stats, which
        may look something like this: 

            IDS Events:       25778   Cmd Overflow:     0
            FTP DIR Hacks:    0       IP Addr Heard:    100
            IP Addr Banned:   200     IP Banned Total:  183     
            IP Dgram Blocked: 2076    ICMP Frm Blocked: 32
            Honeypot Hits:    0       UDP Segs Ignored: 3251968
            UDP Segs Blocked: 22      TCP Segs Ignored: 9967
            TCP Segs Blocked: 2022    TCP Conn Blocked: 763     
            Bogus SYNs:       15776   Smurf Attacks:    0
            Fraggle Attacks:  0       IP Frag Attacks:  0
                      (Tiny=0  Huge=0  Overlapped=0)
            TCP Scans: SYN=1 FIN=0 ACK=57 NUL=0 MAI=82 XMS=0 OTH=9600
            Rejected Logins:  763 (Telnet=763, Rlogin=0, FTP=0,
               TelProxy=0)
            Malicious Logins: 182 (Telnet=182, Rlogin=0, FTP=0,
               TelProxy=0)
            HTTP No-Request:  0       HTTP Bad Request: 0
            HTTP Blocked:     0

        "IDS Events" is the total number of times the IDS has noticed
                something suspicious.

        "Cmd Overflow" is the number of times that someone has
                attempted a buffer overflow attack.

        "FTP DIR Hacks" is the number of attempts to escape from the
                FTP root directory.

        "IP Addr Heard" is the number of unique IP addresses heard.

        "IP Addr Banned" is the number of IP addresses in the "banned
                IP" table. As the table is saved across reboots, it
                is normal for it to be full.

        "IP Banned Total" is the number of new IP addresses banned
                since bootup. This figure may exceed the table size
                because new bans replace stale ones.

        "IP Dgram Blocked" is the number of IP datagrams blocked
                because the sender's IP address was in the banned IP
                table.

        "ICMP Frm Blocked" is the number of ICMP frames blocked
                because the sender's IP address was in the banned IP
                table.

        "Honeypot Hits" is the number of times someone attempted to
                access one of the "honeypot" ports. These are traps
                which lure port scanners into an IP ban.

        "UDP Segs Ignored" is the number of UDP segments ignored
                because there was no matching socket to receive them.

        "UDP Segs Blocked" is the number of UDP segments blocked
                because the sender's IP address was on the banned IP
                list.

        "TCP Segs Ignored" is the number of TP segments ignored
                because there was no matching listener socket.

        "TCP Conn Blocked" is the number of TCP connection attempts
                blocked because the sender was on the banned IP list.

        "Bogus SYNs" is the number of TCP connection attempts blocked
                because the SYN was malformed or maliciously crafted.

        "Smurf Attacks" are distributed denial of service attacks
                which use ICMP directed at broadcast addresses.

        "Fraggle Attacks" are variations of Smurf attacks, where the
                attacker sends lots of traffic to UDP ports 7 (Echo)
                and 19 (CHARGEN)

        "IP Frag Attacks" is the number of IP fragmentation attacks.
                These attacks attempt to overwhelm or crash the IP
                fragment reassembly mechanism.
                Tiny - First fragment is too short to contain valid
                       TCP+IP headers, so it could bypass port-number
                       filtering.
                Huge - Fragment exceeds maximum datagram size.
                Overlapped - Fragments which overlap but don't align.

        "TCP Scans" is the number of TCP port scans detected and
                blocked. Totals for each scan type are shown
                separately:
                SYN - Scanner sends SYN but never completes the 3 way
                      TCP handshake.
                FIN - TCP segments with only the FIN bit
                ACK - Only the ACK flag is set
                NUL - NULL scan (no flags are set)
                MAI - Maimon scan (FIN and ACK flags set)
                XMS - Xmas Tree scan (FIN, PSH and URG flags set)
                OTH - Other types of scan
 
        "Rejected Logins" are Telnet / FTP etc logins which were
                rejected because the login credentials were incorect.

        "Malicious Logins" are TCP logins attempted using suspicious
                credentials.

        "HTTP No-Request" is the number of connections to XRouter's
                HTTP server which didn't contain an HTTP request.
                These are usually the result of port scanning.

        "HTTP Bad Request" is the number of malformed or maliciously
                crafted HTTP requests. These are usually attempts to
                exploit vulnerabilities in certain types of HTTP
                server or operating system.

        "HTTP Blocked" is the number of HTTP server connections
                refused because the sender's IP was in the blocked
                IP list.


</code> **SEE ALSO:** \\
[[packet:xrouter:docs:MAN1#STATS|        STATS(1) -- Display XRouter Statistics.
]] \\

[[packet:xrouter:docs:|< Back to Index]]

----
===== STEALTH =====
<code>STEALTH(9)              XROUTER REFERENCE MANUAL            17/10/2023
</code> **NAME** <code>
        STEALTH -- TCP/IP Stealth Mode

</code> **DESCRIPTION** <code>
        The experimental command IP QUIET [n] controls whether or not
        ICMP error messages are generated.  The command may be used at
        the command prompt, in BOOTCMDS.SYS, or (without the "IP") in
        IROUTE.SYS.

        Hackers use automated software to "probe" the network, looking
        for unprotected TCP or UDP services and "back doors" such as
        NetBios. When they find such a service, they will usually
        exploit known bugs, such as buffer overflow problems, to crash
        the machine or gain access to sensitive areas.

        XRouter has only a handful of standard TCP / UDP services,
        none of which pose much of a security risk if configured
        correctly, so the probes are more of a bandwidth-wasting
        nuisance than a real threat.

        Issuing the command "IP QUIET n", where n is a number between
        1 and 255 puts XRouter into "stealth mode", the level of which
        depends on the number n, which is the sum of the following
        values:

                1       Suppress ICMP echo replies.
                2       Suppress ICMP "Unknown Protocol" messages
                4       Suppress TCP resets
                8       Suppress all other ICMP error messages.

        A value of 0 disables stealth mode and lets TCP/IP operate
        normally.

        Suppressing ICMP messages, may reduce the bandwidth wasted
        and slow up the rate of probing.  But it won't confer any
        extra security, and will certainly have a detrimental effect
        on normal TCP/IP operations.

        ICMP error messages are an integral part of the TCP/IP
        protocol, and are used to inform a sender of network problems
        such as unroutable frames, unsupported protocols, processing
        errors etc.  They are also used for diagnostic purposes, by
        applications such as "Ping" and "TraceRoute".

        Using stealth mode therefore prevents the use of diagnostics
        and the detection of network problems, and may under some
        conditions make everything run more slowly, or fail completely.

        If you suppress ICMP echo replies, your system will not
        respond to "pings".  This may be temporarily useful if you are
        being attacked with echo requests, but you would also be
        denying others the use of a valuable network diagnostic tool.
        It is considered bad practice among the amateur community to
        disable services. It will not *prevent* a pingstorm attack,
        but it will halve the traffic by suppressing the replies.

        If you suppress ICMP "unknown protocol" messages, it will
        reduce the bandwidth wasted by protocol scans, i.e. those in
        which the protocol number is incremented with each probe.

        "Suppressing TCP resets" prevents the TCP layer from sending a
        refusal for connect requests aimed at non-existent TCP
        services. The request is simply ignored instead.  This may be
        useful in slowing up the action of so-called "port scanners".

        The "Suppress all ICMP error messages" option is not
        recommended.  It is provided for experimentation only.

</code> **SEE ALSO:** \\
[[packet:xrouter:docs:MAN1#IP|        IP(1)           -- IP configuration commands.
]] \\
[[packet:xrouter:docs:MAN8#BOOTCMDS.SYS|        BOOTCMDS.SYS(8) -- Commands to Run at Bootup.
]] \\
[[packet:xrouter:docs:MAN8#IPROUTE.SYS|        IPROUTE.SYS(8)  -- IP Routing File.
]] \\

[[packet:xrouter:docs:|< Back to Index]]

----
===== SYNCACHE =====
<code>SYNCACHE(9)            XROUTER REFERENCE MANUAL               6/9/2023
</code> **NAME** <code>
        SYNCACHE -- TCP SYN Cache.

</code> **DESCRIPTION** <code>
        To combat the ever-growing problem of TCP port scanning,
        which wastes TCP resources, XRouter includes a "SYN cache".

        In "normal" RFC793 TCP, a received SYN elicits a SYN|ACK,
        and the TCP state machine allocates resources then moves to
        the  SYN_RECEIVED state, awaiting an ACK from the caller.

        The nastier port scans tend to send a SYN, wait for the ACK,
        then move on without sending a reset. This leaves dozens of
        half-open connections, which eventually prevent new
        connections from being formed.

        With a SYN cache, a received SYN elicits a SYN|ACK as before,
        but no resources are allocated. The SYN is cached for a short
        while. If an ACK is received for our reply, a normal
        connection is created, otherwise the SYN is discarded. This
        makes the TCP stack far more resistant to port scans.

        The TCP CACHE command is used to display and adjust settings.

</code> **SEE ALSO:** \\
[[packet:xrouter:docs:MAN1#TCP|       TCP(1) -- TCP Status / Configuration Commands
]] \\

[[packet:xrouter:docs:|< Back to Index]]

----
===== TDR =====
<code>TDR(9)                  XROUTER REFERENCE MANUAL            21/10/2023
</code> **NAME** <code>
        TDR -- Time Dependent Routing.

</code> **DESCRIPTION** <code>
        Conventional NetRom makes routing decisions based on a fairly
        arbitrary metric, i.e. the "route quality", which is assigned
        by sysops, and disseminated in nodes broadcasts.  There is no
        standard for assigning quality, and not only will each sysop
        have a different notion of the quality of his links relative
        to others, but he will probably wrongly assign the qualities
        of those links relative to each other.  This leads to
        inconsistency and distorted routing.

        XRouter includes two systems which attempt to alleviate this
        problem, namely Automatic Quality Measurement" (Autoqual)
        and "Time Domain Routing" (TDR).  Both systems rely on a
        slightly different understanding of the "goodness" of a link.

        In the better-managed parts of the NetRom network, route
        qualities tend to be assigned according to the baud rate of
        the link, with adjustments for retry rates, duplex / simplex
        and shared channels (in the worst-managed parts, route
        qualities are simply assigned to 192 regardless of how good
        or bad the link is).  The quality is fixed at a compromise
        value.

        But the actual "goodness" of a link may continually change
        with atmospheric conditions, data throughput, other channel
        activity, QRM etc.  At certain times of day for example, it
        may be better to use an alternative link.

        A more accurate notion of "goodness" is simply the "Round
        Trip Time" (RTT) for the link, i.e. the time taken to send a
        packet and get a reply.  After all, this is what *really*
        matters to users. A link which responds quickly (i.e. with a
        low RTT) is perceived by users to be better than a link which
        responds slowly.  The RTT will track changes in retry rate,
        channel loading etc.

        The RTT can be easily and consistently measured by software
        on a continuous basis, thus the "quality" of the link is
        accurately known at all times, and all routers of the same
        type will give comparable values independently of the sysop's
        notions of quality.

        XRouter continually measures RTT and uses it to calculate
        a notional "route quality".  This quality is displayed by the
        "R Q" command, and can either be used as a guide to allow the
        sysop to fix the RQ at a sensible value, or XRouter can use
        it dynamically, by setting the route to use Autoqual.
        (Autoqual is engaged by setting an RQ between 256 and 511).
        This RTT to quality conversion is tailored to the British
        notion of quality, which gives somewhat lower but more
        meaningful qualities.

        Autoqual is merely a tool to help sysops set consistent and
        meaningful route qualities. The qualities are still under
        sysop control, thus open to distortion.

        However, by simply broadcasting RTT values instead of
        qualities, the influence of the sysop is removed, and a
        network based on indisputable *times* rather than arbitrary
        *quality* can be created.  This is a network which has its
        routing metric in the time domain, hence the name "Time
        Domain Routing".  It may to some extent overlap the
        quality-domain network, but the boundaries may be different,
        and the two schemes are not compatible. Consider them to be
        different dimensions, at 90 degrees to each other.

        XRouter implements both time-domain and quality-domain
        routing schemes, and will consider information from both
        domains when making routing decisions.  The same node table
        is used for both schemes, since only the metric is different.
        In some cases a node may have both quality and time metrics.

        As sysop, you have several tools at your disposal for
        controlling the size and balance of the two domains.  For the
        quality domain you have QUALITY which defines the "goodness"
        of the links to your neighbours and the "de-rating" of the
        qualities which they send to you, MINQUAL, which determines
        which nodes get into the nodes table and which are excluded,
        MINTXQUAL, which determines how much information you send to
        your neighbour nodes, and MAXNODES which determines the
        maximum number of nodes visible to you.

        For the time domain, you have MAXTT, which defines the
        furthest node in "Trip Time" (i.e. RTT/2) terms, MAXHOPS
        which defines the furthest node as a function of the number
        of intervening nodes, and MAXNODES as above.

        You may adjust these parameters to favour one domain over the
        other, to exclude one domain altogether, or to strike a
        balance between the number of nodes which exist solely in one
        domain or the other.

        For example, setting MAXTT or MAXHOPS to 0 will exclude all
        time-domain information, and Xrouter will behave as a pure
        old-fashioned NetRom router.  Or you may set MINQUAL to 255,
        excluding all quality-domain information (e.g. if there is a
        nearby node distorting the netrom qualities), providing of
        course you have neighbours which are cabable of time-domain
        routing.  Or you may wish to limit the visibility of a subnet
        from one port (e.g. to a foreign network) by setting a low
        MAXHOPS or MAXTT on that port only.  This gives you control
        which was not possible by quality alone.

        XRouter currently (but see compatibility issues) uses the
        INP3 protocol to disseminate time-domain routing information.
        Unlike NetRom, which uses unconnected-mode "broadcasts" to
        all neighbours simultaneously, INP3 sends data to each
        neighbour individually, using connected-mode.  Whilst it is
        usual to make NetRom nodes broadcasts at 1 hour intervals,
        INP3 updates are sent every 10 minutes, with additional
        updates whenever changes occur.

        The time-domain network thus responds much more rapidly to
        changes than NetRom does, but if the network is unreliable
        (i.e. frequent outages and variable RTT's), a lot of updates
        are generated.  Although INP3 updates are more compact than
        NetRom nodes broadcasts, some sysops may feel that the amount
        of routing information is too much for a poor quality RF link.
        If so, you may disable INP3 completely by setting the route
        MAXTT to 0, or you can agree a low MAXTT with your neighbour
        node, which will reduce the volume of data.

        You may notice that nodes which are learned solely via INP3
        are all stored with a NetRom quality of 0. This is deliberate,
        because these nodes have no presence in the quality domain.

        Compatibility issues:

        Although this is a router manual, not a treatise on advanced
        networking, it must be stressed that time-domain and
        quality-domain metrics are incompatible, and information
        learned from one domain must *never* be "translated" and
        broadcast to the other.  XRouter measures, uses and
        disseminates both time and quality metrics, but always keeps
        them separate.

        Unfortunately, *some* software (which shall henceforth be
        known as "Brand-X") *does* translate information between the
        domains, and you should be aware that this may cause you
        problems if they are within the horizon of either domain.

        For example, in the diagram below, imagine that an XRouter
        node (Xr) measures the trip time (TT) to one of its neighbour
        nodes (A) as 1.5 seconds, and the sysop has assigned a Netrom
        quality of 180.

                     180
                   A ---- Xr ---- Bx
                           \     /
                             \ /
                              C ---- D


        XRouter broadcasts both pieces of information to neighbour
        node (Bx) which is using "Brand-X" software.  That software
        ignores the 180 and will instead manufacture a quality of 253
        from the trip time, using a totally unsuitable algorithm.
        By itself this isn't a problem, until the "Brand-X" node
        broadcasts it to node (C) which is NetRom-only.  Now the
        NetRom node thinks it has a higher quality to (A) via (Bx)
        than via (Xr).  So packets from (C) to (A) will now take the
        longer path.  What's worse, (Bx) will tell (Xr) that it knows
        a better route to (A), and the network will decend into chaos.

        A fully interconnected mesh network is very robust, yet the
        "Brand-X" sysops seem remarkably reluctant to implement links
        which result in a mesh.  Maybe the above explains why!

        Another problem occurs when the "Brand-X" software translates
        in the other direction, i.e. it takes a NetRom quality, which
        is a potentially unreliable piece of information, and
        magically turns it into a trip time and hop count. Yet
        neither trip time nor hop count can ever be inferred from
        quality alone!

        The consequence is that a node which exists only in the
        untrustworthy quality domain, and may have been beyond our
        horizon in that domain, now appears in the more trusted time
        domain where it can bypass the NetRom de-rating process.  The
        information could subsequently pass innocently back into the
        Netrom network with a higher "quality" than it would have
        if received via a more direct pure netrom route.

</code> **HISTORY** <code>
        Early versions of XRouter used a proprietary protocol to
        exchange RTT, hops, IP routing, position and other
        information between themselves.  It was later decided to
        adapt XRouter for INP3 compatibility, believing that it would
        be a good idea to interconnect XRouter's time domain scheme
        with other types of node.

        In hindsight this proved to be a mistake, and it is firmly
        believed that, unless the "Brand-X" software authors correct
        the errors, XRouter and the Netrom network should not be
        connected to any other network which includes "Brand-X"
        nodes. Fortunately, those nodes are now in decline, and BPQ
        is becoming more prevalent. BPQ32 does (correctly) keep time
        and quality domains separate.

</code> **SEE ALSO:** \\
[[packet:xrouter:docs:MAN9#AUTOQUAL|        AUTOQUAL(9)  -- Automatic Route Quality.
]] \\
[[packet:xrouter:docs:MAN9#INP3|        INP3(9)      -- Inter-Node Protocol 3
]] \\
[[packet:xrouter:docs:MAN1#MINQUAL|        MINQUAL(1)   -- Minimum Quality.
]] \\
[[packet:xrouter:docs:MAN1#MINTXQUAL|        MINTXQUAL(1) -- Minimum Quality to Transmit.
]] \\
[[packet:xrouter:docs:MAN1#ROUTES|        ROUTES(1)    -- Add, Drop and List Routes.
]] \\
[[packet:xrouter:docs:MAN1#QUALITY|        QUALITY(1)   -- NetRom Route Quality.
]] \\

[[packet:xrouter:docs:|< Back to Index]]

----
===== TELPROXY =====
<code>TELPROXY(9)             XROUTER REFERENCE MANUAL             27/9/2023

</code> **NAME** <code>
        TELPROXY -- Telnet Proxy Server.

</code> **DESCRIPTION** <code>
        The need may arise for a TCP/IP host on the LAN to connect
        first to XRouter, before making an ongoing connection from
        Xrouter to a target host.  Using normal telnet port 23 for
        this purpose is not always successful, especially if the
        link is required to carry binary data, due to the internal
        end-of-line translations and Telnet command sequences which
        are part of the Telnet protocol.

        The Telnet proxy on TCP port 2323 provides a solution to
        this problem, allowing 100% binary connections not only to
        TCP/IP targets, but also to Netrom and AX25 targets. This
        would typically be used by a TCP/IP-only BBS to perform
        FBB compressed forwarding with netrom and ax25 targets.

        Upon connection to port 2323, the caller may, or otherwise,
        be required to answer a security challenge, according to the
        security criteria specified in ACCESS.SYS.  The options are:
        no challenge, callsign only, or callsign plus password, and
        all of these can be made dependent on the caller's IP source
        address.

        If a password is required, it should be located in file
        USERPASS.SYS.

        After gaining entry, the user is presented with a short text 
        explaining the syntax for the outgoing connection, followed
        by a short prompt ">".  This text is read from file
        TELPROXY.MSG, so you may adjust it to your requirements.
        The user may now issue a telnet, netrom or ax25 downlink
        connect command.  XRouter will respond with "Trying ...".

        If the downlink is successfully made, connection is reported,
        then the stream becomes pure binary for the remainder of the
        session.

        If the downlink fails to connect, an error message is sent
        before the uplink is terminated.

</code> **FILES** <code>
        ACCESS.SYS controls the access requirements for the server.
        TELPROXY.MSG provides an optional alternative login message.
        TELPROXY.ACL controls which targets can be connected to.
        USERPASS.SYS contains the user passwords, if required.

        If required, these files must reside in the same directory
        as the XRouter executable.

</code> **SEE ALSO:** \\
[[packet:xrouter:docs:MAN8#ACCESS.SYS|        ACCESS.SYS(8)   -- Telnet Access Control File.
]] \\
[[packet:xrouter:docs:MAN8#TELPROXY.ACL|        TELPROXY.ACL(8) -- Telnet Proxy Egress Control File.
]] \\
[[packet:xrouter:docs:MAN8#TELPROXY.MSG|        TELPROXY.MSG(8) -- Telnet Proxy Logon Message File
]] \\
[[packet:xrouter:docs:MAN7#TELPROXYPORT|        TELPROXYPORT(7) -- TCP Port for Telnet Proxy.
]] \\
[[packet:xrouter:docs:MAN8#USERPASS.SYS|        USERPASS.SYS(8) -- User Passwords File.
]] \\

[[packet:xrouter:docs:|< Back to Index]]

----
===== TNC2 =====
<code>TNC2(9)                 XROUTER REFERENCE MANUAL             28/9/2023

</code> **NAME** <code>
        TNC2 -- TNC2 Emulator.

</code> **DESCRIPTION** <code>
        The TNC2 Emulator is a feature which allows RS232 devices
        such as weather stations, dumb terminals, GPS and telemetry
        devices to send and receive packets as if they were connected
        to a real TNC2.


                \|/            .---------.
                 |   .-----.   |         |         .-----.
                 '---| Rig |---| XRouter |----<----| GPS |
                     '-----'   |         |  RS232  '-----'
                               '---------'

        For example, imagine you have a weather station which is
        designed to be connected to a TNC via an RS232 cable.  Now
        imagine that you already have an APRS port on your XRouter.
        How would you get your weather station on air?

        You *could* use an additional TNC, radio and antenna, but that
        would be a pointless duplication of equipment.  Far better to
        configure XRouter to emulate a TNC, so that it can interface
        directly to the weather station. This allows the weather
        station to send to, and receive from, the existing APRS port.

        Or you may have a dumb terminal connected to XRouter via an
        RS232 cable, and use it to monitor any port, make connections
        with other stations etc.  This is completely independent of
        XRouter's command interface, and does not require a session
        with the node.

        There are several applications which have TNC2 as one of the
        interface options. You may interface them to any of XRouter's
        radio ports via that means.

        Or perhaps you wish to monitor a radio channel with a data
        logging program, or send the channel activity to a serial
        printer?  The possibilities are limited by your imagination.

        Configuration
        ~~~~~~~~~~~~~
        The emulator requires only an INTERFACE in XROUTER.CFG. It
        does *not* require a PORT. It is usually configured by
        defining an INTERFACE with TYPE=ASYNC and PROTOCOL=TNC2.
        Choose SPEED to suit the peripherals, and MTU=256.

        Example:

           INTERFACE=5
                TYPE=ASYNC
                COM=1
                SPEED=19200
                PROTOCOL=TNC2
                MTU=256
           ENDINTERFACE

        You can have as many TNC emulators as you wish, providing you
        have an RS232 port for each one.  You should preferably use a
        different MYCALL or SSID for each one if there is any chance
        of more than one TNC being used on the same radio port.

        In addition to TYPE=ASYNC, You may also use the TNC2 protocol
        over a TYPE=UDP or TYPE=TCP interface.

        Operation
        ~~~~~~~~~
        Standard TNC2 commands currently recognised are Ctrl-C,
        AUTOLF, CONNECT, CONVERSE, DISCONNECT, DISPLAY, ECHO, FLOW,
        HELP, HEADERLN, KONVERSE, MALL, MCOM, MCON, MONITOR, MRPT,
        MSTAMP, MYCALL, PORT, PORTS and UNPROTO. Other commands may
        be implemented upon request.

        You may set the TNC's callsign (using MYCALL) completely
        independently of XRouter's callsign, and may select any of
        XRouter's radio ports using the PORT command. When you select
        a port, the TNC2 emulator receives from, and transmits to,
        the radio equipment connected to that port. 

        All settings are saved to the file TNCn.CFG where 'n' is the
        interface number.  This file is automatically created if it
        doesn't already exist.  It is read when XRouter starts up,
        so the TNC always returns to its previous configuration.  The
        file contains binary data, so you must not attempt to edit it.

</code> **NOTES** <code>
        The emulator does not currently accept incoming connections.
        That facility may be added upon request.

</code> **SEE ALSO:** \\
[[packet:xrouter:docs:MAN6#TCP-IFACE|        TCP-IFACE(6)   -- Interface type TCP.
]] \\
[[packet:xrouter:docs:MAN6#UDP-IFACE|        UDP-IFACE(6)   -- Interface type UDP.
]] \\
[[packet:xrouter:docs:MAN9#WA8DED|        WA8DED(9)      -- WA8DED TNC Emulator
]] \\
[[packet:xrouter:docs:MAN8#XROUTER.CFG|        XROUTER.CFG(8) -- Main Configuraion File
]] \\

[[packet:xrouter:docs:|< Back to Index]]

----
===== TTYLINK =====
<code>TTYLINK(9)              XROUTER REFERENCE MANUAL             27/9/2023

</code> **NAME** <code>
        TTYLINK -- Keyboard To Keyboard Chat.

</code> **DESCRIPTION** <code>
        TTYLINK is private real-time keyboard-to-keyboard chat
        between sysops, which doesn't involve the CHAT server.

        The TTYLINK server listens for incoming connections on TCP
        port 87 (see TTYLINKPORT) and NetRomX service 87.

        Client sessions are initiated by:

           (a) telnetting to TCP port 87 on the target system,
        or (b) using "TT[ylink] <target_ip>",
        or (c) using "C <nodecall | nodealias> 87"
        or (d) using "TALK <nodecall | nodealias>"
        or (e) using "NTTY <nodecall | nodealias>"

           (Options (c) (d) and (e) require that the target is a
            reachable NetRomX node)

        Upon receiving a connection from a client, the server "pages"
        the sysop, who has 90 seconds to respond. The paging consists
        of a pop-up dialog on top of the sysop's current window, and
        an audible sound (Note: unless AUDIODEVICE is defined, the
        sound only works on older-style PC's which have an internal
        loudsqueaker). The server also sends this to the client:

            TTYLINK at MOBILE:G8PZT-1
            Calling sysop for 90 seconds..
            Type 'M' at any time to leave a short message,
             or 'Q' to quit...

        At any point during or after the 90 seconds, the client has
        the option to leave a short one-line message (160 chars max)
        or to abort the call.

        Here's an example where the sysop responded:

            *** G8PZT-1 has come online to talk ***
            Hello, why are you calling me?
            Because I want to, silly!
            Fair enough, it's mad talking to oneself you know...
            I know, but no-one else is around.
            Ok, bye for now

            *** The other end terminated the chat

        If the sysop takes more than 90 seconds to respond, and the
        client has not disconnected, the sysop can still use the
        TALK command to initiate a chat with the caller.

        Here's an where the sysop didn't respond. Although not
        strictly TTYlink, it is a useful compromise, rather than
        allow an important call to be missed:

            TTYLINK at MOBILE:G8PZT-1
            Calling sysop for 90 seconds..
            Type 'M' at any time to leave a short message,
             or 'Q' to quit...
            No response, please type a short (1 line) message now...
            (or enter a blank line to skip this step)

            Can you call me back to discuss xrpi release asap? 

            Message saved for sysop
            Goodbye

        The message is stored in the sysop's PMS, and a flashing
        asterisk on the top left corner of the status bar alerts the
        sysop to its presence. The sysop can then access their PMS
        to read the message like this:

            CMD(B/H/K/L/R/S/?)>
            l
            Msg# Stat  Rcvd  Time  To      From    Subject
            6 PR   22/05 03:25  SYSOP   G8PZT   TTYLink msg from
                                                 G8PZT@VK2DOT-1

            CMD(B/H/K/L/R/S/?)>
            r 6

            Msg#: 6
            Rcvd: 22/05 03:25
            From: G8PZT
            To:   SYSOP
            Subj: TTYLink msg from G8PZT@VK2DOT-1

            Can you call me back to discuss XRPi release asap?

            CMD(B/H/K/L/R/S/?)>

        It's all a bit untidy at present, but will hopefully be
        tidied up in future revisons.

</code> **SEE ALSO:** \\
[[packet:xrouter:docs:MAN1#NTTY|        NTTY(1)        -- Netrom TTYLink.]] \\
[[packet:xrouter:docs:MAN1#TALK|        TALK(1)        -- Talk to a user or another sysop.]] \\
[[packet:xrouter:docs:MAN1#TTYLINK|        TTYLINK(1)     -- Keyboard chat with another TCP/IP system.]] \\
[[packet:xrouter:docs:MAN7#TTYLINKPORT|        TTYLINKPORT(7) -- TCP Port for TTYLINK Server.]] \\
[[packet:xrouter:docs:MAN9#AUDIO|        AUDIO(9)       -- Audio Output.]] \\
[[packet:xrouter:docs:MAN9#SERVICES|        SERVICES(9)    -- NetRomX Standard Services.]] \\

[[packet:xrouter:docs:|< Back to Index]]

----
===== WA8DED =====
<code>WA8DED(9)               XROUTER REFERENCE MANUAL            19/10/2023
</code> **NAME** <code>
        WA8DED -- WA8DED TNC Emulator.

</code> **DESCRIPTION** <code>
        XRouter can emulate a WA8DED TNC, in both normal mode and
        "host" mode.  Host mode operation is covered in the MAN page
        for DEDHOST.  Normal mode might be used by a human user, or
        by an application designed to work with a WA8DED TNC in this
        mode.

                .---------.                  .-----------.
                | XRouter |------RS232-------| HyperTerm |<--User
                '---------'                  '-----------'


        The user may be located on the same machine as XRouter,
        connected to it either via a pair of "virtual" COM ports, or
        via a pair of "real" COM ports interconnected with a null
        modem cable.

        Alternatively, the user may be located on a seperate machine,
        using an RS232 null-modem cable to interconnect the machines. 


        Configuring WA8DED Emulation
        ~~~~~~~~~~~~~~~~~~~~~~~~~~~~

        The configuration for non-hostmode operation is essentially
        the same as for hostmode, except that an APPL block is not
        required in XROUTER.CFG.  In fact, an interface set up for
        hostmode will work OK in non-hostmode too.

        1) Decide how to interconnect the user and XRouter.

           You can use either a pair of real COM ports and a
           null-modem cable, or a virtual com port driver such as
           Com0Com.

           If using the latter, install it on the PC (if it isn't
           already installed) and note the numbers of the two COM
           ports it provides.  You may need to adjust one or both of
           them to a convenient number for your application.  Ensure
           that "Baud Rate Emulation" and "Enable Buffer Overrun" are
           checked on both sides.


        2) Add an INTERFACE.

           In XROUTER.CFG specify an interface similar to this, where
           "x" represents the interface number...
 
               INTERFACE=x
                    TYPE=ASYNC
                    COM=18
                    PROTOCOL=DEDHOST
                    CHANNELS=4
                    SPEED=9600
                    FLOW=0
                    MTU=256
               ENDINTERFACE

           COM is the number of one of the real or virtual COM ports
           used to connect with the application.  XRouter can use COM
           numbers up to COM32. On Linux, COM is a TTY device name.

           CHANNELS specifies the max no. of host channels the
           interface will provide (between 1 and 32). The total
           number of host channels available to be shared between all
           applications is 64. If XRouter cannot allocate the
           requested number of channels it will fail to start. (In
           versions up to 200e the number of channels was specified
           by INTNUM. This is now deprecated.) 

           MTU must be 256 

           SPEED is the serial baud rate.

           FLOW must always be set to 0. 

           - Don't use CHANNEL, IOADDR, or INTNUM keywords. 

           - Don't try to attach any PORTs to this interface, as they
             are not required. 


        Using WA8DED TNC Emulation in Terminal Mode
        ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

        XRouter's WA8DED emulator starts up in "terminal" mode (i.e.
        not host mode) and may be therefore tested or used in this
        mode using Hyperterm or any other dumb terminal. Wherever
        possible, the emulator behaves the same as a "real" WA8DED
        TNC, as detailed below: 

        In normal mode, commands and information are sent from the
        terminal to the emulator in the form of lines. Lines may be
        up to 256 characters long, including the terminating CARRIAGE
        RETURN.  If the 256th character entered is not a CARRIAGE
        RETURN, it will be discarded and a BELL character will be
        output to the terminal. BACKSPACE and DELETE may be used to
        remove single characters from the line. The entire line may
        be permanently backspaced out by entering a CONTROL-U or
        CONTROL-X. 

        Lines which begin with an ESCAPE character (echoed as '* ')
        are interpreted as commands. Lines without a leading ESCAPE
        character are sent as information. 

        Most commands consist of a single letter. Some commands have
        an optional parameter. The number of spaces (if any) between
        the command and any parameter is not important. If a command
        is issued with no parameter, the current value of that
        command's parameter is displayed. Unless a parameter is
        returned, commands don't normally return any acknowledgement. 

        By default, XRouter's WA8DED emulator provides the operator
        with five virtual TNC channels, numbered 0 to 4 (The actual
        number may be altered between 1 and 32 using the CHANNELS=
        keyword in the supporting INTERFACE).  The terminal is
        logically attached to only one of these channels at a time,
        selected by the 'S' command. 

        Channel 0 is reserved for unproto transmissions and
        monitoring.  This channel does not support connections.
        Information sent on channel 0 is always unproto.  The unproto
        path may be set by issuing a 'C' command when channel 0 is
        selected. 

        Channels other than 0 support connections, but are unproto if
        they are not currently connected.  Outgoing connect requests
        may be issued on any unconnected channel (other than channel
        0), while incoming connect requests will use the first
        available channel (provided the maximum number of connections
        set by the 'Y' command will not be exceeded). 

        Information received on a connected channel that is not
        currently selected will remain queued there until that
        channel is selected.  The 'L' command may be used to
        determine the channel(s) where stored information is located.

        Information for transmission is sent only to the currently
        selected channel.  When a connection is ended, received
        information will remain queued until it has been displayed. 

        Frame monitoring is controlled by the 'M' command.  The
        command parameter determines the types of frames monitored,
        and is a list of desired frames chosen from the letters in
        the following table: 

               LTR       FRAME
               ---       -----
                N        None
                I        I frames
                U        UI frames
                S        Supervisory frames
                C        Monitor while connected
                +        Call signs to be included (maximum of 8)
                -        Call signs to be excluded (maximum of 8)


        The '+' and '-' parameters may not be used together. If
        either is used, it must be the last parameter (followed by
        one to eight callsigns, if applicable).  If no list of
        callsigns is specified to be included or excluded, all
        callsigns will be candidates for monitoring.  Entering a '+'
        or '-' with no callsigns clears the list. 

        An asterisk displayed after a callsign in the digipeater list
        indicates the frame was transmitted by that station.  The
        control field displayed will be one of the following: 

               NAME   DESCRIPTION
               ----   -----------
               RRa  - Receive Ready
               RNRa - Receive Not Ready
               REJa - Reject
               UI   - Unnumbered Information
               DM   - Disconnected Mode
               SABM - Connect Request
               DISC - Disconnect Request
               UA   - Unnumbered Acknowledge
               FRMR - Frame Reject
               Iab  - Information
               ?ccH - Unknown

               a  = Next expected frame number (0 - 7)
               b  = Frame number of this frame (0 - 7)
               cc = Hexadecimal value


        In addition, one of the following characters will be
        displayed, reflecting the protocol version, command/response
        bits, and the poll/final bit: 

           (blank) = version 1 frame without poll/final bit
                 ! = version 1 frame with poll/final bit
                 ^ = version 2 command frame without poll bit
                 + = version 2 command frame with poll bit
                 - = version 2 response frame with final bit
                 v = version 2 response frame without final bit

          The protocol identifier field is displayed in hexadecimal

        An unattended mode, controlled by the 'U' command, provides
        for sending user supplied text to a connecting station, and
        then allows that station to leave a brief message.  This mode
        can operate on all channels simultaneously, but in no way
        limits the operator's ability to interact with one of the
        connected channels or the ability to make outgoing connect
        requests. 

        When unattended mode is enabled, link status messages are
        queued to the associated channel and not output to the
        terminal unless that channel is currently selected.  Link
        status messages will therefore be displayed in chronological
        order with the information from that channel. 

        In addition, text supplied by the user with the 'U' command
        will be sent to any station that connects.  If channel 0 is
        left selected, stations may then connect and leave messages
        on channels 1 - 4 (limited by the 'Y' parameter, of course).
        The 'L' command may be used to determine if messages have
        been left on any channel.  Selecting a channel containing
        messages will cause all link status and information from that
        channel to be displayed.  If xon/xoff handshaking is enabled,
        CONTROL-S and CONTROL-Q may be used to regulate the output to
        the terminal to allow comfortable reading. 


        Command Summary
        ~~~~~~~~~~~~~~~

        (In terminal mode all commands are preceded by ESC character)

          COMMAND      PARAMETER      DESCRIPTION
          -------      ---------      -----------

            A (1)          0          Auto linefeed disabled
                           1          Auto linefeed enabled

          * C      Cs1 [Cs2 ... Cs9]  Connect path (0=unproto path)

          * D                         Disconnect

            E (1)          0          Echo input disabled
                           1          Echo input enabled

          * I              Cs         Tnc source callsign

            JHOST (0)      0          Terminal mode enabled
                           1          Host mode enabled

            K (0)          0          Timestamp disabled
                           1          Timestamp status messages
                           2          Timestamp monitoring & status   

            L            [0-n]        Display channel status

            M (IU)      NIUSC+-       Monitor mode

            S (0)         0-n         Select channel (0=unproto)

            U (0)   0    [text]       Unattended mode disabled
                    1    [text]       Unattended mode enabled

            V (0)                     Displays the software version

            Y (4)         0-n         Maximum incoming connections

            Z (3)          0          Flow disabled, xon/off disabled
                           1          Flow enabled, xon/off disabled
                           2          Flow disabled, xon/off enabled
                           3          Flow enabled, xon/off enabled

    
         (0) Default values are shown in parentheses
          n  Number of channels, as specified by CHANNELS keyword
          *  These commands are applicable to each connection channel


        Command Description
        ~~~~~~~~~~~~~~~~~~~

        The 'A' (AutoLF) command is used to enable or disable the
        automatic insertion of LINEFEED characters after CARRIAGE
        RETURN characters to the terminal. 

        The 'C' (Connect) command is used on channels other than 0 to
        initiate a link connection.  A 'C' command issued when channel
        0 is selected sets the unproto path.  If digipeaters are
        specified, 'v' or 'via' is not required (but is allowed)
        between the destination callsign and the digipeater callsigns,
        and callsigns must be seperated by spaces.  Note that on
        channels > 0 this command ignores the destination path and
        only allows connect to the node.  The default unproto address
        for channel 0 is "CQ". 

        The 'D' (Disconnect) command is used to initiate a link
        disconnection. If there is unsent or unacknowledged
        information remaining, the disconnect request frame will not
        be sent until all information has been transmitted and
        acknowledged. No additional information will be received after
        the 'D' command has been issued.  A second 'D' command may be
        entered to force the transmission of the disconnect request
        frame before all information has been sent and acknowledged.
        A 'D' command issued during the establishment of a link or
        after a disconnect request frame has been transmitted will
        cause an immediate return to the disconnected state. 

        The 'E' (Echo) command is used to enable or disable the
        echoing of input (commands and information) to the terminal. 

        The 'I' (Ident) command is used to set and display the TNC
        source callsign.  The initial value is the APPLCALL. If no
        APPLblock was defined, the initial value is all blanks.
        Changing the TNC source callsign on a connected channel is not
        permitted.  If the TNC source callsign is left blank, the TNC
        will not allow connect commands or unproto transmissions.  The
        callsign stored in channel 0 is used to initialize each
        connection channel upon power up or disconnection. 

        The 'JHOST' command is used to switch between terminal and
        host modes.  See the DEDHOST MAN page for details of host
        mode operation. 

        The 'K' command controls the time stamping of status messages
        and monitored frames. 

        The 'L' (LinkStatus) command is used to display the link
        status of one or all channels.  Information displayed
        includes the connection path and the number of received frames
        not yet displayed, number of send frames not yet transmitted,
        number of transmitted frames not yet acknowledged, and the
        current retry count.  A '+' character preceeding the channel
        number indicates the currently selected channel.  Operation of
        this command when host mode is enabled is somewhat different,
        and is described in the MAN page for DEDHOST. 

        The 'M' (Monitor) command is used to set the frame monitoring
        mode.  The command parameter determines the types of frames
        monitored, and is a list of desired frames chosen from the
        letters in the following table: 

               LTR       FRAME
               ---       -----
                N        None
                I        I frames
                U        UI frames
                S        Supervisory frames
                C        Monitor while connected
                +        Call signs to be included (maximum of 8)
                -        Call signs to be excluded (maximum of 8)

               The '+' and '-' parameters may not be used together.
               If either is used, it must be the last parameter
               (followed by one to eight callsigns, if applicable).
               If no list of callsigns is specified to be included or
               excluded, all callsigns will be candidates for
               monitoring.  Entering a '+' or '-' with no callsigns
               will clear the list. 

        The 'U' (Unattended) command is used to enable or disable
        unattended modes. 

        The 'V' (Version) command just displays the software version.
        In this respect it behaves like TheFirmware instead of WA8DED. 

        The 'Y' command is used to set the maximum number of
        connections that may established by incoming requests.  This
        command has no effect on the operators ability to initiate
        outgoing connection requests. 

        The 'Z' command is used to enable or disable flow control and
        XON/XOFF handshaking to the terminal.  If flow control is
        enabled, output to the terminal will be inhibited while
        entering commands or information.  If flow control is
        disabled, output to the terminal will not be restricted.
        Flow control and xon/xoff handshaking should be disabled
        during periods in which the TNC is operated without a
        terminal, to avoid suspending output which will consume
        buffers.  If XON/XOFF handshaking is enabled, terminal
        scrolling may be stopped and started using CONTROL-S and
        CONTROL-Q characters.  Flow control and XON/XOFF handshaking
        are not performed when host mode is enabled.

        The '@' command is a software maintenance command.  A
        parameter of 'B' displays the number of free buffers. 
    
</code> **SEE ALSO:** \\
[[packet:xrouter:docs:MAN9#DEDHOST|        DEDHOST(9)     -- WA8DED Hostmode Emulation.
]] \\
[[packet:xrouter:docs:MAN8#XROUTER.CFG|        XROUTER.CFG(8) -- Main Configuration File.
]] \\

[[packet:xrouter:docs:|< Back to Index]]

----
===== WPAGES =====
<code>WPAGES(9)               XROUTER REFERENCE MANUAL             29/3/2024

</code> **COMMAND** <code>
        WPAGES -- White Pages Database.

</code> **DESCRIPTION** <code>
        The WP (White Pages) database on this mailbox is part of a
        world wide distributed database, which holds details of all
        recently active Packet users. The database is primarily used
        by mailboxes to make mail routing decisions. The data is
        also available to users via a number of search commands.

        The data is collected from two main sources:

           a) from the details a user enters when they register on a
              mailbox.
           b) from the headers of mail in transit.

        There are 3 classes of data as follows:

            /U    User-entered, via one or more of the "N" commands.
                  This is the most reliable date.

            /I    "Is-BBS", generated by each BBS for its own
                  callsign, and inferred from routing headers, when
                  the user call and BBS call are the same.

            /G    "Guessed" or "Gleaned" from routing headers, when
                  the user call and BBS call are different. Not to
                  be trusted, because users often send mail from
                  BBS's that are not their "Home" BBS.

        WP data is stored in memory, mirrored in the file WP.DAT,
        which is located in the PMS folder. This is a plain text
        file, so it can be edited with any text editor if necessary.
        The file is read only at boot-up, and is written whenever
        there are any changes.

        Most mailboxes with WP capability share their data by means
        of regular "WP Update" messages.  These were supposed to be
        sent to "regional" servers, which would collate the data and
        send it via regional and national servers to a world server.

        That system has fallen apart over time. The current advice
        is to send WP updates as private messages to your immediate
        neighbours only. This can be set up using one or more
        "WpUpdateTo" directives in PMS.CFG.

        XRouter only shares "/U" (user-entered) data via WP updates.

        If a user has not sent a message, and has not re-registered
        on a BBS within a certain period, their details are purged
        from the WP database. That period is commonly 90 days, but
        can be as little as 30 days. XRouter currently does not
        expire WP entries.

        There are many packet users who NEVER log into a mailbox,
        and who are therefore "invisible" to WP.

        The local database can be searched using the I, I@, IC, IH,
        IN, IQ and IZ commands, which each have their own MAN pages.

</code> **SEE ALSO:** \\
[[packet:xrouter:docs:MAN4#INFO|        INFO(4) -- Display Mailbox or White Pages Information.]] \\
[[packet:xrouter:docs:MAN8#PMS.CFG|        PMS.CFG(8) -- PMS Configuration File.]] \\

[[packet:xrouter:docs:|< Back to Index]]

----
===== WX =====
<code>WX(9)                   XROUTER REFERENCE MANUAL             28/2/2024

</code> **NAME** <code>
        WX(9) -- Weather Information System.

</code> **INTRODUCTION** <code>
        XRouter can gather and store weather information from a local
        weather source and/or from the APRS weather broadcasts of up
        to 5 neighbour nodes. It can display
        the information in response to the WX and INFO commands.

        It can also display the information via its HTTP interface,
        the NetRomX weather server, the integral MQTT server, and
        can broadcast it in APRS-style beacons.

- How it is accessed & presented
- How to set it up
- Wacky ideas

</code> **DATA SOURCES** <code>

        - APRS Weather broadcasts from nearby nodes.
        - Files deposited by external WX programs e.g. Cumulus
        - MQTT messages addressed to the nodecall.

</code> **DATA STORED** <code>

        For non-local sources, e.g. APRS broadcasts, the following
        basic information is stored, if the source provides it:

	    - Observation date/time
            - Callsign of the originating source
            - Latitude and longitiude of the observation
            - Distance of the observation from XRouter
            - Barometric pressure
            - Air temperature
            - Humidity
            - Wind direction
            - Wind speed
            - Wind gust speed
	    - Rainfall in last 24 hours
            - Rainfall in the last hour
            - Rainfall since midnight

        For local sources, e.g. import files or MQTT messages, the
        following additional data is stored, if the source provides
        it:

            - Sensor battery state
            - Light level
            - UV level

        If the source provides the required data, the following
        "derived" values may also be stored:

            - Today's pressure max/min and the times thereof.
            - Today's average pressure.
            - Today's temperature max.min and the times thereof.
            - Today's average temperature
            - Tofay's humidity max/min and the times thereof
            - Today's average humidity.
            - Today's maximum wind and gust speeds and times thereof
            - Running average wind direction (last 11 readings)
            - Running average wind speed
            - Current rainfall rate
            - Today's maximum rainfall rate and time threof
            - Temperature trend.
            - Dew Point
            - Wind Chill
            - Heat Index
            - Wind Run

</code> **STORAGE UNITS / PRECISION** <code>

        Parameter     Stored as        Precision
        --------------------------------------------
        Lat/long        Degrees        0.01 minutes
        Date/time       Seconds        1 sec
        Pressure        Millibars      0.1 mb
        Temperature     Degrees C      0.1 C
        Humidity        Percent        1 percent
        Wind speed      Miles Per Hour 0.1 mph
        Wind direction  Degrees        1 degree
        Rainfall        Millimetres    0.1 mm
        Wind Run        Miles          0.001 mile
        Max/Min times   Hour:minute    1 minute
        Dew point       Degrees C      0.1 C
        Wind Chill      Degrees C      0.1 C
        Heat Index      Degrees C      0.1 C

</code> **STORAGE ACROSS REBOOTS** <code>

        The WXSAV.DAT file preserves most data across reboots, but
        for the first few observations after a reboot there will be
        no trend or running average information. That will appear
        after a few observations.

</code> **DATA ACCESS** <code>

        COMMAND LINE
            The WX command is used to display a list of available WX
            datasets, to display the data from a specified source,
            or to obtain a WX summary from another XRouter. See the
            WX(1) man page for details.

            The page displayed by the INFO PAGE command contains a
            brief local weather summary comprising date, time, air 
            pressure, temperature, humidity, wind speed, gust speed,
            and wind direction, if such information is available.

        WEB PAGE
            If XRouter's HTTP server is enabled, and local weather is
            available, it is displayed on the following page:
            http://{ipaddress[:port]}/localwx
            where ipaddress and port are those of XRouter

        WX SERVER
            XRouter's "weather summary server", accessed via NetromX
            service number 16, returns local weather information, if
            available. The information is returned in a machine and
            human readable plain text form. See the WX-SVC(9) manual
            page for more details.

        MQTT BROKER
            XRouter's integral MQTT broker makes weather information
            available, both as "events" and upon request. The former
            are published whenever new data arrives, and the latter
            are published upon request. The broker may be accessed
            either via MQTTPORT on the LAN and/or amprnet, or via a
            NetromX connection to service 1883. The inbuilt MQTT
            client can be used to make such a connection, as can any
            other client of your choosing.

            To receive WX "events", subscribe to the following topic:

                xrouter/event/{nodecall}/wx/{callsign | #}

            To request WX information, first subscribe to

                xrouter/status/{nodecall}/wx[callsign]

            then PUBlish xrouter/get/{nodecall}/wx[/callsign]

        APRS BROADCASTS
            XRouter can be configured to broadcast APRS-format WX
            beacons at specified intervals on specified PORTs.







</code> **MQTT/Json** <code>
~~~~~~~~~
</code> **Some weather stations supply rainfall in total bucket tips, e.g. "Rainfall":1186, others as total mm, e.g. "rain_mm" : 467.106.** <code>


</code> **If "mm" is not prsent** <code>

{"time" : "2024-03-04 18:58:15", "model" : "Fineoffset-WH65B", "id" : 80, "battery_ok" : 1, "temperature_C" : 6.200, "humidity" : 89, "wind_dir_deg" : 204, "wind_avg_m_s" : 0.000, "wind_max_m_s" : 0.000, "rain_mm" : 514.096, "uv" : 0, "uvi" : 0, "light_lux" : 0.000, "mic" : "CRC"}

</code> **There doesn't seem to be any standard for the field names. For instance the observation timestamp could be sent as "timestamp" or "observed" instead of "time". Temperature could be sent as "temp", temperature_deg_c, "temperature_C" and so on.** <code>

        Xrouter can be customised to recognise the field names used in
        the data source, using a set of optional directives in
        XROUTER.CFG as follows:

          Name       Default          Purpose
	  --------------------------------------------------------
          WXBATTERY  "battery_ok"     Sensor battery indication
          WXBEARING  "wind_deg"       Wind direction in degrees
          WXGUST     "wind_max_m_s"   Gust speed in metres per sec
          WXHUMID    "humidity"       Relative humidity in pecent
          WXID       "id"             Sensor number
          WXLIGHT    "light_lux"      Solar Irradiance in lux
          WXMODEL    "model"          Sensor make/model
          WXPRESS    "pressure"       Air pressure in millibars
          WXRAIN     "rain_mm"        Total rainfall in mm
          WXSPEED    "wind_speed_m_s" Wind speed in metres per sec
          WXTEMP     "temperature_c"  Air temperature in degress C
          WXUV       "uv"             UV level
          WXUVINDEX  "uvi"            UV Index

</code> **RELATED DIRECTIVES** <code>

        WXSENSOR    A string of characters (max 31) which identifies
                    the desired weather sensor in the source data
                    stream, e.g. "Fineoffset-WH65B".
                    For use where the data source might contain data
                    from more than one weather sensor, or from other
                    types of sensor that may share the same parameter
                    names, e.g. tyre pressure sensors. There is no
                    default. If specified, only data whose "model"
                    field contains the specified string is accepted.

        WXSENSORID  A string of characters (max 15) which uniquely
                    identifies a particular sensor among sensors of
                    the same make/model. e.g. "80".
                    Can be used in conjunction with WXSENSOR, or on
                    its own. There is no default. If specified, only
                    data whose "id" field contains the specified
                    string is accepted.

        WXBUCKET    Specifies the "bucket size" in mm for a bucket
                    tipping pluviometer. This is the amount of rain
                    required to increment the "rainfall" count by one
                    unit.
                    Bucket sizes typically range from 0.1 to 1mm,
                    with 0.3mm and 0.254mm being common sizes for
                    amateur weather stations. Defaults to 0.3

        WXWINDGAIN  A correction factor which can be applied to the
                    wind speed input to compensate for non-ideal
                    siting of the anemometer. Default is 1.0.
                    The "standard height" for wind speed measurements
                    is 10 metres above unobstructed ground. Due to
                    air resistance and obstructions, wind speed
                    reduces at lower heights. If the wind speed at 4m
                    above ground was half the level at 10 metres, a
                    WXWINDGAIN of 2 would cause the "correct" wind
                    speed to be displayed. However, the meaning of
                    "correct" wind speed is debateable -  if a 
                    greenhouse in a sheltered garden can withstand a
                    wind speed of 49mph before collapsing, it is the
                    ground level wind speed that's important, not
                    the 10m AGL speed.
                    WXWINDGAIN can also be used to adjust







</code> **Directives:** <code>
~~~~~~~~~~~
</code> **WXMODEL - optional. For use where . The field name defaults to "model" is specified by** <code>

</code> **WXBATTERY:** <code>
</code> **Optional. Defaults to "battery_ok"** <code>

</code> **WXBEARING:** <code>
</code> **Optional. Defaults to "direction"** <code>






</code> **WXFILE:** <code>
</code> **Specifies the pathname of a file from which XRouter can read weather data. There is no default. If WXFILE is specified, and the file exists, XRouter reads its contents once per minute. The contents of the file may be in Cumulus WXNOW.TXT or REALTIME.TXT formats, which are well documented on the web.** <code>

(list the name value pairs expected here)

"Temperature:" Degrees centrigrade
"Barometer:" 	Pressure (millibars)
"Wind:"		speed in MPH;
"Direction:"	Degrees;
"Gust:"		speed in MPH
"Humidity:" 	0-100 (percent)


</code> **WXGUST:** <code>
</code> **Specifies the field name used for reading the wind gust speed from a JSON message or weather file. Max 15 characters. Defaults to "gust"** <code>

</code> **WXHUMID:** <code>
</code> **Specifies the field name used for reading the humidity (in percent) from a JSON message or weather file. Max 15 characters. Defaults to "humidity".** <code>

</code> **WXID:** <code>
			pztncpy (WxId, args, 15);
			break;

		case CMD_WXLIGHT:
			pztncpy (WxLight, args, 15);
			break;

		case CMD_WXMODEL:
			pztncpy (WxModel, args, 15);
			break;

		case CMD_WXPRESS:
			pztncpy (WxPress, args, 15);
			break;

		case CMD_WXRAIN:
			pztncpy (WxRain, args, 15);
			break;

		case CMD_WXRAINTYPE:
			break;

		case CMD_WXSENSOR:
			pztncpy (WxSensor, args, 31);
			break;

		case CMD_WXSENSORID:
			pztncpy (WxSensorId, args, 15);
			break;

		case CMD_WXSPEED:
			pztncpy (WxSpeed, args, 15);
			break;

		case CMD_WXTEMP:
			pztncpy (WxTemp, args, 15);
			break;

		case CMD_WXTIME:
			pztncpy (WxTime, args, 15);
			break;

		case CMD_WXWINDGAIN:
			WxWindFactor = atof (args);

</code> **WXUVINDEX:** <code>
</code> **Specifies the JSON field name used for reading the UV index. Defaults to "uvi".** <code>


</code> **OPTIONS** <code>

</code> **UPDATING VIA HTTP** <code>

</code> **If you have a weather station that can be configured to upload to a custom server using Wunderground PWS protocol, it can upload directly to XRouter.** <code>

</code> **Configure the weather station as follows:** <code>

a) choose "Upload to custom server"
b) choose Wunderground protocol
c) Set the "Server IP/Hostname:" field to Xrouter's IP
d) Set "Path:" to /wx/report?
e) Set "station ID:" to a string of your choice, e.g. KidderWX
f) Set "Station Key:" to a suitable password of your choice
g) Set "Port:" to whatever your HTTPPORT is set to
h) Set "Upload Interval" to your choice
i) Save

</code> **Configure XRouter as follows** <code>



# Updates sent as GET requests to /wx/report
# Uses Wunderground PWS upload protocol
# PWS station ID
</code> **WXSENSORID=Fal** <code>

# Password
</code> **WXCMD=12345** <code>

</code> **WXWINDGAIN=2.0** <code>


</code> **API (see REST-WX.9.MAN) and possibly MQTT** <code>

        a) Retrieve List of Weather Stations:
        ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

        Request-Type: GET
        Request-URL:  /api/v1/weather/stations

        If successful, the response is an un-named JSON array of
        objects, each object containing the following fields:







</code> **It is strongly recommended that you use WXSENSOR to avoid reading erroneos data from other type of device.** <code>
        

</code> **SEE ALSO:** \\
[[packet:xrouter:docs:MAN1#WX|        WX(1) -- Display Weather Information.]] \\
[[packet:xrouter:docs:MAN#WXID.7|        WXID.7]] \\
[[packet:xrouter:docs:MAN#WXLIGHT.7|        WXLIGHT.7]] \\
[[packet:xrouter:docs:MAN#WXMODEL.7|        WXMODEL.7]] \\
[[packet:xrouter:docs:MAN#WXPRESS.7|        WXPRESS.7]] \\
[[packet:xrouter:docs:MAN#WXRAIN.7|        WXRAIN.7]] \\
[[packet:xrouter:docs:MAN#WXRAINTYPE.7|        WXRAINTYPE.7]] \\
[[packet:xrouter:docs:MAN#WXSENSOR.7|        WXSENSOR.7]] \\
[[packet:xrouter:docs:MAN#WXSENSORID.7|        WXSENSORID.7]] \\
[[packet:xrouter:docs:MAN#WXSPEED.7|        WXSPEED.7]] \\
[[packet:xrouter:docs:MAN#WXTEMP.7|        WXTEMP.7]] \\
[[packet:xrouter:docs:MAN#WXTIME.7|        WXTIME.7]] \\
[[packet:xrouter:docs:MAN#WXWINDGAIN.7|        WXWINDGAIN.7]] \\
[[packet:xrouter:docs:MAN#WXUV.7|        WXUV.7]] \\
[[packet:xrouter:docs:MAN9#WX-SVC|        WX-SVC(9)      -- NetRomX Weather Service]] \\
[[packet:xrouter:docs:MAN8#XROUTER.CFG|        XROUTER.CFG(8) -- Main Configuration File.]] \\
[[packet:xrouter:docs:MAN#|        ]] \\

[[packet:xrouter:docs:|< Back to Index]]

----
===== WX-SVC =====
<code>WX-SVC(9)               XROUTER REFERENCE MANUAL               7/9/2023
</code> **NAME** <code>
        WX-SVC -- NetRomX Weather Service

</code> **DESCRIPTION** <code>
        The weather service returns local weather information, if
        available. It is accessed via NetromX service number 16.

        The information is returned in machine-readable plain text
        form. A typical response would look like this:

        Observed: Mon 17 May 2021 06:01:23 +0001
        Pressure: 1007.2 mB
        Temperature: 11.2 C
        Humidity: 67 %
        Wind: 23 mph
        Direction: 178 deg
        Gust: 31 mph
        Rain-24h: 24.7 mm
        Rain-Today: 19.7 mm
        Rain-1h: 3.2 mm

        When the client has recieved the information, the server
        terminates the connection.

        Some fields may be missing if there is no information in them.

        The information is derived from received APRS broadcasts, or
        from the WXNOW or CUMULUS format files generated by home
        weather stations or weather applications. The filename is
        specifed by the WXFILE directive in XROUTER.CFG.

        Once per minute, XRouter checks the file specified by the
        WXFILE directive. If the file is present, and the information
        therein is more up to date than the previous data, the
        contents of the file are imported.

        A WXNOW.TXT file only has 2 lines, for example:

        Feb 01 2009 12:34
        272/010g006t069r010p030P020h61b1050

        where:  272   = Wind direction in degrees.
                010   = Average wind speed in MPH.
                g006  = Gust speed in MPH
                t069  = Temperature in degrees Farenheit
                r010  = Rainfall in last hour in 0.01 inch.
                p030  = Rainfall in last 24H in 0.01 inch.
                P020  = Rainfall since midnight in 0.01 inch.
                h61   = Humidity in percent.
                b1050 = barometric pressure in millibars.


        The Cumulus "realtime.txt" file is a text file with a single
        line of space separated values. It contains a list of key
        values of the sensors and is re-created frequently. After
        creation, it can be set to automatically upload to a website
        (or to XRouter) via FTP.

        An example of the format is as follows (all one line):

        18/10/08 16:03:45 8.4 84 5.8 24.2 33.0 261 0.0 1.0 999.7 W 6
        mph C mb mm 146.6 +0.1 85.2 588.4 11.6 20.3 57 3.6 -0.7 10.9
        12:00 7.8 14:41 37.4 14:38 44.0 14:28 999.8 16:01 998.4 12:06
        1.8.2 448 36.0 10.3 10.5 13 0.2 14 260 2.3 3 1 1 NNW 2040 ft
        12.3 11.1 420.1 1 13.6

        XRouter currently parses the following fields from
        realtime.txt:

           1    Observation date
           2    Observation time
           3    Temperature
           4    Humidity
           6    Wind speed
           8    Wind direction
           9    Rain rate per hour
           10   Rain today
           11   Barometric pressure
           14   Wind units - m/s, mph, km/h, kts
           15   Temperature units - degree C, degree F
           16   Pressure units - mb, hPa, in
           17   Rainfall units - mm, in
           41   Gust speed
           48   Rainfall last hour


        There is another (non-standard) format that XRouter can import
        from a WX file. This consists of "<name>: <value>" pairs as
        follows:

           Temperature: 22.7
           Barometer: 1015
           Wind: 6
           Direction: 178
           Gust: 12
           Humidity: 67
        
        The fields can be in any order, and need not all be present.
        They may be seperated by spaces or tabs.

        At present, temperature must be in Centigrade, pressure in
        millibars, and wind speeds in MPH. There are plans to make
        this accept other units. 

        If you don't have a weather station that outputs one of the
        above formats, by using suitable software or scripts you could
        extract weather information from your WX station and write it
        to a file in one of the above 3 formats.

        For example, you could use a cheap RTL dongle and "rtl_433"
        software on the Pi to receive and decode the 433.9 MHz OOK
        transmissions from your weather station to its base unit.

        You could even pull weather information for your area off the
        web and write it to a file. But that is beyond the scope of
        this document.

</code> **SEE ALSO:** \\
[[packet:xrouter:docs:MAN1#WX|        WX(1)       -- Display Weather Information.
]] \\
[[packet:xrouter:docs:MAN7#WXFILE|        WXFILE(7)   -- Specify Weather Import File.
]] \\
[[packet:xrouter:docs:MAN9#SERVICES|        SERVICES(9) -- NetRomX Standard Services.
]] \\

[[packet:xrouter:docs:|< Back to Index]]

----
===== YAM =====
<code>YAM(9)                  XROUTER REFERENCE MANUAL             29/9/2023

</code> **NAME** <code>
        YAM -- "Yet Another Modem" HDLC Modem.

</code> **DESCRIPTION** <code>
        The "YAM" modem conects to a COM port, and implements the
        functions of a TNC in a FPGA (Field Programmable Gate Array).

        XRouter includes support for the YAM modem, and the interface
        should be defined in XROUTER.CFG as follows:

           INTERFACE=10       <- Adjust to suit
              TYPE=YAM
              COM=1           <- COM port to which YAM is connected
              MTU=256
              SPEED=1200      <- Radio speed (not serial comms speed!)
              PROTOCOL=HDLC   <- Only HDLC supported at present
           ENDINTERFACE

        SPEED is the *radio* baud rate and should match the modem's
        configuration, otherwise TXDELAY and TXTAIL timings will be
        wrong.  You can omit SPEED and define RFBAUDS in the port
        instead.  Communication between between XRouter and YAM via
        the RS232 cable always takes place at 19200 bauds.

        PROTOCOL *must* be HDLC.  No other protocols are supported at
        present.

        Each YAM interface supports only one PORT.  You must use a
        separate INTERFACE and PORT for each YAM board.

        Port Settings
        ~~~~~~~~~~~~~
        A typical PORT might be defined as follows:

           PORT
              ID=YAM 1200 Bauds 144.650MHz
              INTERFACENUM=10
              CHANNEL=A
              SPEED=1200
              FULLDUP=0
              TXDELAY=150
           ENDPORT

        CHANNEL is ignored, but must be present.  FULLDUP can be used,
        as the YAM is capable of full duplex operation, but SOFTDCD is 
        ignored because it has no meaning for a YAM board.

        YAM will INTERLOCK with other YAM interfaces and with all
        types of SCC card, but not with KISS TNC's since XRouter has
        no knowledge of, or control over when a KISS TNC is
        transmitting.

        Notes
        ~~~~~
        The YAM modem uses TXD, RXD, RTS, CTS, DTR, DSR, RI and DCD so
        a full 8 wire plus ground cable is required.

        Some PC's either don't provide enough DC voltage/current to
        supply the YAM board or the RS232 inputs sink too much
        current.  This is a hardware problem, not an XRouter problem.
        It can be overcome by using an external supply to power the
        YAM board.

        XRouter does not program the FPGA therefore YAM modems must be 
        initialised by running YAMINIT (supplied with the modem)
        before starting XRouter.  It is probably best to do this in a
        startup batch file.  "YAMINIT yam12v11.mcs 1" will program the
        YAM for COM1 with 1200 baud RF speed.  The YAM is capable of
        1200, 2400 or 9600 baud simply by choosing the appropriate
        .MCS file.

        For further information you must refer to the YAM
        manufacturer's documentation.

</code> **CAVEATS** <code>
        YAM has not been tested since the XRouter code was ported from
        DOS to Windows.  Reports would be welcome.

</code> **SEE ALSO:** \\
[[packet:xrouter:docs:MAN8#XROUTER.CFG|        XROUTER.CFG(8) -- Main Configuration File.
]] \\

[[packet:xrouter:docs:|< Back to Index]]

----